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

> Understand ego-browser/src/index.ts in Ego-Lite. This file acts as a dual-mode entry point for the SDK, enabling CLI execution or API injection into your host environment.

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

---

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

```javascript
// 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.

```javascript
// 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.

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/index.ts) module orchestrates functionality defined across the ego-browser package:

| File | Role in Ecosystem |
| --- | --- |
| [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) | Central entry point; CLI driver and SDK installer (current file) |
| [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) | Generates the helper context injected by `installEgoSdk` |
| [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts) | Executes heredoc scripts inside the async wrapper for CLI mode |
| [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) | Core CDP transport, session handling, and target management |
| [`src/output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/output-sink.ts) | Buffered output sink used by the indexed logging system |
| [`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts) | Emits version-update notices forwarded during SDK installation |
| [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) for context generation and [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) for CDP communication, providing agents with high-level browser control without manual protocol handling.

## Frequently Asked Questions

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