How AI Agents Inherit User Login State in ego-lite: Task Space Architecture Explained

AI agents inherit user login state in ego-lite by claiming the same task space where authentication cookies were stored, transferring ownership without clearing the persistent cookie jar maintained in src/state.ts.

ego-lite is a minimal Node.js harness that enables AI agents to control a Chromium browser via the Chrome DevTools Protocol (CDP). The framework utilizes isolated task spaces to manage persistent browser sessions, allowing agents to seamlessly assume authenticated identities by accessing shared cookie stores rather than re-authenticating.

Understanding Task Spaces and Session Isolation

Task spaces are isolated browsing contexts where each AI agent operates within a sandboxed browser tab that maintains its own cookies, localStorage, and sessionStorage. According to the ego-lite source code, every task space tracks an owner (designated as either agent or user), a unique name or ID, and a dedicated persistent storage layer.

These spaces are managed through the runtime state singleton defined in src/state.ts, which serves as the central repository for all session data. When a task space is initialized via newTaskSpace(), the framework creates a clean storage container for that context. Conversely, completeTaskSpace() tears down the environment and optionally purges its data.

The Mechanism Behind Login State Inheritance

Because authentication state binds to the task space rather than the agent, an AI agent can inherit a user’s login credentials by claiming ownership of the same space where the authentication occurred. The claimTaskSpace(nameOrId) function, exposed through src/helpers.ts, transfers ownership of the task space without clearing its stored cookies.

Once claimed, the agent activates the session using useTaskSpace(id), which injects the stored cookies into the current browsing context. Every subsequent HTTP request then automatically includes these cookies, allowing the agent to navigate authenticated endpoints as the original user. This architecture decouples identity from authentication state, enabling seamless handoffs between manual user sessions and automated workflows.

Practical Implementation of Session Handoff

The following implementation demonstrates how to preserve a GitHub login session across user and agent interactions using the task space API.

Step 1: User Authentication

First, the user (or an automated learning tool from skills/ego-browser/learnings/) logs into the target service. The resulting authentication cookies are automatically persisted to the current task space's cookie jar stored in the runtime state.

// User logs in via the ego-lite harness
await ego.navigate('https://github.com/login');
await ego.fill('input[name="login"]', 'my-user');
await ego.fill('input[name="password"]', 'my-secret');
await ego.click('button[name="commit"]');
// Cookies are now stored in the active task space within src/state.ts

Step 2: Agent Claims the Session

Later, an AI agent claims the named task space to inherit the authenticated state without requiring credentials.

// Agent claims the existing task space
const space = await ego.claimTaskSpace('github-session');
await ego.useTaskSpace(space.id);
// All subsequent requests include the stored GitHub cookies

// Navigate as the authenticated user
await ego.navigate('https://github.com/settings/profile');

Persistence Across Restarts

The runtime state in src/state.ts supports serialization to disk, meaning task space data—including cookie jars—survives container restarts. When the ego-lite harness restarts, it reloads the state singleton through the CDP transport layer managed in src/browser-runtime.ts, restoring all previously stored sessions. Agents can immediately reclaim task spaces via claimTaskSpace() without requiring re-authentication, making this approach suitable for long-running automation workflows that span multiple deployment cycles.

Security and Isolation Considerations

Cookie jars are strictly isolated per-task-space according to the security model documented in the repository. Never share a task space between unrelated agents or untrusted contexts, as ownership transfer via claimTaskSpace() grants full access to the stored authentication tokens. Each sensitive workflow should operate within its own named task space to maintain proper security boundaries and prevent credential leakage between different agent processes.

Summary

• Task spaces isolate browser sessions with dedicated cookie storage managed in src/state.ts
• claimTaskSpace(nameOrId) transfers ownership without clearing cookies, enabling login state inheritance
• useTaskSpace(id) activates the inherited session for the current agent context
• State persists to disk via the runtime singleton, surviving container restarts and process recycling
• Security requires strict isolation—never share task spaces between untrusted agents or concurrent workflows

Frequently Asked Questions

What is the difference between claimTaskSpace and useTaskSpace?

claimTaskSpace(nameOrId) transfers ownership of a task space from its current owner (user or agent) to the calling agent without clearing stored cookies, effectively granting inheritance of the login state. useTaskSpace(id) then activates that task space for the current execution context, ensuring all subsequent browser operations conducted through the CDP transport utilize the inherited cookies and storage.

Where does ego-lite store authentication cookies?

Authentication cookies are stored in the runtime's state singleton, implemented in src/state.ts. Each task space maintains its own isolated cookie jar within this state object, which the binary-level CDP transport accesses when executing navigation commands. This ensures that credentials remain bound to the specific task space and do not leak between different browsing contexts or agent sessions.

Can multiple agents share the same login session simultaneously?

No, task spaces support only a single owner at a time. While one agent can claim a space after another releases it using claimTaskSpace(), concurrent access is not permitted by design. This prevents race conditions and ensures cookie consistency, though agents can pass sessions sequentially without re-authentication, provided they reference the same task space ID.

Do login states survive ego-lite process restarts?

Yes, the src/state.ts module supports persistence to disk through its serialization interface. When configured, the cookie jar and task space metadata serialize before shutdown and reload upon restart via the harness initialization in src/browser-runtime.ts. This allows agents to reclaim fully authenticated sessions via claimTaskSpace() even after the Node.js process or Docker container has been recycled.

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