Understanding the Shared Mutable Runtime State in ego-lite

The shared mutable runtime state in ego-lite is a singleton object defined in package/ego-browser/src/state.ts that centralizes session tracking, CDP transport configuration, and runtime helpers, allowing coordinated mutation across the browser-automation harness via the setOverrides API.

The citrolabs/ego-lite browser automation framework relies on a single source of truth for runtime coordination. This shared mutable runtime state acts as a globally accessible singleton that modules import to access live session data, network configuration, and platform utilities, ensuring consistent behavior during complex CDP (Chrome DevTools Protocol) interactions.

Where the Shared Mutable Runtime State Is Defined

The state is declared and exported from package/ego-browser/src/state.ts. According to the source code, lines 24–40 declare the singleton object itself, while lines 42–56 expose the public API including mutation helpers. The object is exported as state and imported wherever runtime coordination is required.

Because it is imported as a module singleton rather than instantiated per request, every component sees the same live data. This design enables snapshot management, coordinated session handling, and consistent helper behavior throughout the runtime.

Structure of the Runtime State Object

The state object contains distinct categories of runtime data that mutate as the browser session progresses:

Transport and CDP Configuration

• send – The request sender function, defaulting to defaultSend, which forwards CDP messages to the browser runtime.
• cdpOverride – An optional override object for custom CDP handling.

Session Tracking Fields

• sessionId – The active session identifier.
• sessionTargetId – The target ID associated with the current session.
• sessionAt – Timestamp of session initiation.
• sessionInflight – Tracks pending operations.
• preferredTargetId – User-preferred target override.

Platform and Environment

• platform – Runtime platform information.
• agentWorkspace – Workspace resolution path, populated via src/env.ts.

Utility Helpers

• now – Timestamp generation utility.
• sleep – Async delay function.
• writeFile – File system helper for output operations.

Configuration Defaults

• defaultTimeout – Global timeout setting for operations.
• networkDomainEnabled – Flag controlling network domain instrumentation.

How Mutability and Override Works

The state is intentionally mutable to support testing and dynamic configuration. The setOverrides function temporarily replaces parts of the state object and returns a restoration closure.

When you invoke setOverrides, you pass a partial state object containing only the keys you wish to replace—commonly the send function for mocking CDP responses during unit tests. The function snapshots the previous values, applies your overrides, and returns a restore function that reverts the state to its original configuration when called.

This pattern is thread-safe for the single-threaded JavaScript runtime and ensures that global behavior can be modified for specific test scopes without side effects on subsequent operations.

Where the State Is Consumed Across the Codebase

Multiple modules import the state singleton to coordinate behavior:

• src/helpers.ts – Provides high-level automation helpers that rely on state utilities like sleep and now.
• src/ref-state.ts – Uses state.sessionId and related fields to track reference mapping across JavaScript snapshots.
• src/browser-runtime.ts – Invokes state.send (or its override) to forward CDP commands to the embedded browser.
• src/env.ts – Supplies agentWorkspace and environment loading logic consumed by the state object.

Practical Code Examples

Reading the Current Session ID

import { state } from 'ego-browser/src/state.js';

const currentSession = state.sessionId;
console.log('Active session:', currentSession);

Overriding the Send Function for Testing

import { setOverrides } from 'ego-browser/src/state.js';

const restore = setOverrides({
  send: async (req) => ({ result: { mocked: true } }),
});

await someHelperThatCallsSend();   // will receive the mocked response

restore(); // revert to the original implementation

Using Built-in Helper Utilities

import { state } from 'ego-browser/src/state.js';

console.log('Timestamp:', state.now());

await state.sleep(500);  // pause for 0.5 seconds

Detecting CDP Override Status

import { cdpAvailable } from 'ego-browser/src/state.js';

if (cdpAvailable()) {
  console.log('Custom CDP handling is in effect');
}

Summary

• The shared mutable runtime state in ego-lite lives in package/ego-browser/src/state.ts (lines 24–56).
• It is a singleton object accessed via the state export, containing session tracking, CDP transport, and utility helpers.
• Mutability is controlled through setOverrides, which enables temporary state replacement with restoration capabilities.
• Core consumers include src/browser-runtime.ts, src/ref-state.ts, and src/helpers.ts, forming the backbone of coordinated browser automation.

Frequently Asked Questions

Where is the shared mutable runtime state defined in ego-lite?

The state is defined in package/ego-browser/src/state.ts, specifically between lines 24–40 for the object declaration and lines 42–56 for the API exports. This file exports the singleton as state and the mutation helper setOverrides.

How do I temporarily override state values in ego-lite for testing?

Import setOverrides from src/state.ts and pass an object containing the properties you wish to replace, such as the send function for mocking CDP responses. The function returns a restore callback that reverts the changes when invoked, ensuring isolated test behavior.

What session-related fields are tracked in the ego-lite state object?

The state tracks sessionId, sessionTargetId, sessionAt (timestamp), sessionInflight (pending operations), and preferredTargetId. These fields enable the runtime to maintain consistent session context across CDP commands and reference snapshots.

Which modules depend on the shared state singleton?

The primary consumers are src/browser-runtime.ts (for CDP transport), src/helpers.ts (for utility functions), src/ref-state.ts (for session-aware reference mapping), and src/env.ts (for workspace configuration). Together, these modules form the runtime coordination layer that relies on the shared mutable state.

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