How claimTaskSpace Transfers Ownership from a User to an Agent in ego-lite

The claimTaskSpace helper in ego-lite resolves a user-owned task space, invokes the native ego.claimTaskSpace bridge to flip the ownership field from "user" to "agent", and then activates the space with selectTaskSpace so the agent can operate inside it.

In the citrolabs/ego-lite repository, agents sometimes need to take control of task spaces that were originally created by a user. The claimTaskSpace async helper orchestrates this hand-off in three sequential stages—resolution, native bridge claiming, and activation—providing a clean API for ownership transfer.

Step‑by‑Step Ownership Transfer Flow

Resolve the Task Space

Before any ownership change can happen, claimTaskSpace must locate the target. It delegates this to findTaskSpace, which internally calls listTaskSpaces and matches the supplied identifier—either a string name or a numeric id. This resolution step ensures the helper is working with a valid space object that actually exists in the runtime. In package/ego-browser/src/helpers.ts, this lookup logic is implemented around lines 40‑47.

Claim the Space via the Native Ego Bridge

Once the space is resolved, the internal claimResolvedTaskSpace function takes over (lines 29‑42 in package/ego-browser/src/helpers.ts). It first validates that the native method ego.claimTaskSpace is available. It then extracts the space’s numeric identifier via taskSpaceNumericId and calls ego.claimTaskSpace(id, space.name). The Ego runtime performs the actual ownership mutation, updating the space’s ownership property from "user" to "agent" (or in some cases to "agentDelegatedToUser"). The return value is normalized and its id is re-checked before proceeding.

Select the Now‑Claimed Space

After the runtime confirms the ownership switch, claimTaskSpace calls selectTaskSpace to make the claimed space the active context for the current Node invocation. This helper executes ego.useTaskSpace(id) (see lines 45‑51 in package/ego-browser/src/helpers.ts). Subsequent helper calls—such as page.goto or locator.click—then operate within this agent-owned context.

Practical Code Examples

Claim a Task Space by Name

import { claimTaskSpace } from "./helpers.js";

async function takeControl() {
  // "checkout-flow" is a user-owned task space created earlier
  const space = await claimTaskSpace("checkout-flow");
  console.log("Now owned by agent:", space);
}

takeControl();

Claim a Task Space by Numeric ID

import { claimTaskSpace } from "./helpers.js";

async function takeControlById() {
  // Assuming the numeric id is 7
  const space = await claimTaskSpace(7);
  console.log("Claimed task space:", space);
}

takeControlById();

Both snippets follow the same three-phase flow: resolve the specified space, invoke the native ego.claimTaskSpace to flip the ownership field, and select the space so that later helper calls act within that context.

Key Source Files and Helper Functions

Several modules in ego-browser cooperate to make the transfer safe and predictable:

• package/ego-browser/src/helpers.ts – Houses the public claimTaskSpace API and the internal claimResolvedTaskSpace, findTaskSpace, and selectTaskSpace logic.
• package/ego-browser/src/state.ts – Provides the runtime state singleton used by helpers for workspace paths and active context tracking.
• package/ego-browser/src/ego-errors.ts – Supplies error handling utilities such as assertNoEgoError, which guards native bridge invocations against runtime failures.

Summary

• claimTaskSpace is the public async helper that agents use to take over user-owned task spaces.
• It resolves the target space by name or numeric id through findTaskSpace.
• Ownership is changed natively via ego.claimTaskSpace(id, space.name), which mutates the ownership field from "user" to "agent".
• The helper finishes by calling selectTaskSpace, which runs ego.useTaskSpace(id) to activate the claimed context.
• Supporting infrastructure in helpers.ts, state.ts, and ego-errors.ts ensures the process is robust and errors are caught early.

Frequently Asked Questions

What happens to the ownership field when claimTaskSpace is called?

The Ego runtime updates the space’s ownership property from "user" to "agent" or "agentDelegatedToUser" when the native ego.claimTaskSpace method succeeds. This mutation happens inside the runtime, not in the helper itself.

Can claimTaskSpace resolve a task space by both name and numeric id?

Yes. The helper accepts either a string name or a numeric id. Internally, findTaskSpace calls listTaskSpaces and matches the identifier, returning the full space object needed for the claim step.

What native method actually performs the ownership transfer?

The native bridge method ego.claimTaskSpace performs the actual transfer. The helper validates its existence, builds the call with taskSpaceNumericId(id) and space.name, and then normalizes the result.

Does claimTaskSpace automatically activate the claimed space?

Yes. After a successful claim, the helper automatically invokes selectTaskSpace, which executes ego.useTaskSpace(id) to set the space as the active context for the current invocation.

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