# How Prime Agent's Daemon Protocol Handles Background Session Management

> Discover how Prime Agent's daemon protocol manages background sessions. Learn about persistent sessions, snapshot replay, and dynamic attach/resume for seamless operation.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: internals
- Published: 2026-08-12

---

**Prime Agent uses a long-running daemon process with a typed protocol (defined in [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts)) to manage interactive sessions that persist beyond client disconnects, supporting resident sessions, snapshot replay, and dynamic attach/resume operations.**

The **daemon protocol** is the contract that enables Prime Agent to run background sessions independently of any connected client. This architecture allows AI coding sessions to survive network interruptions, IDE restarts, or complete client handoffs. The protocol is implemented across a suite of TypeScript files in `packages/coding-agent/src/modes/daemon/` and governs everything from initial handshake to graceful shutdown.

## Core Daemon Protocol Concepts for Session Management

### Protocol Versioning and Capabilities

Every daemon-client interaction begins with capability negotiation. The protocol declares its identity through `DAEMON_PROTOCOL_INFO` (line 112 of [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts)), which includes the protocol name, version, and schema ID. This ensures version compatibility before any session operations begin.

Clients advertise their supported features via `DAEMON_DEFAULT_CLIENT_CAPABILITIES` and `DAEMON_SUPPORTED_CLIENT_CAPABILITIES` (lines 117-122). The daemon responds with `DAEMON_DEFAULT_SERVER_CAPABILITIES` (line 131), declaring features like snapshotting and session ownership that govern how background sessions behave.

### Session Lifecycle Modes

The `DaemonSessionLifecycle` type (line 175) defines two critical modes:

- **`"resident"`** — Sessions survive client disconnects and continue running in the background
- **`"client_owned"`** — Sessions terminate automatically when the owning client disconnects

When a client connects, the daemon returns `DaemonAttachResult` (lines 285-307), containing `sessionId`, `attachId`, `resumeCursor`, and the `sessionLifecycle` designation. This metadata determines whether the session can be resumed later.

### Snapshot and Replay Infrastructure

For resident sessions, the protocol defines `DaemonSessionSnapshot`, `DaemonReplayInfo`, and `DaemonReplayStatus` (lines 266-285). These types enable:

- Periodic persistence of session transcripts
- Full state restoration for new clients
- Cursor-based replay positioning

The [`snapshot-transcript-cache.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/snapshot-transcript-cache.ts) module handles the actual snapshot creation and storage operations.

## Background Session Management Flow

### Step 1: Daemon Initialization

The daemon process starts via [`daemon-launch.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-launch.ts), binding to a Unix socket path. It immediately advertises `DAEMON_PROTOCOL_VERSION = 7` (line 53) and `DAEMON_SCHEMA_ID` (line 64) from [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts).

Environment propagation helpers `collectDaemonClientEnv` and `collectDaemonLaunchEnv` (lines 186-206) ensure API keys and other critical variables flow from launching client to daemon process via `DAEMON_CLIENT_ENV_KEYS`.

### Step 2: Client Handshake and Attach

New clients use [`daemon-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-client.ts) to establish communication. The handshake sequence:

1. Client sends `daemon_hello` with its capabilities
2. Daemon responds with `DaemonAttachResult`
3. Client inspects `sessionLifecycle` to understand persistence guarantees

The `attachId` field supports multiple clients observing the same session simultaneously.

### Step 3: Background Persistence for Resident Sessions

Resident sessions trigger automatic snapshot creation through [`snapshot-transcript-cache.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/snapshot-transcript-cache.ts). Each snapshot conforms to `DaemonSessionSnapshot` and captures:

- Complete conversation transcript
- Session metadata
- Tool execution state

These snapshots enable true background operation—work continues even with zero connected clients.

### Step 4: Resume and Dynamic Attachment

Later clients can attach to existing sessions using the `attach` capability. The protocol validates the `resumeCursor` against stored snapshots, then streams the transcript delta to bring the new client to current state.

The [`daemon-session-list.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-session-list.ts) module maintains the in-memory catalog of active sessions available for attachment.

### Step 5: Health Monitoring via Heartbeats

Client liveness detection relies on `DaemonHeartbeat` (re-exported from agent connection, line 146) and the [`heartbeat-catalog.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/heartbeat-catalog.ts) implementation. Clients poll periodically; missed heartbeats trigger reconnection logic or daemon restart coordination via [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts).

### Step 6: Graceful Shutdown Handling

When shut down, the daemon:

- Marks sessions with `DaemonSessionClosedReason = "shutdown"`
- Writes final snapshots for resident sessions
- Sends `daemon_shutdown_in_progress` errors to attached clients

This ensures no background work is lost ungracefully.

## Protocol Implementation Files

| File | Responsibility | Key Exports |
|------|---------------|-------------|
| [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts) | Message types, versioning, capability constants | `DAEMON_PROTOCOL_INFO`, `DaemonAttachResult`, `DaemonSessionLifecycle` |
| [`daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-mode.ts) | Socket handling, session creation, shutdown orchestration | Daemon process entry point |
| [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts) | Multi-daemon coordination, worker recovery | Process supervision logic |
| [`daemon-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-client.ts) | Client-side RPC implementation | `DaemonClient` class with `connect()`, `attach()` methods |
| [`daemon-session-list.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-session-list.ts) | Active session registry | In-memory session catalog |
| [`snapshot-transcript-cache.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/snapshot-transcript-cache.ts) | Periodic snapshot creation and replay | Snapshot persistence and retrieval |
| [`heartbeat-catalog.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/heartbeat-catalog.ts) | Liveness monitoring | Heartbeat message management |

## Practical Code Examples

### Launching the Daemon

```bash
prime-agent --mode daemon --daemon-socket /tmp/prime-daemon.sock &

```

The daemon immediately advertises protocol version 7 and its schema ID for client negotiation.

### Attaching to a Resident Session

```typescript
import { DaemonClient } from "packages/coding-agent/src/modes/daemon/daemon-client.js";

const client = new DaemonClient("/tmp/prime-daemon.sock");
await client.connect();  // transmits daemon_hello

const attachResult = await client.attach({
  sessionId: "abc123",      // from previous DaemonAttachResult
  attachId: "client-42",
});

console.log(`Lifecycle: ${attachResult.sessionLifecycle}`);
console.log(`Resume cursor: ${attachResult.resumeCursor}`);

```

The `attachResult` contains all metadata needed for session continuity, including snapshot availability.

### Triggering Manual Snapshot

```typescript
import { DaemonClient } from ".../daemon-client.js";

await client.saveSnapshot({
  sessionId: "abc123",
  snapshot: {
    transcript: [...],
    metadata: { checkpoint: "pre-deployment" },
  },
});

```

Manual snapshots supplement automated periodic snapshots from [`snapshot-transcript-cache.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/snapshot-transcript-cache.ts).

## Design Decisions in the Daemon Protocol

**Type safety at the boundary** — Every message in [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts) is fully typed, preventing version skew between client and daemon.

**Explicit capability gating** — Features like `attach`, `resume`, and snapshot replay must be declared in capability flags before use, avoiding runtime errors on unsupported configurations.

**Environment isolation with selective propagation** — Rather than inheriting all environment variables, the daemon receives only keys listed in `DAEMON_CLIENT_ENV_KEYS`, reducing secret exposure.

## Summary

- **Daemon protocol versioning** via `DAEMON_PROTOCOL_INFO` ensures compatible client-daemon communication
- **Dual lifecycle modes** (`resident` vs `client_owned`) give explicit control over session persistence
- **Snapshot and replay infrastructure** enables seamless client handoffs and crash recovery
- **Heartbeat monitoring** maintains system health visibility across distributed components
- **Capability-based feature negotiation** prevents misuse of advanced features like dynamic attachment

## Frequently Asked Questions

### How does Prime Agent handle client disconnections without losing work?

The **daemon protocol** distinguishes between `resident` and `client_owned` session lifecycles. Resident sessions continue executing in the daemon process after disconnect, with [`snapshot-transcript-cache.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/snapshot-transcript-cache.ts) persisting state periodically. When a new client connects via [`daemon-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-client.ts), the `attach()` method retrieves the latest snapshot using `resumeCursor` from `DaemonAttachResult`, restoring full context.

### What happens if the daemon crashes during a background session?

The [`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts) module coordinates recovery. On restart, the supervisor checks [`daemon-session-list.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-session-list.ts) for sessions with persisted snapshots. For resident sessions with valid `DaemonSessionSnapshot` records, the daemon can replay from the last checkpoint. The `DaemonReplayStatus` type (lines 280-285 of [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts)) communicates replay progress to reconnecting clients.

### Can multiple clients connect to the same background session simultaneously?

Yes, through the `attach` capability declared in `DAEMON_SUPPORTED_CLIENT_CAPABILITIES`. Each attachment receives a unique `attachId` in its `DaemonAttachResult`. The daemon broadcasts output to all attached clients while maintaining a single execution context. This enables collaborative debugging scenarios where multiple developers observe the same AI session.

### How are API keys and secrets protected when the daemon outlives the launching client?

Environment propagation is strictly controlled via `collectDaemonLaunchEnv` and `DAEMON_CLIENT_ENV_KEYS` (lines 186-206). Only explicitly listed keys flow to the daemon process. The daemon stores no client credentials internally—sensitive state lives in the snapshot's encrypted transcript metadata, with access governed by filesystem permissions on the socket path and snapshot storage.