Relay wire protocol

Find the canonical method contract #

The manifest lists 74 methods in four namespaces. 25 of them are mutations that need an idempotency key. The relay and the desktop router each hold the same two lists in code.

Four methods serve the reply style, the text improvement, and the context overview. The desktop does all of their work.

A new context measurement arrives in the runtime event of chat:stream.

A registered connection sends a type and payload envelope. RegisterPayload uses deviceId, relayProtocolVersion, and optional deviceName, sessionId, resumeToken, and targetDesktopDeviceId. The device UUID must match a device row the account registered over HTTP that is not forgotten and matches the connection’s role and relay eligibility. Request payloads reject unknown fields, so a client that puts a userId into its own payload fails the whole frame.

The manifest also pins size limits that the desktop enforces in code.

pnpm check:rpc-contract

The version gate sits at registration #

The relay protocol version is 1.7. The manifest names 1.7 as current and as minimum, and the desktop, the iOS app, and the Android app all report 1.7 in RegisterPayload. Version 1.7 gave the chat methods their agent-neutral run.chat names. The relay holds no translation for an older wire.

At registration the relay computes the required version as the higher of 1.7 and the highest minimum_relay_protocol_version of the compatibility rules in the database. It caches the rules for 60 seconds. A connection below the required version is refused before it can send a request.

The registration fails with one of three error codes.

• protocolUpdateRequired: relayProtocolVersion is absent or lower than the required version. The message asks the user to update the app.
• invalidRelayProtocolVersion: relayProtocolVersion does not parse as a version.
• relayProtocolPolicyUnavailable: the relay cannot read the compatibility rules, or a rule holds a version that does not parse.

A second check runs over HTTP before the socket opens. POST /public/compatibility/check takes a desktop descriptor, a mobile descriptor, or both, each with appVersion, platform, and relayProtocolVersion. The answer holds compatible, a decision, a message, policyVersion, requiredRelayProtocolVersion, and one result per descriptor with knownVersion and protocolSupported. The decision is one of compatible, missingClient, invalidVersion, unsupportedDesktopVersion, unsupportedMobileVersion, unsupportedPair, protocolUpdateRequired, and blockedByPolicy.

The desktop calls this check with a 5-second timeout before it connects. It sends only its own descriptor. The check fails open: when it is unreachable, returns an error status, or returns a body that does not parse or has no desktop result, the desktop connects anyway, and the registration gate remains the enforcing check. A negative answer stops the connection with a compatibility error.

Both agents use the same RPC methods #

Codex and Claude sessions use the same methods. No method name contains an agent, except the account and usage methods in the system namespace. The desktop reads the agent from the session record and routes each run.chat call to that agent.

Both activate methods are mutations. The desktop switches the account, emits a desktop event that names the agent, and answers with the new list. A failed event only delays the desktop window until its next periodic read.

Inspect the request and response shapes #

{
  "type": "rpc.request",
  "payload": {
    "id": "request-101",
    "method": "system.ping",
    "params": {},
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
  }
}

{
  "type": "rpc.response",
  "payload": {
    "clientId": "<source-client-id>",
    "id": "request-101",
    "result": {
      "ok": true,
      "service": "desktop-relay",
      "timestampMs": 1789214400000,
      "capabilities": ["run.cancel.exact-run.v1"]
    },
    "isFinal": true
  }
}

The desktop does not trust the envelope alone. It compares the relay’s userId with the user of its own sign-in and answers forbidden on a mismatch. It uses the relay’s clientId as the device id in idempotency scope keys. The permission list of a relay request is always rpc.

Before a reply leaves the desktop, the sender scans the result for a snake_case key. One such key replaces the whole reply with a validation error, so a handler cannot leak an internal field name to a phone.

Every hop has its own deadline #

On the desktop every relay RPC waits for one of two semaphores. 8 permits serve light calls. 2 permits serve heavy calls, so a slow media read cannot hold up system.ping.

Both -32603 replies are plain internal errors without a retryable flag. A phone must not read them as proof that nothing ran.

The dispatch limit is a timeout around the handler future. At the limit the desktop drops that future, and the handler stops at its next await point. A mutation that is cut there leaves its durable claim in the running state. A handler whose work must finish starts it as a separate task and awaits only the result. run.chatOutboxStopAndSendNow does this: it stops the run and then sends the message, also when the relay no longer waits.

A concrete mutation: submit an outbox message #

{
  "type": "rpc.request",
  "payload": {
    "id": "request-102",
    "method": "run.chatOutboxSubmit",
    "idempotencyKey": "submit-operation-201",
    "params": {
      "queueId": "queue-201",
      "operationId": "operation-201",
      "sessionId": "<existing-session-id>",
      "userText": "Explain the settings flow.",
      "promptText": "Explain the settings flow.",
      "attachments": [],
      "speedMode": "standard",
      "createdAt": 1789214400000,
      "updatedAt": 1789214400000,
      "intent": "enqueue",
      "sendMode": "queue",
      "source": "composer"
    }
  }
}

The remote adapter decodes WorkspaceChatOutboxSubmitRequest, validates that the session exists, then calls submit_outbox_request. The result contains entries and receipt, and receipt has queueId and operationId. This enqueue example saves the message at the back of the queue and sends it when the session is idle.

Four more fields are optional: threadId, expectedChatSettings, accessMode, and expectedActiveRunId. The struct rejects any field it does not know.

To retry the same uncertain operation, keep its immutable operation payload and idempotency identity. Do not generate a new operationId because a network request timed out. An edited message is a different operation and must go through the explicit queue or composer action.

run.chatOutboxStopAndSendNow is the second outbox mutation with a precondition. Its params are sessionId, queueId, operationId, expectedRunId, expectedThreadId, and expectedTurnId. The three expected values name the run that the phone saw, so the desktop never stops a different run.

Routing is bound to live connection generations #

Pending RPC admission takes the user authority gate and the routing transition lock. It rejects a draining server, stale source registration, or a changed desktop connection generation. The pending key includes the user UUID, normalized desktop device ID, and trimmed request ID. The record also retains the desktop connection ID and source client.

This prevents a late reply from a previous desktop socket from being treated as the current request’s result. Pending requests are bounded at process, user, desktop, and client levels. An identical existing pending record is a duplicate request. A different record under the same key is a conflict. Neither case is a new untracked forward.

Two layers protect different operations #

The scope key joins user, device, method, and key, so the same key from another phone or for another method is a different claim, and the fingerprint is a SHA-256 of the serialized params. A retryable row with the same fingerprint is reclaimed and run again. A stored response over 256 KiB is recorded as ambiguous. 48 hours after its reply is stored, a key is forgotten, and a repeat runs as a new mutation.

Errors classify by code. Invalid request, method not found, invalid params, unauthorized, forbidden, not found, conflict, validation, billing, payment required, and not implemented are terminal and replay as stored. Parse errors and anything flagged retryable are retryable. Internal, database, external-service, and unknown codes are ambiguous. If acquiring the durable claim fails, no mutation executes. If execution finishes but its result cannot be saved, the router reports an ambiguous outcome rather than a success that hides a missing replay record.

Four methods may run again after an interrupted first copy: run.chatOutboxSubmit, files.appendChatAttachmentUploadChunk, files.finishChatAttachmentUpload, and files.cancelChatAttachmentUpload. Each has its own domain record that makes a second run harmless. Chunk append also releases its finished claim, because the upload ledger reconciles completion. The outbox’s separate (sessionId, operationId) fingerprint protects message delivery after the RPC handler returns. These layers do not make every arbitrary side effect exactly-once.