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

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, 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 (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 (lines 35-38), helperContext() builds the execution context for command-line script runs
2. SDK Installation: In 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 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():

// 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 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) and SDK installation (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 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 (lines 35-38) and the SDK installer in 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 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.

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