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(id) or the low-level ego.claimTaskSpace(id, name?) to transfer ownership from the user to the agent, enabling automated interaction within that isolated browsing context.

In the ego-lite browser automation library, task spaces represent isolated browsing contexts that can be owned by either the agent or the user. When a space is user-owned, the agent cannot execute actions like navigation or clicking until it explicitly claims ownership. This guide explains the exact methods and source implementations for transferring control.

Understanding Task Space Ownership Models

ego-lite implements a strict ownership model to prevent unauthorized automation in user-controlled contexts. A user-owned task space is created when a user manually opens a new tab or window, while an agent-owned space is spawned by your automation script. The library exposes specific Chrome DevTools Protocol (CDP) calls to manage these transitions safely.

According to the source code in citrolabs/ego-lite, the runtime provides two low-level CDP methods on the ego object:

• ego.claimTaskSpace(id, name?) – Transfers ownership of the task space with numeric ID id to the agent
• ego.takeOverTaskSpace() – Allows the agent to become the default owner of a newly created space

These primitives ensure that automation only occurs in explicitly claimed contexts.

Methods to Claim a User-Owned Task Space

Using the High-Level Helper (Recommended)

The most reliable approach uses the public helper claimTaskSpace(nameOrId) defined in package/ego-browser/src/helpers.ts at lines 224–236. This function accepts either a numeric ID or a string name, resolves it to a task-space object, calls ego.claimTaskSpace, and automatically selects the space for subsequent actions.

// Claim by numeric ID
const space = await taskSpaces.claim(3);
console.log('Claimed space:', space);

// Claim by string name
const space = await taskSpaces.claim('research-task');

Using Low-Level CDP Calls

For advanced use cases requiring direct protocol access, invoke ego.claimTaskSpace directly. This method requires the numeric ID and optionally accepts a name parameter for logging purposes.

// Direct CDP call
await ego.claimTaskSpace(7, 'automation-space');

Taking Over Newly Created Spaces

When a user creates a space and you need immediate control before any interaction occurs, use taskSpaces.takeOver(id?). Without arguments, it claims the most recently created space. With a specific ID, it targets that exact context.

// Take over the most recent user-created space
await taskSpaces.takeOver();

// Take over a specific space by ID
await taskSpaces.takeOver(5);

Step-by-Step Implementation Workflow

Follow this sequence to safely claim and operate within a user-owned task space:

1. List available task spaces (optional) to identify the target ID or name of the user-owned space
2. Call taskSpaces.claim with the identifier, or use ego.claimTaskSpace for low-level control
3. Verify ownership transfer – the helper automatically selects the space, but confirm space.owned === true in the returned object
4. Execute automation actions – use standard helpers like nav, click, or type within the claimed context

Complete Code Examples

The following patterns demonstrate practical implementations based on the runtime API documentation in package/ego-browser/src/format.ts (lines 701–713):

// Example 1: Claim by numeric ID and auto-select
const space = await taskSpaces.claim(3);
console.log('Ownership transferred:', space);

// Example 2: Claim by descriptive name
const space = await taskSpaces.claim('research-task');
console.log('Resolved and claimed:', space);

// Example 3: Direct helper import for standalone usage
import { claimTaskSpace } from 'ego-lite/helpers';
await claimTaskSpace('7');  // Equivalent to taskSpaces.claim(7)

// Example 4: Preemptive takeover of new user space
await taskSpaces.takeOver();  // Claims most recent space before user interaction

Error Handling and Edge Cases

Ownership claims may fail if the space is already agent-owned, the ID does not exist, or the browser context was destroyed. The library wraps CDP errors in user-friendly messages as implemented in package/ego-browser/src/ego-errors.ts (lines 53–61).

try {
  await taskSpaces.claim(999);  // Non-existent ID
} catch (error) {
  console.error('Claim failed:', error.message);
  // Handles "Task space not found" or "Already owned" scenarios
}

Always verify the returned task space object contains id and url properties before proceeding with navigation to ensure the claim succeeded.

Summary

• Task spaces in ego-lite are isolated browsing contexts with strict ownership rules separating user and agent control
• Use taskSpaces.claim(nameOrId) for the simplest resolution and ownership transfer via the helper in src/helpers.ts
• Call ego.claimTaskSpace(id, name?) directly when you need low-level CDP access without helper abstractions
• Apply taskSpaces.takeOver() to claim newly created user spaces before any manual interaction occurs
• Check error handling in src/ego-errors.ts for robust automation that handles invalid IDs or ownership conflicts

Frequently Asked Questions

Can I claim a task space by its URL instead of ID or name?

No, ego-lite requires either the numeric task space ID or the registered string name to claim ownership. The claimTaskSpace helper in src/helpers.ts only resolves these two identifier types. You must first list available spaces to map a URL to its corresponding ID.

What happens if I try to claim a space already owned by the agent?

The ego.claimTaskSpace CDP call will return successfully without error, as the space is already under agent control. However, the helper functions in src/helpers.ts may skip redundant selection steps. Check the returned space object's properties to confirm the current state.

Is there a way to claim ownership automatically when a user creates a new tab?

Yes, use taskSpaces.takeOver() immediately after detecting a new space creation. This method, documented in src/format.ts, claims the most recent task space without requiring you to know its ID beforehand. Implement this in an event listener for new tab creation to automate the handoff.

Why does my automation fail with "Cannot interact with user-owned space" even after claiming?

This error occurs when the claim operation completed but the space selection did not persist. The taskSpaces.claim helper should auto-select the space, but if using low-level ego.claimTaskSpace directly, you must manually call the selection method afterward. Verify your context by checking ego.currentTaskSpace after claiming.

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