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

> Learn how to close a task space in ego-lite using the completeTaskSpace helper. Discover how to keep or remove task spaces efficiently in your agent scripts.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
// 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):

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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】.