Complete Reference to ego-browser Helper Functions in citrolabs/ego-lite

The ego-browser package exposes over 50 helper functions organized into logical facades—page, browser, taskSpaces, site, fetch, cdp, and help—that agents can invoke directly from the injected script context without importing modules.

The citrolabs/ego-lite repository provides a comprehensive browser automation environment through its ego-browser package. These ego-browser helper functions are assembled by the helperContext() function defined in [src/helpers.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L822‑L850) and injected into the global scope of agent scripts, enabling seamless web automation, tab management, and network interception.

The Core Facades

The helper system organizes functionality into distinct facades that mirror common automation patterns. Each facade is a property of the global helper context available to agents.

Page Facade (Playwright-Style Automation)

The page facade provides Playwright-compatible actions that operate on the current active tab. In src/helpers.ts, this facade aggregates drivers from multiple source files to offer a complete automation API.

Key functions include:

• Navigation: goto, reload, waitForLoadState, waitForURL
• Locators: locator, getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle, getByTestId
• Waiting: waitForTimeout, waitForSelector, waitForFunction, waitForRequest, waitForResponse, waitForEvent
• Observation: screenshot, snapshot, snapshotRaw, elementCenter, drainEvents, info, url, title
• Input: keyboard (press, down, up, insertText, type) and mouse (click, dblclick, move, down, up, wheel, drag)

These methods are implemented across [src/driver/nav.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts), [src/driver/waits.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts), and [src/driver/observe.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts).

Browser Facade (Tab Management)

The browser facade handles multi-tab workflows and tab lifecycle management. According to the source code in src/helpers.ts, these helpers manage the browser context beyond the current page.

Available functions:

• listTabs, currentTab, switchTab — Enumerate and activate tabs
• openOrReuseTab, closeTab — Tab creation and cleanup
• ensureRealTab — Validate tab existence
• iframeTarget — Target specific iframe contexts

TaskSpaces Facade (Isolated Browsing Contexts)

The taskSpaces facade manages isolated browsing environments for multi-agent workflows. This allows agents to create sandboxed sessions that don't interfere with each other.

Core methods:

• list, switch, new, useOrCreate — CRUD operations for task spaces
• claim, complete, handOff, takeOver — Ownership and lifecycle management
• waitForAgentControl — Synchronization primitive for agent handshakes

Site Facade (Learned Site Skills)

The site facade exposes learned automation patterns and external tool integrations. Implemented in [src/learning/index.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/learning/index.ts), this facade enables agents to leverage pre-trained site-specific behaviors.

Functions include:

• skills, skillsForUrl — Retrieve available automation patterns for domains
• runTool, runBrowserTool — Execute external tools or browser-based tool chains
• learnContext — Initiate learning mode for new site interactions

Fetch Facade (Network Layer)

The fetch facade provides dual-network access through src/http.ts. It differentiates between browser-context requests and server-side fetches:

• fetch.browser(url, options) — Makes requests through the browser's network stack (respecting cookies, CORS, and authentication state)
• fetch.server(url, options) — Executes server-side HTTP requests outside the browser context

Additional Utility Facades

Beyond the five core facades, ego-browser exposes specialized utilities for debugging, documentation, and testing.

CDP (Chrome DevTools Protocol)

The cdp facade provides a low-level escape hatch to the Chrome DevTools Protocol. Agents can invoke raw CDP commands using:

await cdp('Network.enable');
await cdp('Runtime.evaluate', { expression: 'window.location.href' });

Help System

The help function, defined in [src/help-runtime.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/help-runtime.ts), generates runtime documentation for any helper function. Call help('functionName') to retrieve signature and usage information without leaving the script context.

Dynamic Loading and Testing

Two additional utilities manage extensibility and validation:

• loadAgentHelpers — Dynamically imports user-defined helpers from <agentWorkspace>/agent_helpers.js
• __testing — Exposes internal test utilities including setOverrides and decodeUnserializableJsValue (test environments only)

Standalone Helper Exports

In addition to the façade architecture, src/helpers.ts (lines 30‑50) re-exports granular utilities from driver modules for direct access:

Pointer Actions ([src/driver/pointer.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts)): click, dblclick, hover, drag, wheel, scrollIntoViewIfNeeded

Keyboard Interactions ([src/driver/keyboard.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts)): press, down, up, insertText, focus, fill, pressSequentially, check, uncheck, setChecked, selectOption, dispatchEvent

Locator Queries ([src/driver/locator.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/locator.ts)): textContent, innerText, inputValue, isChecked, isVisible, isHidden, isEnabled, isDisabled, isEditable, getAttribute, blur, boundingBox, count, allInnerTexts, allTextContents, innerHTML, evaluateLocator, evaluateAll

File and Media ([src/driver/files.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/files.js) and [src/driver/screencast.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/screencast.ts)): setInputFiles, startScreencast, stopScreencast

Network ([src/http.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts)): browserFetch, serverFetch

Practical Usage Examples

Navigate to a page and interact with elements using the page facade:

await page.goto('https://example.com');
await page.locator('button#submit').click();
const title = await page.title();

Execute a site-specific extraction tool:

const result = await site.runTool('my-site', 'extractData', { selector: '#info' });
console.log(result);

Manage isolated task spaces for multi-step workflows:

const space = await taskSpaces.new('research-space');
await taskSpaces.waitForAgentControl(space.id);
await taskSpaces.handOff(space.id, 'agent-2');

Perform authenticated API calls through the browser's network layer:

const data = await fetch.browser('https://api.example.com/protected');

Summary

• helperContext() in src/helpers.ts assembles 50+ helper functions into a cohesive API (lines 822‑850)
• Five core facades provide complete coverage: page (automation), browser (tabs), taskSpaces (isolation), site (skills), and fetch (networking)
• CDP access enables low-level browser control when high-level abstractions are insufficient
• Standalone exports from driver modules (pointer.ts, keyboard.ts, locator.ts) offer granular control for custom automation logic
• Global injection means agents call these functions directly without import statements or module resolution

Frequently Asked Questions

How do I access ego-browser helper functions in my agent script?

The helpers are automatically injected into the global scope of every agent script executed within the ego-browser environment. You can call page.goto(), browser.listTabs(), or any other helper directly without importing modules or requiring statements, as the runtime prepares the context via helperContext() before script execution.

What is the difference between page.goto and fetch.browser?

page.goto navigates the current browser tab to a URL and waits for the page to load, returning when the navigation completes. fetch.browser performs an HTTP request through the browser's network stack without changing the visible page, similar to fetch() in a web page, and returns the response body. Use goto for UI automation and fetch.browser for API calls that require the browser's cookies and authentication state.

Can I add custom helper functions to ego-browser?

Yes. The loadAgentHelpers function dynamically imports user-provided helpers from <agentWorkspace>/agent_helpers.js. Place your custom JavaScript file in the agent workspace directory, and ego-browser will load these functions into the helper context alongside the built-in facades, allowing you to extend the API with domain-specific utilities.

Where are the low-level pointer and keyboard actions implemented?

Low-level input actions are implemented in dedicated driver modules: pointer interactions (click, drag, scroll) reside in [src/driver/pointer.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts), while keyboard interactions (press, fill, selectOption) are defined in [src/driver/keyboard.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts). These are re-exported through src/helpers.ts for direct access or use via the page facade's mouse and keyboard sub-objects.

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