Contracts overview
The versioned wire and file shapes, one file per contract; a breaking change is a new file.
Living doc, checked against the code 2026-11-14
The versioned wire and file shapes: one file per contract. A breaking change is a new file.
A file is named <name>.v<N>.md and titled # <name>.v<N> — <what crosses the boundary>; the docs site shows
each one under a reader’s name instead. Most wire types live in crates/protocol; a contract names its types and
the code that speaks it.
What is here
| file | what |
|---|---|
acp-integration.v1.md |
acp-integration.v1 — accepted design for ACP role, capability, authority and lifecycle contract; no runtime activation |
hc-terminal-rpc.v1.md |
hc-terminal-rpc.v1 — the terminal attachment an ACP agent needs from hc (private prototype, off in both gateway roles) |
acp-provider-registry.v1.md |
acp-provider-registry.v1 — unshipped operator declaration codec; registration never establishes readiness |
adapter-degradation.v1.md |
adapter-degradation.v1 — what one client is told when its speech adapters fail |
answer-card.v1.md |
answer-card.v1 — what a frontend shows beside a spoken answer (the render frame is live; the four card types are a draft) |
capture.v1.md |
capture.v1 — a capture: annotated keyframes, marks, narration and OCR, from a frontend to the brain |
avatar-action.v1.md |
avatar-action.v1 — the five avatar verbs, their closed arguments and the rig’s vocabulary |
avatar-puppet.v1.md |
avatar-puppet.v1 — what a rig draws from typed picks: overrides, gaze, clips, the director and the gate |
frontend.v5.md |
frontend.v5 — the frontend WebSocket: the hello, owner admission, features as the minor, and every frame (public; schema) |
admin.v6.md |
admin.v6 — the Admin owner socket: one request, one answer, every request and projection (owner; schema) |
decision.v1.md |
decision.v1 — the typed-decision wire the gateway asks a local decision model over (live, off by default) |
dictation.v1.md |
dictation.v1 — hold-to-talk, the typed words, and “scratch that” |
links.v1.md |
links.v1 — an operator-activated list of web links (built; experimental) |
meeting.v1.md |
meeting.v1 — typed meeting events into the gateway’s store (gateway half built, off by default) |
panel-card.v1.md |
panel-card.v1 — the panel the brain or a tool fills, drawn in the conversation |
connector.v1.md |
connector.v1 — a connector: an account linked on the gateway’s host, walked in the app |
proactive-card.v1.md |
proactive-card.v1 — what Vulpine may say unprompted, and what the operator may answer |
reading.v1.md |
reading.v1 — the read verb on the wire: start_read, reading_control, reading_progress |
reach-pair.v1.md |
reach-pair.v1 — pairing a new key with a gateway over reach: the invitation, one stream, one answer line |
reach-ws.v1.md |
reach-ws.v1 — the frontend protocol’s WebSocket carried over reach, one QUIC stream per WebSocket |
reach-voice.v1.md |
reach-voice.v1 — one protocol 5 session over reach as a control stream and Opus datagrams (schema) |
reach-mcp.v1.md |
reach-mcp.v1 — one agent session over reach: a delegated key, a hello, then MCP JSON-RPC both ways (experimental; schema) |
satellite-controls.v1.md |
satellite-controls.v1 — a satellite’s button, dial and mute switch on the wire |
skill.v1.md |
skill.v1 — a skill: a procedure in words over catalog tools |
sidecar-envelope.v1.md |
sidecar-envelope.v1 — the bounded tree a sidecar window draws: one snapshot, then revisioned patches (draft) |
voice-profile-manifest.v1.md |
voice-profile-manifest.v1 — the consent and provenance a Voice Profile candidate must carry (draft) |
turn-budget.v1.md |
turn-budget.v1 — each turn leg’s millisecond budget; the numbers are in turn-budget.v1.toml |
utterance.v1.md |
utterance.v1 — one typed record per committed spoken utterance |
tool.v1.md |
tool.v1 — a catalog tool: one call shape, eight shared actions, one manifest, any handler (accepted) |
tool-index.v1.md |
tool-index.v1 — the one list of registered tools, each with its provenance record (schema) |
tool-pack.v1.md |
tool-pack.v1 — the unit a user downloads: one strict tar.gz, its pack.json, and the signed tools index (accepted) |
extension-pack.v1.md |
extension-pack.v1 — one installable unit over the existing carriers: the manifest, its record and the one validator (accepted) |
visual.v1.md |
visual.v1 — a script visual: a sandboxed Luau program a frontend runs and draws |
file.v1.md |
file.v1 — a file the gateway shows from its own disk: named on the render, fetched by its hash |
page.v1.md |
page.v1 — a named web page from the gateway’s registry, shown in the render panel |
hardpoint.v1.md |
hardpoint.v1 — a typed runtime slot, the implementation a user binds into it, and the qualification before ready (accepted; 1.0 built for stt and tts) |
hardpoint.stt.v1.md |
hardpoint.stt.v1 — the stt slot: the built-ins, the STT worker wire on loopback, the probe and the fallback |
hardpoint.tts.v1.md |
hardpoint.tts.v1 — the tts slot: the built-in, a Wyoming TTS server on loopback, the probe (rendered to bytes, never played) and the fallback |
api-surfaces.toml |
the API catalog: every external surface, reach ALPN, protocol version constant and contract here, each with its stability label (public, owner, internal, experimental); rendered as the API surfaces page. A new contract file needs a row (docs-check api_catalog) |
hooks.v1.md |
hooks.v1 — a lifecycle boundary’s typed event, from the subsystem that commits it to a consumer the user supplies (accepted; the session boundaries are live) |
schema/ |
one JSON Schema per wire (frontend protocol 5, Admin 6, decision.v1), generated from crates/protocol and drift-tested; never hand-edited. Each has a contract file beside it that names every frame (docs-check contract_frames) |
See also
docs/STANDARD.md, “Templates” — the contract template.- ARCHITECTURE — one voice turn end to end.
- Glossary — the names the contracts use.