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

> Learn to use ego-lite task space handoff and takeover APIs. Transfer and reclaim browser control programmatically with handOffTaskSpace() and takeOverTaskSpace() helpers.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
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:

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

```

Hand off a specific space with ownership checking:

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

```

Immediately take over a specific space:

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

```

Complete workflow with user interaction period:

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)** – Contains `handOffTaskSpace`, `takeOverTaskSpace`, `findTaskSpace`, `selectTaskSpace`, and `waitForAgentControl` implementations.
- **[`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts)** – Manages the singleton runtime state accessed by the helper functions.
- **[`package/ego-browser/src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.