Streaming

Connect

Streaming is server to server only. Use Node 22 or later or Python 3. Browsers cannot set the Authorization header on the WebSocket upgrade. Keep the key in the server process.

Use the API origin with WSS and /v1/system-zero/stream. Authenticate on the upgrade with Authorization: Bearer <key>. Request only system-zero.stream.v1 in Sec-WebSocket-Protocol.

Use text JSON messages. Send no browser Origin, URL credential, cookie authentication, compression, binary data, query or trailing slash.

Message flow

Read hello and its limits, then send start before its deadline. Questions, routing, scheduling and the cache key stay fixed for the connection.

Use append_text for string state, append_items for array state, or replace for a complete new state. append_attachments changes only the inline attachment list. Each accepted change receives ack.

With on_change, changes schedule decisions. With on_request, send decide for the current accepted version and read scheduled. A decision embeds the ordinary HTTP reply. Its covered_event_ids identifies the changes included in that dispatch.

Answer each JSON ping with pong and the same nonce within 10000 milliseconds of the completed ping write. Native WebSocket controls are separate. A missed pong closes with 1013 and reason slow_reader.

Idle = 120 seconds with no client application message and no decide in flight; the clock restarts when a decide settles; heartbeats do not count. The client ends normally with WebSocket close code 1000. There is no client goodbye or client ping JSON message.

A server close can send goodbye first. Durable stream resume is unsupported. Reconnect and replay the full desired state with the same per-state idempotency key and byte-identical request.

Client messages

Server messages

Shared fields

State is a string, object or array. An object changes through replace. Each decision follows the ordinary decide API's validation, availability, billing and limits. An ack accepts state into connection memory; it grants no input availability and confirms no decision, charge or durable save.

Question names use at most 64 ASCII letters, digits and underscores, starting with a letter or underscore. Attachment names use at most 64 ASCII letters, digits, underscores or hyphens, starting with a letter. Attachment names must be unique.

If start omits prompt_cache_key, the server uses stream_id. For byte-identical replay across connections, send an explicit stable prompt_cache_key. Do not combine route committee with mode deliberate.

Omitting replace.attachments retains the current list. An empty list removes every attachment. Text and array appends keep attachments unchanged. Inline data has no separate MIME field.

Ordering and sequence

Each accepted mutation receives ack and increments state_version once.

IDs are precisely evt_1, evt_2 and so on; a rejected update leaves the next ID available for a corrected retry.

Text appends concatenate exactly, arrays append complete values, and replace changes the complete string, array or object state.

Use replace to change an object state; attachments can change independently.

An ack means accepted state in gateway memory, not a decision, bill or durable save.

Every accepted mutation, including an attachment append or replacement, creates a new version with its own supplied key; an unchanged version retains its key.

Rejected mutations leave the previous key intact; an unkeyed mutation clears it.

The gateway maintains one decide in flight and one pending intent.

Dense changes coalesce into the latest state.

In on_request mode, decide must name the current accepted version; its snapshot is chosen when dispatch becomes eligible.

state_version is its cumulative coverage watermark; covered_event_ids names only the mutation batch newly frozen into that dispatch.

An ack precedes any decision that covers it.

Only a successful decision, never an ack or error, resolves an event-to-decision observation.

During shutdown, valid mutations are applied and acknowledged with scheduled: false; they never start another decide on this connection.

Server seq starts at 1 and increases for every server message.

Idempotency keys contain 1 to 255 printable ASCII characters after trimming surrounding ASCII spaces. An unkeyed mutation clears the previous key.

Reconnect creates a new stream with new event numbering.

Replay the full desired state in start, then append only mutations absent from that replay.

Use full-jitter reconnect backoff, honoring any longer server retry delay.

Heartbeats neither bill inference nor extend idle/lifetime.

Limits

Read the limits advertised in hello. Stream limits do not enlarge ordinary HTTP limits. Idle time excludes heartbeats and time spent waiting for a decision. Account stream capacity is max(1, floor(max_concurrent / 2)).

receipt_timeout_ms is a legacy wire hint, not a complete receipt deadline. Continue checking peer liveness and receipt inactivity.

max_duration_ms

3600000 milliseconds

idle_timeout_ms

120000 milliseconds

start_timeout_ms

10000 milliseconds

heartbeat_interval_ms

30000 milliseconds

native_heartbeat_interval_ms

10000 milliseconds

receipt_timeout_ms

240000 milliseconds

max_control_queue_frames

2 frames

pong_timeout_ms

10000 milliseconds

max_message_bytes

4194304 UTF-8 bytes

max_decide_body_bytes

3665920 UTF-8 bytes

max_pending_events

4096 events

max_events

100000 events

max_events_per_second

5 events per second

max_send_queue_bytes

4194304 bytes

max_send_queue_frames

64 frames

min_interval_ms

0 milliseconds

event_burst

10 events

max_messages_per_second

40 messages per second

message_burst

80 messages

max_streams_per_process

4 streams

max_native_control_frames_per_second

8 frames per second

native_control_frame_burst

16 frames

max_native_control_bytes_per_second

512 bytes per second

native_control_byte_burst

1024 bytes

maximum_decision_interval

60000 milliseconds

mutation_burst

10 events

application_message_rate

40 messages per second

application_message_burst

80 messages

max_pending_probes

2 probes

write_progress_timeout

5000 milliseconds

decision_settlement_timeout

5000 milliseconds

close_handshake_timeout

5000 milliseconds

consecutive_retryable_failures

3 failures per state version

protocol_refusal_limit

3 refusals per window

protocol_refusal_window

60000 milliseconds

account_decision_burst

5 starts

account_decision_ceiling

60 starts per minute

Errors and close codes

Read error.envelope and error.retry. Decision failures keep the ordinary HTTP status and error envelope. A rejected mutation leaves state, version and its next event ID unchanged. A fatal error requires a following close.

In on_change mode, a 429 or 503 other than maintenance, or HTTP 409 idempotency_conflict, with retry permitted by the HTTP response schedules the latest state again after its Retry-After delay.

The gateway emits an error frame for each failure and stops automatic retries at three consecutive retryable failures for the same version.

The third error has fatal: true and retains the HTTP retry fields.

It is followed by goodbye with reason overload, the Retry-After delay in resume.retry_after_ms, and close 1013 so the client reconnects and replays.

The same fatal outcome applies immediately when the next automatic retry would reach or exceed the stream's remaining lifetime.

On_request never retries itself.

Retaining the key does not guarantee recovery of an original reply after a dropped connection.

Retry-After-Ms takes precedence over Retry-After.

Honor goodbye.resume.retry_after_ms and any longer server retry delay. Use reconnect backoff. A goodbye is best effort; a transport close can arrive without it.

The server never sends 1006; clients can observe it after abrupt loss and reconnect with backoff.

Example exchange

Illustrative JSON messages from a server runtime. Replace MODEL_ID and SERVED_BY with values from authenticated discovery. Timing, counts and probabilities illustrate the reply shape. In this exchange the server restarts after the decision, sends goodbye, then closes with code 1012. Wait at least 500 milliseconds before reconnecting.

{
  "type": "hello",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 1,
  "protocol": "system-zero.stream.v1",
  "request_id": "example-opening",
  "limits": {
    "max_duration_ms": 3600000,
    "idle_timeout_ms": 120000,
    "start_timeout_ms": 10000,
    "heartbeat_interval_ms": 30000,
    "native_heartbeat_interval_ms": 10000,
    "receipt_timeout_ms": 240000,
    "max_control_queue_frames": 2,
    "pong_timeout_ms": 10000,
    "max_message_bytes": 4194304,
    "max_decide_body_bytes": 3665920,
    "max_pending_events": 4096,
    "max_events": 100000,
    "max_events_per_second": 5,
    "max_send_queue_bytes": 4194304,
    "max_send_queue_frames": 64,
    "min_interval_ms": 0,
    "event_burst": 10,
    "max_messages_per_second": 40,
    "message_burst": 80,
    "max_streams_per_process": 4,
    "max_native_control_frames_per_second": 8,
    "native_control_frame_burst": 16,
    "max_native_control_bytes_per_second": 512,
    "native_control_byte_burst": 1024
  },
  "rate_limit": null
}

{
  "type": "start",
  "event_id": "evt_1",
  "request": {
    "model": "MODEL_ID",
    "state": "Initial log\n",
    "questions": {
      "ready": {
        "type": "boolean",
        "instructions": "Is the job ready?"
      }
    },
    "prompt_cache_key": "example-affinity"
  },
  "decision_mode": "on_request",
  "min_interval_ms": 0,
  "idempotency_key": "example-state-1"
}

{
  "type": "ack",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 2,
  "event_id": "evt_1",
  "state_version": 1,
  "state_bytes": 15,
  "synthesized_body_bytes": 158,
  "scheduled": false
}

{
  "type": "append_text",
  "event_id": "evt_2",
  "text": "Job is ready.\n",
  "idempotency_key": "example-state-2"
}

{
  "type": "ack",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 3,
  "event_id": "evt_2",
  "state_version": 2,
  "state_bytes": 30,
  "synthesized_body_bytes": 173,
  "scheduled": false
}

{
  "type": "decide",
  "state_version": 2
}

{
  "type": "scheduled",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 4,
  "state_version": 2,
  "in_flight": false
}

{
  "type": "ping",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 5,
  "nonce": 1
}

{
  "type": "pong",
  "nonce": 1
}

{
  "type": "decision",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 6,
  "state_version": 2,
  "covered_event_ids": [
    "evt_1",
    "evt_2"
  ],
  "reply": {
    "id": "szd_0123456789abcdef0123456789abcdef",
    "model": "MODEL_ID",
    "served_by": "SERVED_BY",
    "created": 1790000000,
    "context": {
      "route": "direct",
      "tokens": 32
    },
    "answers": {
      "ready": {
        "type": "boolean",
        "probability": 0.9,
        "confidence": 0.9,
        "calibration_version": "unpublished",
        "decision": true,
        "alternatives": [
          {
            "decision": false,
            "confidence": 0.1
          }
        ],
        "calibrated": false
      }
    },
    "usage": {
      "input_tokens": 32,
      "cached_input_tokens": 0,
      "media_tokens": 0,
      "long_input_tokens": 0,
      "media_items": 0,
      "thought_tokens": 0
    }
  },
  "request_id": "example-decision",
  "http_status": 200,
  "server_timing": null,
  "latency_ms": null,
  "rate_limit": null,
  "queue_ms": 0,
  "decide_ms": 40000
}

{
  "type": "goodbye",
  "stream_id": "szws_0123456789abcdef0123456789abcdef",
  "seq": 7,
  "reason": "shutdown",
  "state_version": 2,
  "last_decision_state_version": 2,
  "resume": {
    "supported": false,
    "action": "reconnect_and_replay",
    "retry_after_ms": 500
  }
}