Protocol frames

Generated WebSocket frame shapes exchanged by callers, the relay, and listeners.

This page is generated from the built Zod schemas in packages/shared/src/protocol.ts and packages/shared/src/e2ee.ts, and describes frame shape only.

For what an implementation is required to do — lifecycle, ordering, error obligations, idempotency, and which behaviors are a deployment’s choice rather than the protocol’s — see the normative protocol specification. Where the two disagree about shape, the schemas win.

Caller to relay

call_request

Send an encrypted call payload.

Field	Type	Required
type	call_request	yes
envelope	object	yes
message_id	string	no
delivery_mode	sync / durable	no
correlation_id	string	yes
traceparent	string	no

Relay to caller

call_status

Report unauthenticated lifecycle metadata.

Field	Type	Required
type	call_status	yes
state	ringing / answered / working	yes
call_id	string	no
correlation_id	string	no

call_queued

Acknowledge a durable submission. A receipt, not a reply.

Field	Type	Required
type	call_queued	yes
call_id	string	yes
message_id	string	yes
correlation_id	string	yes
submitted_at	integer	yes
expires_at	integer	yes

call_error

Return an unauthenticated relay-operational error.

Field	Type	Required
type	call_error	yes
origin	relay	yes
code	unknown_handle / offline / timeout / canceled / unauthorized / rate_limited / message_too_large / protocol_error / busy	yes
call_id	string	no
correlation_id	string	no

call_outcome

Return an encrypted, authenticated peer outcome.

Field	Type	Required
type	call_outcome	yes
call_id	string	yes
terminal	completed / failed	yes
terminal_reason	completed / failed / canceled / expired / delivery_failed / revoked / indeterminate_execution	no
envelope	object	yes
lease_id	string	no

Relay to listener

incoming_call

Deliver an encrypted call with relay-attested routing metadata.

Field	Type	Required
type	incoming_call	yes
call_id	string	yes
from	string	yes
envelope	object	yes
message_id	string	no
delivery_mode	sync / durable	no
lease_id	string	no
execute_by	integer	no
correlation_id	string	yes
traceparent	string	no

cancel_call

Request cancellation.

Field	Type	Required
type	cancel_call	yes
call_id	string	yes
lease_id	string	no

Listener to relay

call_accepted

Confirm ownership of queued work.

Field	Type	Required
type	call_accepted	yes
call_id	string	yes
lease_id	string	no

call_started

Confirm the answering process started.

Field	Type	Required
type	call_started	yes
call_id	string	yes
lease_id	string	no

call_outcome

Return an encrypted, authenticated peer outcome.

Field	Type	Required
type	call_outcome	yes
call_id	string	yes
terminal	completed / failed	yes
terminal_reason	completed / failed / canceled / expired / delivery_failed / revoked / indeterminate_execution	no
envelope	object	yes
lease_id	string	no

call_rejected

Reject an invalid encrypted request.

Field	Type	Required
type	call_rejected	yes
call_id	string	yes
code	protocol_error	yes
lease_id	string	no

call_cancelled

Confirm cancellation completed.

Field	Type	Required
type	call_cancelled	yes
call_id	string	yes
phase	pending / running	yes
lease_id	string	no

call_not_cancelled

Explain why cancellation did not complete.

Field	Type	Required
type	call_not_cancelled	yes
call_id	string	yes
reason	already_terminal / unknown / too_late	yes
lease_id	string	no

Important bounds

• Messages are limited to 64,000 bytes; replies to 256,000 bytes.
• Conversation contexts expire after 30 minutes and allow at most 10 turns.
• Each caller has a 30-call hourly budget.
• An encrypted WebSocket frame is limited to 2,063,019 bytes.
• Optional W3C trace context is normalized and must match the correlation ID.

Call messages, task and context identifiers, successful replies, peer failure details, and offered-task lists exist only inside signed HPKE envelopes. Routing and lifecycle metadata remain visible to the relay.