car-proto

JSON-RPC 2.0 protocol types for Common Agent Runtime client-server communication.

What it does

Shared serde-defined types used by both car-server-core (server) and any Rust client. Single source of truth for request / response / notification shapes so the server and clients can't drift.

The protocol is bidirectional over WebSocket:

• Client → Server — session.init, tools.register, proposal.submit, verify, etc.
• Server → Client (callback) — tools.execute (awaits a response)
• Server → Client (notification) — host.event, voice.event (no response expected)

Every connection using the protocol-v3 surface negotiates the exact PROTOCOL_VERSION through server.handshake after transport auth. Bundled clients require infer.model-identity.v1 and models.catalog-identity.v1, send both in required_capabilities, and verify that both appear in the reply's negotiated_capabilities. Until negotiation succeeds, handshake-gated methods fail with -32005; a missing, malformed, or different version fails with -32006, and an unsupported mandatory capability fails with -32008. Negotiation state belongs to the WebSocket session, so reconnects negotiate again.

Clients that depend on exact host-managed agent/tool approval overrides require permissions.agent-tool-overrides.v1 in the handshake. This lets them fail closed before using the associated WebSocket RPCs against an older daemon.

Where it fits

If you're building a Rust WebSocket client to talk to car-server, depend on this crate to get type-safe request/response handling. For other languages, the wire format is documented in docs/websocket-protocol.md — reach for raw JSON.