# How Task Space IDs Are Handled in Ego-Lite: Validation, Resolution, and Usage

> Discover how ego-lite handles task space IDs with validation, resolution, and usage for unique browsing contexts. Learn about the numeric ID system.

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

---

**Ego-Lite assigns every browsing context a unique numeric task space ID at creation, strictly validates these identifiers through `taskSpaceNumericId()`, and automatically resolves string names to numeric IDs before executing low-level Chrome DevTools Protocol calls.**

Ego-Lite is an open-source browser automation framework that isolates each browsing context within a dedicated *task space*. Every task space receives a **numeric ID** when instantiated, and this identifier serves as the canonical reference for all runtime operations. Understanding how these task space IDs are validated, resolved, and utilized is essential for writing reliable automation scripts with the `citrolabs/ego-lite` codebase.

## Understanding Task Space ID Assignment

When Ego-Lite creates a new task space, the runtime assigns a **numeric identifier** that uniquely represents that browsing context. This `id` property is stored within the task space object and serves as the only accepted form of identification for low-level CDP (Chrome DevTools Protocol) calls.

All public task-space helpers—including `taskSpaces.claim()`, `taskSpaces.switch()`, and `taskSpaces.complete()`—require this numeric identifier. The system explicitly rejects any non-numeric values to ensure unambiguous task-space ownership checks and prevent agent-user confusion.

## Numeric ID Validation and Type Safety

The core validation logic resides in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). Before any operation executes, Ego-Lite validates the input through a dedicated helper that enforces type safety.

### The `taskSpaceNumericId()` Validator

The `taskSpaceNumericId(space, op)` function verifies that `space.id` is a finite number. If validation fails, it throws a clear, descriptive error message indicating which operation failed and what type was received instead:

- **Valid input**: A finite numeric ID proceeds to the CDP layer
- **Invalid input**: Throws error: "`${op} requires a numeric task space id, got ${typeof space.id}`"

This validation occurs at the boundary of every high-level operation, ensuring that only sanitized numeric identifiers reach the browser automation layer.

## Resolving Names to Numeric IDs

While the runtime requires numeric IDs, developers often reference task spaces by human-readable names. Ego-Lite provides a resolution pipeline that converts string identifiers to their numeric equivalents before validation.

### Listing Available Task Spaces

The `listTaskSpaces()` function returns an array of task-space objects, each containing:
- `id`: The numeric identifier (number)
- `name`: The human-readable name (string)
- `taskId`: The task identifier (string)

This listing serves as the source of truth for all lookup operations.

### Finding and Matching Task Spaces

The resolution flow follows a specific priority order in `findMatchingTaskSpace()`:

1. **Direct ID match**: If the argument is a number, return the space with matching `id`
2. **Name matching**: Fall back to matching against the `name` property
3. **taskId matching**: Match against the `taskId` property
4. **Numeric string coercion**: If the argument is a numeric string (e.g., `"3"`), convert it to a number and match on `id`

The `findTaskSpace(nameOrId)` orchestrator calls `listTaskSpaces()` first, then delegates to `findMatchingTaskSpace()` to execute this logic. Once resolved, high-level operations pass the resulting numeric ID through `taskSpaceNumericId()` before calling `ego.useTaskSpace()`.

## Working with Task Space IDs in Practice

Below are practical implementations showing how to work with task space IDs according to the Ego-Lite source code:

```javascript
// Create (or reuse) a task space by name, then get its numeric id
const mySpace = await taskSpaces.useOrCreate('research-task');
// mySpace.id is the numeric identifier required for further calls
console.log('Task-space numeric id:', mySpace.id);

// Switch to a task space using its numeric id
await taskSpaces.switch(mySpace.id);

// Claim a user-owned space by numeric id
await taskSpaces.claim(3);

// Complete a space and decide whether to keep it
await taskSpaces.complete(mySpace.id, { keep: false });

```

For programmatic resolution of names to IDs:

```javascript
// Resolve a name or string id to the numeric id in one step
async function resolveToNumeric(nameOrId) {
  const space = await taskSpaces.useOrCreate(nameOrId);
  return space.id;   // validated by taskSpaceNumericId internally
}

```

## Summary

- **Numeric exclusivity**: Ego-Lite accepts only numeric task space IDs for low-level operations, rejecting strings or other types at the validation layer.
- **Validation location**: The `taskSpaceNumericId()` function in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) enforces type safety and provides clear error messages.
- **Resolution pipeline**: String names are resolved to numeric IDs via `findTaskSpace()` → `listTaskSpaces()` → `findMatchingTaskSpace()`, supporting name, taskId, or numeric string lookups.
- **API consistency**: All public methods (`claim`, `switch`, `complete`) normalize inputs through the same validation path before invoking `ego.useTaskSpace()`.

## Frequently Asked Questions

### What happens if I pass a string instead of a number to task space methods?

The `taskSpaceNumericId()` validator throws a runtime error indicating which operation was attempted and what type was received. For example, calling `taskSpaces.claim("research")` results in: *"claim requires a numeric task space id, got string"*. You must either pass a numeric ID directly or use `useOrCreate()` to resolve the name first.

### How does Ego-Lite handle numeric strings like "3"?

During the resolution phase, `findMatchingTaskSpace()` detects numeric strings using a type check and coercion pattern. If the argument resembles a number (e.g., `"3"`), the function converts it to a number and attempts to match against the `id` field. This provides flexibility while maintaining strict numeric typing at the CDP boundary.

### Can I retrieve a task space ID by name?

Yes. Call `await taskSpaces.useOrCreate('your-name')` to either create a new space or retrieve an existing one. The returned object contains the `id` property, which is the validated numeric identifier. Alternatively, use the lower-level `findTaskSpace(name)` helper to look up the space object without claiming it.

### Where is the task space ID validation implemented?

All validation logic lives in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). Key functions include `taskSpaceNumericId()` for validation, `listTaskSpaces()` for retrieval, and `findMatchingTaskSpace()` for name-to-ID resolution. The end-to-end test suite in `package/ego-browser/src/taskspace-e2e.test.mjs` verifies correct ID handling across creation, switching, claiming, and completion workflows.