What Is `package/ego-browser/src/index.ts` in Ego-Lite? CLI Driver and SDK Installer Explained

The index.ts file in package/ego-browser/src/ serves as the dual-mode entry point for the ego-browser SDK, either executing helper-driven scripts directly via CLI or injecting the full automation API into a host environment through the installEgoSdk function.

The package/ego-browser/src/index.ts module is the central gateway for the ego-browser SDK within the Ego-Lite system. This TypeScript entry point dynamically determines its execution context—running as a standalone command-line processor when invoked directly, or installing state-aware automation helpers when required as a library. Understanding this file is critical for developers building browser automation agents that leverage Ego-Lite's high-level API over underlying Chrome DevTools Protocol (CDP) plumbing.

Dual-Purpose Architecture: CLI Driver vs. SDK Installer

The module implements two complementary execution paths detected at runtime. The logic branch occurs near the end of the file where isDirectCli() checks whether the process was invoked directly via Node.js.

Command-Line Execution Path (isDirectCli)

When the module is executed directly (e.g., node ego-browser), the CLI path activates. The isDirectCli() check (lines 75‑78) detects this execution mode and triggers runMain() (lines 56‑58), which evaluates helper-driven code supplied via STDIN within an async context. This allows agent scripts to run as one-off processes without requiring a persistent host application.

// Example: Executing a script via CLI
echo "await page.goto('https://example.com'); await click('button')" | \
  node $(npm root)/ego-browser/src/index.js

SDK Installation Path (installEgoSdk)

When the module is required by a host application—the default case when the browser runtime embeds the SDK—it exposes the installEgoSdk function (lines 44‑48). This function injects all public helper methods onto a target object, typically globalThis, enabling agents to call high-level automation primitives without manual CDP configuration.

// Example: Installing the SDK in a host application
import { installEgoSdk } from 'ego-browser';

installEgoSdk();  // Installs helpers on globalThis
await page.goto('https://example.com');
await click('a[href="/login"]');

Core SDK Installation Mechanisms

The installEgoSdk function (lines 48‑65) orchestrates several subsystems to create a fully-featured, state-aware automation environment.

Helper Context and Async Wrapping (wrapReady)

The SDK builds the helper context via helpers.helperContext() and wraps asynchronous helpers using wrapReady (lines 19‑38). This ensures that all async operations execute only after the optional ready signal resolves, preventing race conditions during browser initialization.

Buffered Logging and Output Capture (createBufferedLog)

To capture diagnostic output without interfering with host communication, the module installs a buffered logging sink via createBufferedLog (lines 67‑73). This intercepts console.log calls and stores them for later flushing, ensuring that agent logs remain accessible even in embedded contexts where standard output might be redirected.

// Example: Custom buffered logger configuration
import { installEgoSdk } from 'ego-browser';

installEgoSdk(globalThis, {
  cliLog: (msg) => myLoggingService.send(msg)
});

Session Management and Method Wrapping (wrapInvalidating)

The SDK wraps mutating ego-runtime methods—such as task-space operations and session management—using wrapInvalidating (lines 81‑99). This automatically invalidates the session state when destructive operations occur, ensuring that the agent maintains accurate internal state without manual cache management.

Tab Creation and Target Management (wrapCreateTab)

Tab lifecycle management is handled by wrapCreateTab (lines 103‑118), which intercepts calls to createTab and manages the "preferred target" state. This wrapper ensures that new tabs are properly registered within the session and that subsequent operations target the correct browser context automatically.

Exposing Ego Runtime Methods (exposeEgoMethods)

Finally, exposeEgoMethods (lines 121‑142) maps the remaining untouched ego-runtime methods directly onto the target object. This exposes core primitives like goto, snapshot, and element resolution utilities while maintaining the buffered logging and session invalidation hooks established earlier in the installation process.

Relationship to Core Runtime Files

The index.ts module orchestrates functionality defined across the ego-browser package:

File	Role in Ecosystem
src/index.ts	Central entry point; CLI driver and SDK installer (current file)
src/helpers.ts	Generates the helper context injected by installEgoSdk
src/run.ts	Executes heredoc scripts inside the async wrapper for CLI mode
src/browser-runtime.ts	Core CDP transport, session handling, and target management
src/output-sink.ts	Buffered output sink used by the indexed logging system
src/update-notice.ts	Emits version-update notices forwarded during SDK installation
src/element-resolver.ts	Resolves CSS/XPath locators for helper methods like click
src/driver/*	Low-level driver implementations (keyboard, mouse, navigation)

These files constitute the runtime layer that index.ts initializes, abstracting CDP complexity into the clean click, goto, and snapshot API available to automation agents.

Summary

• package/ego-browser/src/index.ts functions as the dual-mode entry point for Ego-Lite's browser automation SDK.
• CLI mode (isDirectCli → runMain): Executes helper-driven scripts supplied via STDIN when the module runs directly.
• SDK mode (installEgoSdk): Injects automation helpers onto globalThis or a specified target object when required as a library.
• Key subsystems: Async-ready wrapping (wrapReady), buffered logging (createBufferedLog), session invalidation (wrapInvalidating), and tab management (wrapCreateTab).
• Integration: Works with helpers.ts for context generation and browser-runtime.ts for CDP communication, providing agents with high-level browser control without manual protocol handling.

Frequently Asked Questions

How does index.ts determine whether to run as CLI or install as SDK?

The module checks isDirectCli() (lines 75‑78) to detect if it was invoked directly via Node.js with STDIN input. If true, it calls runMain() to execute the script; otherwise, it exports installEgoSdk for library consumption.

What helper methods become available after calling installEgoSdk?

The function exposes high-level automation primitives including click, goto, snapshot, and task-space utilities. These methods are built via helpers.helperContext() and wrapped with session management and logging logic before installation onto the target object.

Why does the SDK use buffered logging instead of standard console output?

The createBufferedLog mechanism (lines 67‑73) captures console.log output into a buffer for later flushing. This prevents diagnostic messages from corrupting structured communication between the agent and host runtime, particularly important when Ego-Lite operates as an embedded browser automation engine.

Can I customize the target object where helpers are installed?

Yes. While installEgoSdk() defaults to globalThis, you can pass any object as the first argument to install helpers onto a specific namespace. The second argument accepts an options object—including cliLog—for customizing logging behavior during installation.

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