Skip to content

ACP Conformance ​

This document is the single source of truth for where this repository stands relative to the Agent Client Protocol (ACP) specification. Update it in the same PR as any agent-client-protocol version bump or any change to the bridged method surface.

Spec position ​

FactValue
Wire protocolv1
Pinned Rust SDKagent-client-protocol 5.0.0 (rsworkspace/Cargo.toml)
Bundled schema (effective spec level)1.15.1; the direct schema dependency matches the SDK pin
Latest upstream SDK at last review5.0.0 (2026-11-02)
Latest upstream schema at last review1.16.0 (2026-11-09)
Highest adoptable schema1.15.1; the SDK pins agent-client-protocol-schema at exactly =1.15.1
Last reviewed2026-11-09

Upstream repositories: spec/schema, Rust SDK.

The SDK's exact schema pin caps our effective spec level. The direct schema dependency must match that pin so Cargo feature unification applies to the same types. SDK 5.0.0 forwards every v1 opt-in flag used here; proxy-chain schema types are enabled by the SDK itself. Pinning it past the SDK's requirement would put two schema crates in the graph, at which point the flags no longer apply to the types the SDK actually re-exports, so schema releases above the SDK's pin are tracked as gaps here rather than adopted early.

Companion crates ​

The Rust SDK repository publishes more than the core crate, so tracking only agent-client-protocol hides capability that upstream already ships. The freshness task reads the recorded versions straight out of this table, so it stays the one place they live.

Most companions release in lockstep with the core crate: -http, -conductor, -polyfill, -derive, and -trace-viewer have carried the core's exact version number on the same day since 1.0.0, so a core bump is a reliable signal that they moved too. The schema lives in the spec repository and versions independently (the SDK pins it exactly, see above). -rmcp is now aligned at 5.0.0 but has an independent history, and -tokio has not released since 2026-04-21. The cookbook is also published; the upstream test harness and yopo workspace package were not on crates.io at this review.

CrateLatestAdoptedPosition
agent-client-protocol5.0.0yesThe core dependency this document tracks.
agent-client-protocol-schema1.16.0yes (1.15.1)Capped by the SDK's exact pin, see above.
agent-client-protocol-derive5.0.0transitivePulled in by the core crate; no direct dependency.
agent-client-protocol-http5.0.0yes (server feature)Official axum-based Streamable HTTP + WebSocket transport. It now serves all remote traffic: main builds AcpHttpServer over a per-connection NatsAgentComponent (acp-nats-server/src/component.rs), which retired the hand-rolled transport.rs and connection.rs (3,052 lines with their tests). compat.rs layers back the three behaviors upstream omits: Origin enforcement on every verb (upstream checks it server-side only on the WebSocket upgrade), Acp-Protocol-Version validation against the negotiated version (the transport spec says clients SHOULD send it and upstream never reads it), and X-Accel-Buffering: no on SSE. Drain is handled inside the component, which selects on a shutdown watch. Client feature deliberately not enabled: it wants reqwest 0.13 against the workspace's =0.12.28. See "Remote transport behavior changes" below.
agent-client-protocol-polyfill5.0.0noRe-evaluated at 5.0.0: a conductor-chain proxy exposing request-scoped native MCP servers through loopback HTTP to agents supporting MCP 2026-07-28. This bridge does not host a conductor chain or route native MCP requests, so adopting the polyfill does not close its routing gap.
agent-client-protocol-rmcp5.0.0noRe-evaluated at 5.0.0: the default feature set contains no rmcp integration; rmcp_3 opts into rmcp 3.4.0 server adapters. The workspace already uses rmcp 3.x, but the ACP bridge does not host native SDK MCP servers, so this adapter has no runtime role here.
agent-client-protocol-conductor5.0.0noRe-evaluated at 5.0.0: binary and library for stdio proxy chains using proxy/initialize and proxy/successor. Chain construction and successor handoff remain a different problem from the subject-routed NATS bridge.
agent-client-protocol-tokio0.11.1noNot updated since 2026-04-21 and superseded by the core crate's own runtime-agnostic surface. Treated as dormant; a release would be worth investigating.
agent-client-protocol-trace-viewer5.0.0noRe-evaluated at 5.0.0: protocol trace inspection remains developer tooling, with no runtime role in the bridge.
agent-client-protocol-cookbook5.0.0noPublished examples and recipes, re-evaluated at 5.0.0. Reference material rather than a bridge runtime dependency.

Remote transport behavior changes ​

Adopting the official transport moved several decisions from this repository to upstream. None is a spec regression, and two are strictly more correct, but each is observable to a client.

ChangeBeforeNowWhy it is acceptable
connectionId in the initialize result bodyinjectedabsentNot a field in the ACP v1 schema. Upstream returns it only as the Acp-Connection-Id header, which is the conformant surface.
Connection id formatUUIDv7 (time-sortable) via AcpConnectionIdUUIDv4ConnectionRegistry::next_connection_id is private and hardcoded, so the value object no longer governs the wire and was deleted. This is a genuine loss, not an improvement.
SSE stream scopingevery message broadcast to all listeners on a connectionrouted by whether the payload carries sessionIdUpstream splits connection-scoped and session-scoped streams. A session/update always carries a session id, so it reaches that session's listeners rather than everyone on the connection. Less leakage between sessions.
Session-scoped request missing Acp-Session-Id400202, routed from params.sessionIdUpstream recovers the session from the payload instead of demanding the header.
Request naming an unknown session404202, forwardedSession lifetime belongs to the agent, not the transport. The old transport kept its own set of known sessions to answer 404 itself.
Connection id after a failed initializereturnednot returnedUpstream tears the half-built connection down. The old behavior handed out an id for a connection that never initialized.
Browser WebSocket upgradeallowed for same-origin/loopbackrejectedServerOptions::default uses CorsOptions::Disabled, which rejects any request carrying an Origin header on the upgrade path. Non-browser clients send no Origin and are unaffected. Recoverable in one line (CorsOptions::AllowAnyOrigin) if a browser client appears, since compat::enforce_origin is the real gate either way.
/healthabsentservedServerOptions::default provides it and nothing in the repo conflicts.
JSON-RPC arrays (SDK 5.0 migration)accepted as batchesrejected without dispatching entriesUpstream removed batch handling from every SDK transport. HTTP returns 400 with -32600 and id: null; WebSocket and stdio return the same JSON-RPC error. This follows the remote transport RFD and SDK change.
initialize.protocolVersion (SDK 5.0 migration)backend response could retain legacy version 0the explicit v1 connection returns version 1SDK version negotiation selects the connection protocol and normalizes the response. Subsequent Acp-Protocol-Version headers must match the returned version; the compatibility layer still rejects mismatches.
Session SSE stream (SDK 5.0 migration)unbounded stream allocation for unknown sessionsbounded pre-load streams plus agent-confirmed sessionsUpstream permits limited unconfirmed streams so clients can subscribe before session/load replay. Agent responses confirm sessions; unknown IDs return 404 once those unconfirmed slots are full. Caller headers alone do not establish known sessions.
Concurrent SSE readers (SDK 5.0 migration)messages broadcast to multiple readers of one logical streamone active reader per connection or session streamA duplicate reader receives 409. Different logical streams remain independent, and the accepted reader receives queued responses and updates.

Policy ​

Opt in to unstable spec features ahead of stabilization. The default for every unstable feature is to enable the flag, wire the routing, and test it. Opting out is the exception and requires a rationale in the matrix below.

Why this matters here ​

The bridge decodes every message into typed SDK structs and re-serializes them (acp-nats/src/wire.rs). Fields the pinned SDK does not model are silently stripped in transit, and unknown session/update variants fail decode. Spec lag means silent data loss, not graceful passthrough, so this matrix must stay accurate.

Conformance matrix ​

Status values: implemented (routed, typed, tested), capabilities implemented (capability payloads round-trip, but the methods behind them are not routed), half-wired (one half of the path is routed and tested, but the end-to-end flow cannot complete in a release build, so the surface does not work in production), unwired (SDK flag enabled but no routing), dropped (peers may send it, the bridge strips or rejects it), unrepresentable (pinned SDK cannot express it), not supported (deliberate opt-out with rationale), watch-only (tracked for adoption, deliberately not implemented while upstream still churns).

A green test suite does not earn a status of implemented. half-wired exists because a surface can be fully unit-tested on both sides of a seam that nothing connects in a release build.

Agent-side methods (client to agent) ​

Spec surfaceSpec stage (schema 1.15.1)Our statusNotes
initializestableimplemented
authenticatestableimplementedterminal authentication shapes are stable
logoutstable (0.13.3)implemented
session/newstableimplementedincludes additionalDirectories
session/loadstableimplementedincludes additionalDirectories
session/liststableimplemented
providers/listunstable (0.11.7)implementedunstable_llm_providers now reaches the SDK request table; boundary dispatch forwards to the existing bridge and NATS handler.
providers/setunstable (0.11.7)implementedRouted through the SDK boundary and existing NATS handler with unstable_llm_providers.
providers/disableunstable (0.11.7)implementedRouted through the SDK boundary and existing NATS handler with unstable_llm_providers.
session/promptstableimplemented
session/cancel (notification)stableimplemented
session/set_modestableimplemented
session/set_config_optionstableimplemented1.4.0 shape, boolean and model_config round-trip tested
session/set_modelremoved upstream (0.13.5)removeddeleted with the SDK migration; model switching goes through model_config config options
session/forkunstableimplemented
session/resumestable (0.12.2)implemented
session/closestable (0.12.2)implemented
session/deletestable (0.13.6)implementedrouted end to end with tests, span acp.session.delete
JSON-RPC request cancellationstable (1.2.0)implementedboundary honors $/cancel_request: bridge-side work is dropped and the request answers with request_cancelled (tested); prompt-turn cancellation on the runner side remains session/cancel per spec
JSON-RPC batches (inbound)removed from SDK 5.0.0not supportedArrays are rejected with one invalid-request error and no entry dispatch. See the transport behavior changes above.
auth/statusunstable (1.15.0)implementedGlobal NATS subject auth.status and boundary handler.
session/statusunstable (1.15.0)implementedSession-scoped status request.
session/set_titleunstable (1.15.0)implementedSession-scoped title update.
session/archive, session/unarchiveunstable (1.15.0)implementedSession-scoped archive operations; list filtering and returned archive metadata also survive typed transport.
proxy/initialize, proxy/successorunstable (1.15.0)not supportedThese install proxy-chain topology and successor handoff. The bridge is an Agent endpoint with per-connection NATS dispatch, not an SDK proxy endpoint; forwarding the requests alone cannot establish a chain.
ext/* (extension methods)stableimplementedpassthrough

Client-side methods (agent to client) ​

Spec surfaceSpec stageOur statusNotes
fs/read_text_filestableimplemented
fs/write_text_filestableimplemented
session/request_permissionstableimplemented
session/updatestableimplementedunknown variants fail decode and are dropped with a session_update/decode_failure error metric
terminal/createstableimplemented
terminal/outputstableimplemented
terminal/releasestableimplemented
terminal/wait_for_exitstableimplemented
terminal/killstableimplemented
elicitation/createstable (1.7.0)implementedrouted both through the bridge-owned ClientHandler::elicitation_create and the SDK byte-stream boundary (AgentRequest::CreateElicitationRequest); ElicitationScope::Request (pre-session, no session id) is not routable since all NATS client subjects and NatsClientProxy construction are session-scoped
elicitation/complete (notification)stable (1.7.0)implementedrouted as a ClientHandler::elicitation_complete notification
mcp/message (request and notification)unstable (1.10.0 request-scoped revision)not supportedNative MCP messages bind to a containing request, not a session. The bridge has no request-lifetime MCP host or client destination; preserving the payload alone cannot route it.
mcp/connect, mcp/disconnectremoved (1.10.0)removedReplaced upstream by request-scoped mcp/message; the bridge never routed the earlier connection-scoped lifecycle.
auth/status_updateunstable (1.15.0)not supportedThis notification can precede any session. Client subjects and NatsClientProxy construction require a session ID, so the bridge lacks a connection-scoped client destination. Do not advertise working push status through this bridge.
ext/*stableimplementedpassthrough
ext/session/prompt_response (bridge extension, not spec)n/aremovedReverses this row's earlier "deliberately retained" position, on evidence that was not in front of it. The extension was the completion half of the original prompt design (#31): register a session waiter, publish the prompt, and take the answer back as a client-role notification correlated on meta.prompt_id. #43 replaced that whole design with request/reply, and the current path uses a JetStream response consumer filtered on {req_id}, which is durable across a restart in a way a process-local oneshot map is not. What survived #43 was the receive half alone, with register_waiter marked #[cfg(test)], so resolve_waiter always returned false and every notification was logged and dropped. Completing it was not possible either: nothing in the workspace publishes this method, and no subject type exists to publish it with, so the send half had no counterpart to build against. The retained rationale (a response outliving its caller) is real but belongs to the ADR#0055 Jsonrpc-Id demux, which needs many concurrent waiters per session; this registry allowed exactly one and rejected a second. Now deleted: the registry, its suppression window, the handler, the ClientMethod variant, and the orphaned semconv entries. The subject still parses, as a generic ext. method, so a publisher that sends it reaches the client's ext handler instead of a decode-and-drop.

Payload-level capabilities ​

Spec surfaceSpec stageOur statusNotes
additionalDirectories (session/new, session/load)stable (0.13.5)implementedround-trip tested through the bridge
Message IDs on chunksstable (0.13.6)implemented1.4.0 shape, round-trip tested
Session usage updatesstable (0.13.6)implemented1.4.0 shape, round-trip tested
Session config optionsstableimplemented1.4.0 shape, ConfigOptionUpdate round-trip tested
Boolean config optionsstable (1.3.0)implementedstabilized shape, round-trip tested
model_config option categorystable (1.1.0)implementedround-trip tested
NES (next edit suggestions)removed (1.12.0)removedUpstream removed the types and flag. Existing elicitation capability coverage remains; there is no NES payload to preserve in schema 1.15.1.
Plan operationsunstable (0.13.4)implementedPlanUpdate/PlanRemoved round-trip tested with unstable_plan_operations
Providersunstable (0.11.7)implementedCapability payloads and providers/list, providers/set, providers/disable are representable and routed with unstable_llm_providers.
MCP-over-ACP message typesunstable (1.10.0 request-scoped revision)capabilities implementedMcpServer::Acp, capability payloads, and request-scoped requestId/serverId message envelopes survive typed transport. mcp/message requests and notifications remain deliberately unrouted: the bridge has no request-lifetime MCP binding or native MCP server host. Schema 1.10 removed mcp/connect and mcp/disconnect together with connection IDs. Enabling the flag alone does not implement that lifecycle.
Elicitation enum option descriptionsstable (1.7.0)implementedEnumOption descriptions on StringPropertySchema.one_of round-trip tested
Tool call namestable (1.8.0)implementedNonempty names on tool_call and tool_call_update survive public wire decode and re-encode.
Session notices and compactionstable (1.11.0)implementedClient session.notices/session.compaction capabilities and notice, compaction_update, compaction_summary_chunk updates round-trip.
Subagents and session message viewsunstable (1.10.0, revised 1.13.0/1.14.0)implementedunstable_subagents preserves subagent identity, working directories, message references, and the subagent_update, session_message, session_message_chunk variants.
Client system promptunstable (1.12.0)implementedunstable_session_system_prompt preserves systemPrompt on new/load/fork/resume and its capability. Stabilized in schema 1.16.0, which remains above the SDK exact pin.
Archive and status metadataunstable (1.15.0)implementedArchive list filters/metadata and auth/session lifecycle capabilities round-trip.
Protocol v2unstable, heavy churnwatch-onlythe SDK still gates it behind unstable_protocol_v2; the freshness workflow surfaces releases, and this migration keeps the existing v1-only boundary

SDK 5.0 review ​

The schema changelog was reviewed from 1.5.0 through 1.15.1 alongside the SDK changelog. Schema 1.6 added tool names; 1.7 stabilized elicitation and terminal authentication and introduced compaction; 1.8/1.9 added notices and stabilized tool names; 1.10 introduced subagents and request-scoped MCP; 1.11 stabilized notices/compaction; 1.12 removed NES and added client system prompts; 1.13/1.14 revised subagent message identity and working directories; 1.15 added status, title, archive, and proxy methods. Patch releases also tightened decoding and clarified protocol behavior.

SDK-boundary adapters explicitly select Agent.v1() / Client.v1(), use agent_client_protocol::v1::schema, and retain the bridge-owned callback traits. Public regression coverage lives in acp-nats/tests/schema_1_15_conformance.rs, acp-nats/tests/method_routing.rs, and acp-nats/tests/schema_1_15_dispatch.rs; boundary and HTTP tests exercise dispatch, cancellation, shutdown, and array rejection. These tests establish bridge behavior, not support for the deliberately excluded proxy and MCP lifecycles.

Upgrade ritual ​

A version bump of agent-client-protocol (or the schema it bundles) is never just a version change. Every bump PR must:

  1. Diff the schema changelog between the old and new pinned versions (changelog).
  2. For each added or stabilized method: add subject mapping in acp-nats/src/nats/parsing.rs, a handler (bridge trait method plus its match arm in the boundary dispatch and NATS dispatch), and tests, or add a matrix row with an opt-out rationale. The byte-stream boundary no longer needs per-method registrations: connect_agent_boundary routes through the SDK's ClientRequest/ClientNotification enums, so a method missing from its match answers method_not_found instead of being silently unreachable (see ADR#0020, amendment of 2026-07-09).
  3. For each added field or session/update variant: add a round-trip test through the bridge. Typed re-encode means unmapped fields are silently dropped, so a green compile proves nothing about coverage.
  4. For each new unstable flag: enable it per the opt-in policy and wire it. A flag that only exists in a schema release above the SDK's exact pin cannot be enabled; move the direct schema dependency in lockstep with the SDK's requirement and record the gap as a matrix row instead.
  5. Update the ## Companion crates table with the new versions, and re-evaluate every row marked no. Companions release in lockstep with the core crate, so a bump is exactly when a gap that blocked adoption may have closed. The freshness task parses that table, so leaving it stale disables the check.
  6. Update this document (matrix and spec position table) in the same PR.

The scheduled freshness workflow (.github/workflows/acp-freshness.yml) embeds this checklist in the issue it files when drift is detected.

Released under the Apache License 2.0.