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

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. 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:

// 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:

// 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 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. 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.

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