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

> Discover task spaces in ego-lite isolated browsing contexts that let AI agents manage separate tabs history and DOM snapshots for concurrent tasks without interference.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-08-23

---

**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](https://github.com/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), redirects subsequent helper calls—such as tab creation or page interactions—to operate within the selected space.

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), accepts an optional `keep` parameter that preserves tabs for future reference when set to `true`.

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.