What is a Task Space in ego-lite and How Does It Provide Isolation?

A Task Space in ego-lite is an isolated browsing context that maintains its own tabs, navigation history, and CDP session while inheriting the user's login state from the underlying browser process.

Task Spaces serve as the fundamental sandboxing mechanism in the citrolabs/ego-lite browser automation framework. According to the project's architecture, each Task Space operates as a logical container within the ego-browser runtime, giving agents a dedicated environment to execute web tasks without interfering with other operations or the user's main browsing session.

Core Architecture of Task Spaces

The Task Space model is implemented as a strict isolation layer between the agent runtime and the browser process. In src/state.ts, the system maintains a singleton that stores current task-space mappings and CDP session caches, ensuring that each space maintains independent DOM access and snapshot capabilities.

Isolated Browsing Contexts

Every Task Space receives its own private collection of tabs and navigation history. As documented in AGENTS.md, this means actions performed in one space—such as DOM manipulation, navigation, or screenshot capture—cannot affect another space's state. The isolation is enforced at the browser runtime level, with each space maintaining a separate Chrome DevTools Protocol (CDP) session that prevents cross-task contamination.

Login State Inheritance

Unlike traditional browser profiles that enforce complete cookie isolation, Task Spaces intentionally inherit the user's authenticated sessions. Because the space lives inside the same browser process as the user's main window, it automatically shares cookies, localStorage, and other authentication data. This design, noted in CONTRIBUTING.md, allows agents to leverage existing logins while keeping their operational context sandboxed.

Task Space Ownership and Control Flow

The ownership model determines which entity—agent or human user—can issue commands to a given space. The src/helpers.ts file defines the taskSpaces facade that exposes methods enforcing these ownership semantics.

Agent vs User Ownership

Each Task Space can be owned by either an agent or a user. When an agent creates a space via useOrCreateTaskSpace, it gains exclusive rights to manipulate that space's tabs and execute browser commands. Conversely, user-owned spaces preserve manual browsing state that agents can later claim when automation is required.

Control Hand-off Mechanisms

ego-lite provides explicit functions for transferring control between agents and users:

• handOffTaskSpace — Returns control to the user for manual interaction (e.g., solving CAPTCHAs)
• takeOverTaskSpace — Allows the agent to assume control of a user-owned space
• waitForAgentControl — Blocks execution until the agent regains control rights

These functions are critical for hybrid workflows where certain steps require human judgment before automation resumes.

Working with Task Spaces: Practical Implementation

Because every heredoc execution runs in a fresh Node process, the task-space identifier must be re-attached each round to maintain continuity. The following examples demonstrate the lifecycle management methods defined in src/helpers.ts and documented in src/format.ts.

Creating or Reusing a Task Space

// Attach to existing space or create new one
const task = await taskSpaces.useOrCreate('research-project');
console.log('Working in task space', task.id);

The useOrCreate method checks the current session cache in src/state.ts for an existing agent-owned space with the specified identifier. If none exists, it initializes a new CDP session and returns the numeric id required for subsequent operations.

Claiming User-Authenticated Sessions

// Assume user has manually logged in
await taskSpaces.claim('login-session');
await taskSpaces.takeOver('login-session');

The claim function transfers ownership from user to agent, while takeOver activates agent control without destroying the inherited authentication state stored in the browser's cookie jar.

Switching Between Contexts

// Switch by numeric ID
await taskSpaces.switch(2);

// Switch by registered name
await taskSpaces.switch('email-automation');

The switch method updates the active CDP session pointer in the runtime state, allowing a single agent to manage multiple concurrent workflows without cross-contamination.

Completing Task Execution

// Terminate space and clean up resources
await taskSpaces.complete(task.id, { keep: false });

Setting keep: true preserves the tab set for future sessions, while false tears down the CDP session and releases browser resources back to the pool.

Summary

• Task Spaces provide isolated browsing contexts with private tab sets and CDP sessions while preserving user authentication state.
• The ownership model distinguishes between agent-controlled and user-controlled spaces, enforced through functions like claimTaskSpace and handOffTaskSpace.
• Isolation guarantees prevent DOM and navigation leakage between spaces, making debugging deterministic and workflows safe.
• Statelessness of Node processes requires re-attaching to spaces via useOrCreateTaskSpace on each execution round.
• Core implementation resides in src/helpers.ts (API facade), src/state.ts (session management), and is documented in AGENTS.md and CONTRIBUTING.md.

Frequently Asked Questions

How does a Task Space differ from a standard browser incognito window?

A standard incognito window enforces complete session isolation, including cookie separation. A Task Space deliberately shares the underlying browser's authentication state (cookies, local storage) while isolating only the operational context—tabs, history, and CDP sessions. This allows agents to work with pre-authenticated websites without requiring credential management, while keeping their automation steps sandboxed from other tasks.

Can multiple agents share the same Task Space simultaneously?

No. The ownership model in src/helpers.ts enforces exclusive access. A space can be owned by either one agent or the user at any given time. While multiple agents can switch between different spaces using switchTaskSpace, only the current owner can issue browser commands. The waitForAgentControl function provides a blocking mechanism to coordinate sequential access when agents need to hand off work.

What happens to Task Space data when the Node process restarts?

Task Spaces are stateless relative to the Node process. Each heredoc execution spawns a fresh process, so the agent must re-attach to existing spaces using useOrCreateTaskSpace with the same identifier. The space persists in the browser runtime (maintained by the ego-browser process), but the Node-side reference must be re-established via the taskSpaces API on every run.

Why does Task Space isolation matter for agent debugging?

Because each space maintains independent CDP sessions and tab lists, actions in one space cannot corrupt the DOM or navigation state of another. This eliminates non-deterministic cross-contamination where one workflow's JavaScript execution or page navigation might interfere with another. The explicit isolation makes reproduction of bugs deterministic—developers can inspect a specific Task Space's snapshot without interference from concurrent automation tasks.

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