# Task Spaces in ego-lite: Isolated Browsing Contexts for Safe Agent Control

> Discover task spaces in ego-lite: isolated browsing contexts for safe agent control. Learn how these secure environments protect interactive jobs with strict ownership.

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

---

**Task spaces in ego-lite are isolated browsing contexts that keep interactive jobs separate and safely managed, each identified by a numeric ID and optional name with strict ownership rules governing agent access.**

Task spaces form the core isolation mechanism in the citrolabs/ego-lite browser automation framework. Each space represents a distinct browsing context that prevents cross-contamination between automated tasks. Understanding how to create, claim, and manage these spaces is essential for building robust agent workflows that handle both autonomous and user-interactive scenarios.

## What Are Task Spaces in ego-lite?

Task spaces in ego-lite provide isolated environments where automated agents can perform web interactions without interfering with each other. Each space carries a unique numeric **id** and an optional **name** (referred to as *taskId* in the API), allowing developers to reference specific contexts either numerically or semantically.

The runtime maintains strict metadata for every space, including its `createdBy` field, `ownership` status, and `recentTabTitles`. These properties enable the system to track who controls the browsing session and what content is currently active.

## Task Space Ownership Model

Every task space operates under one of two ownership modes that dictate who can perform actions:

- **agent**: Created by the ego-lite agent itself. The agent retains full authority to select, switch, and control the space without restrictions.
- **user**: Created or seized by the end-user (human). When a space has user ownership, the agent **must claim** it before performing any automated actions.
- *other*: Any ownership value outside these two categories triggers an error condition.

This ownership model prevents agents from accidentally interrupting active user sessions while enabling seamless handoffs between automated and manual control.

## How to Use Task Spaces in ego-lite

The public API surface for task-space operations resides in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), where the façade is constructed and injected into user scripts via `helperContext()`. All methods are asynchronous and return plain objects containing the space's `id`, `taskId`, `name`, `createdBy`, `ownership`, and `recentTabTitles`.

### Listing and Creating Task Spaces

To view existing contexts or initialize new ones, use the listing and factory methods:

```javascript
// List all available spaces
const spaces = await taskSpaces.list();

// Create a new agent-owned space
const newSpace = await taskSpaces.new('checkout-flow');

// Reuse existing or create if missing (creates agent-owned)
const task = await taskSpaces.useOrCreate('checkout-flow');
// Returns: { taskId: 'checkout-flow', id: 1, name: 'checkout-flow', ... }

```

### Switching Between Task Spaces

Agents can only switch contexts for spaces they own. The `switch` method accepts the numeric ID:

```javascript
// Switch to an existing agent-owned space
await taskSpaces.switch(7);

```

Attempting to switch to a user-owned space without claiming it first results in an error.

### Claiming User-Owned Spaces

When a user creates a space or takes control via `handOff`, the agent must explicitly claim control:

```javascript
// Claim a space by name or ID before using it
const claimed = await taskSpaces.claim('checkout-flow');
// Now ownership transfers to agent

```

The `claim` method is the only way to convert a user-owned space to agent ownership.

### Completing and Handing Off Control

Task spaces persist until explicitly completed. Use `complete` to close them, or `handOff` to transfer control to the user:

```javascript
// Give control back to the user
await taskSpaces.handOff(task.id);

// Wait until agent regains control
await taskSpaces.waitForAgentControl(task.id, { timeout: 30000 });

// Take back control from user
await taskSpaces.takeOver(task.id);

// Close the space (keep: false closes the tab)
await taskSpaces.complete(task.id, { keep: false });

```

## Complete Code Examples

The following patterns from `src/taskspace-e2e.test.mjs` demonstrate the full lifecycle:

```javascript
// 1️⃣ Create (or reuse) a task space and select it
const task = await taskSpaces.useOrCreate('checkout-flow');
console.log('Selected space id:', task.id);

// 2️⃣ Claim a user-owned space before using it
const claimed = await taskSpaces.claim('checkout-flow');
console.log('Now agent-owned:', claimed);

// 3️⃣ Switch to an existing agent-owned space by numeric id
await taskSpaces.switch(7);

// 4️⃣ Hand off the space to the user (so the user can take over)
await taskSpaces.handOff(task.id);

// 5️⃣ Later, take back control
await taskSpaces.takeOver(task.id);

// 6️⃣ Finish the task space (optionally keep the browser tab)
await taskSpaces.complete(task.id, { keep: false });

```

## Error Handling and Edge Cases

When an agent attempts to interact with a user-owned space without claiming it, the runtime returns error code `EGO_TASK_SPACE_USER_IN_CONTROL`. As defined in [`src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ego-errors.ts), this error triggers a helpful guidance message on the agent surface rather than exposing raw native errors to end users.

The end-to-end tests in `src/taskspace-e2e.test.mjs` validate these error conditions, ensuring that the ownership model correctly prevents unauthorized agent actions while providing clear remediation paths.

## Implementation Details

The `taskSpaces` façade is constructed in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 815-819) and exposed to automation scripts through `helperContext()`. This architecture keeps the implementation details separate from the public API while providing consistent access to space management functions across the runtime.

## Summary

- Task spaces in ego-lite provide isolated browsing contexts identified by numeric IDs and optional names.
- The ownership model distinguishes between **agent** and **user** control, requiring explicit claims for the latter.
- Core operations include `useOrCreate`, `claim`, `switch`, `handOff`, `takeOver`, and `complete`.
- Attempting to use user-owned spaces without claiming them triggers `EGO_TASK_SPACE_USER_IN_CONTROL` errors.
- The API façade resides in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and is injected via `helperContext()`.

## Frequently Asked Questions

### What is the difference between a task space ID and taskId?

The **id** is a numeric identifier assigned by the runtime, while **taskId** (also called **name**) is an optional string label you provide when creating the space. You can reference spaces by either the numeric ID in methods like `switch()` or by the string name in methods like `claim()` or `useOrCreate()`.

### How do I handle the EGO_TASK_SPACE_USER_IN_CONTROL error?

When you encounter error code `EGO_TASK_SPACE_USER_IN_CONTROL`, call `await taskSpaces.claim(idOrName)` to transfer ownership from the user to the agent. This error prevents agents from interrupting active user sessions, ensuring safe collaboration between human and automated control.

### Can multiple agents control the same task space simultaneously?

No. Task spaces enforce single-controller semantics based on the ownership field. Only one entity—either an agent or a user—can actively control a space at any time. Use `handOff` and `takeOver` to pass control back and forth between parties.

### Where is the taskSpaces API defined in the source code?

The API is defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) where the façade object is constructed and injected into scripts via `helperContext()`. Error codes like `EGO_TASK_SPACE_USER_IN_CONTROL` are defined in [`src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ego-errors.ts), and usage examples appear in `src/taskspace-e2e.test.mjs`.