How to Claim Ownership of a User-Owned Task Space in ego-lite

To claim ownership of a user-owned task space in ego-lite, call taskSpaces.claim(nameOrId) or the low-level ego.claimTaskSpace(id, name?) to transfer control from the user to the agent, enabling automated interaction within that isolated browsing context.

In the citrolabs/ego-lite browser automation framework, a task space represents an isolated browsing context that operates under discrete ownership. When a space is user-owned, the agent cannot execute actions within it until it explicitly claims ownership through specific CDP (Chrome DevTools Protocol) calls or helper methods. Understanding how to claim ownership of a user-owned task space in ego-lite is essential for agents that need to interact with pages initiated or controlled by human users.

Understanding Task Space Ownership Models

ego-lite distinguishes between two ownership states for task spaces:

• Agent-owned spaces: Created and controlled automatically by the automation framework
• User-owned spaces: Initiated by human users or external processes, requiring explicit transfer before agent interaction

According to the source code in package/ego-browser/src/format.ts (lines 701-713), the runtime API exposes ownership transfer methods through the taskSpaces namespace, while low-level CDP interactions are handled directly on the ego runtime object.

Core Methods for Claiming Ownership

The library provides multiple abstraction levels for claiming task spaces, from low-level CDP calls to high-level helper functions.

Low-Level CDP Calls

For direct control without helper abstractions, the ego runtime exposes two critical methods:

• ego.claimTaskSpace(id, name?) – Transfers ownership of the task space with numeric ID id to the agent, with an optional name parameter for identification
• ego.takeOverTaskSpace() – Allows the agent to become the default owner of a newly created space immediately upon creation

These methods are implemented as raw CDP calls to the underlying browser instance and form the foundation of the ownership transfer mechanism.

High-Level Helper API

The public helper claimTaskSpace(nameOrId) in package/ego-browser/src/helpers.ts (lines 224-236) provides the most common interface for ownership transfer. This helper:

1. Resolves the supplied identifier (numeric ID or string name) to a task-space object
2. Invokes ego.claimTaskSpace with the resolved parameters
3. Automatically selects the space for subsequent actions

As documented in the runtime API generation logic, this corresponds to the taskSpaces.claim entry point.

Taking Over Newly Created Spaces

For spaces freshly created by users, the taskSpaces.takeOver(id?) method offers a streamlined approach. When called without arguments, it claims the most recently created user-owned space, making it ideal for reactive automation scenarios where users initiate actions that agents must immediately continue.

Step-by-Step Implementation Guide

Follow this workflow to claim and activate a user-owned task space:

1. Enumerate available spaces (optional) to identify the target ID or name of the user-owned space
2. Invoke the claim method using either taskSpaces.claim(identifier) or the direct helper claimTaskSpace(identifier)
3. Verify ownership transfer – the helper automatically switches to the claimed space, but verify the returned space object confirms successful transfer

If working with a newly created space, substitute step 2 with taskSpaces.takeOver() to claim the most recent addition.

Practical Code Examples

Claim by Numeric ID

// Transfer ownership using the high-level API
const space = await taskSpaces.claim(3);
console.log('Claimed space:', space);
// Agent can now navigate, click, and interact within this space

Claim by String Name

// Resolve name to ID internally before claiming
const space = await taskSpaces.claim('research-task');
console.log('Claimed space:', space);

Direct Helper Invocation

// Equivalent to taskSpaces.claim(7) but imported directly from helpers
import { claimTaskSpace } from 'ego-lite/helpers';

await claimTaskSpace('7');
// Space 7 is now active and owned by the agent

Taking Over Newly Created Spaces

// Become owner of the most recent user-created space
await taskSpaces.takeOver();
// Immediate interaction possible without knowing the specific ID

Error Handling and Edge Cases

The package/ego-browser/src/ego-errors.ts file (lines 53-61) implements error wrapping for failed ownership transfers. When ego.claimTaskSpace encounters invalid IDs, already-claimed spaces, or permission conflicts, the runtime generates structured error objects that include:

• The original CDP error context
• The attempted space identifier
• Suggested resolution steps

Always wrap claim attempts in try-catch blocks when dealing with dynamic space IDs to handle scenarios where the user has already released the space or the ID has changed.

Summary

• User-owned task spaces require explicit ownership transfer before agent interaction in ego-lite
• Two abstraction levels exist: low-level CDP calls (ego.claimTaskSpace, ego.takeOverTaskSpace) and high-level helpers (claimTaskSpace, taskSpaces.claim)
• Automatic space selection occurs when using the helper API, immediately enabling nav, click, and other browsing actions
• Source implementation resides in package/ego-browser/src/helpers.ts (lines 224-236) with API documentation in package/ego-browser/src/format.ts (lines 701-713)
• Error handling is centralized in package/ego-browser/src/ego-errors.ts for debugging ownership conflicts

Frequently Asked Questions

What happens if I try to interact with a user-owned space without claiming it first?

The agent will receive a permission error indicating the space is under user control. According to the error handling implementation in package/ego-browser/src/ego-errors.ts, the runtime throws a controlled exception preventing any nav, click, or evaluation operations until claimTaskSpace or takeOver successfully transfers ownership.

Can I use a space name instead of a numeric ID when claiming ownership?

Yes. The claimTaskSpace(nameOrId) helper in package/ego-browser/src/helpers.ts accepts either format. When a string name is provided, the helper resolves it to the internal numeric ID before calling ego.claimTaskSpace, making the API flexible for human-readable space management.

What is the difference between taskSpaces.claim and taskSpaces.takeOver?

taskSpaces.claim(id) requires you to specify the exact space identifier (name or ID) you want to own, regardless of when it was created. taskSpaces.takeOver(id?) specifically targets newly created spaces—when called without arguments, it claims the most recent user-owned space, making it ideal for reactive workflows where the user just opened a new tab or context.

How do I verify that ownership transfer was successful?

The helper methods return a space object containing the confirmed ID and ownership state. Check the returned object’s properties to verify the transfer. If the promise resolves without error, the space is immediately active and selected for subsequent operations, as implemented in the resolution logic at lines 224-236 of the helpers module.

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