# Daemon Protocol Message Shapes for Session Attachment in Prime Agent

> Understand Prime Agent's daemon protocol message shapes for session attachment. Learn about attach command, DaemonAttachResult response, and session_attached event.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: api-reference
- Published: 2026-09-06

---

**Prime Agent's daemon protocol defines three core message shapes for session attachment: the `attach` command, `DaemonAttachResult` response, and `session_attached` event.**

The **daemon protocol message shapes for session attachment** govern how clients reconnect to active coding sessions in Prime Agent's architecture. These JSON‑L messages carry session state, snapshot data, and replay metadata across the daemon‑client boundary. This guide breaks down each message shape with exact TypeScript definitions from [`packages/coding-agent/src/modes/daemon/daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-protocol.ts).

## Attach Command Shape

The attachment flow begins with the client sending a command to the daemon. In [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts) lines 73‑84, the `DaemonCommand` union includes the attach entry:

```typescript
{
  id?: string;                 // optional envelope id
  type: "attach";
  activeSessionId: string;     // target session identifier
  supportsExtensionUi?: boolean;
} & DaemonAttachClientMetadata &
    DaemonClientEnv &
    DaemonLaunchEnv;

```

### Required and Optional Fields

- **`activeSessionId`** — The unique session identifier the client wants to join.
- **`id`** — Optional envelope identifier; the SDK auto‑generates a UUID when omitted.
- **`supportsExtensionUi`** — Requests UI extension support from the daemon.

The command extends three additional interfaces for complete attachment metadata:

| Extended Interface | Purpose | Key Fields |
|---|---|---|
| `DaemonAttachClientMetadata` | Client capabilities and telemetry policy | `capabilities`, `resumeCursor`, `telemetryDisabled`, `recoveryConfig` |
| `DaemonClientEnv` | Forwarded environment variables | `env` (whitelisted vars for the session) |
| `DaemonLaunchEnv` | Launch‑time environment for subprocesses | `launchEnv` |

### Telemetry and Capability Negotiation

The `telemetryDisabled` flag carries special semantics: if set, a telemetry‑enabled worker **must reject** the attach request. This enforces strict opt‑out compliance at the protocol level.

The `capabilities` array lists client‑side features such as `attach_snapshot` and `event_sequence`, which determine what data the daemon includes in its response.

## Attach Result Shape

The daemon responds with a `DaemonAttachResult` structure (defined in [`daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-protocol.ts) lines 26‑46):

```typescript
export interface DaemonAttachResult {
  protocol: DaemonProtocolInfo;          // { name: "prime-agent.daemon", version: 7 }
  activeSessionId: string;               // echoed from command
  state?: SessionSummary;                // omitted with "slim_attach" capability
  messages?: AgentMessage[];             // omitted with "slim_attach" capability
  snapshot: DaemonSessionSnapshot;       // full session state
  replay: DaemonReplayInfo;              // replay status and cursors
  lastEventSequence: DaemonEventSequence;
  lastEventCursor?: DaemonEventCursor;
  snapshotStream?: { 
    id: string; 
    messageCount: number; 
    targetChunkBytes: number 
  };
  client: {
    id: DaemonClientId;
    capabilities: DaemonClientCapability[];
  };
}

```

### Protocol Version Confirmation

The `protocol` field confirms interoperability at version `7` with name `prime-agent.daemon`. Clients must validate this before processing the remaining payload.

### Snapshot and Replay Semantics

- **`snapshot`** — Contains the complete session state including message history, context tree, and environment.
- **`replay`** — Indicates whether the client must replay missed events: values are `complete`, `partial`, or `unavailable`.
- **`state` and `messages`** — Conditionally omitted when the client negotiated the `slim_attach` capability, reducing payload size for lightweight clients.

The `snapshotStream` property appears when the snapshot exceeds inline size limits, providing a chunked download handle.

## Session‑Attached Event Shape

After processing the attach command, the daemon emits a `session_attached` event on the outbound channel (lines 140‑148):

```typescript
{
  type: "session_attached",
  activeSessionId: string,
  state: SessionSummary,
  messages: AgentMessage[],
  snapshot?: DaemonSessionSnapshot,
  replay?: DaemonReplayInfo,
  lastEventSequence?: DaemonEventSequence
}

```

This **asynchronous event** mirrors `DaemonAttachResult` fields but follows the daemon's event‑driven architecture. Clients receive it through their socket listener rather than as a direct RPC response.

The dual delivery mechanism—synchronous result plus asynchronous event—enables both request‑response patterns and stream‑based session management.

## Practical Implementation Examples

### Sending an Attach Command

```typescript
import {
  createDaemonCommandEnvelope,
  DAEMON_PROTOCOL_INFO,
  DaemonAttachClientMetadata,
  DaemonClientEnv,
} from '.../daemon-protocol';

const attachCmd = {
  type: 'attach',
  activeSessionId: 'session-123',
  supportsExtensionUi: true,
} as const;

const meta: DaemonAttachClientMetadata = {
  telemetryDisabled: true,
  capabilities: ['attach_snapshot', 'event_sequence'],
};

const clientEnv: DaemonClientEnv = { 
  env: { HERDR_PANE_ID: '42' } 
};

const envelope = createDaemonCommandEnvelope(
  { ...attachCmd, ...meta, ...clientEnv },
  'cmd-001',
  undefined,
  DAEMON_PROTOCOL_INFO.version
);

socket.write(JSON.stringify(envelope) + '\n');

```

### Handling the Session‑Attached Event

```typescript
socket.on('data', (chunk) => {
  const lines = chunk.toString()
    .split('\n')
    .filter(Boolean);
    
  for (const line of lines) {
    const event = JSON.parse(line);
    if (event.type === 'session_attached') {
      console.log('Attached to', event.activeSessionId);
      // event.snapshot holds full session state
      initializeSession(event.snapshot, event.replay);
    }
  }
});

```

## Protocol Files and References

| File Path | Relevant Definitions |
|---|---|
| [`packages/coding-agent/src/modes/daemon/daemon-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-protocol.ts) | `DaemonCommand` attach variant, `DaemonAttachResult`, `session_attached` event type |
| [`packages/coding-agent/src/modes/daemon/daemon-worker-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-worker-protocol.ts) | Worker‑side attach handling, session‑plane routing |
| [`packages/coding-agent/src/modes/daemon/daemon-protocol.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-protocol.test.ts) | Compatibility tests for attach commands and `session_attached` shape validation |

Lines 71‑84 of [`daemon-worker-protocol.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-worker-protocol.ts) define `DaemonAttachClientMetadata` and the core attach‑command processing logic according to the Prime Agent source code.

## Summary

- **Three message shapes** implement session attachment: the `attach` command, `DaemonAttachResult` response, and `session_attached` event.
- **Capability negotiation** via `capabilities` array and `telemetryDisabled` flag controls payload contents and attachment eligibility.
- **Dual delivery pattern** provides both synchronous result and asynchronous event for flexible client architectures.
- **Protocol version 7** requires explicit validation in `DaemonAttachResult.protocol`.
- **Slim attach mode** reduces bandwidth by omitting `state` and `messages` when the client signals support.

## Frequently Asked Questions

### What is the minimum required field for an attach command?

The `activeSessionId` string is the only required field. All other properties—including `id`, `supportsExtensionUi`, and extended metadata—are optional. The daemon assigns default values for omitted envelope identifiers and capability sets.

### How does the daemon handle telemetry opt-out?

When `telemetryDisabled: true` appears in `DaemonAttachClientMetadata`, telemetry‑enabled workers reject the attachment with an error response. This enforcement happens at the protocol layer before session state transmission begins.

### What triggers the `session_attached` event versus the `DaemonAttachResult` response?

The daemon emits `DaemonAttachResult` immediately as the RPC response to the attach command. It then broadcasts `session_attached` on the outbound event channel, enabling both direct response handling and event‑stream consumption patterns in clients.

### When should a client use the `slim_attach` capability?

Request `slim_attach` when the client maintains local session state or when bandwidth constraints make full message history undesirable. With this capability, the daemon omits `state` and `messages` from `DaemonAttachResult`, reducing payload size significantly.