# How to Switch to an Agent-Owned Task Space in ego-lite: A Complete Developer Guide

> Learn how to switch to an agent-owned task space in ego-lite. This guide details using the switchTaskSpace helper and its permission validations for developers.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-21

---

**In ego-lite, you can only switch to task spaces where the `ownership` field is set to `"agent"` or `"agentDelegatedToUser"` using the `switchTaskSpace` helper, which validates permissions before invoking the native `ego.useTaskSpace` bridge.**

The **ego-lite** framework (maintained in the `citrolabs/ego-lite` repository) provides isolated browsing contexts called **task spaces** that enforce strict security boundaries between agent and user control. To programmatically activate a specific browsing context for your automation scripts, you must understand the ownership validation rules that prevent unauthorized context switches.

## What is an Agent-Owned Task Space?

In ego-lite, a **task space** represents an isolated browsing context with a defined ownership model. The `ownership` property determines who controls the space:

- **`"agent"`** – Fully controlled by the automation agent
- **`"agentDelegatedToUser"`** – Delegated to user but switchable by agent
- **`"user"`** – User-controlled; the agent cannot switch to these spaces

Only spaces with agent-related ownership flags can be activated via the SDK. Attempting to switch to a user-owned space triggers a permission error.

## Prerequisites for Switching Task Spaces

Before calling `switchTaskSpace`, ensure you have:

1. Imported the function from the `ego-browser` package (exported in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) lines 120–130)
2. Confirmed the native runtime is available via `globalThis.ego.useTaskSpace`
3. Identified the target space name or numeric ID

## How to Switch to an Agent-Owned Task Space

The `switchTaskSpace` function in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 52–63) performs a four-step validation process before activating a task space.

### Step 1: Validate the Runtime Environment

The function first checks that the native `ego.useTaskSpace` bridge method exists in the global runtime. Without this native binding, task space isolation cannot be enforced at the browser level.

### Step 2: Locate the Target Task Space

The helper calls `findTaskSpace` (implemented in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 440–460) to resolve your supplied identifier—either a string name or numeric ID—into a full task space descriptor object containing the `ownership` field.

### Step 3: Verify Ownership Permissions

Using the `isAgentOwned` predicate (defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 35–45), the function validates that the space's `ownership` value is either `"agent"` or `"agentDelegatedToUser"`. If the space is user-owned, the function throws: `"switchTaskSpace requires an agent-owned task space, got ownership ..."`.

### Step 4: Activate the Space

Once validated, `selectTaskSpace` invokes the native `ego.useTaskSpace` bridge, making the target space active for the current script execution context.

## Code Examples for switchTaskSpace

### Basic Switch by Name

Switch to a known agent-owned space using its string identifier:

```javascript
// Assuming the ego runtime is already injected (globalThis.ego)
import { switchTaskSpace } from 'ego-browser'

await switchTaskSpace('my-agent-space')

```

### Switch by Numeric ID

You can also reference task spaces by their internal numeric ID:

```javascript
await switchTaskSpace(42)   // 42 must refer to an agent-owned space

```

### Handling Permission Errors

Wrap your switch calls to handle cases where the space is not agent-owned:

```javascript
try {
  await switchTaskSpace('user-space')
} catch (err) {
  console.error('Cannot switch:', err.message)
  // → "switchTaskSpace requires an agent-owned task space, got ownership ..."
}

```

### Complete Workflow Example

Combine `listTaskSpaces` with ownership checking for robust space management:

```javascript
import { listTaskSpaces, switchTaskSpace } from 'ego-browser'

async function ensureAgentSpace(name) {
  const spaces = await listTaskSpaces()
  const target = spaces.find(s => s.name === name)

  if (!target) throw new Error(`No task space named ${name}`)
  
  // Explicit ownership check before attempting switch
  if (target.ownership !== 'agent' && target.ownership !== 'agentDelegatedToUser') {
    throw new Error(`Task space ${name} is not agent-owned`)
  }

  await switchTaskSpace(name)   // Now the agent owns the active context
}

```

## Understanding the Ownership Security Model

The ownership validation in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) enforces a critical security boundary. By checking the `ownership` field before invoking `ego.useTaskSpace`, ego-lite ensures that:

- Agents cannot hijack user browsing sessions
- Scripts fails fast with descriptive errors when attempting invalid switches
- The `agentDelegatedToUser` state allows flexible handoff scenarios while maintaining agent oversight

## Summary

- **Use `switchTaskSpace`** from `ego-browser` to activate agent-owned browsing contexts.
- **Valid ownership values** are `"agent"` or `"agentDelegatedToUser"`; user-owned spaces trigger errors.
- **Implementation files**: [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 35–45 for `isAgentOwned`, lines 52–63 for `switchTaskSpace`, lines 440–460 for `findTaskSpace`) and [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) (lines 120–130 for exports).
- **Native bridge**: The function ultimately calls `ego.useTaskSpace` after validation.
- **Error handling**: Always wrap switches in try-catch blocks to handle permission denials gracefully.

## Frequently Asked Questions

### What error occurs when trying to switch to a user-owned task space?

The function throws a runtime error with the message: `"switchTaskSpace requires an agent-owned task space, got ownership ..."` followed by the actual ownership value detected. This prevents agents from accessing user-private browsing contexts.

### Can I switch to a task space using just the numeric ID?

Yes. The `findTaskSpace` helper accepts both string names and numeric IDs. Pass the integer directly to `switchTaskSpace(id)`, and the internal resolver will locate the corresponding task space descriptor before performing the ownership check.

### What is the difference between `"agent"` and `"agentDelegatedToUser"` ownership?

Both values allow the agent to switch to the space, but `"agentDelegatedToUser"` indicates the space was originally agent-created but temporarily delegated to user control. The agent retains the right to reclaim it, whereas pure `"user"` spaces are permanently restricted from agent access.

### Where is `switchTaskSpace` exported in the SDK?

The function is exported from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) at lines 120–130 as part of the public API, making it available via `import { switchTaskSpace } from 'ego-browser'`.