Stream Protocol Contract

Provider bytes are never exposed directly. Each adapter parses its wire stream and emits the same additive StreamPart union. Consumers can therefore switch providers without changing text, reasoning, tool-call, source, usage, or finish handling.

The SSE parser is regression-tested for:

• UTF-8 code points split across arbitrary byte boundaries;
• LF, CRLF, and bare CR line endings, including a CRLF pair split across chunks;
• UTF-8 BOMs, comments/keep-alives, named events, and multi-line data: fields;
• a final event without a trailing blank line;
• cancellation of the underlying reader when a consumer stops early.

Every successful provider stream must produce exactly one finish part. Provider usage shapes are normalized into Usage; provider finish values are normalized into the locked FinishReason union. A provider error event produces one typed error part and rejects usage and finishReason with the same error object.

Compatibility rule

StreamPart is additive. Applications should handle the variants they need and retain a default branch so a new non-breaking part does not break an older consumer.

for await (const part of result.fullStream) {
  switch (part.type) {
    case 'text-delta':
      process.stdout.write(part.text);
      break;
    case 'error':
      throw part.error;
    default:
      break;
  }
}

Additive parts since 1.8

Additive parts and fields in 1.9

1.9 left wire v1 output unchanged in every byte. The tool-state fields and the data-part id ride carriers a v1 client already drops wholesale, and the two brand-new part types are v2-only — including when they sit inside a sub-agent frame, which is filtered recursively. 2.3 does not keep that property; see Wire versions in 2.3.

Additive fields in 2.3

2.3 adds no member to StreamPart or to DeuzUIPart. It adds optional fields to parts that already exist, and toDeuzStreamResponse (and toDeuzAgentStreamResponse, which frames a native run's parts the same way) forwards them on the UI wire. A field that is absent means what it meant in 2.2.

useChat (@deuz-sdk/react) reads these fields; the frozen @deuz-sdk/core/react hook ignores them.

Wire versions in 2.3

A response negotiated to v1 still has no id: lines and no v2-only part. It is not byte-identical to 2.2 output any more: the fields above marked "v1 and v2" ride parts a v1 client already receives (text-delta, reasoning-delta, tool-call, tool-result, step-finish, finish), and approvalId has its new form. A client that does not know a key ignores it, so a 2.2 reader keeps working. tool-state.outcome, the 'unpriced-model' warning and the native agent frames below ride v2-only parts.

Native agent frames (2.3)

toDeuzAgentStreamResponse serializes a native run (streamAgent, resumeStreamAgent). Its ordinary parts go out as above. What only a native run has goes out as data-agent parts on the existing data-${string} member: { type: 'data-agent', id: <kind>, payload: { kind, seq, … } }. The id is the frame's kind, so a reader that knows nothing of agent frames reconciles each kind in place.

• seq is the frame's own SSE event id, the number on its id: line. With store and streamId, every leg journaled under that streamId numbers on from the last stored event, so seq grows across the whole run and is the cursor a replay resumes after. Without a store, each response numbers from 0.
• v2 only. data-* parts are v2 parts, so a client that negotiated v1 gets the run's ordinary parts and no frame.
• A refused leg is detached. A leg the run refuses before it begins (another executor holds the run, another scope, an unknown run, invalid options) goes out on its own response with no id: lines and is not journaled. Its frames still number from 0, and fold on their own.
• Folding. agentStateFromParts and applyUIPart (into AssistantTurnState.agent) apply a frame only when its seq is above the state's, so a replay or an out-of-order frame applies nothing twice. A frame of another run, later in the sequence, starts that run's state. A data-agent part whose payload is not a well-formed frame (a malformed one, or an app's own data-agent data) changes no agent state: agentStateFromParts skips it, and applyUIPart keeps it as an ordinary data part.

See Native agent runs for the route and client code.

The 2.3 wire fields are pinned by test/ui-display.test.ts, test/chat-reasoning.test.ts, test/ui-text-signature.test.ts and test/ui-agent.test.ts in packages/core.

Additive parts in 2.4

2.4 adds no member to StreamPart and one to DeuzUIPart, and new values of the open CallWarning['type'] union. With none of the 2.4 options set, and for every request that does not ask for the handshake, the wire is what 2.3 sent, byte for byte.

A native V3 run's eventsV3 (context, working-memory and memory-intent) are not serialized: toDeuzAgentStreamResponse frames an AgentStreamV3 as it frames an AgentStream, so compiled context, retrieval results and memory intents never reach the UI wire.

The frozen @deuz-sdk/core/react hook ignores the 2.3 and 2.4 additions and is deprecated in favour of @deuz-sdk/react; it will be removed in 3.0.

The capability handshake (2.4)

The handshake tells a 2.4 client which chat and stream features the route behind it supports. It is separate from the v1/v2 negotiation and does not change it.

1. A client lists what it understands in the x-deuz-capabilities request header. useChat sends chat-snapshot-v1, durable-stream, message-ids on every POST and on a resume read from a URL endpoint, unless capabilityHandshake: false.
2. A route that passes capabilities: { request, announce } to toDeuzStreamResponse, toDeuzObjectStreamResponse, toDeuzAgentStreamResponse, createDeuzStream or resumeDeuzStreamResponse answers a request that listed anything with the same response header, on any wire version, and on v2 with the first capabilities frame. The list is announce plus what the serializer knows itself: durable-stream for a durable response, or for a resume over a DurableStreamStateStore. Values are lower-case tokens, each once, sorted and joined by ', '; another value throws a TypeError when the response is built.
3. A request without the header, which is every 2.3 client, gets no header and no frame.
4. The client uses a feature only once the server announced it.

parseDeuzCapabilities(source) reads the set from a Request, Response, Headers or header value, and formatDeuzCapabilities builds a header value. A browser reads a cross-origin response header only when the server exposes it with Access-Control-Expose-Headers; otherwise the client reads the first frame.

Durable responses (2.4, preview)

A response with durable: { store, lease } and a streamId keeps the 2.3 frame format, id: numbering and replay through resumeDeuzStreamResponse. What changes is the order: each frame is committed to the DurableStreamStateStore before it is sent, in batches (20 ms or 16 KiB by default), by one producer fenced by its lease token under stream:<streamId>. When the producer is fenced off, the stored log moved past it, or the store fails, the response sends nothing it did not commit, ends with a redacted error frame without an event id and without [DONE], and hands a thrown store error to onStoreError. A client that reconnects to the resume endpoint gets every committed frame once, in order.

The 2.4 wire behaviour is pinned by test/ui-capabilities.test.ts, test/internal-capabilities.test.ts, test/ui-durable.test.ts and test/stream-durable-store.test.ts in packages/core.

Run the focused protocol suite with npm run test:protocol.