How to Use Task Space Handoff and Takeover APIs in ego-lite

The task space handoff and takeover APIs in ego-lite enable agents to transfer browser control to users and reclaim it programmatically via the handOffTaskSpace() and takeOverTaskSpace() helpers in package/ego-browser/src/helpers.ts.

The ego-lite repository provides a task-space subsystem that isolates browsing contexts, allowing automated agents and human users to operate on separate workflows without interference. Understanding how to use task space handoff and takeover APIs is essential for building interactive automation that gracefully transitions control between scripts and operators. These lightweight JavaScript helpers delegate heavy lifting to the underlying Chrome DevTools Protocol (CDP) runtime while exposing a clean, promise-based interface.

Task Space Handoff and Takeover API Reference

The task-space subsystem exposes two primary public helpers that manage ownership transitions between agent and user contexts:

handOffTaskSpace([nameOrId]) returns control of the current task space to the user and hides the agent overlay. When invoked on a space already owned by the user, it resolves to { done: false, skipped: "user-owned" } to prevent redundant operations. This function is implemented starting at line 26 of package/ego-browser/src/helpers.ts.

takeOverTaskSpace([nameOrId]) re-acquires control of a task space for the agent, restoring the overlay visibility. This counterpart to the handoff function is located at line 47 of package/ego-browser/src/helpers.ts.

Both methods accept an optional nameOrId parameter to target specific task spaces by identifier or name, defaulting to the current active space when omitted.

Implementation Workflow and Architecture

When you invoke these task space handoff and takeover APIs, the helpers execute a consistent four-step workflow defined in the source:

1. Validate the ego runtime – Each helper verifies that globalThis.ego exists and exposes the corresponding native method (ego.handOffTaskSpace or ego.takeOverTaskSpace).

2. Resolve the target space – If a nameOrId argument is provided, the helper calls findTaskSpace() to locate the space and switches to it via selectTaskSpace() or selectTaskSpaceIfProvided().

3. Execute the native call – The operation is performed by the runtime's CDP-based implementation after passing through assertNoEgoError() to translate runtime-specific errors into standard JavaScript exceptions.

4. Return a promise – handOffTaskSpace returns an object indicating completion status, while takeOverTaskSpace resolves when the agent successfully regains control.

Ownership Validation and Error Handling

Internally, task spaces are represented as objects containing id, name, and an ownership flag set to either "agent" or "user". The handOffTaskSpace function specifically checks this ownership flag before proceeding, ensuring agents never attempt to hand off spaces they do not already control. This design prevents invalid state transitions and redundant CDP calls.

Polling for Control Restoration

After handing off control, scripts can wait for the user to finish without blocking the main thread by using waitForAgentControl(). This read-only utility polls ego.snapshot until the agent regains ownership, respecting configurable intervals and timeout parameters:

await waitForAgentControl('my-report-space', { timeout: 300 });

Code Examples

The following examples demonstrate common patterns for using task space handoff and takeover APIs in production scripts.

Hand off the current task space implicitly:

await handOffTaskSpace();
// => { done: true }

Hand off a specific space with ownership checking:

const result = await handOffTaskSpace('my-report-space');
if (result.skipped) {
  console.log('Space already under user control');
}

Immediately take over a specific space:

await takeOverTaskSpace('my-report-space');

Complete workflow with user interaction period:

await handOffTaskSpace('my-report-space');
await waitForAgentControl('my-report-space', { timeout: 300 }); // wait up to 5 min
await takeOverTaskSpace('my-report-space');

Key Source Files in ego-lite

Understanding the architecture requires familiarity with these specific files:

• package/ego-browser/src/helpers.ts – Contains handOffTaskSpace, takeOverTaskSpace, findTaskSpace, selectTaskSpace, and waitForAgentControl implementations.
• package/ego-browser/src/state.ts – Manages the singleton runtime state accessed by the helper functions.
• package/ego-browser/src/driver/nav.ts – Implements the low-level ego methods that perform CDP session management and UI overlay toggling.

Summary

• Task space handoff and takeover APIs provide programmatic control transitions between agents and users in ego-lite.
• Use handOffTaskSpace([nameOrId]) to surrender control and takeOverTaskSpace([nameOrId]) to reclaim it.
• Both helpers reside in package/ego-browser/src/helpers.ts and validate the ego runtime before executing CDP commands.
• The APIs prevent redundant handoffs by checking ownership flags, returning { done: false, skipped: "user-owned" } when appropriate.
• waitForAgentControl() enables non-blocking polling for control restoration after handoff.

Frequently Asked Questions

What happens if I call handOffTaskSpace on a space the user already owns?

The helper detects the "user" ownership flag and returns { done: false, skipped: "user-owned" } without invoking the native runtime method. This prevents unnecessary CDP calls and maintains idempotent behavior.

How can my script wait for the user to finish working before taking over?

Use the waitForAgentControl() utility from package/ego-browser/src/helpers.ts. This function polls ego.snapshot until ownership returns to "agent", accepting a timeout option measured in seconds to prevent indefinite hanging.

Can I target a specific task space by name instead of the current one?

Yes. Both handOffTaskSpace() and takeOverTaskSpace() accept an optional nameOrId string parameter. When provided, the helpers internally call findTaskSpace() and selectTaskSpace() to switch contexts before executing the ownership transfer.

Where does the actual CDP implementation live?

The high-level helpers delegate to methods on the global ego object, which are implemented in package/ego-browser/src/driver/nav.ts. This separation keeps the JavaScript API layer testable while the runtime handles session management and UI overlay toggling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}