How AI Agents Interact with the ego-lite Browser Using the Helper System

The helper system in ego-lite provides AI agents with a Playwright-style API through the helperContext() function, which injects facades for page interaction, browser management, and task-space isolation directly into agent scripts.

The ego-lite browser (citrolabs/ego-lite) exposes a high-level abstraction layer that eliminates the need for agents to handle raw Chrome DevTools Protocol (CDP) commands. By assembling a context object that maps to underlying driver modules, the helper system enables agents to perform complex browser automation using familiar method calls like page.goto() and locator.click().

Understanding the Helper System Architecture

At runtime, the ego-lite browser constructs a helper context that becomes the execution environment for agent scripts. This architecture delegates low-level CDP interactions to specialized driver modules while exposing a unified, Promise-based API to the agent.

The helperContext() Factory

The entry point for all agent-browser interaction is the helperContext() function defined in [helpers.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). According to the source code, this factory assembles multiple facades—page, browser, taskSpaces, site, fetch, and cdp—into a single object that gets injected into the agent's scope. When an agent script executes via runMain() in src/run.ts, it receives this context without requiring any import statements, allowing immediate access to browser automation primitives.

Facade Pattern Implementation

Each facade serves as a thin abstraction over concrete driver implementations. For example, the page facade delegates navigation to [driver/nav.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts), pointer actions to [driver/pointer.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts), and keyboard input to [driver/keyboard.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts). This separation ensures that agents interact with semantic APIs (e.g., await element.click()) while the system handles CDP command serialization, snapshot management, and event queue coordination behind the scenes.

Core Facades for Browser Automation

The helper system exposes six primary facades that cover the full spectrum of browser interaction, from DOM manipulation to network interception.

Page Facade and Locator API

The page facade provides Playwright-compatible methods including page.goto(), page.screenshot(), and page.locator(). When agents call page.locator(selector), they receive a strict locator object that supports chained actions like click(), fill(), and innerText(). Internally, these methods route through [driver/locator.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/locator.ts) for element resolution and [driver/waits.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts) for automatic waiting logic, ensuring elements are ready before interaction.

Browser and TaskSpace Management

The browser facade handles tab lifecycle through methods like browser.listTabs(), browser.switchTab(), and browser.openOrReuseTab(). The taskSpaces facade provides isolation primitives—taskSpaces.new(), taskSpaces.claim(), and taskSpaces.handOff()—that enforce ownership policies. As implemented in helpers.ts, these checks ensure agents only modify DOM contexts they own, preventing accidental interference with user-controlled browsing sessions.

Site Skills and Network Fetch

The site facade loads domain-specific automation logic from [src/learning/index.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/learning/index.ts), allowing agents to execute pre-learned workflows via site.runTool(). The fetch facade offers dual-context network access: fetch.server() for Node.js-side requests and fetch.browser() for origin-mimicking fetch within the browser context, bypassing CORS restrictions when necessary.

Practical Agent Implementation Examples

Agents write standard JavaScript that executes within the helper-injected scope. The following examples demonstrate common automation patterns using the ego-lite helper system.

Basic Navigation and Element Interaction

// Navigate and interact using the page facade
await page.goto('https://example.com');
const submitBtn = page.locator('button[type="submit"]');
await submitBtn.waitFor();
await submitBtn.click();

This code relies on [driver/nav.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts) for navigation and [driver/pointer.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts) for the click action, with implicit waiting handled by [driver/waits.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts).

Form Completion and Keyboard Input

// Fill login credentials and submit
await page.goto('https://auth.example.com');
await page.locator('input#email').fill('agent@example.com');
await page.locator('input#password').fill('securePassword123');
await page.keyboard.press('Enter');

The fill() method coordinates with [driver/keyboard.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts), while page.keyboard provides direct access to key press emulation.

Task Space Isolation

// Create isolated context for sensitive workflow
const checkoutSpace = await taskSpaces.new('secure-checkout');
await page.goto('https://checkout.example.com');

// Complete workflow and release control
await taskSpaces.handOff();

Task spaces enforce boundaries defined in [src/state.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts), with ownership validation occurring in the facade layer before any DOM mutation.

Element Screenshots and Evaluation

// Capture specific element screenshot
const chart = page.locator('.data-visualization');
await chart.screenshot({ path: 'chart.png' });

// Execute custom JavaScript in page context
const title = await cdp.evaluate(() => document.title);

The screenshot() method utilizes [driver/observe.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts), while cdp.evaluate() provides direct access to the JavaScript execution environment via [src/cdp-eval.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/cdp-eval.ts).

Summary

• The helper system centralizes browser automation logic in package/ego-browser/src/helpers.ts, exposing a unified API through helperContext().
• Facades abstract CDP complexity, with the page facade offering Playwright-compatible locators and the browser facade managing tab lifecycles.
• Task spaces provide isolation boundaries, ensuring agents operate only within owned contexts through the taskSpaces facade.
• Driver modules (pointer.ts, keyboard.ts, nav.ts, locator.ts, waits.ts, observe.ts) implement concrete actions triggered by facade methods.
• Agents execute scripts without imports, receiving pre-injected helpers that handle snapshot consistency, event draining, and ownership validation automatically.

Frequently Asked Questions

What is the helperContext() function in ego-lite?

The helperContext() function is the factory method defined in helpers.ts that constructs and returns the complete set of browser automation helpers. It creates facades for page interaction, browser management, task spaces, site-specific skills, and network fetching, then injects these into the agent's execution scope so scripts can call methods like page.goto() without module imports.

How do task spaces isolate agent sessions?

Task spaces create isolated browsing contexts using the taskSpaces facade methods like new(), claim(), and handOff(). As implemented in the helper system, each task space maintains ownership metadata in src/state.ts, and the facade layer validates that agents only manipulate DOM elements within spaces they explicitly own, preventing cross-contamination between agent workflows and user browsing sessions.

Can agents execute custom JavaScript in the browser?

Yes, agents can execute arbitrary JavaScript using the cdp.evaluate() helper or the evaluate method on locator objects. These functions route through src/cdp-eval.ts to send direct Chrome DevTools Protocol commands, allowing agents to read page properties, modify the DOM, or invoke browser APIs that are not covered by the high-level facade methods.

Where are mouse and keyboard actions implemented?

Mouse actions such as click() and hover() are implemented in driver/pointer.ts, while keyboard actions including fill() and press() reside in driver/keyboard.ts. These driver modules receive calls from the page and locator facades, then translate them into CDP input dispatch commands with proper coordinate calculation and key event simulation.

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