Where to Find the Source Code for Ego‑Lite’s Agent‑Callable Helpers

TL;DR: The agent‑callable helpers for ego-lite are defined and aggregated in package/ego-browser/src/helpers.ts, specifically inside the helperContext() factory, which exposes page, browser, task-spaces, site, fetch, and utility helpers to any script running in the Ego‑Lite browser runtime.

If you’re using the open‑source browser‑automation framework ego-lite from the citrolabs/ego-lite repository, you may wonder where the helpers that agents can actually call are implemented. This guide walks you through the exact file locations, the internal structure of the helperContext() function, and the list of helpers available for your automation scripts.

The Core File: package/ego-browser/src/helpers.ts

All agent-callable helpers are defined in package/ego-browser/src/helpers.ts. This file builds a facade object — a set of namespaces such as page, browser, taskSpaces, site, fetch, and utility functions — that are injected into the execution environment of an agent script.

The central function is helperContext(), which constructs and returns the entire helper interface. Here’s how the file’s structure works:

• helpers.ts imports and references low‑level actions from the driver/ folder (e.g., pointer control, keyboard, navigation).
• It then creates several facade‑creating functions (e.g., createPageFacade(), createBrowserFacade(), createTaskSpacesFacade(), createSiteFacade()).
• Finally, helperContext() aggregates all these facades into a single object that is made available globally when the script runs.

How helperContext() Injects the Helpers into Agent Scripts

The entry point for the browser package is package/ego-browser/src/index.ts. When a script starts, this file calls helperContext() and exposes the returned helpers as global variables. That means every script running inside the Ego‑Lite environment can directly call functions like page.goto(), browser.listTabs(), or taskSpaces.new() without any explicit import.

The actual injection logic is simple: the result of helperContext() is assigned to the script’s global scope. This is what makes the helpers “agent‑callable” — no special setup is required from the agent side.

Helper Facades: A Breakdown of Agent‑Callable Functions

The helpers.ts file groups the helpers into logical namespaces. The table below lists the main facades and the functions each exposes:

Facade	Exported Helpers (selected)	Source
page	goto, info, url, title, locator, click, fill, press, screenshot, waitForLoadState	[helpers.ts → createPageFacade()](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L84-L108)
browser	listTabs, currentTab, switchTab, openOrReuseTab, closeTab, ensureRealTab, iframeTarget	[helpers.ts → createBrowserFacade()](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L73-L83)
taskSpaces	list, switch, new, useOrCreate, claim, complete, handOff, takeOver, waitForAgentControl	[helpers.ts → createTaskSpacesFacade()](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L85-L97)
site	skills, skillsForUrl, runTool, runBrowserTool, learnContext	[helpers.ts → createSiteFacade()](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L99-L107)
fetch	server, browser (network helpers)	[helpers.ts → helperContext().fetch](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L228-L231)
Utility	cdp, evaluate, help (dynamic help generator)	[helpers.ts → export statements](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L27-L33)

All of these helpers are ultimately returned by helperContext() and injected into the execution environment of an agent script.

Optional Custom Helpers via agent_helpers.js

Ego‑Lite also lets you mount your own agent-callable helpers by placing an agent_helpers.js file in the agent workspace (which you can retrieve via state.agentWorkspace()). This file is loaded lazily by the function loadAgentHelpers() (defined at the end of helpers.ts).

Whenever a script runs, loadAgentHelpers() checks for the file and executes it, so any functions you define inside become available. This is useful for adding project‑specific helpers without modifying the core library source.

Code Examples: Using Agent‑Callable Helpers in Your Scripts

Here are practical examples of what you can do right after the helpers are injected.

1. Basic Navigation & Interaction

// Inside an ego‑lite script (helpers are automatically available)
await page.goto('https://example.com');
await page.waitForLoadState('networkidle');
await page.locator('#login').click();
await page.locator('#username').fill('alice');
await page.locator('#password').fill('s3cr3t');
await page.locator('button[type=submit]').click();

2. Using task‑space helpers

// Create a new task space and switch to it
const ts = await taskSpaces.new('my-workspace');
await taskSpaces.switch(ts.id);

// Later, hand the space back to the user
await taskSpaces.handOff();

3. Fetching data from the browser context

// Perform a browser‑origin fetch (runs inside the page)
const json = await fetch.browser('https://api.example.com/data', {
  method: 'GET',
});
console.log(json);

4. Loading a custom agent helper

// Assuming you placed `agent_helpers.js` in the agent workspace
const extra = await loadAgentHelpers();
if (extra.myHelper) {
  await extra.myHelper(); // custom logic defined by you
}

5. Dynamically getting help text

// Retrieve documentation for the `page` facade
const docs = help('page');
console.log(docs);

Key Files in the Helper System

The following paths are essential when exploring the source code of the agent‑callable helpers:

File / Folder	Purpose
package/ego-browser/src/helpers.ts	Central definition of all agent‑callable helpers (helperContext)
package/ego-browser/src/index.ts	CLI entry point that injects the helper context into scripts
package/ego-browser/src/state.ts	Singleton runtime state used by helpers (e.g., workspace path)
skills/ego-browser/agent_helpers.js (runtime‑generated)	Optional user‑supplied helpers loaded at runtime (see loadAgentHelpers())
package/ego-browser/src/driver/*	Implementation of low‑level actions referenced by the helpers (pointer, keyboard, nav, etc.)

Summary

• The source code for ego-lite’s agent-callable helpers lives in package/ego-browser/src/helpers.ts.
• helperContext() in that file returns a facade object containing page, browser, taskSpaces, site, fetch, and utility helpers.
• The entry point src/index.ts injects these helpers globally into every agent script‑‑no imports required.
• Custom helpers can be added by placing an agent_helpers.js file in the agent workspace; it’s loaded by loadAgentHelpers().
• The full source includes the driver/ folder for low‑level implementation details.

Frequently Asked Questions

Where exactly is the page helper defined in ego‑lite?

The page facade is created in package/ego-browser/src/helpers.ts within the createPageFacade() function (lines 84–108). It exports methods like goto(), locator(), click(), and screenshot().

Can I add custom agent‑callable helpers to ego-lite?

Yes. Create an agent_helpers.js file in the agent workspace (as defined by state.agentWorkspace()). The loadAgentHelpers() function loads and returns the exported helper object, so your custom functions become available inside scripts.

How does helperContext() make helpers available to the agent script?

The helpers.ts file calls helperContext() to build the complete facade object, and then src/index.ts injects that object into the global scope of the agent script. That way, page, browser, taskSpaces, etc., appear as global variables without any import statement.

What is the purpose of the driver/ folder in the helper system?

The driver/ folder contains low‑level implementations that the high‑level helpers rely on, such as pointer control, keyboard input, and navigation. It provides the actual browser automation primitives that make the helper functions work.

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