# The Role of `globalThis.ego` Bindings in ego-lite: How the JavaScript-Host Bridge Works

> Discover how globalThis.ego bindings in ego-lite create the JavaScript-host bridge for browser automation, task management, and CDP communication. Learn about this essential native object.

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

---

**TLDR: `globalThis.ego` is the native bridge object that ego-lite injects into the JavaScript environment, enabling all browser automation, task-space management, and CDP communication between agent-written code and the host runtime.**

ego-lite, maintained by **citrolabs** in the `citrolabs/ego-lite` repository, is designed to run inside a native "ego" host application. That host injects a **global `ego` object** onto `globalThis`, and every high-level helper in the `ego-browser` package depends on this binding to talk to the host. Understanding the role of `globalThis.ego` bindings in ego-lite is essential for anyone building browser-automation agents on top of this runtime.

## What Is the `globalThis.ego` Binding?

The `globalThis.ego` binding is a singleton object that the native ego-lite host makes available to the JavaScript sandbox. It is not a library import or a module export — it is a **globally available host API** that scripts and helper functions reference directly. All communication between the JavaScript agent layer and the native runtime flows through this object, making it the single most important architectural component in the package.

The binding exposes several categories of functionality:

- **CDP messaging** — `sendCDPMessage`, `listTabs`, and related methods for Chrome DevTools Protocol automation.
- **Task-space lifecycle** — `createTaskSpace`, `useTaskSpace`, `claimTaskSpace`, and others for managing isolated browsing contexts.
- **Utility endpoints** — `fetch`, `snapshot`, and host-implemented helpers.

## How `globalThis.ego` Enables CDP Transport

The low-level transport layer in ego-lite relies on `globalThis.ego` to route every Chrome DevTools Protocol call. The runtime detection happens in [[`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts):

```ts
export function isBrowserRuntime() {
  return Boolean(
    globalThis.ego && typeof globalThis.ego.sendCDPMessage === "function",
  );
}

```

Without the `globalThis.ego` bindings in ego-lite, this check returns `false`, and the package would fall back to a server-side transport. When the binding is present, every CDP command such as `Runtime.evaluate` is forwarded through `ego.sendCDPMessage`. This abstraction lets agent code run identically in both hosted and server modes.

## Using `globalThis.ego` for Task-Space Management

Task-space management is another critical role of the binding. Helpers such as `listTaskSpaces`, `switchTaskSpace`, and `newTaskSpace` retrieve the host API via `globalThis.ego` and forward calls like `ego.listTaskSpaces()` or `ego.createTaskSpace()`.

Below is the implementation of `listTaskSpaces` from [[`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L108):

```ts
export async function listTaskSpaces() {
  const ego = globalThis.ego;
  if (!ego || typeof ego.listTaskSpaces !== "function") {
    throw new Error("listTaskSpaces requires ego.listTaskSpaces");
  }
  return normalizeTaskSpaces(
    assertNoEgoError(await ego.listTaskSpaces(), "listTaskSpaces"),
  );
}

```

Notice the pattern: validate that `globalThis.ego` exists, call the host method, and normalize the result. This defensive check is the standard practice across all helpers in the package.

## Building Facades with `helperContext()`

The `helperContext()` function in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) constructs the public API surface — `page`, `browser`, `taskSpaces`, `site`, and `fetch` — and adds the `ego` binding to each helper set. As shown in the source:

```ts
export function helperContext(extra: any = {}) {
  const all = {
    page: createPageFacade(),
    browser: createBrowserFacade(),
    taskSpaces: createTaskSpacesFacade(),
    site: createSiteFacade(),
    fetch: { server: serverFetch, browser: browserFetch },
    cdp,
    ...extra,
  };
  return { ...all, help: … };
}

```

This facade construction means agent scripts can call `ego` methods transparently without manually reaching into `globalThis.ego` themselves. The facades are **thin wrappers** that validate the binding, forward the call, and translate raw host results into the ergonomic API exposed to agents.

## Practical Code Examples

### Listing All Task Spaces

When an agent wants to see the available task spaces, the `taskSpaces.list()` helper forwards to `globalThis.ego.listTaskSpaces()`:

```ts
import { taskSpaces } from 'ego-browser';

async function showSpaces() {
  const spaces = await taskSpaces.list();   // → calls globalThis.ego.listTaskSpaces()
  console.log(spaces);
}

```

### Sending a Raw CDP Command

The `cdp` helper injects a session ID automatically by consulting `globalThis.ego`:

```ts
import { cdp } from 'ego-browser';

async function getTitle() {
  const result = await cdp('Runtime.evaluate', { expression: 'document.title' });
  console.log(result.result.value);
}

```

### Creating an Isolated Task Space

Task-space creation forwards directly to the host runtime:

```ts
import { taskSpaces } from 'ego-browser';

async function startWorkspace() {
  const space = await taskSpaces.new('my-workspace'); // → ego.createTaskSpace()
  console.log('Created task space', space.id);
}

```

## Key Files That Implement the Bridge

| File | Purpose | Link |
|------|---------|------|
| [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) | Aggregates public helpers; retrieves `globalThis.ego` for task-space & other APIs. | [helpers.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) |
| [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) | Implements low-level CDP transport; checks for `globalThis.ego.sendCDPMessage`. | [browser-runtime.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) |
| [`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts) | Holds runtime state (session IDs, timeouts) used by the `ego` bridge. | [state.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) |
| [`src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ego-errors.ts) | Normalises error objects coming from the `ego` host. | [ego-errors.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) |

## Summary

- **`globalThis.ego`** is the runtime-injected bridge between agent JavaScript code and the native ego-lite host.
- It supplies **CDP messaging** (`sendCDPMessage`, `listTabs`), **task-space lifecycle** methods (`createTaskSpace`, `useTaskSpace`, `claimTaskSpace`), and **utility endpoints** (`fetch`, `snapshot`).
- All high-level helpers in `ego-browser` are **thin wrappers** that validate the presence of the binding, call the corresponding host method, and normalize results.
- The primary implementation lives in [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) and [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts), with supporting utilities in [`state.ts`](https://github.com/citrolabs/ego-lite/blob/main/state.ts) and [`ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/ego-errors.ts).

## Frequently Asked Questions

### Is `globalThis.ego` available in all JavaScript environments?

No. `globalThis.ego` exists only when the script runs inside the native ego host application. The `isBrowserRuntime()` check in [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) verifies that `globalThis.ego.sendCDPMessage` is a function; if it is not, the package falls back to server-based alternatives.

### What happens if `globalThis.ego` is missing?

Helpers like `listTaskSpaces()` throw explicit errors such as `"listTaskSpaces requires ego.listTaskSpaces"`. Each helper independently guards against a missing binding, so failures fail fast with clear messages.

### Can agent scripts call `globalThis.ego` directly?

Yes. The `helperContext()` function exposes the `ego` binding to each helper set, so agent scripts can call methods like `ego.createTaskSpace()` directly. When using the provided facades, however, the wrapper handles normalization and error translation for you.

### Does the binding support both browser and server fetch modes?

Yes. The `fetch` facade in `helperContext()` includes both `serverFetch` and `browserFetch`, letting the same codebase adapt depending on whether `globalThis.ego` is present. The binding itself is what distinguishes the browser runtime from server operations in `ego-lite`.