# Understanding helperContext() in ego-lite: The Agent API Foundation

> Discover how helperContext() in ego-lite creates the unified Playwright-style API for your automation scripts and agents. Learn its core function today.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-08-23

---

**`helperContext()` is the central factory function that constructs the unified, Playwright-style API surface exposed to automation scripts and agents running inside the ego-lite runtime.**

The `helperContext()` function serves as the architectural backbone of the ego-lite browser automation framework. Located in the core helpers module, this function assembles the high-level JavaScript API that agents interact with when controlling browser sessions. By centralizing the creation of browser facades and utility helpers, `helperContext()` in ego-lite ensures that every execution context—whether launched from the command line or embedded as an SDK—presents an identical, well-documented interface.

## What helperContext() Does in ego-lite

`helperContext()` acts as the single source of truth for ego-lite's public helper surface. According to the source code in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), the function instantiates wrapper objects that translate low-level driver operations into intuitive, Playwright-compatible method calls.

The function constructs five primary facades:

- **`page`**: Provides methods for navigation, element interaction, and content extraction
- **`browser`**: Manages browser-level operations and contexts  
- **`taskSpaces`**: Handles isolated workspace management via `useOrCreate()`
- **`site`**: Offers site-specific skill detection and execution
- **`fetch`**: Enables network request capabilities

Each facade wraps underlying driver modules—including **pointer**, **keyboard**, **navigation (nav)**, and **observation (observe)** systems—presenting a unified interface that abstracts away implementation complexities.

## The Playwright-Style Facade Architecture

The facades generated by `helperContext()` deliberately mirror the Playwright API design, allowing developers familiar with Playwright to immediately leverage ego-lite. For example, the `page` facade exposes methods like `goto()`, `locator()`, and `title()`, which internally delegate to the framework's lower-level drivers defined in the helpers module.

This abstraction layer resides in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (around line 822), where the function constructs these objects and binds them to the active browser context. The result is a **consistent programming model** where agents interact with high-level helpers rather than managing raw driver instances directly.

## Self-Documenting API with the help() Method

Beyond creating functional facades, `helperContext()` injects a **`help`** function into the returned helper object. This method generates runtime documentation for all available helpers by delegating to ego-lite's internal help engine.

When called on any facade—for example, `page.help()`—the function returns structured documentation describing available methods, their parameters, and usage examples. This self-documenting capability ensures that agents can discover capabilities programmatically without consulting external documentation.

## Synchronizing CLI and SDK Execution Contexts

One critical architectural guarantee provided by `helperContext()` is the elimination of API drift between execution environments. The function is invoked in two primary locations:

1. **CLI Entry Point**: In [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) (lines 35-38), `helperContext()` builds the execution context for command-line script runs
2. **SDK Installation**: In [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts), the `installEgoSdk` function utilizes `helperContext()` to configure the embedded runtime

By sourcing helpers from the same factory function, ego-lite guarantees that **scripts behave identically** whether executed via the CLI or imported as an SDK module. Any new helper added to the core automatically propagates to both contexts.

## Extending with Agent-Specific Helpers

`helperContext()` supports extensibility through agent-specific helper loading. The function integrates helpers from [`agent_helpers.js`](https://github.com/citrolabs/ego-lite/blob/main/agent_helpers.js) via `loadAgentHelpers`, merging project-specific utilities into the default helper surface.

This mechanism allows individual projects to extend the ego-lite API without modifying core source code. Custom helpers loaded through this pathway receive the same facade treatment and documentation capabilities as built-in helpers, maintaining consistency across the extended API.

## Practical Usage Examples

The following patterns demonstrate how scripts interact with the helper context created by `helperContext()`:

```javascript
// Navigation and content extraction via the page facade
await page.goto('https://example.com');
const title = await page.title();
console.log('Page title:', title);

// Playwright-style locator interactions
await page.locator('button.submit').click();
const greeting = await page.locator('h1').innerText();
console.log('Greeting:', greeting);

// Task-space management for isolated workspaces
const space = await taskSpaces.useOrCreate('my-space');
console.log('Using task space:', space.name);

// Site-specific skill detection and execution
const skills = await site.skills(); // auto-detects current URL
if (skills.length) {
  const result = await site.runTool('my-site', 'extractData', { selector: '.data' });
  console.log('Extracted:', result);
}

// Runtime documentation access
console.log(page.help()); // prints documentation for page methods

```

These examples illustrate how `helperContext()` aggregates disparate browser automation capabilities into a cohesive, agent-friendly interface.

## Summary

- `helperContext()` in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) serves as the central factory for ego-lite's public API surface, creating facades that wrap low-level browser drivers
- The function generates Playwright-compatible helpers (`page`, `browser`, `taskSpaces`, `site`, `fetch`) that abstract pointer, keyboard, navigation, and observation systems
- A built-in `help()` method provides runtime documentation generation, making the API self-discoverable for automation agents
- By powering both the CLI entry point ([`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts)) and SDK installation ([`index.ts`](https://github.com/citrolabs/ego-lite/blob/main/index.ts)), `helperContext()` ensures perfect API parity between command-line and embedded execution contexts
- The function supports extension through `loadAgentHelpers`, allowing projects to inject custom utilities into the standard helper surface without modifying core ego-lite code

## Frequently Asked Questions

### What file contains the definition of helperContext() in ego-lite?

The `helperContext()` function is defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) at approximately line 822. This module constructs all facade objects and configures the help documentation system before returning the complete helper surface to callers.

### How does helperContext() ensure the CLI and SDK APIs remain identical?

`helperContext()` is invoked by both the CLI entry point in [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) (lines 35-38) and the SDK installer in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). By sourcing the helper surface from the same factory function, ego-lite guarantees that any new capability or bug fix automatically applies to both execution contexts, preventing API drift.

### Can I add custom helpers to the ego-lite runtime without modifying core files?

Yes. `helperContext()` loads project-specific helpers from [`agent_helpers.js`](https://github.com/citrolabs/ego-lite/blob/main/agent_helpers.js) through the `loadAgentHelpers` function. These custom helpers are merged into the standard helper object, receiving the same facade treatment and documentation support as built-in helpers, allowing you to extend the API surface for specific automation projects.

### What is the purpose of the help() method attached to ego-lite helpers?

The `help()` method provides runtime introspection capabilities for the helper facades created by `helperContext()`. When called on any facade (such as `page.help()` or `taskSpaces.help()`), it returns structured documentation describing available methods and parameters, enabling agents to discover capabilities programmatically without external documentation references.