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

> Explore over 50 ego-browser helper functions in citrolabs/ego-lite. Access page, browser, site, fetch, and more directly from your script context. Master web automation today.

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

---

**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/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`](https://github.com/citrolabs/ego-lite/blob/main/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/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/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/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`](https://github.com/citrolabs/ego-lite/blob/main/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/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```ts
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/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`](https://github.com/citrolabs/ego-lite/blob/main/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/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/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/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/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/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/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:

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

```

Execute a site-specific extraction tool:

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

```

Manage isolated task spaces for multi-step workflows:

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

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

```

## Summary

- **`helperContext()`** in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/pointer.ts), [`keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/keyboard.ts), [`locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/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/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/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) for direct access or use via the `page` facade's `mouse` and `keyboard` sub-objects.