How to Switch to an Agent-Owned Task Space in ego-lite: A Complete Developer Guide

In ego-lite, you can only switch to task spaces where the ownership field is set to "agent" or "agentDelegatedToUser" using the switchTaskSpace helper, which validates permissions before invoking the native ego.useTaskSpace bridge.

The ego-lite framework (maintained in the citrolabs/ego-lite repository) provides isolated browsing contexts called task spaces that enforce strict security boundaries between agent and user control. To programmatically activate a specific browsing context for your automation scripts, you must understand the ownership validation rules that prevent unauthorized context switches.

What is an Agent-Owned Task Space?

In ego-lite, a task space represents an isolated browsing context with a defined ownership model. The ownership property determines who controls the space:

• "agent" – Fully controlled by the automation agent
• "agentDelegatedToUser" – Delegated to user but switchable by agent
• "user" – User-controlled; the agent cannot switch to these spaces

Only spaces with agent-related ownership flags can be activated via the SDK. Attempting to switch to a user-owned space triggers a permission error.

Prerequisites for Switching Task Spaces

Before calling switchTaskSpace, ensure you have:

1. Imported the function from the ego-browser package (exported in src/index.ts lines 120–130)
2. Confirmed the native runtime is available via globalThis.ego.useTaskSpace
3. Identified the target space name or numeric ID

How to Switch to an Agent-Owned Task Space

The switchTaskSpace function in src/helpers.ts (lines 52–63) performs a four-step validation process before activating a task space.

Step 1: Validate the Runtime Environment

The function first checks that the native ego.useTaskSpace bridge method exists in the global runtime. Without this native binding, task space isolation cannot be enforced at the browser level.

Step 2: Locate the Target Task Space

The helper calls findTaskSpace (implemented in src/helpers.ts lines 440–460) to resolve your supplied identifier—either a string name or numeric ID—into a full task space descriptor object containing the ownership field.

Step 3: Verify Ownership Permissions

Using the isAgentOwned predicate (defined in src/helpers.ts lines 35–45), the function validates that the space's ownership value is either "agent" or "agentDelegatedToUser". If the space is user-owned, the function throws: "switchTaskSpace requires an agent-owned task space, got ownership ...".

Step 4: Activate the Space

Once validated, selectTaskSpace invokes the native ego.useTaskSpace bridge, making the target space active for the current script execution context.

Code Examples for switchTaskSpace

Basic Switch by Name

Switch to a known agent-owned space using its string identifier:

// Assuming the ego runtime is already injected (globalThis.ego)
import { switchTaskSpace } from 'ego-browser'

await switchTaskSpace('my-agent-space')

Switch by Numeric ID

You can also reference task spaces by their internal numeric ID:

await switchTaskSpace(42)   // 42 must refer to an agent-owned space

Handling Permission Errors

Wrap your switch calls to handle cases where the space is not agent-owned:

try {
  await switchTaskSpace('user-space')
} catch (err) {
  console.error('Cannot switch:', err.message)
  // → "switchTaskSpace requires an agent-owned task space, got ownership ..."
}

Complete Workflow Example

Combine listTaskSpaces with ownership checking for robust space management:

import { listTaskSpaces, switchTaskSpace } from 'ego-browser'

async function ensureAgentSpace(name) {
  const spaces = await listTaskSpaces()
  const target = spaces.find(s => s.name === name)

  if (!target) throw new Error(`No task space named ${name}`)
  
  // Explicit ownership check before attempting switch
  if (target.ownership !== 'agent' && target.ownership !== 'agentDelegatedToUser') {
    throw new Error(`Task space ${name} is not agent-owned`)
  }

  await switchTaskSpace(name)   // Now the agent owns the active context
}

Understanding the Ownership Security Model

The ownership validation in src/helpers.ts enforces a critical security boundary. By checking the ownership field before invoking ego.useTaskSpace, ego-lite ensures that:

• Agents cannot hijack user browsing sessions
• Scripts fails fast with descriptive errors when attempting invalid switches
• The agentDelegatedToUser state allows flexible handoff scenarios while maintaining agent oversight

Summary

• Use switchTaskSpace from ego-browser to activate agent-owned browsing contexts.
• Valid ownership values are "agent" or "agentDelegatedToUser"; user-owned spaces trigger errors.
• Implementation files: src/helpers.ts (lines 35–45 for isAgentOwned, lines 52–63 for switchTaskSpace, lines 440–460 for findTaskSpace) and src/index.ts (lines 120–130 for exports).
• Native bridge: The function ultimately calls ego.useTaskSpace after validation.
• Error handling: Always wrap switches in try-catch blocks to handle permission denials gracefully.

Frequently Asked Questions

What error occurs when trying to switch to a user-owned task space?

The function throws a runtime error with the message: "switchTaskSpace requires an agent-owned task space, got ownership ..." followed by the actual ownership value detected. This prevents agents from accessing user-private browsing contexts.

Can I switch to a task space using just the numeric ID?

Yes. The findTaskSpace helper accepts both string names and numeric IDs. Pass the integer directly to switchTaskSpace(id), and the internal resolver will locate the corresponding task space descriptor before performing the ownership check.

What is the difference between "agent" and "agentDelegatedToUser" ownership?

Both values allow the agent to switch to the space, but "agentDelegatedToUser" indicates the space was originally agent-created but temporarily delegated to user control. The agent retains the right to reclaim it, whereas pure "user" spaces are permanently restricted from agent access.

Where is switchTaskSpace exported in the SDK?

The function is exported from src/index.ts at lines 120–130 as part of the public API, making it available via import { switchTaskSpace } from 'ego-browser'.

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