TTL for CDP Sessions in ego-lite: Understanding the 2-Second Timeout

In ego-lite, Chrome DevTools Protocol (CDP) sessions automatically expire after 2000 milliseconds (2 seconds), as defined by the SESSION_TTL_MS constant in browser-runtime.ts, forcing the runtime to re-attach to the browser when the TTL is exceeded.

The ego-lite browser automation framework maintains short-lived connections to Chrome's DevTools Protocol to ensure fresh execution contexts. This aggressive timeout prevents stale sessions from accumulating and guarantees that every CDP command runs against an active browser instance.

How the 2-Second TTL Works

The session lifetime logic centers on a hardcoded constant and a timestamp comparison performed during every session acquisition.

The SESSION_TTL_MS Constant

At line 5 of package/ego-browser/src/browser-runtime.ts, the framework declares the session lifespan:

const SESSION_TTL_MS = 2000;

This constant defines the maximum age of a cached CDP session identifier before it is considered invalid.

Session Validation in ensureSession()

When ensureSession() is invoked, it validates the existing session by checking the elapsed time since creation. According to the source code at lines 107–110 of browser-runtime.ts, the runtime performs this check:

if (state.sessionId && Date.now() - state.sessionAt < SESSION_TTL_MS) {
  return state.sessionId;
}

If the difference between the current time and state.sessionAt exceeds 2000 ms, the condition fails and the code path proceeds to create a new CDP session.

Key Source Files

The TTL implementation spans three critical files in the ego-browser package.

browser-runtime.ts

Located at package/ego-browser/src/browser-runtime.ts, this file defines SESSION_TTL_MS and implements the session creation, validation, and refresh orchestration logic.

state.ts

The package/ego-browser/src/state.ts module maintains the runtime state object containing the sessionId string and the sessionAt timestamp used for TTL calculations.

helpers.ts

The package/ego-browser/src/helpers.ts file exposes the high-level ensureSession() and invalidateSession() functions that agents use to interact with the CDP lifecycle.

Managing CDP Session Lifetime

Developers can interact with the TTL behavior through high-level helpers or rely on automatic management.

Automatic Re-attachment

The runtime handles expiration transparently. When ensureSession() detects a stale session, it automatically attaches a new CDP session before executing commands:

// First call establishes the session
await ensureSession();
console.log('Session age (ms):', Date.now() - state.sessionAt);

// Wait beyond the 2-second TTL
await new Promise(r => setTimeout(r, 2500));

// This call triggers re-attachment automatically because 2500 > 2000
await ensureSession();

Manual Invalidation

To force a fresh session regardless of the remaining TTL, use the invalidateSession() helper exported from package/ego-browser/src/helpers.ts:

import { invalidateSession, ensureSession } from 'ego-browser';

// Clear cached session data immediately
invalidateSession();

// Acquire a guaranteed fresh session
const freshId = await ensureSession();
console.log('New session ID:', freshId);

Summary

• CDP sessions in ego-lite expire after exactly 2000 ms (2 seconds) according to the SESSION_TTL_MS constant declared in browser-runtime.ts.
• The ensureSession() function validates freshness by verifying that Date.now() - state.sessionAt is less than the TTL threshold.
• Sessions older than 2 seconds are automatically discarded and re-attached on the next CDP command invocation.
• Use invalidateSession() to manually purge the current session before the TTL expires, forcing immediate re-attachment.

Frequently Asked Questions

What happens when a CDP session expires in ego-lite?

When the elapsed time since state.sessionAt exceeds SESSION_TTL_MS (2000 ms), ensureSession() invalidates the cached sessionId and executes the attachment logic to create a new browser session, ensuring no command runs against a stale connection.

Can I change the TTL for CDP sessions in ego-lite?

No. The SESSION_TTL_MS constant is hardcoded to 2000 in package/ego-browser/src/browser-runtime.ts with no configuration interface exposed. Modifying the source code and rebuilding the package is required to alter the timeout duration.

How do I force a new CDP session before the TTL expires?

Import invalidateSession() from ego-browser and call it to clear state.sessionId and state.sessionAt. The subsequent ensureSession() call will immediately attach a new CDP session regardless of how much time remains on the original TTL.

Where does ego-lite store the session timestamp?

The framework tracks the session creation time in state.sessionAt, defined in package/ego-browser/src/state.ts. This Unix timestamp is compared against the current time during every ensureSession() invocation to determine if the cached session is still valid.

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