How to Claim a User-Owned Task Space in Ego-Lite: Complete SDK Guide

To claim a user-owned task space in Ego-Lite, invoke the claimTaskSpace(nameOrId) helper, which resolves the space identifier, calls ego.claimTaskSpace() to transfer ownership from the user to the agent, and activates the context via ego.useTaskSpace().

In the Ego-Lite browser automation framework, task spaces represent isolated execution contexts that can be owned by either the user or the agent. When a task space is user-owned, the runtime restricts agent operations until ownership is explicitly transferred through the claiming mechanism.

Understanding Task Space Ownership

Ego-Lite supports two distinct ownership models for task spaces. When a space is agent-owned, the agent has immediate operational access. However, when a task space is user-owned, the agent cannot perform actions until it claims the space. This security boundary ensures agents cannot interfere with user-controlled contexts without explicit authorization.

The ownership transfer mechanism is exposed through the public helper function claimTaskSpace(), implemented in package/ego-browser/src/helpers.ts (lines 18-27) and exported as part of the official SDK surface in package/ego-browser/src/index.ts (lines 24-33).

The claimTaskSpace Implementation

According to the Ego-Lite source code, the claiming process follows a specific four-step sequence to safely transfer control:

Step 1: Resolve the Task Space

The helper accepts either a string name or numeric ID as nameOrId. It first validates the input by calling findTaskSpace(nameOrId), which looks up the space and returns its metadata.

Step 2: Transfer Ownership via the Runtime

After resolution, the function invokes the runtime method ego.claimTaskSpace(id, name). This internal call performs the actual ownership transfer from the user to the agent, updating the runtime state to reflect the new ownership model.

Step 3: Select the Claimed Space

Immediately following the ownership transfer, the helper calls ego.useTaskSpace to select the newly claimed space as the active context for the current invocation. This ensures subsequent browser automation commands operate within the correct isolated environment.

Step 4: Return Normalized Metadata

Finally, the function returns the normalized task-space object, allowing the caller to access metadata and confirm successful claiming.

Code Examples: Claiming Task Spaces

Claim a user-owned task space by its string name:

// Claim a user-owned task space by name
const space = await claimTaskSpace('my-user-space');
console.log('Claimed task space:', space);
// The agent now has full control over the space

Claim using a numeric identifier:

// Claim by numeric id
const space2 = await claimTaskSpace(42);
console.log('Claimed by id:', space2);

Complete Agent Workflow Integration

In production scenarios, claiming a task space typically follows this integrated pattern:

// 1. List available task spaces (optional discovery)
const spaces = await listTaskSpaces();
console.log('Available task spaces:', spaces);

// 2. Claim a specific user-owned space
await claimTaskSpace('support-ticket-123');

// 3. Execute automation actions within the claimed space
await navigate('https://example.com');
await click('@login-button');

// 4. Complete the task and optionally preserve the space
await completeTaskSpace('support-ticket-123', { keep: true });

Summary

• User-owned spaces require explicit claiming before agents can operate on them, enforcing security boundaries in the Ego-Lite runtime.
• The claimTaskSpace(nameOrId) helper handles the complete lifecycle: resolution, ownership transfer via ego.claimTaskSpace(), and activation via ego.useTaskSpace().
• Implementation resides in package/ego-browser/src/helpers.ts (lines 18-27) and is exported through package/ego-browser/src/index.ts (lines 24-33) as part of the official SDK.
• Supports both string names and numeric IDs for flexible space identification.
• Returns normalized metadata to confirm successful ownership transfer.

Frequently Asked Questions

What happens if I try to operate on a user-owned task space without claiming it first?

The Ego-Lite runtime will block agent operations and throw a permission error. The ego.claimTaskSpace() runtime method must complete successfully before the agent gains execution privileges within that context.

Can I claim a task space using either its name or its ID?

Yes, the claimTaskSpace(nameOrId) helper accepts either a string name (e.g., 'support-ticket-123') or a numeric ID (e.g., 42). The function internally calls findTaskSpace() to resolve the identifier before proceeding with the ownership transfer.

What is the difference between claimTaskSpace() and useTaskSpace()?

claimTaskSpace() is a high-level helper function that performs ownership transfer from user to agent, while useTaskSpace() is a lower-level runtime method that simply selects an already-claimed space as the active context. The helper function internally calls both ego.claimTaskSpace() and ego.useTaskSpace() to provide a complete claiming workflow.

How do I release a task space back to the user after claiming it?

Use the completeTaskSpace(nameOrId, options) helper with the keep parameter set according to your persistence needs. Setting { keep: true } preserves the space state while returning ownership to the user, whereas omitting or setting keep: false closes the space entirely.

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