How to Complete or Close a Task Space in Ego-Lite: A Developer Guide

Use the await completeTaskSpace(nameOrId, { keep }) helper with keep: false to close the space or keep: true to leave it open, ensuring it is the final heredoc in your agent script.

Ego-Lite is an open-source agent framework where task spaces isolate browsing contexts. When an agent finishes its work, it must explicitly complete or close a task space in ego-lite using the provided helper functions. This guide explains the completeTaskSpace implementation and proper lifecycle management based on the citrolabs/ego-lite source code.

Understanding Task Space Completion in Ego-Lite

A task space represents an isolated browsing context that an agent works within during execution. According to the repository's contribution guidelines, every agent script should start with useOrCreateTaskSpace(name) and finish with completeTaskSpace(name, { keep })【CONTRIBUTING.md†L184-L186】. Leaving a space hanging causes resource leaks and unexpected behavior, making explicit closure mandatory.

The completeTaskSpace helper resides in package/ego-browser/src/helpers.ts and handles the validation and state transitions required to properly terminate a task space【helpers.ts†L274-L314】.

The completeTaskSpace Helper Function

The function signature is:

await completeTaskSpace(nameOrId, { keep })

The nameOrId parameter identifies the target task space, while the mandatory keep flag determines the final behavior according to the logic defined in helpers.ts【helpers.ts†L128-L131】.

When keep is false (Default Behavior)

Setting keep: false (the default policy) causes the helper to claim the task space if it is user-owned, then immediately close it. The call resolves with { done: true }, indicating successful completion. The documentation in skills/ego-browser/SKILL.md confirms that keep defaults to false by policy, meaning spaces close unless a concrete reason exists to keep the page visible【SKILL.md†L88-L93】.

When keep is true

Setting keep: true causes the task space to be skipped rather than closed, leaving it open and visible for the user. This is useful when the live page must remain accessible after the agent finishes. The call resolves with { done: false, skipped: "user-owned" }【SKILL.md†L88-L93】.

Proper Task Space Lifecycle

The repository enforces a strict lifecycle pattern. completeTaskSpace must be the last heredoc in a series of agent-generated scripts, running only after prior heredocs have confirmed that work is truly finished【SKILL.md†L71-L93】. This sequencing ensures that all intermediate operations complete before the final state transition occurs.

Code Examples

Normal Completion – Close the Task Space

Use this pattern when the agent has finished all operations and the task space can be safely terminated:

// Re-attach at the start of a heredoc
await useOrCreateTaskSpace("checkout-flow");

// Perform actions such as navigation, clicks, etc.
await page.click("#submit-order");

// Close the task space (claims if needed, then closes)
await completeTaskSpace("checkout-flow", { keep: false });
// → Returns { done: true }

Keep the Page Visible After Finishing

Use this pattern when the user needs to review the final state (such as an order confirmation page):

await useOrCreateTaskSpace("order-review");

// Perform review actions
await page.screenshot({ path: "confirmation.png" });

// Leave the task space open for user interaction
await completeTaskSpace("order-review", { keep: true });
// → Returns { done: false, skipped: "user-owned" }

Implementation Details

The core logic for completeTaskSpace is implemented in package/ego-browser/src/helpers.ts, where it manages the state transitions between active, claimed, and closed states【helpers.ts†L274-L314】. The user-facing documentation in skills/ego-browser/SKILL.md specifies that when keep: true, the helper skips user-owned spaces and reports the skip status, whereas keep: false triggers the claim-and-close workflow【SKILL.md†L88-L93】【SKILL.md†L107-L108】. For a quick reference of these helpers, see AGENTS.md【AGENTS.md†L28-L30】.

Summary

• Mandatory closure: Every task space must be explicitly closed using completeTaskSpace to prevent resource leaks.
• Keep flag behavior: Set keep: false to claim and close the space (returns { done: true }), or keep: true to skip and leave it open (returns { done: false, skipped: "user-owned" }).
• Position matters: This helper must be the final heredoc in your agent script sequence.
• Start pattern: Always begin scripts with useOrCreateTaskSpace(name) and end with completeTaskSpace(name, { keep }).

Frequently Asked Questions

What happens if I don't close a task space in Ego-Lite?

Leaving a task space open causes resource leaks and unexpected behavior. The contribution guidelines explicitly require that every agent script finish with completeTaskSpace to ensure proper cleanup of browsing contexts【CONTRIBUTING.md†L184-L186】.

Can I close a task space without claiming it first?

When keep is set to false, the completeTaskSpace helper automatically claims the space if it is user-owned before closing it. You do not need to manually claim it beforehand; the helper handles this transition atomically【helpers.ts†L128-L131】.

Why must completeTaskSpace be the last heredoc in a script?

The documentation specifies this ordering because completeTaskSpace terminates the task space context. If earlier heredocs in the sequence still need to perform actions on the space, running this helper prematurely would invalidate their execution context. It should run only after prior heredocs confirm the work is truly finished【SKILL.md†L88-L93】.

How do I know if a task space was successfully closed or skipped?

Check the return value of completeTaskSpace. If the space was closed, it returns { done: true }. If it was skipped (when keep: true), it returns { done: false, skipped: "user-owned" }, indicating the space remains open for user interaction【SKILL.md†L88-L93】.

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