Wire Protocol

Source

This page normatively reflects spec/WIRE_PROTOCOL.md in the chio repository. Status: Normative shipped surface. Version 1.0, dated 2026-04-13. The keywords MUST, SHOULD, and MAY are normative.

Where the specification defers to shipped code, the page reflects that code at the pin: the native message catalog and framing in crates/core/chio-core-types/src/message.rs and crates/kernel/chio-kernel/src/transport.rs, the hosted edge in crates/protocol/chio-mcp-remote/src/remote_mcp/http_service.rs, the trust-control routes and request types under crates/platform/chio-control-plane/src/trust_control/, the schema files under spec/schemas/chio-wire/v1/, and the validation harness crates/core/chio-core-types/tests/wire_protocol_schema.rs.

Synopsis

Wire version chio-wire-v1: a frame is a length prefix and one canonical JSON object whose type, status, or code field selects the variant.

+----------------------+---------------------------+
| 4-byte length prefix | canonical JSON payload    |
+----------------------+---------------------------+

Surface model

Chio ships these cooperating protocol surfaces:

The native Chio transport does not define a session-initialization message. Initialization in the shipped stack happens on the hosted MCP surface. Native direct peers obtain capability material out of band and then begin sending AgentMessage frames immediately.

Native Chio transport

Framing

Each native Chio frame is a 4-byte length prefix followed by the canonical JSON payload. Normative rules:

• The length prefix MUST be an unsigned 32-bit integer in big-endian byte order.
• The length value MUST count only the payload bytes that follow the prefix.
• The payload MUST be canonical JSON as produced by RFC 8785-style canonicalization.
• The maximum permitted payload length is 16,777,216 bytes (16 MiB).
• A sender MUST NOT emit a larger frame.
• A receiver MUST reject any frame whose advertised length exceeds that maximum.

Example: a payload length of 256 bytes is encoded as 00 00 01 00.

Sender requirements

• Senders MUST serialize native messages as canonical JSON before writing the frame.
• Senders MUST emit exactly one top-level JSON object per frame.
• Senders MUST use the discriminators and field names defined in the message catalog.

Receiver behavior and error recovery

Native receiver behavior is defined by the shipped transport implementation in crates/kernel/chio-kernel/src/transport.rs.

• If EOF occurs before the 4-byte prefix is fully read, the receiver MUST treat the connection as closed and deliver no partial message.
• If EOF occurs after the prefix but before the full payload is read, the receiver MUST treat the connection as closed and deliver no partial message.
• If the advertised length is greater than 16 MiB, the receiver MUST reject the frame as message_too_large.
• If the payload is not valid JSON for the expected message family, the receiver MUST reject the frame as a deserialization failure.

Recovery rules:

• Chio defines no in-band resynchronization marker for the native framed lane.
• After connection_closed, message_too_large, or deserialization failure, an implementation SHOULD close the current transport and establish a new connection before continuing.
• Serialization failure on send is terminal for the attempted message; no partial frame is defined.

Native message catalog

The native message catalog is defined by crates/core/chio-core-types/src/message.rs and crates/kernel/chio-kernel/src/transport.rs.

AgentMessage

All agent-to-kernel frames are JSON objects with a type discriminator.

tool_call_request required fields:

tool_call_request optional fields, from the Rust type and the schema spec/schemas/chio-wire/v1/agent/tool_call_request.schema.json:

The schema closes the object with "additionalProperties": false, so a peer sends no other field. AgentMessage::authorization_conflict names the combinations the native session handler refuses before evaluation: approval_token together with a non-empty approval_tokens; a threshold_approval_proposal with an empty approval_tokens; and a non-empty approval_tokens without a threshold_approval_proposal.

KernelMessage

All kernel-to-agent frames are JSON objects with a type discriminator.

tool_call_chunk fields:

tool_call_response fields:

capability_list fields:

capability_revoked fields:

ToolCallResult

KernelMessage.tool_call_response.result is a tagged object with a status discriminator.

ToolCallError

ToolCallResult.status = "err" carries a tagged error object with a code discriminator.

Signed artifact requirements

These nested signed Chio objects appear directly on the native wire:

• CapabilityToken
• ChioReceipt

Hosted MCP HTTP session transport

The hosted edge is implemented by chio mcp serve-http in crates/protocol/chio-mcp-remote/src/remote_mcp/http_service.rs.

Endpoint shape

• POST /mcp carries JSON-RPC requests and notifications.
• GET /mcp is the notification replay and live stream.
• DELETE /mcp terminates an existing session.

Session headers:

• MCP-Session-Id
• MCP-Protocol-Version

Initialization rules

• An initialize request MUST be sent to POST /mcp.
• An initialize request MUST be a JSON-RPC request and therefore include an id.
• An initialize request MUST NOT include MCP-Session-Id.
• A successful initialize response MUST return an SSE stream and include MCP-Session-Id on the HTTP response.
• After successful initialize, the client MUST send notifications/initialized before relying on ready-state operations.

Established-session rules

• Non-initialize requests MUST include MCP-Session-Id.
• If the session has a bound protocol version and the client sends MCP-Protocol-Version, that header MUST match the stored session value.
• POST requests MUST use Content-Type: application/json.
• GET notification streams MUST include MCP-Session-Id.
• Ready-state methods such as tools/list and tools/call MUST not run until the session has received notifications/initialized.

The shipped edge checks request headers in crates/protocol/chio-mcp-remote/src/remote_mcp/oauth/bearer_auth.rs before it reads a body. A POST must advertise both application/json and text/event-stream in Accept, and a GET must advertise text/event-stream; otherwise the edge answers 406 Not Acceptable. A POST whose Content-Type does not start with application/json gets 415 Unsupported Media Type. An MCP-Protocol-Version that differs from the session's bound version gets 400 Bad Request, and an unknown MCP-Session-Id gets 404 Not Found.

Notification stream and replay

• At most one active GET notification stream is allowed per session.
• Notification replay uses the Last-Event-ID request header.
• Event identifiers are encoded as {session_id}-{sequence}.
• Replay requests outside the retained event window fail with 409 Conflict.
• Hosted deployments that reuse one upstream owner across multiple sessions MUST keep late notifications and task handles scoped to the originating session. They MUST NOT fan out unattributed notifications or allow a different session to act on a foreign task id.

Hosted session lifecycle

Hosted sessions move through these states:

• initializing
• ready
• draining
• deleted
• expired
• closed

Requests against draining, deleted, expired, or closed sessions MUST not silently resume prior state. Clients encountering those terminal states MUST re-run initialization.

Version negotiation

The machine-readable negotiation artifact for the shipped stack is spec/versions/chio-protocol-negotiation.v1.json. Hosted MCP negotiation rules:

• Clients MAY send initialize.params.protocolVersion.
• The server compares that value against its supported version set.
• The current shipped implementation supports one MCP protocol version: 2025-11-25.
• Compatibility determination is therefore an exact-match test against that supported set.
• The current implementation has no downgrade path; unsupported requested versions are rejected rather than silently downgraded.
• On success, the selected version is echoed in result.protocolVersion and exposed again under result.capabilities.experimental.chioProtocol.selectedProtocolVersion.
• On failure, initialize is rejected with JSON-RPC -32600 plus a structured Chio protocol error descriptor in error.data.chioError.

Model metadata admission

• Hosted tools/call requests MAY carry model metadata under either _meta.modelMetadata or _meta.chioModelMetadata.
• The hosted edge normalizes that payload into Chio request model_metadata.
• Caller-supplied metadata MUST be treated as asserted provenance at admission time even if the caller marks it verified.
• Receipts and downstream exports MUST preserve the effective provenance class instead of silently upgrading caller assertions into verified runtime truth.

Native direct transport versioning

• Native Chio framed transport is currently chio-wire-v1.
• Native direct peers do not negotiate in-band; compatibility is an exact-match, out-of-band requirement.
• Because no in-band downgrade exists, incompatible native peers MUST close or reset the transport instead of attempting best-effort interop.

Trust-control capability lifecycle

The trust-control service is implemented by chio trust serve. The route constants live in crates/platform/chio-control-plane/src/trust_control/service_types/paths.rs; the issuance, federated issuance, and receipt query types in crates/platform/chio-control-plane/src/trust_control/service_types/requests.rs; and the revocation types RevokeCapabilityRequest and RevokeCapabilityResponse in crates/platform/chio-control-plane/src/trust_control/config_and_public.rs.

Capability issuance

Endpoint: POST /v1/capabilities/issue.

Request body:

Success response:

Federated and delegated issuance

Endpoint: POST /v1/federation/capabilities/issue.

Delegation-relevant request fields:

Success response fields relevant to delegation:

Normative delegation rules from the shipped service:

• If upstreamCapabilityId is supplied, the request MUST also carry a delegation policy bound to that exact parent capability id.
• If a delegation policy is supplied, the requested child capability MUST NOT exceed the policy ceiling.
• The trust-control service MUST reject untrusted delegation-policy signers.

Receipt query

Endpoint: GET /v1/receipts/query.

Supported query parameters:

minCost and maxCost are unsigned 64-bit minor-unit values. Supplying either requires costCurrency as exactly three uppercase ASCII letters. When both bounds are present, minCost must not exceed maxCost. The service validates these rules in ReceiptQuery::validated_cost_currency (crates/kernel/chio-kernel/src/receipt_query.rs).

Response body:

Revocation

Endpoint: POST /v1/revocations.

Request body:

Success response:

Error taxonomy

The machine-readable error registry for the shipped stack is spec/errors/chio-error-registry.v1.json. Registry guarantees:

• every Chio error entry has a unique numeric code
• every entry names one category
• every entry is marked transient: true|false
• every entry carries explicit retry guidance

The current registry categories: protocol, auth, capability, guard, budget, tool, internal, transaction.

Surface mapping rules:

• Native Chio ToolCallError discriminators map deterministically to registry entries such as capability_denied, capability_expired, capability_revoked, policy_denied, tool_server_error, and internal_error.
• Hosted MCP initialize-time protocol rejection communicates the numeric Chio protocol code under JSON-RPC error.data.chioError.code.
• Trust-control remains HTTP-status-driven; registry codes define the stable cross-surface classification and retry semantics.

Sequence diagrams

The specification carries these diagrams; each one is reproduced from its source text.

Hosted initialization

Capability issuance

Delegated issuance

Native tool invocation with receipt

Revocation propagation

Error handling

HTTP substrate surface

The HTTP substrate is a cooperating protocol surface alongside the native Chio transport, the hosted MCP edge, and the trust-control lifecycle APIs. It lets Chio evaluate and sign receipts for arbitrary HTTP API requests, not only agent-protocol traffic. The normative specification is spec/HTTP-SUBSTRATE.md, which defines the sidecar evaluation protocol, the typed request and receipt models, and the deterministic mapping from HttpReceipt to the core ChioReceipt type. The HTTP Transport page documents it in full.

Sidecar evaluation protocol

The HTTP substrate uses a sidecar model. A Chio kernel runs as a local process and exposes these HTTP endpoints on localhost; the routes are registered in crates/products/chio-api-protect/src/proxy/router.rs:

Language-specific middleware (chio-tower for Rust, chio-spring-boot for the JVM, ChioMiddleware for .NET, and the Python, TypeScript, and Go substrate SDKs) intercepts incoming HTTP requests, constructs a ChioHttpRequest, sends it to POST /chio/evaluate, and enforces the returned verdict.

Relationship to language SDKs

The language-specific SDKs consume this surface as HTTP clients over the sidecar evaluation protocol; they do not evaluate policy on their own. The kernel remains the single trust anchor for capability validation, guard evaluation, and receipt signing. Platform-level SDK documentation lives in docs/sdk/PLATFORM.md.

Schemas and conformance

Versioned native message schemas live under spec/schemas/chio-wire/v1/, one directory per message family. The validation harness loads these files:

Normative requirements:

• Schema files in that directory are the machine-readable contract for the native Chio message families.
• Implementations MUST continue to serialize the native message variants in a form accepted by those schemas.
• Schema validation MUST be exercised against live Rust serialization, not handwritten examples alone.

The shipped validation harness for this document is crates/core/chio-core-types/tests/wire_protocol_schema.rs. It serializes live Rust values of each variant and validates them against the schema files named in the table.

The signed-artifact registry, spec/schemas/registry.json, registers 13 schema ids under the same tree. It covers the signed objects the wire carries; the message-family directories are not in it.

Related

• Protocol Reference: capability, receipt, and manifest field semantics.
• HTTP Transport: the sidecar evaluation protocol, the typed request model, and the receipt mapping in full.
• IETF Internet-Draft: the standards-track document over the same surfaces.
• Schemas and Errors: the negotiation artifact and the error registry field by field.
• Bridges
• Bilateral Federation