What Are Task Spaces in ego-lite? Isolated Browsing Contexts for AI Agents

Task spaces in ego-lite are isolated browsing contexts that allow AI agents to manage separate sets of tabs, navigation history, and DOM snapshots without interference between concurrent tasks.

Task spaces form the foundational isolation mechanism in the ego-lite browser automation framework. As implemented in the citrolabs/ego-lite repository, these abstractions enable AI agents to juggle multiple independent workflows—such as research, data extraction, and form submission—within a single browser instance while maintaining strict separation of state.

Core Architecture of Task Spaces in ego-lite

Each task space owns a dedicated set of browser resources including tabs, navigation history, and captured DOM snapshots. The runtime injects a taskSpaces façade into every agent script through helperContext() (defined in package/ego-browser/src/helpers.ts), bundling all operations needed to manage these isolated contexts.

Internally, the system maps each task space to a numeric ID (taskSpaceNumericId) that corresponds to a Chrome DevTools Protocol (CDP) session. This mapping persists in the runtime's shared state (src/state.ts) and refreshes automatically whenever a snapshot occurs.

Creating and Accessing Task Spaces

The useOrCreate Method

The primary entry point for working with task spaces is taskSpaces.useOrCreate(nameOrId). Located at lines ~885-892 of package/ego-browser/src/helpers.ts, this method returns an existing space when referenced by numeric ID or string name, or instantiates a new one if no match exists.

const research = await taskSpaces.useOrCreate('research');
// Returns: { id: 3, name: 'research', owner: 'agent' }

Ownership Models

Task spaces operate under distinct ownership rules that determine control permissions:

• Agent-owned: The AI can directly switch, modify, or complete the space.
• User-owned: Control belongs to a human operator, restricting direct agent manipulation.

Ownership transfers occur through three dedicated methods: claim for initial acquisition, handOff for transferring agent ownership to a user, and takeOver for reclaiming control from a user.

Managing Task Space Lifecycles

Switching Contexts

To activate a specific browsing context, call taskSpaces.switch(idOrName). This method, implemented via switchTaskSpace at line ~249 of src/helpers.ts, redirects subsequent helper calls—such as tab creation or page interactions—to operate within the selected space.

await taskSpaces.switch(research.id);
await browser.openOrReuseTab('https://example.com');

Control Handoff and Synchronization

For human-in-the-loop workflows, taskSpaces.handOff(id) transfers an agent-owned space to user control, while taskSpaces.takeOver(id) performs the reverse operation. When waiting for control restoration, taskSpaces.waitForAgentControl(idOrName, options) blocks execution until the agent regains authority, polling the underlying CDP session status (defined at line ~300 of src/helpers.ts).

Completion and Cleanup

Terminate a task space using taskSpaces.complete(idOrName, { keep }). The concrete implementation, completeTaskSpace at line ~292 of src/helpers.ts, accepts an optional keep parameter that preserves tabs for future reference when set to true.

// Close the space but retain tabs
await taskSpaces.complete(research.id, { keep: true });

Technical Implementation Details

The public API signatures for these operations are declared in package/ego-browser/src/format.ts (lines ~650-770), which also defines the example usage strings displayed by the help() function. Underlying transport and session attachment logic resides in src/browser-runtime.ts, managing CDP connections and automatic re-snapshotting when script references encounter empty mappings.

When a script references a task space with an empty map entry, the runtime silently triggers a re-snapshot to rebuild the ID-to-session correlation, ensuring references remain valid across multiple script execution rounds.

Complete Working Example

The following demonstrates a full workflow using task spaces in ego-lite:

// 1️⃣ Create or reuse a task space called "research"
const research = await taskSpaces.useOrCreate('research');

// 2️⃣ Switch to that space so further calls operate within it
await taskSpaces.switch(research.id);

// 3️⃣ Open a tab inside the active space
await browser.openOrReuseTab('https://news.ycombinator.com');

// 4️⃣ Perform actions on the page (the `page` façade works inside the chosen space)
await page.waitForLoadState('networkidle');
const titles = await page.locator('a.storylink').allTextContents();
console.log(titles);

// 5️⃣ Hand the space off to a human user (e.g., for manual inspection)
await taskSpaces.handOff(research.id);

// … later the agent can reclaim it …
await taskSpaces.takeOver(research.id);
await taskSpaces.waitForAgentControl(research.id);

// 6️⃣ When the job is finished, close the space but keep the tab for later reference
await taskSpaces.complete(research.id, { keep: true });

Summary

• Task spaces provide isolated browsing contexts within ego-lite, separating tabs, history, and DOM state between concurrent AI workflows.
• The taskSpaces façade exposes methods including useOrCreate(), switch(), handOff(), and complete() via helperContext() injection.
• Ownership states (agent vs. user) enforce strict control permissions, with takeOver() and waitForAgentControl() enabling collaborative human-in-the-loop automation.
• CDP session mapping occurs through numeric IDs managed in src/state.ts, with automatic re-snapshotting ensuring reference stability across script executions.

Frequently Asked Questions

How do task spaces differ from standard browser contexts in ego-lite?

Standard browser contexts represent low-level CDP sessions, while task spaces add a higher-level abstraction that bundles tab management, ownership tracking, and lifecycle hooks specifically designed for AI agent workflows. The façade methods in src/helpers.ts handle the complexity of mapping friendly names to underlying numeric IDs (taskSpaceNumericId).

Can multiple agents control the same task space simultaneously?

No. Task spaces enforce exclusive ownership at any given moment—either agent-owned or user-owned. While one agent worksheet is executing within a space, other scripts cannot interfere. Control transfers require explicit handOff or takeOver operations to prevent race conditions.

What happens to tabs when I complete a task space?

By default, taskSpaces.complete() closes all associated tabs and terminates the CDP session. However, passing { keep: true } in the options object preserves the tabs for later reference, allowing workflows to resume investigation without losing navigation state.

Where are task space mappings stored during script execution?

The runtime maintains task space metadata—including the mapping between numeric IDs and CDP sessions—in the shared state module (src/state.ts). This state persists across script rounds within a single browser runtime instance, with automatic re-snapshotting triggered whenever a script references a space with stale or empty mappings.

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