How Task Spaces Isolate Agent and User Browsing Contexts in Ego‑Lite

Task spaces in ego‑lite create lightweight, independent Chrome DevTools Protocol (CDP) sessions that separate agent automation from manual user browsing through isolated navigation states, cookie stores, and element reference maps.

The citrolabs/ego-lite repository implements a sophisticated browser isolation mechanism that allows a single Chrome instance to maintain completely separate contexts for automated agents and human users. Unlike traditional automation frameworks that monopolize the browser window, ego‑lite uses task spaces to ensure agent actions never contaminate user tabs while enabling controlled hand‑offs between automation and manual control.

Architecture of Task Space Isolation

Independent CDP Sessions

Each task space maintains its own CDP session created on‑demand by the runtime at package/ego-browser/src/browser-runtime.ts. These sessions encapsulate:

• Navigation state – separate histories and current URLs per space
• Cookie stores – isolated cookie jars preventing cross‑site leakage
• Storage – independent localStorage and sessionStorage namespaces
• DOM snapshots – distinct page representations for automation

Because each space operates over a dedicated CDP session, network requests and JavaScript execution in one task space remain invisible to others, even when running concurrently within the same browser process.

Ownership Model and Context Boundaries

Task spaces enforce a strict ownership model that designates every space as either agent‑owned or user‑owned. The runtime prevents accidental cross‑context operations:

• Agent‑owned spaces are created exclusively for automation via taskSpaces.useOrCreate()
• User‑owned spaces represent tabs opened by human users
• Claim operations – The taskSpaces.claim() function (defined in package/ego-browser/src/helpers.ts) transfers ownership from user to agent only after explicit invocation

This boundary ensures that an automated agent cannot accidentally click elements or extract data from a user’s personal banking tab, while still allowing intentional collaboration through controlled hand‑offs.

Technical Implementation in the Source Code

The Task Space Facade API

The primary interface for managing isolation resides in package/ego-browser/src/helpers.ts (lines 182–249). This facade exposes methods that wrap the underlying ego.useTaskSpace implementation:

• taskSpaces.useOrCreate(nameOrId) – Reuses an existing agent‑owned space or initializes a new CDP session with isolated state
• taskSpaces.claim(nameOrId) – Transfers ownership of a user‑owned space to the agent after verification
• taskSpaces.switch(nameOrId) – Activates the target space, attaching its CDP session and rebuilding the reference map
• taskSpaces.handOff(nameOrId) / takeOver(nameOrId) – Bidirectional ownership transfer between agent and user
• taskSpaces.complete(nameOrId, { keep }) – Destroys the space and optionally closes the underlying tab

According to the source code at lines 182–249, these methods internally signal the ego runtime to swap sessions, ensuring complete sandboxing of page state during transitions.

Reference Map Isolation

Element references in ego‑lite use the @N notation (e.g., @1, @2) managed by package/ego-browser/src/ref-map.ts and package/ego-browser/src/ref-state.ts. The system maintains per‑space ref maps that are:

1. Built fresh when activating a task space via taskSpaces.switch()
2. Destroyed when leaving the space
3. Never shared between spaces

This guarantees that stale element references from a user’s shopping cart cannot be reused by an agent operating in a different task space, preventing dangerous context confusion during automation sequences.

Documentation and Type Signatures

The API contracts and usage examples are formally documented in package/ego-browser/src/format.ts (lines 653–781). This file defines the human‑readable help text returned by the help() function, reinforcing the isolation semantics for developers implementing agent workflows.

Working with Task Spaces in Practice

Create a dedicated research environment that remains isolated from user tabs:

// Create or reuse an agent-owned task space
const research = await taskSpaces.useOrCreate('research-task');

// Navigate and interact within the isolated context
await nav.goto('https://example.com');
await click('a[href="login"]');
await waitForNavigation();

// Hand control to the user for manual review
await taskSpaces.handOff(research.id);

// Later reclaim the space for automated data extraction
await taskSpaces.takeOver(research.id);
await nav.reload();
await extract.data();

// Clean up the isolated session
await taskSpaces.complete(research.id, { keep: false });

Safely operate on a user‑owned tab without polluting other contexts:

// Claim ownership before automation
const userTab = await taskSpaces.claim('123');
await taskSpaces.switch(userTab.id);

// Agent actions execute in isolated CDP session
await nav.goto('https://secure.example.com');
await fill('input#username', 'agent_user');
await click('button#submit');

// Element references @1, @2 only valid in this space
const buttonRef = await ref('@1');

Summary

• Task spaces provide lightweight isolation by binding separate CDP sessions to distinct browsing contexts within a single Chrome instance.
• Ownership enforcement via claim(), handOff(), and takeOver() prevents unauthorized access between agent automation and user browsing.
• Per‑space reference maps in src/ref-map.ts ensure element handles (@N) are never valid across context boundaries.
• The facade API in package/ego-browser/src/helpers.ts (lines 182–249) offers a safe surface for creating, switching, and destroying isolated environments.
• Complete session sandboxing guarantees that cookies, storage, and DOM state remain segregated according to the task space ownership model.

Frequently Asked Questions

What is a task space in ego‑lite?

A task space is an isolated browsing context within the ego‑lite browser runtime that maintains its own Chrome DevTools Protocol session, navigation history, cookie store, and DOM snapshot. Implemented primarily in package/ego-browser/src/helpers.ts, task spaces allow agents and users to share a single browser instance without sharing state.

How do task spaces prevent cross‑contamination between agent and user browsing?

Task spaces enforce isolation through separate CDP sessions that buffer network traffic and JavaScript execution contexts at the runtime level (src/browser-runtime.ts). Additionally, the ownership model requires explicit claim() or handOff() operations to transfer control, while per‑space reference maps in src/ref-map.ts invalidate element handles when switching contexts.

Can an agent access a user‑owned task space without claiming it?

No. The taskSpaces API explicitly prevents agents from operating on user‑owned spaces. Attempting to invoke navigation or interaction methods on an unclaimed user space will fail at the runtime boundary. The agent must first call taskSpaces.claim(nameOrId) to transfer ownership, ensuring intentional context sharing.

What happens to element references when switching between task spaces?

Element references using the @N syntax are stored in space‑specific maps maintained by src/ref-map.ts and src/ref-state.ts. When taskSpaces.switch() activates a new space, the runtime rebuilds the reference map for that context, effectively nullifying any handles from the previous space. This prevents the agent from accidentally interacting with elements from a different browsing context.

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