Repository navigation
Ego Native API Reference
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.
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.
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.
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.
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.
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.
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.
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.
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.
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); // 7Invalid arguments throw TypeError.
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.
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.
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.
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.
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.
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.
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.
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 |
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.
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.
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.
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.
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 |
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
|
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 |