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

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, 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 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 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/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:

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

Handling the asynchronous response:

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

Capturing transport errors:

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/package/ego-browser/src/index.ts). The core logic resides in 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 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 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 for logic, 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 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.

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