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

> Discover the 2-second TTL for CDP sessions in ego-lite. Learn how SESSION_TTL_MS forces re-attachment to the browser and optimize your runtime.

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

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts), the framework declares the session lifespan:

```typescript
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`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts), the runtime performs this check:

```typescript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts):

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.