# Understanding the Shared Mutable Runtime State in ego-lite

> Explore the shared mutable runtime state in ego-lite, a singleton object managing session tracking and CDP config. Learn how the setOverrides API coordinates mutations across the browser-automation harness.

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

---

**The shared mutable runtime state in ego-lite is a singleton object defined in [`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** – Provides high-level automation helpers that rely on `state` utilities like `sleep` and `now`.
- **[`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts)** – Uses `state.sessionId` and related fields to track reference mapping across JavaScript snapshots.
- **[`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)** – Invokes `state.send` (or its override) to forward CDP commands to the embedded browser.
- **[`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts)** – Supplies `agentWorkspace` and environment loading logic consumed by the state object.

## Practical Code Examples

### Reading the Current Session ID

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

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

```

### Overriding the Send Function for Testing

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

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

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts), [`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts), and [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)** (for CDP transport), **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** (for utility functions), **[`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts)** (for session-aware reference mapping), and **[`src/env.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/env.ts)** (for workspace configuration). Together, these modules form the runtime coordination layer that relies on the shared mutable state.