Specification Overview ​

This section contains the formal specification of the Agent Host Protocol (AHP). It defines the normative requirements for compliant implementations.

Status ​

Conventions ​

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC 2119.

Protocol Version ​

The current protocol version is 1. The version is a single integer that increments when new features require capability negotiation or behavioral semantics change.

Version history:
  1 — Initial: core session lifecycle, streaming, tools, permissions

See Versioning for the full version strategy.

Base Protocol ​

AHP uses JSON-RPC 2.0 as its message framing. The protocol is transport-agnostic — any reliable, ordered, bidirectional message stream can carry AHP messages. See Transport.

Channels are the routing key ​

Every push-style interaction in AHP is scoped to a channel — a URI-identified subscribable resource (the root catalogue, a session, a terminal, a changeset, …). The wire protocol surfaces this consistently:

• Every command's params carries a top-level channel: URI, declared on the BaseParams interface that every command params type extends. Channel-scoped commands (createSession, disposeSession, fetchTurns, completions, …) pass the target URI; connection-level commands (initialize, ping, listSessions, the resource* commands, authenticate) narrow channel to the literal 'ahp-root://'.
• Every notification's params carries a top-level channel: URI, including the action envelope, dispatchAction, unsubscribe, and every protocol notification (root/sessionAdded, auth/required, …).

Implementations can therefore dispatch any incoming message by inspecting (method, params.channel) without per-method deserialisation. This invariant is verified at compile time in types/version/message-checks.ts. See Channels & Subscriptions for the URI scheme, the subscription mechanism, and the per-method table.

Message Categories ​

Requests ​

A JSON-RPC request has an id and a method. The server MUST respond with exactly one response carrying the same id.

{ "jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": { "channel": "ahp-root://" } }

Responses ​

A success response:

{ "jsonrpc": "2.0", "id": 1, "result": { "snapshot": { "resource": "...", "state": { ... }, "fromSeq": 5 } } }

An error response:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32603, "message": "No agent for provider" } }

Notifications ​

A JSON-RPC notification has a method but no id. It MUST NOT receive a response.

{ "jsonrpc": "2.0", "method": "action", "params": { "channel": "ahp-session:/<uuid>", "action": { ... }, "serverSeq": 6 } }

Structure ​

The specification is organised around the channels that AHP exposes — each channel page describes its URI, state, lifecycle, actions, and notifications. Cross-cutting concerns (transport, authentication, versioning) have their own pages.

• Transport — How messages are delivered between client and server.
• Lifecycle — Connection handshake, reconnection, and disconnection.
• Channels & Subscriptions — The channel model, the universal channel: URI routing key, and the subscription mechanism shared by every channel type.
• Authentication — RFC 9728 / RFC 6750 authentication flow.
• Root Channel — ahp-root:// — agents, terminals catalogue, host config, session catalogue events.
• Session Channel — ahp-session:/<uuid> — per-session state, turns, tool calls, pending messages.
• Terminal Channel — per-terminal pty state, data flow, claims, command detection.
• Telemetry Channel — ahp-otlp: — OpenTelemetry logs, traces, and metrics emitted by the agent host.
• Versioning — Protocol version negotiation and compatibility.
• Common Types — Cross-cutting types, base command/notification shapes, and JSON-RPC wire types.
• Root Channel Reference — RootState, root actions, root commands, and root notifications.
• Session Channel Reference — SessionState, session actions, and session commands.
• Terminal Channel Reference — TerminalState, terminal actions, and terminal commands.
• Changeset Channel Reference — ChangesetState, changeset actions, and changeset commands.
• Messages — Index of every JSON-RPC method with links to the channel page that documents it.
• Error Codes — Application-specific error codes.

JSON Schema ​

Machine-readable JSON Schema (2020-12) definitions are published for all protocol types:

These schemas are generated from the TypeScript type definitions and can be used for validation, code generation, or editor support.