# What CDP Methods Are Exposed by the ego‑lite Browser’s `globalThis.ego` Object?

> Discover the three Chrome DevTools Protocol CDP methods exposed by ego-lite's globalThis.ego: sendCDPMessage, onCDPMessage, and onSendCDPMessageError. Learn how to handle CDP messages.

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

---

**The `ego‑lite` browser exposes exactly three Chrome DevTools Protocol (CDP) members through `globalThis.ego`: `sendCDPMessage` for transmitting raw JSON payloads, and two callbacks—`onCDPMessage` and `onSendCDPMessageError`—for handling asynchronous responses and transport‑level errors.**

The `ego‑lite` browser, maintained in the `citrolabs/ego-lite` repository, provides a minimal bridge for agents to interact directly with the Chrome DevTools Protocol. Unlike high‑level SDK wrappers, the `globalThis.ego` object offers only the fundamental primitives required to construct, dispatch, and receive raw CDP commands. These exposed methods serve as the foundation upon which all higher‑level browser automation logic is built.

## The Core CDP Interface on `globalThis.ego`

According to the source in [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts), the CDP bridge deliberately restricts surface area to three members. These constitute the only direct CDP interface available to scripts executing within the browser context.

### `sendCDPMessage(payload: string)`

The **`sendCDPMessage`** method functions as the primary entry point for all CDP communication. Defined in [[`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) lines 27‑28](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts#L27-L28), this function accepts a JSON string payload that must contain an `id`, `method`, and optional `params` and `sessionId`.

When invoked, the runtime serializes the payload and transmits it to the browser’s DevTools agent. If the task is inactive or the session has terminated, the call triggers the `onSendCDPMessageError` callback rather than throwing a synchronous exception.

### `onCDPMessage` Callback

The **`onCDPMessage`** property is a configurable callback invoked by the runtime whenever a CDP response or event arrives. As implemented in [[`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) lines 44‑46](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts#L44-L46), agents assign a function to this property to parse incoming messages.

The callback receives a single string argument—the raw JSON response—which agents must parse to correlate with the original request `id` or handle spontaneous CDP events emitted by the browser.

### `onSendCDPMessageError` Callback

The **`onSendCDPMessageError`** callback handles transport failures and session lifecycle errors. According to the same source region 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#L45-L46), this function is triggered when `sendCDPMessage` cannot complete its operation, such as when the underlying browser context is destroyed or the task is no longer active.

## Practical Usage Examples

The following patterns demonstrate the minimal workflow required to execute CDP commands through `globalThis.ego`.

Sending a navigation command:

```javascript
const payload = JSON.stringify({
  id: 1,
  method: "Page.navigate",
  params: { url: "https://example.com" }
});
globalThis.ego.sendCDPMessage(payload);

```

Handling the asynchronous response:

```javascript
globalThis.ego.onCDPMessage = (msg) => {
  const data = JSON.parse(msg);
  if (data.id === 1) {
    console.log("Navigation result:", data.result);
  }
};

```

Capturing transport errors:

```javascript
globalThis.ego.onSendCDPMessageError = (error) => {
  console.error("CDP transport failed:", error);
};

```

## Implementation Architecture and Source Locations

The CDP bridge is installed when the SDK initializes `globalThis.ego` in [[`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). The core logic resides in [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts), where the raw CDP primitives are defined.

Internal drivers verify the presence of `sendCDPMessage` before executing low‑level operations. In [[`src/driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/pointer.ts) line 460](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts#L460), the pointer implementation checks for the CDP bridge availability prior to dispatching input events. Similarly, [[`src/driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/keyboard.ts) line 667](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts#L667) performs equivalent validation for keyboard synthesis.

These checks confirm that `sendCDPMessage` serves as the foundational dependency for all CDP‑backed functionality within the `ego‑lite` runtime.

## Summary

- **`sendCDPMessage`** is the sole method for transmitting raw CDP JSON payloads to the browser DevTools agent.
- **`onCDPMessage`** provides the asynchronous callback mechanism for receiving CDP responses and events.
- **`onSendCDPMessageError`** handles transport‑level failures when the CDP bridge cannot deliver messages.
- Higher‑level abstractions like `browser.cdp` or `browser.listTabs` are constructed atop these three primitives but are not themselves exposed on `globalThis.ego`.
- The implementation spans [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) for logic, [`index.ts`](https://github.com/citrolabs/ego-lite/blob/main/index.ts) for global installation, and driver files for runtime validation.

## Frequently Asked Questions

### Can I use `globalThis.ego` to access all Chrome DevTools Protocol domains?

No. The `globalThis.ego` object exposes only the transport primitives (`sendCDPMessage` and the two callbacks). While you can construct and send JSON payloads for any valid CDP domain (such as `Page`, `Runtime`, or `Network`), you must manually format the commands and parse responses. The object does not provide pre‑built methods for specific CDP domains.

### What happens if I call `sendCDPMessage` when the browser session is closed?

If the session is inactive or the task has ended, `sendCDPMessage` will not throw a synchronous exception. Instead, the runtime invokes the `onSendCDPMessageError` callback with details about the failure. This asynchronous error handling design prevents blocking script execution while ensuring agents can react to lifecycle changes.

### Are there TypeScript definitions available for the `globalThis.ego` CDP interface?

The `ego‑lite` source defines these members in [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) with minimal typing. The `sendCDPMessage` parameter is typed as `string`, and both callbacks accept function types with string arguments. For strict typing, you would extend the global interface declarations to match the expected CDP request and response schemas provided by the Chrome DevTools Protocol documentation.

### How does `ego‑lite` differ from Puppeteer or Playwright’s CDP access?

Unlike Puppeteer or Playwright, which expose high‑level abstraction classes over CDP, `ego‑lite` provides a minimal bridge directly on `globalThis.ego` accessible from within the browser context. This approach allows agents to issue raw CDP commands without external Node.js process orchestration, but requires manual payload construction and response correlation using the three exposed members.