overview.md

Specification Overview

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

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.

Extensions

The x- prefix is reserved for implementation-defined extensions to channel URI schemes, command methods, notification methods, and action types. AHP-defined names in these namespaces MUST NOT begin with x-, and future protocol versions will not assign names with that prefix.

Implementations MAY use x- names by prior agreement between peers. Such names are not part of the AHP standard; their semantics, discovery, and negotiation are implementation-defined.

Protocol Version

Protocol versions are SemVer MAJOR.MINOR.PATCH strings; see the GitHub Releases page for the current published version. Peers negotiate a shared version at initialization: the client offers InitializeParams.protocolVersions (an array, most-preferred first) and the server selects one and returns it as InitializeResult.protocolVersion.

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: the chats catalog, default chat, active clients, customizations, changesets, and aggregated status.
• Automation Catalogue Channel — ahp-automations:// — synchronized full states for durable trigger-based session workflows.
• Automation Run Channel — ahp-automation-run:/<id> — task lifecycle and linked sessions.
• Chat Channel — ahp-chat:/<cid> — per-chat conversation state: turns, streaming, tool calls, pending messages, and input requests.
• 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.
• Chat Channel Reference — ChatState, chat actions, and chat commands.
• Terminal Channel Reference — TerminalState, terminal actions, and terminal commands.
• Changeset Channel Reference — ChangesetState, changeset actions, and changeset commands.
• Annotations Channel Reference — AnnotationsState and annotations actions.
• Automation Catalogue Channel Reference — AutomationState, automation actions, and automation commands.
• Automation Run Channel Reference — AutomationRunState and automation-run actions.
• Resource Watch Channel Reference — ResourceWatchState, resource-watch actions, and resource-watch commands.
• Telemetry Channel Reference — OTLP capability types and notifications.
• MCP Channel Reference — Upstream MCP wire surface and AHP capability links.
• 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.