Streaming 101: when is a response actually finished?

Streaming is a way to deliver a response incrementally while work proceeds, instead of waiting to deliver the whole body at once. It is a delivery behavior, not a language, model or agent framework. It can make progress visible sooner; it does not by itself make generation faster or the answer correct.

Think of a download progress display. Seeing bytes arrive is different from having a complete, usable file. The analogy has a limit: a generated response usually does not have a known final size, and its content still needs review.

In the supplied lab, an event has an event: line, a data: line containing JSON and a blank line that ends the event. The reader must wait for that boundary before parsing the JSON. The service invents start, text_delta and done for this teaching exercise. They are not a provider's API contract.

Our fictional service writes three additions: Café , pump: and check seal. The client accumulates them into Café pump: check seal. while marking the preview as partial. The accented character is intentional: one character can occupy more than one byte. The same decoder keeps its state across reads.

Follow four decisions in order:

1. Confirm the HTTP status and content type before interpreting the body.
2. Decode bytes, retain unfinished text, then parse complete event records.
3. Update the preview as deltas arrive while keeping it visibly provisional.
4. Require the documented completion and acceptable stop reason, then validate the assembled result before the application's next action.

HTTP 200 only describes the response status. The body can subsequently break, end early or contain invalid events. Our lab waits for normal transport end, valid records and done with reason normal before marking a result ready-for-content-review. That deliberately narrow result is not permission to execute a tool or publish the text.

Download fde-streaming-lab.mjs into a new folder. Use the same Node.js 24 command throughout:

node --version
node fde-streaming-lab.mjs

The file starts a server bound to 127.0.0.1 on an available port, makes six requests and closes the listener. It writes no files and reads no credentials. The server's short pauses make intermediate states observable; they are not measurements of inference performance. It does not retry failed requests.

Before running it, predict the completion decision for each case:

Compare httpStatus, transportEnded, events, completionObserved, reason and decision. All six begin with 200. In previews, find text that appeared before any completion event. Do not infer a token count from text length, event count or receivedChunkBytes: the lab runs no model or tokenizer.

receivedChunkBytes records actual body reads; their grouping can vary by runtime and transport. parserSlices counts the pieces passed into our decoder. The fragmented case deliberately re-slices received bytes on the client. It does not claim that the network delivered one-byte packets. The controlled experiment isolates the parser's ability to preserve boundaries.

Keep the original file. In a first copy, change SLICE_BYTES = 1 to SLICE_BYTES = 7 and rerun. The fragmented case should have fewer parser calls but the same five events and complete text. A reader that relies on each read being a complete JSON object cannot meet that property.

Starting from the original, make a second copy and change REQUIRE_DONE = true to REQUIRE_DONE = false. This deliberately weakens the example's acceptance rule. The missing-done case now promotes Café pump: even though no completion arrived. The lost connection, invalid record and explicit length limit should still be withheld. Explain why a check that only asserts a nonempty response would miss this defect. Do not carry this broken rule into an application.

This is a small protocol lesson, not a general-purpose SSE implementation. The reader supports only the two-field, LF-delimited records emitted by this server. A complete SSE parser also handles other line endings, comments, multiple data lines and additional fields. Use the maintained SDK or parser appropriate to your production service, then test its behavior at your application's boundary.

Claude's documented stream has message and content-block events, text or tool input deltas, a stop reason and final message_stop. These names differ from our teaching protocol. Follow the provider's current SDK and event contract. Tool input can arrive as JSON fragments: a fragment is not yet validated tool arguments. Assemble the intended input, validate its schema and authorize the operation in trusted application code before executing it.

If the stream fails, retain an explicitly incomplete preview and the request's safe diagnostic metadata. A missing final event does not tell you whether a remote operation continued, how much it cost or whether an external effect occurred. Reconnection and safe retry are separate designs. This lab performs one attempt per case and has no continuation, replay or effect reconciliation.

In the UI, separate “receiving,” “ready for review,” “stopped” and “interrupted.” Do not let partial markup run as HTML or partial tool input trigger an action. When a user cancels, stop consuming and request supported cancellation; verify what the provider actually promises about remote work and billing. The local connection-lost case does not test provider cancellation.

For a real deployment, inspect buffering at the application, proxy and gateway. Measure first useful output and completed useful output separately. A responsive animation cannot establish either result. Do not add timing claims based on this fixture's deliberate pauses.

Produce a small integration card with:

• The actual endpoint, content type, event schema and supported client version.
• Which preview states are visible and what qualifies as completed input.
• The acceptable stop reasons and content checks before downstream work.
• What happens after malformed data, a disconnect, timeout or user cancellation.
• How request identity, retry policy and unknown usage are recorded safely.

Keep your six predictions, observed report and two independent changes. Ask a receiver why both a clean HTTP end and a visible sentence can still be insufficient. Then give them a tool-input fragment and ask what must happen before an agent may use it. A good explanation names assembly, validation, authorization and the unresolved remote outcome without inventing certainty.

Continue in the guided streaming lesson with existing training access, then build the first bounded LangChain agent.

Primary references checked 22 October 2026:

• MDN: using server-sent events
• Anthropic: streaming messages
• Node.js 24: HTTP