Relay wire protocol

Find the canonical method contract #

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, and the accepted protocol floor is the higher of 1.6 and the database compatibility policy. Request payloads reject unknown fields, so a client that puts a userId into its own payload fails the whole frame.

pnpm check:rpc-contract

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": {},
    "isFinal": true
  }
}

On the desktop every relay RPC waits for one of two semaphores, 8 concurrent light calls and 2 concurrent heavy ones such as timeline loads, reconciliation, media, attachments, and Git diffs. Waiting more than 8 seconds returns busy, and dispatch is capped at 45 seconds, or 95 for run.codexChatLoad and its thread variant.

A concrete mutation: submit an outbox message #

{
  "type": "rpc.request",
  "payload": {
    "id": "request-102",
    "method": "run.codexChatOutboxSubmit",
    "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; receipt has queueId and operationId. This enqueue example saves the message at the back of the queue and sends it automatically when the session is idle.

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

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, and 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.

Replay after interruption is method-specific. Chunk append can reconcile completion through its own domain ledger. 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.