Skip to content

Ego Native API Reference

liuwd8 edited this page Aug 29, 2026 · 3 revisions

EgoBindings is the native JavaScript bridge between a Node Runtime and the Browser Process. It installs globalThis.ego in every Node Runtime so the upper-level SDK can access Ego Browser Spaces, tabs, page snapshots, task state, and CDP.

This page documents the JavaScript inputs, outputs, and field meanings of the native globalThis.ego contract. For the surrounding process model, see Ego Browser CLI Architecture.

Scope

EgoBindings is installed before the SDK preload runs. The SDK may wrap native methods, expose higher-level global helpers, or add properties such as ego.helpers, but those SDK additions are outside this reference.

Helpers such as gotoUrl(), click(), and useOrCreateTaskSpace() are SDK APIs and are not documented here.

Common conventions

Current Task Space

The following methods operate on the Task Space selected by ego.useTaskSpace(id):

  • createTab()
  • listTabs()
  • snapshot()
  • closeTaskSpace()
  • completeTaskSpace()
  • markTaskSpaceError()
  • handOffTaskSpace()
  • takeOverTaskSpace()
  • setAgentTaskState()
  • animationHighlightMouseToPosition()
  • sendCDPMessage()

The selection is stored in the current EgoBindings instance and is valid only within its Node Runtime. A new Runtime does not inherit it.

Error results

Most asynchronous methods resolve their Promise with an error object:

{
  error: 'Task space not selected',
  error_code: 'EGO_TASK_SPACE_NOT_SELECTED',
}
Field Type Meaning
error string Human-readable message or reason
error_code string Stable value for programmatic handling

snapshot() is the exception: it rejects its Promise with an Error containing message and error_code. Invalid arguments synchronously throw TypeError.

Profiles

await ego.listProfiles()

Lists regular Profiles that may be used to create a Task Space.

Input

No arguments.

Output

Promise<object>:

{
  profiles: [
    {
      id: 'Default',
      name: 'Personal',
      isDefault: true,
    },
  ],
}
Field Type Meaning
profiles Array<object> Available Profiles
profiles[].id string Unique locator accepted by createTaskSpace()
profiles[].name string User-visible name; may be duplicated and is not a locator
profiles[].isDefault boolean Whether this Profile is selected when profileId is omitted

The internal Ego authentication Profile is not returned. Passing any argument throws TypeError.

Task Spaces

await ego.listTaskSpaces()

Lists Task Spaces managed by the current Browser Process.

Input

No arguments.

Output

Promise<object>:

{
  taskSpaces: [
    {
      id: 7,
      taskId: 'checkout-flow',
      name: 'checkout-flow',
      profileId: 'Default',
      profileName: 'Personal',
      createdBy: 'agent',
      ownership: 'agent',
      recentTabTitles: ['Checkout', 'Cart'],
    },
  ],
}
Field Type Meaning
taskSpaces Array<object> Task Space descriptors
taskSpaces[].id number Unique numeric locator used by other native methods
taskSpaces[].taskId string Compatibility field equal to name; do not use as a locator
taskSpaces[].name string User-visible Space name
taskSpaces[].profileId string Unique locator of the owning Profile
taskSpaces[].profileName string User-visible Profile name
taskSpaces[].createdBy string Creator: agent or user
taskSpaces[].ownership string Control state: agent, user, or agentDelegatedToUser
taskSpaces[].recentTabTitles Array<string> Up to three recently used tab titles

Passing any argument throws TypeError.

await ego.deleteSpaces(options)

Deletes regular Spaces in bulk. This method does not use the current Task Space.

Input

Parameter Type Required Meaning
options object Yes Exactly one deletion selector
options.scope 'all' One of Delete all non-running regular Spaces
options.scope 'task' One of Delete non-running Spaces created by an agent
options.ids number[] One of Delete the specified numeric Space IDs; must not be empty

scope and ids are mutually exclusive. Scope-based deletion skips Spaces with a running agent task. Explicit ids do not apply that skip rule.

await ego.deleteSpaces({scope: 'task'});
await ego.deleteSpaces({scope: 'all'});
await ego.deleteSpaces({ids: [7, 9]});

Output

Promise<object>:

{
  deletedSpaceIds: [7, 9],
  skippedRunningSpaceIds: [11],
}
Field Type Meaning
deletedSpaceIds number[] IDs of deleted Spaces
skippedRunningSpaceIds number[] IDs skipped because an agent task was running

If the user cancels closing, the method returns an EGO_OPERATION_FAILED error object. Invalid options throw TypeError.

await ego.createTaskSpace(name, profileId?)

Creates an agent-controlled Task Space.

Input

Parameter Type Required Meaning
name string Yes Non-empty user-visible name
profileId string No Profile id returned by listProfiles()

Omitting profileId, passing an empty string, or passing 'default' selects the active or last-used regular Profile. A Profile display name is not accepted as a locator.

Output

Promise<object>:

{
  id: 7,
  taskId: 'checkout-flow',
  name: 'checkout-flow',
}
Field Type Meaning
id number Unique Task Space locator
taskId string Compatibility field equal to name
name string User-visible name

An unknown Profile returns EGO_PROFILE_NOT_FOUND. Failure to create a Space returns EGO_BROWSER_UNAVAILABLE. Invalid arguments throw TypeError.

await ego.claimTaskSpace(id, name?)

Claims an existing Space for agent control.

Input

Parameter Type Required Meaning
id number Yes Numeric Space ID returned by listTaskSpaces()
name string No New name assigned while claiming; omitted or empty preserves the current name

Output

Promise<object> with the same shape as createTaskSpace():

{
  id: 7,
  taskId: 'checkout-flow',
  name: 'checkout-flow',
}

Claiming does not select the Space. Call ego.useTaskSpace(task.id) before using task-scoped methods. A missing Space returns EGO_TASK_SPACE_NOT_FOUND. Invalid arguments throw TypeError.

ego.useTaskSpace(id)

Selects the current Task Space for this EgoBindings instance. It stores the numeric ID locally and does not create, claim, or validate the Space.

Input

Parameter Type Required Meaning
id number Yes Numeric ID returned by createTaskSpace(), claimTaskSpace(), or listTaskSpaces()

Output

Synchronously returns the provided id:

const selectedId = ego.useTaskSpace(7); // 7

Invalid arguments throw TypeError.

await ego.closeTaskSpace()

Closes the selected Task Space and its browser window.

Input

No arguments. A Task Space must already be selected.

Output

Promise<string>:

<id> task space closed.

A missing, unselected, or user-controlled Space returns an error object.

await ego.completeTaskSpace()

Marks the selected task complete, removes agent task state, and keeps the Space and its tabs open.

Input

No arguments. A Task Space must already be selected.

Output

Promise<string>:

<id> task space completed.

A missing, unselected, or user-controlled Space returns an error object.

await ego.markTaskSpaceError(message)

Marks the selected task as failed, keeps the Space, and exposes the failure reason to the user.

Input

Parameter Type Required Meaning
message string Yes User-visible task failure reason

Output

Promise<string>:

<id> task space marked as error.

A missing, unselected, or user-controlled Space returns an error object. Invalid arguments throw TypeError.

await ego.handOffTaskSpace()

Transfers control of the selected Task Space to the user.

Input

No arguments. A Task Space must already be selected.

Output

Promise<string>:

<id> has been handed off to the user.

After handoff, methods requiring agent control return EGO_TASK_SPACE_USER_IN_CONTROL until takeOverTaskSpace() succeeds.

await ego.takeOverTaskSpace()

Takes control of the selected Task Space back from the user.

Input

No arguments. A Task Space must already be selected.

Output

Promise<string>:

<id> has been taken over by the agent.

await ego.setAgentTaskState(state)

Updates the user-visible progress text for the selected task.

Input

Parameter Type Required Meaning
state string Yes Task progress text shown to the user

Output

Promise<string>:

<id> state updated.

A missing, unselected, inactive, or user-controlled Space returns an error object. Invalid arguments throw TypeError.

Tabs and pages

await ego.createTab(url)

Opens a URL in the selected Task Space. An empty or new-tab page may be reused; otherwise Ego creates a foreground tab.

Input

Parameter Type Required Meaning
url string Yes URL to open

Output

Promise<object>:

{
  targetId: 'A1B2C3...',
}
Field Type Meaning
targetId string DevTools Target ID for the tab

Failure to obtain page contents returns EGO_WEB_CONTENTS_UNAVAILABLE. Invalid arguments throw TypeError.

await ego.listTabs()

Lists all tabs in the selected Task Space.

Input

No arguments. A Task Space must already be selected.

Output

Promise<object>:

{
  tabs: [
    {
      index: 0,
      targetId: 'A1B2C3...',
      url: 'https://example.com/',
      title: 'Example Domain',
      active: true,
    },
  ],
}
Field Type Meaning
tabs Array<object> Tab descriptors
tabs[].index number Zero-based index in the window
tabs[].targetId string DevTools Target ID
tabs[].url string Current page URL
tabs[].title string Current page title
tabs[].active boolean Whether this is the active tab

await ego.snapshot(options?)

Captures a structured snapshot of the active tab.

Input

Parameter Type Required Meaning
options object No Snapshot options
options.scope 'full_page' | 'only_within_viewport' No Full page or current viewport; defaults to full_page
options.includeActionMarks boolean No Include action markers in textual content
options.interactiveOnly boolean No Include only interactive elements
options.includeStableLocator boolean No Return stable locator hints when available
options.maxResultLength number No Maximum content length; 0 or omitted means unlimited

Output

Promise<object>:

{
  content: '...',
  refs: [
    {
      refId: 3,
      backendNodeId: 17,
      role: 'button',
      name: 'Continue',
      loc: 'role:button[name=Continue]',
      frameId: '...',
    },
  ],
}
Field Type Meaning
content string Structured page text
refs Array<object> Metadata for referenced elements
refs[].refId number Reference ID unique within this snapshot
refs[].backendNodeId number CDP Backend Node ID within the owning Renderer
refs[].role string Accessibility role
refs[].name string Accessibility name
refs[].loc string Reusable locator hint; omitted when unavailable
refs[].frameId string DevTools Frame ID; normally omitted for the top-level document

On failure, the Promise rejects with an Error containing message and error_code.

await ego.animationHighlightMouseToPosition(x, y)

Shows a mouse-move highlight in the content area of the selected Task Space.

Input

Parameter Type Required Meaning
x number Yes Horizontal coordinate relative to the browser content view
y number Yes Vertical coordinate relative to the browser content view

Output

Promise<string>:

<id> mouse highlight shown.

A missing, unselected, unavailable, or user-controlled Space returns an error object. Invalid arguments throw TypeError.

Browser information

await ego.getBrowserVersion()

Reads the current Ego Browser version and known update state. It does not trigger a network check, download, or upgrade.

Input

No arguments.

Output

Promise<object>:

{
  currentVersion: '1.2.3',
  updateAvailable: false,
}
Field Type Meaning
currentVersion string Current Ego Browser version
updateAvailable boolean Whether the browser has already detected an available update

Passing any argument throws TypeError. Use ego-browser upgrade to perform an upgrade.

Chrome DevTools Protocol

ego.sendCDPMessage(message)

Sends a raw CDP message through the selected Task Space.

Input

Parameter Type Required Meaning
message string Yes JSON-encoded CDP command or request
ego.sendCDPMessage(JSON.stringify({
  id: 1,
  method: 'Runtime.enable',
}));

Output

Synchronously returns undefined. CDP responses and events arrive through ego.onCDPMessage. Failures before dispatch arrive through ego.onSendCDPMessageError.

The message is not sent if no Task Space is selected, the Space does not exist, the Space has not been claimed by an agent, or the user has control. Target.createTarget is blocked; use createTab() instead.

ego.onCDPMessage

Callback property for CDP responses and events.

Input

Assign a function to register it. Assign a non-function value to clear it:

ego.onCDPMessage = message => {
  console.log(JSON.parse(message));
};

Callback output

Parameter Type Meaning
message string JSON-encoded CDP response or event

ego.onSendCDPMessageError

Callback property for errors occurring before a CDP message is dispatched.

Input

Assign a function to register it. Assign a non-function value to clear it:

ego.onSendCDPMessageError = (message, errorCode) => {
  console.error(message, errorCode);
};

Callback output

Parameter Type Meaning
message string Human-readable send failure
errorCode string Stable code such as EGO_TASK_SPACE_NOT_SELECTED

Error codes

JavaScript exposes the string in error_code. The numeric value is the underlying Native CliErrorCode enum value used for IPC and debugging.

Value error_code string Meaning
0 EGO_BROWSER_UNAVAILABLE Browser Process or usable browser is unavailable
1 EGO_CDP_CHANNEL_UNAVAILABLE CDP channel is unavailable
2 EGO_CDP_SEND_FAILED CDP send failed
3 EGO_INVALID_ARGUMENT Argument count, type, or content is invalid
4 EGO_INVALID_RESULT_PAYLOAD Result payload has an invalid shape
5 EGO_OPERATION_FAILED Operation failed without a more specific code
6 EGO_PROFILE_NOT_FOUND Requested Profile was not found
7 EGO_RESULT_CONVERSION_FAILED Native result could not be converted to JavaScript
8 EGO_SNAPSHOT_FAILED Page snapshot failed
9 EGO_TASK_HOST_DISCONNECTED Task-side connection was lost
10 EGO_TASK_SPACE_INACTIVE Space is not assigned to an agent and must be claimed
11 EGO_TASK_SPACE_NOT_FOUND Requested Task Space was not found
12 EGO_TASK_SPACE_NOT_SELECTED useTaskSpace() has not selected a Task Space
13 EGO_TASK_SPACE_UNAVAILABLE Task Space is temporarily unavailable
14 EGO_TASK_SPACE_USER_IN_CONTROL User currently controls the Task Space
15 EGO_WEB_CONTENTS_UNAVAILABLE Active page contents are unavailable