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

> Find ego-lite agent-callable helpers source code in helpers.ts. Discover page, browser, task-spaces, site, fetch, and utility helpers for the Ego-Lite runtime.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: api-reference
- Published: 2026-08-22

---

**TL;DR:** The agent‑callable helpers for `ego-lite` are defined and aggregated in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)

All agent-callable helpers are defined in **[`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/agent_helpers.js)

Ego‑Lite also lets you mount your own agent-callable helpers by placing an **[`agent_helpers.js`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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

```ts
// 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

```ts
// 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

```ts
// 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

```ts
// 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

```ts
// 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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Central definition of all agent‑callable helpers (`helperContext`) |
| [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | CLI entry point that injects the helper context into scripts |
| [`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) | Singleton runtime state used by helpers (e.g., workspace path) |
| [`skills/ego-browser/agent_helpers.js`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) file calls `helperContext()` to build the complete facade object, and then [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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.