Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Was this page helpful?