Skip to content

Wire schemas

hotl has two machine-readable wires, and both now have a published JSON Schema generated from the Rust types that produce them:

Wire Version key Schema
hotl -p --json event stream schema_version on every line (now 2) json-stream-v2.schema.json
hotl acp payloads (results, session/update bodies, client requests and replies) schemaVersion (now 1) acp-v1.schema.json

Each file’s $id is its URL. hotl schema json-stream and hotl schema acp print the same bytes, so a client can pin the schema of the binary it runs.

An additive change — a new frame type, a new optional field — keeps the version and the same file. A breaking change bumps the version and publishes a new file beside the old one (json-stream-v3.schema.json); the old URL keeps resolving. Optional fields are omitted rather than sent as null unless the schema says null is a value.

acp-v1.schema.json is one file with every payload under $defs:

Method or message $defs entry
initialize result InitializeResult
session/new, session/load, fork result SessionOpenResult
session/prompt result PromptResult
session/update params SessionUpdateParams (its update is a stream frame or an ACP-only kind)
session/set_plan, set_mode, set_effort, set_model, set_goal results PlanAck, ModeAck, EffortAck, ModelAck, GoalAck
session/reload_config result ReloadAck / ReloadSessionAck
session/steer, session/fold results Queued; session/cancel → Cancelled; stops → StoppedAck; the rest → Ack
server → client session/request_permission, request_question, request_egress RequestPermissionParams, RequestQuestionParams, RequestEgressParams
what the client answers them with PermissionReply, QuestionReply, EgressReply

hotl acp is ACP-shaped: JSON-RPC over stdio, session/* methods, session/update notifications. It is not upstream ACP v1 — its initialize answers protocolVersion: "0.1", prompts take params.text, updates carry update.type. The initialize result says so in upstream’s own extension slot: agentCapabilities._meta.hotl names the dialect, the upstream schema release it was checked against (acpSchema), and every method it speaks (extensions). An ACP v1 client such as Zed will not drive it today.