Accepted
agent-device can run a client on one machine and reach a daemon on another machine through the
HTTP JSON-RPC transport, including agent-device proxy in front of a local macOS daemon. Client and
remote host package versions can differ. Many version skews are safe because the client sends a
stable command request envelope and the daemon executes only the requested command.
Package semver is too strict for this boundary: a 0.15 client and 0.17 remote daemon can often interoperate. At the same time, the client needs a cheap way to fail before sending command RPC when the transport protocol itself is no longer compatible.
The daemon HTTP /health payload advertises a rpcProtocolVersion integer alongside service and
package version metadata. Remote clients compare this value before sending JSON-RPC requests.
Package version is diagnostic only and must not be used as a compatibility gate. Missing
rpcProtocolVersion is treated as a legacy remote daemon and is allowed unless a later security or
protocol decision explicitly retires legacy compatibility.
A persistent client may cache a successful probe when /health advertises an instance ID for
both the daemon endpoint and, if proxied, its upstream daemon. It sends those IDs as conditional
headers on every cached RPC. A daemon refuses a stale instance with a typed HTTP 409 response
before dispatch, and a proxy refuses its own stale instance before forwarding. The proxy passes
the expected upstream instance to the daemon, which makes the same pre-dispatch check. On a
mismatch the client clears the cache, probes /health again, and retries the refused RPC once
only when the new peer's protocol is compatible. Peers without complete instance IDs retain
per-command probes. A peer that advertises an instance ID must continue honoring the conditional
RPC headers in future versions: older clients may hold a cached identity across a restart, and
must receive a pre-dispatch refusal before retrying a mutating command.
rpcProtocolVersion changes only when an older client and newer daemon, or newer client and older
daemon, cannot safely communicate over the HTTP RPC boundary for existing commands. Bump it for
breaking changes to:
- HTTP route requirements for
/health,/rpc,/upload, or/artifacts/*. - Authentication semantics required to authorize RPC, upload, or artifact requests.
- JSON-RPC envelope shape, method naming, request id handling, or command request projection.
- Response, error, artifact, upload, or progress-stream framing that existing clients parse.
- Existing command request or response contracts when the old side would misinterpret the payload rather than fail clearly.
Do not bump it for additive changes:
- New commands.
- New optional request fields or flags that older daemons can ignore or reject with a normal command error.
- New optional response fields that older clients can ignore.
- Package version changes, refactors, or implementation-only daemon/proxy changes.
When a single command needs finer-grained compatibility in the future, prefer command-level feature or capability metadata over bumping the whole RPC protocol, unless the shared transport contract is also affected.
- Gate by package version: simple, but rejects compatible version skew and makes proxy usage brittle across frequent releases.
- Do not check compatibility: maximizes compatibility but fails later, after the client has sent an RPC payload that a remote daemon may parse incorrectly.
- Full schema negotiation: more precise, but too much machinery for the current JSON-RPC boundary.
Protocol-breaking changes must update DAEMON_RPC_PROTOCOL_VERSION, tests that assert /health
metadata, and at least one remote-client regression test that proves mismatched protocols fail before
command RPC.
The bump rules above are enforced rather than remembered (#1432). test/wire-compat/surface.ts
declares the wire surface grouped by the bullets in this decision, and test/wire-compat/ledger.json
records what each declaration hashes to and at which protocol version. The unit lane fails when a
declaration's shape moves without the ledger following, and pnpm check:daemon-wire-compat compares
the ledger against the last released tag: drift since that release must carry either a bump or a
compatibleChanges acknowledgment invoking the additive list above. Where a bullet is only partly
digestible — the /health and /rpc path literals inside http-server.ts — the manifest records
the gap and its reason instead of implying coverage. See test/wire-compat/README.md.
Legacy remote daemons without rpcProtocolVersion remain reachable. This keeps the first release of
the proxy compatible with older HTTP daemons, but it means absence of the marker is not proof of
compatibility.
A daemon on the local state directory publishes capabilities in daemon.json. This is the
command-level metadata the decision above prefers to a protocol bump. A daemon that predates a
capability omits it, so a client treats absence as "cannot do this" and never infers it from the
package version.
quiesce is how a client replaces an incompatible daemon without destroying other clients' work.
The client sends daemon_quiesce with the daemon token and the pid and start time recorded in
daemon.json. The daemon checks the token and that it is that instance, refuses a request that
reached it as a remote-origin one, then closes admission and counts what it holds in a single
synchronous step: requests in flight, sessions, repair sessions and live leases. Any of them
refuses with daemon-busy and reopens admission in that same step. Otherwise it answers
draining, keeps admission closed, and shuts down. The request is answered before dispatch, so
it joins neither the in-flight count nor the command registry.
The daemon accepts a quiesce only when it can prove its own start time and the request names it with the pid; a daemon that cannot is never addressed. A
client never signals a daemon that did not accept one, except to retire it after it answered
draining.
The census counts what the contract names and nothing else. A resumable upload still streaming and a host-administration human-control hold that names no lease are outside it, the same boundary idle reap draws, so a quiesce can end them. A daemon started with an HTTP auth hook marks every HTTP request remote-origin and so refuses a quiesce over HTTP; the socket transport is unaffected.