Wire Protocol

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. The smallest valid frame is an agent heartbeat: 20 payload bytes behind the prefix 00 00 00 14.

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

{"type":"heartbeat"}

Transports

Four cooperating transports carry Chio messages:

Session initialization happens on the hosted MCP edge. The native transport has no initialization message: direct peers obtain capability material out of band and begin sending AgentMessage frames immediately.

Native framing

One governed call on the native transport is a tool_call_request frame in, zero or more tool_call_chunk frames out, and one tool_call_response that carries the result and the signed ChioReceipt. The kernel checks the capability and policy before it invokes the tool.

Framing

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

• 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.

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

The kernel's transport implementation defines native receiver behavior.

• 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 follows three rules:

• The native framed transport has no in-band resynchronization marker.
• 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 versioning

• The native framed transport version is 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.

Native message catalog

The core message types and the kernel transport define the catalog. Every frame is a JSON object with a type discriminator.

AgentMessage

Agent-to-kernel frames.

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

Kernel-to-agent frames.

tool_call_chunk fields:

tool_call_response fields:

capability_list carries one field, capabilities: an array of CapabilityToken the kernel considers valid. capability_revoked carries one field, id: the revoked capability identifier, as a string.

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

Two nested signed Chio objects appear directly on the native wire: CapabilityToken and ChioReceipt.

• Implementations MUST preserve all fields on those nested objects exactly as received.
• A native sender MUST NOT rewrite or recanonicalize nested signed object fields prior to forwarding.
• Receivers SHOULD verify signatures before treating capability or receipt content as authoritative.

Hosted MCP HTTP session transport

chio mcp serve-http serves the hosted edge. JSON-RPC requests arrive over HTTP POST, and results and notifications return on SSE streams bound to one session.

Endpoints and session headers

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

The session headers are MCP-Session-Id and 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 edge checks request headers 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 six states: initializing, ready, draining, deleted, expired, and 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

spec/versions/chio-protocol-negotiation.v1.json is the machine-readable negotiation artifact.

• Clients MAY send initialize.params.protocolVersion.
• The server compares that value against its supported version set, which holds one MCP protocol version: 2025-11-25.
• Compatibility is an exact-match test against that set. There is no downgrade path: the edge rejects an unsupported requested version.
• 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.

Trust control plane endpoints

chio trust serve runs the Trust Control Plane. It issues capabilities directly and under federation, answers receipt queries, and records revocations, all as JSON over HTTP. The revocation types are RevokeCapabilityRequest and RevokeCapabilityResponse.

Capability issuance

Endpoint: POST /v1/capabilities/issue. The request body:

The success response carries one field, capability: the signed issued CapabilityToken.

Federated and delegated issuance

Endpoint: POST /v1/federation/capabilities/issue. Delegation-relevant request fields:

• presentation: passport presentation proving federated subject identity.
• expectedChallenge: challenge the presentation must satisfy.
• capability: requested issued capability body.
• delegationPolicy: optional signed ceiling for delegated issuance.
• upstreamCapabilityId: optional imported parent capability anchor for multi-hop lineage.

Success response fields relevant to delegation:

• capability: newly issued child capability.
• delegationAnchorCapabilityId: optional lineage anchor persisted by the trust control plane.
• subjectPublicKey: resolved subject key used for issuance.

The service verifies the presentation and challenge, checks the delegation policy, resolves upstream state, and persists applicable lineage before it answers. Its delegation rules:

• 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 plane 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. When either is set, receipts without financial metadata are excluded. Supplying either requires costCurrency as exactly three uppercase ASCII letters, and when both bounds are present, minCost must not exceed maxCost. ReceiptQuery::validated_cost_currency applies these rules.

Revocation

Endpoint: POST /v1/revocations. The request body carries one field, capabilityId: the capability identifier to revoke, as a string.

Revocation changes the state the kernel consults on use. The agent learns of it in one of two ways: a capability_revoked notification that can arrive before its next call, or a capability_revoked error and a signed receipt on its next tool_call_request under that capability.

Error taxonomy

spec/errors/chio-error-registry.v1.json is the machine-readable error registry. It guarantees four properties for every entry:

• a unique numeric code
• exactly one named category
• a transient: true|false marker
• explicit retry guidance

Registry categories: protocol, auth, capability, guard, budget, tool, internal, transaction.

Each transport maps onto the registry:

• 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.
• The trust control plane answers with HTTP status codes; registry codes define the stable cross-transport classification and retry semantics.

Native failure handling

HTTP sidecar

The HTTP sidecar lets the kernel evaluate and sign receipts for arbitrary HTTP API requests alongside agent-protocol traffic. spec/HTTP-SUBSTRATE.md defines the sidecar evaluation protocol, the typed request and receipt models, and the deterministic mapping from HttpReceipt to the core ChioReceipt type. HTTP Transport documents it in full.

Sidecar evaluation protocol

A Chio kernel runs as a local process and exposes these HTTP endpoints on localhost:

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

Relationship to language SDKs

Sidecar SDKs are HTTP clients of the sidecar evaluation protocol and hold no policy of their own. The kernel is the single trust anchor for capability validation, guard evaluation, and receipt signing. Rust's chio-tower evaluates through the kernel inside the application process; see the Rust integration contract.

Schemas and conformance

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

• 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 validation test 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 schema ids under the same tree for the signed objects the wire carries. The message-family directories sit outside it. Each registered directory and its ids: