Specification Overview

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

Status

DRAFT

This specification is a working draft and is under active development. Breaking changes to wire types, actions, and state shapes are expected. Do not rely on backward compatibility until the protocol reaches production 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

Direction	Type	Examples
Client → Server (notification)	Fire-and-forget	unsubscribe, dispatchAction
Client → Server (request)	Expects a response	initialize, reconnect, subscribe, createSession, disposeSession, listSessions, fetchTurns, resourceRead, resourceWrite, resourceList, resourceCopy, resourceDelete, resourceMove, resourceResolve, resourceMkdir, createResourceWatch
Server → Client (request)	Symmetrical reverse direction; expects a response	Any resource* request (resourceRead, resourceWrite, resourceList, resourceCopy, resourceDelete, resourceMove, resourceResolve, resourceMkdir, resourceRequest) plus createResourceWatch
Server → Client (notification)	Pushed	action, root/sessionAdded, root/sessionRemoved, root/sessionSummaryChanged, auth/required
Server → Client (response)	Correlated by id	Success result or JSON-RPC error

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:

Schema	Description
state.schema.json	State types
actions.schema.json	Action types
commands.schema.json	Command parameters and results
notifications.schema.json	Notification types
errors.schema.json	Error codes

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