How to Complete a Task Space and Dismiss or Close the Overlay Using ego-lite

To complete a task space and dismiss its overlay in the citrolabs/ego-lite runtime, invoke the completeTaskSpace helper with the option { keep: false } to permanently destroy the space and remove the UI, or { keep: true } to hide the overlay while keeping the space active for debugging.

A task space in ego-lite represents an isolated browsing context that agents create, claim, and manage during automated workflows. When you need to finish work within a specific context, you must properly signal completion to the host runtime and control whether the associated UI overlay remains visible or is dismissed entirely.

Using the completeTaskSpace Helper

The primary mechanism to finish a task space and manage its overlay is the async function completeTaskSpace, exported from package/ego-browser/src/helpers.ts (beginning at line 274). This helper abstracts the runtime calls required to either persist the space for later inspection or tear it down completely.

Function Signature

export async function completeTaskSpace(
  ego: EgoRuntime,
  nameOrId: string | number,
  opts: { keep: boolean }
): Promise<{ done: boolean; skipped?: string }>

The function accepts three arguments:

• ego – The active EgoRuntime instance.
• nameOrId – either the string name or numeric ID of the target task space.
• opts.keep – A boolean flag determining whether the space survives after the overlay closes.

How to Close a Task Space and Remove the Overlay Permanently

To finish a task and completely destroy its associated browsing context, set the keep option to false. This workflow first claims the space to ensure ownership, then terminates the session and dismisses the overlay from the screen.

Under the hood, the helper executes:

1. selectTaskSpace to locate the target by name or ID.
2. claimResolvedTaskSpace to assert ownership.
3. ego.closeTaskSpace() to destroy the space and dismiss the overlay permanently.

// Complete the task and destroy the space
await completeTaskSpace(ego, "my-task-space", { keep: false });
// Returns: { done: true }

Use this mode when you have extracted all necessary data and no longer need the browsing context.

How to Dismiss the Overlay While Preserving the Space

For debugging or multi-step workflows, you may want to hide the overlay without destroying the underlying task space. Setting keep: true dismisses the UI but leaves the space intact, marked as user-owned.

Internally, this path calls ego.completeTaskSpace() (without claiming or closing), which signals the host to hide the overlay while preserving the isolated context.

// Dismiss overlay but keep space alive for inspection
await completeTaskSpace(ego, 42, { keep: true });
// Returns: { done: false, skipped: "user-owned" }

This approach is useful when you need to temporarily clear the UI to reveal the underlying page or return to the space later in the session.

CLI and Integration Usage

The helper is registered as a CLI command in package/ego-browser/src/index.ts at line 130 under the name "completeTaskSpace". You can invoke it directly from the command line:

ego-browser <<'JS'
  await completeTaskSpace("demo-run", { keep: false });
JS

Integration tests demonstrating these flows live in package/ego-browser/src/taskspace-e2e.test.mjs, which validates both the preservation and destruction paths against a live runtime.

Summary

• Task spaces in ego-lite are isolated browsing contexts identified by name or numeric ID.
• completeTaskSpace in package/ego-browser/src/helpers.ts (line 274+) provides the unified interface to finish tasks and control overlays.
• { keep: false } claims the space via claimResolvedTaskSpace, then calls ego.closeTaskSpace() to permanently destroy the space and remove the overlay.
• { keep: true } invokes ego.completeTaskSpace() to hide the overlay while leaving the space active, returning { done: false, skipped: "user-owned" }.
• The function is exposed to CLI tools via registration in package/ego-browser/src/index.ts.

Frequently Asked Questions

What is the difference between dismissing and closing a task space overlay?

Dismiss refers to hiding the UI overlay while keeping the underlying browsing context alive (using { keep: true }), whereas close means both hiding the overlay and destroying the task space entirely (using { keep: false }). The former preserves state for debugging, while the latter frees resources.

How do I keep a task space alive after completing the task?

Pass { keep: true } as the options argument to completeTaskSpace. This triggers the runtime's ego.completeTaskSpace() method without claiming or closing the space, returning a result object with done: false and skipped: "user-owned".

Where is the completeTaskSpace function defined in the ego-lite repository?

The implementation resides in package/ego-browser/src/helpers.ts starting at line 274. The function is also registered for CLI access in package/ego-browser/src/index.ts around line 130. Additional usage examples appear in package/ego-browser/src/taskspace-e2e.test.mjs.

What does the completeTaskSpace helper return?

The function returns a Promise resolving to an object with done: boolean and an optional skipped?: string property. When keep is false, done is true. When keep is true, done is false and skipped contains the string "user-owned" to indicate the space was preserved.

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