Ego-Browser Public Helpers for Agent Scripts: Complete API Reference (2024)

The ego-browser package exposes 40+ public helpers to agent scripts through a globally injected SDK, including CDP methods, pointer/keyboard actions, navigation controls, observation tools, waits, and site-specific skill runners—all defined in src/helpers.ts and installed via installEgoSdk().

The ego-browser package from the citrolabs/ego-lite repository provides a thin SDK that injects a helper context into the global runtime for agent scripts. These ego-browser public helpers enable browser automation, observation, navigation, and AI-powered site interactions without requiring external dependencies. All helpers are defined in src/helpers.ts and re-exported from src/index.ts, making them available as top-level globals like click, page, and site.skills.

This guide covers every public helper grouped by functional area, with implementation details from the source code and practical usage examples.

---

Core CDP and Evaluation Helpers

The lowest-level helpers provide direct access to the Chrome DevTools Protocol (CDP) and raw JavaScript evaluation.

Helper	Purpose	Source
cdp	Send raw CDP commands to the browser	src/helpers.ts lines 5–9
evaluate	Execute JavaScript in the page context	src/helpers.ts lines 5–9

These form the foundation that higher-level helpers build upon.

---

Pointer and Mouse Action Helpers

All mouse and pointer interactions are imported from src/driver/pointer.js and re-exported through the main helpers module.

// Click with options
await click('#submit', { button: 'left', modifiers: ['Control'] });

// Drag and drop
await drag('#source', '#target');

// Hover with precise positioning
await hover('.tooltip-trigger', { position: { x: 10, y: 5 } });

// Scroll element into view if needed
await scrollIntoViewIfNeeded('.lazy-image');

Available pointer helpers:

• click — Single click with configurable button and modifiers
• dblclick — Double-click action
• hover — Mouse hover with optional positioning
• drag — Drag-and-drop between elements
• wheel — Scroll wheel events
• scrollIntoViewIfNeeded — Conditional scroll into viewport

Defined in src/helpers.ts lines 30–36.

---

Keyboard and Input Helpers

Text entry, form interaction, and keyboard events come from src/driver/keyboard.js.

// Type with human-like delays
await fill('#search', 'ego-browser helpers', { timeout: 5000 });

// Press special keys
await press('Enter');
await press('Control+a');

// Sequential keystroke simulation
await pressSequentially('#otp-input', '123456', { delay: 100 });

// Checkbox state management
await check('#terms');
await uncheck('#newsletter');
await setChecked('#remember-me', true);

// Focus and dispatch custom events
await focus('#email');
await dispatchEvent('#form', 'submit');

Full list of input helpers:

• press, down, up — Key press, hold, and release
• insertText — Direct text insertion
• focus — Element focus
• fill — Clear and type into field
• pressSequentially — Keystroke-by-keystroke typing
• check, uncheck, setChecked — Checkbox manipulation
• selectOption — Dropdown selection
• dispatchEvent — Custom DOM event firing

Defined in src/helpers.ts lines 37–49.

---

Locator and Element Query Helpers

Extract data from page elements using helpers from src/driver/locator.js.

// Basic text extraction
const heading = await textContent('h1');
const visibleText = await innerText('.article-body');

// Form state inspection
const emailValue = await inputValue('#email');
const isAgreed = await isChecked('#consent');

// Multiple element handling
const allLinks = await allTextContents('a[href]');
const count = await count('.list-item');

// Evaluate within element context
const computedStyle = await evaluateLocator('.banner', el => getComputedStyle(el).height);

Available locator utilities:

• textContent, innerText — Text extraction variants
• inputValue — Current form field value
• isChecked — Checkbox state
• getAttribute — DOM attribute retrieval
• count — Element count matching selector
• allInnerTexts, allTextContents — Batch text extraction
• innerHTML — Raw HTML content
• evaluateLocator, evaluateAll — Custom JS execution in element scope

Defined in src/helpers.ts lines 50–70.

---

Navigation and Tab Control Helpers

Manage browser tabs, frames, and navigation state via src/driver/nav.js.

// Tab management
const tabs = await listTabs();
await switchTab(tabs[1].id);
await closeTab(tabs[0].id);

// Navigation with error handling
await goto('https://example.com', { waitUntil: 'networkidle' });
await openOrReuseTab('https://docs.example.com');

// Frame/iframe targeting
const frame = await iframeTarget('#preview-frame');

// Ensure we're on a real tab (not devtools/extension)
await ensureRealTab();

// Page metadata
const info = await pageInfo();
console.log(info.url, info.title);

Navigation helpers include:

• INTERNAL_URL_PREFIXES — Constants for internal URL schemes
• pageInfo — Current page metadata
• listTabs, currentTab — Tab enumeration
• switchTab, openOrReuseTab, closeTab — Tab lifecycle
• goto — Navigation with load state waiting
• ensureRealTab — Validation helper
• iframeTarget — Frame context targeting

Defined in src/helpers.ts lines 71–82.

---

Observation and Screenshot Helpers

Capture page state for analysis or debugging through src/driver/observe.js.

// Structured accessibility snapshot
const snap = await snapshot(); // Returns AX tree for LLM consumption
const raw = await snapshotRaw(); // Unprocessed snapshot data

// Visual capture
await screenshot({ path: 'debug.png', fullPage: true });

// Coordinate calculation for pointer actions
const center = await elementCenter('#target');

// Event drainage for synchronization
await drainEvents();

Observation helpers:

• snapshot — Accessibility tree snapshot (AI-optimized format)
• snapshotRaw — Raw snapshot without processing
• screenshot — PNG capture with sizing options
• elementCenter — Coordinate calculation
• drainEvents — Process pending browser events

Defined in src/helpers.ts lines 83–89.

---

Wait and Synchronization Helpers

Control timing and conditions for action execution via src/driver/waits.js.

// Explicit delays
await waitForTimeout(1000); // 1 second

// Page state waits
await waitForLoadState('domcontentloaded');
await waitForLoadState('networkidle');

// Element availability
await waitForSelector('.dynamic-content', { timeout: 10000 });

// Custom conditions
await waitForFunction(() => window.__appReady === true, { polling: 100 });

// Network waits
await waitForURL(/\/dashboard/);
await waitForRequest('**/api/session');
await waitForResponse(req => req.url().includes('/api/data'));

Wait helpers:

• waitForTimeout — Fixed delay
• waitForLoadState — Page lifecycle events
• waitForSelector — Element availability
• waitForFunction — Custom predicate polling
• waitForURL — Navigation pattern matching
• waitForRequest, waitForResponse — Network event waiting

Defined in src/helpers.ts lines 90–98.

---

File Upload and Screencast Helpers

Specialized utilities for file handling and video recording.

// File upload
await setInputFiles('#file-input', ['/path/to/upload.pdf']);

// Screencast recording
await startScreencast({ outputPath: '/recordings/session.webm' });
// ... perform actions ...
await stopScreencast();

Helper	Source
setInputFiles	src/driver/files.js via src/helpers.ts line 99
startScreencast, stopScreencast	src/driver/screencast.js via src/helpers.ts lines 100–101

---

Network Fetch Helpers

HTTP requests from both browser and Node contexts.

// Browser-context fetch (uses page's cookies, headers)
const html = await browserFetch('https://api.example.com/data', {
  headers: { 'Accept': 'application/json' }
});

// Server-side fetch (bypasses CORS, uses proxy config)
const proxyData = await serverFetch('https://internal.service/metrics');

Source: src/http.js via src/helpers.ts lines 18–22.

---

Task-Space Management Helpers

Advanced session isolation and handoff controls implemented directly in src/helpers.ts starting at line 107.

// Create isolated automation context
const space = await newTaskSpace('invoice-processing');
await switchTaskSpace(space.id);

// Or reuse existing
const existing = await useOrCreateTaskSpace('customer-onboarding');

// Hand control to human user
await handOffTaskSpace({ message: 'Please solve the CAPTCHA' });

// Resume after human intervention
await waitForAgentControl();
await takeOverTaskSpace();

// Cleanup
await completeTaskSpace(space.id);

Task-space API:

• listTaskSpaces — Enumerate active spaces
• switchTaskSpace — Change active context
• newTaskSpace, useOrCreateTaskSpace — Space acquisition
• claimTaskSpace — Exclusive access locking
• completeTaskSpace — Clean termination
• handOffTaskSpace, takeOverTaskSpace — Human/AI control transfer
• waitForAgentControl — Resume signal

---

Site-Skill and Learning Helpers

AI-powered site-specific automation through learned patterns, defined near lines 64–78 in src/helpers.ts.

// Discover available skills for current URL
const skills = await siteSkillsForUrl();
console.log(skills); // ['searchProducts', 'addToCart', 'checkout']

// Invoke learned skill
const result = await runSiteTool('github', 'searchRepos', {
  query: 'ego-lite',
  language: 'typescript'
});

// Browser-side skill execution
await runSiteBrowserTool('linkedin', 'sendConnectionRequest', {
  profileUrl: 'https://linkedin.com/in/example'
});

// Context enrichment for skill learning
await learnContext(['.product-card', '.price', '.add-to-cart']);

Site-skill helpers:

• siteSkillsForUrl — Skill discovery for URL
• siteSkills — Direct skill access
• runSiteTool — Node-side skill execution
• runSiteBrowserTool — Browser-context skill execution
• learnContext — Feedback for skill improvement

---

SDK Installation and Helper Context

Helpers are not automatically global—they must be installed via the SDK entry point.

According to src/index.ts lines 51–63, installEgoSdk() performs the injection:

// Inside ego-browser runtime
import { installEgoSdk } from 'ego-browser';

// Installs all helpers as globals: click, page, site.skills, etc.
installEgoSdk();

// Now helpers are available globally
await goto('https://example.com');
await click('button');

The helperContext() function (line 822 in src/helpers.ts) builds the complete facade object containing all exported helpers. Additional utilities include:

• loadAgentHelpers (lines 52–65) — Load custom helper extensions
• __testing (line 667) — Internal testing utilities (not for production use)

---

Summary

The ego-browser public helpers provide a comprehensive browser automation API for agent scripts:

• 40+ documented helpers across 11 functional categories
• Zero external dependencies once SDK is installed
• Global availability after installEgoSdk() runs
• Layered architecture from low-level CDP to high-level site skills

Key implementation files to reference:

• src/helpers.ts — Central definition and export hub
• src/index.ts — SDK installation and global injection
• src/driver/*.js — Core automation implementations
• src/http.js — Network utilities
• src/learning/* — Site-skill discovery and execution

---

Frequently Asked Questions

How do I access ego-browser helpers in my agent script?

Call installEgoSdk() from ego-browser at script startup. This injects all helpers into the global scope as properties of helperContext(), making functions like click, goto, and snapshot available without imports, as implemented in src/index.ts lines 51–63.

What is the difference between browserFetch and serverFetch?

browserFetch executes requests within the page context, inheriting cookies, session storage, and CORS policies. serverFetch runs from the Node.js side, bypassing CORS and using configured proxy settings, making it suitable for internal API calls.

Can I extend ego-browser with custom helpers?

Yes. Use loadAgentHelpers() (defined in src/helpers.ts lines 52–65) to load additional helper modules. Custom helpers integrate into the same helperContext() facade and become available to agent scripts after SDK installation.

How do site skills work in ego-browser?

Site skills are AI-learned automation patterns for specific websites. The siteSkillsForUrl() function discovers available skills, while runSiteTool() and runSiteBrowserTool() execute them in Node or browser contexts respectively. The learnContext() helper provides feedback to improve skill accuracy over time.

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