fix(react-headless): stream adapters surface errors, truncation and refusals instead of ending the turn silently

[ankit-thesys]

Closes #1312.

Replaces #1276, which was closed unmerged by accident. Rebased on current main (react-headless 0.17.0). The adapters are unchanged since 0.16.3, so the original adapter cases reproduce on the published 0.17.0. The follow-up also fixes a null-chunk regression introduced on this branch and stored refusal conversion.

Problem

Several wire shapes made a stream adapter do one of three things:

• end the turn silently (no message, no error);
• render a failed or cut-off answer as if it succeeded;
• drop a tool call.

The original adapter cases were reproduced against the published package through AgentInterface. The follow-up regressions have targeted tests; the LangGraph null-chunk crash was introduced on this branch, while repeated tool IDs and stored refusals also affect main.

adapter	case	before	after
openAIAdapter, openAIReadableStreamAdapter, agUIAdapter, openAIResponsesAdapter	in-stream {"error":{…}} record under HTTP 200 (OpenAI SDK, OpenRouter, OpenUI Gateway)	blank turn / answer with no error	RUN_ERROR → error callout; streamed text kept
agUIAdapter, openAIAdapter, openAIResponsesAdapter, vercelAIAdapter	route answers a failure as a plain JSON error body (application/json, HTTP 200)	blank turn	RUN_ERROR
agUIAdapter, openAIAdapter, openAIResponsesAdapter	data:{…} without the optional space (Go fmt.Fprintf, several Python frameworks)	blank turn	parsed (the SSE spec makes the space optional)
openAIAdapter, openAIReadableStreamAdapter	finish_reason: length / content_filter	truncated answer looks complete	RUN_ERROR (code = reason), text kept
openAIAdapter, openAIReadableStreamAdapter	delta.refusal	empty turn	refusal rendered as text
openAIAdapter, openAIReadableStreamAdapter	tool-call turn finished with stop (Gemini, OpenAI-compatible proxies)	no TOOL_CALL_END: the call never reaches "executing"	TOOL_CALL_END on any non-truncating finish reason — the same lifecycle as a tool_calls turn
openAIAdapter, openAIReadableStreamAdapter	repeated tool-call id on argument chunks	call restarts with an empty name	one named call, arguments accumulated; parallel calls stay separate
openAIMessageFormat.fromApi	stored assistant refusal with null content	empty bubble after reload	refusal restored as text; combined with content when both exist
langGraphAdapter	tool_call_chunks: null	crash on this PR branch	null-safe handling; subsequent text and complete tool calls preserved
openAIResponsesAdapter	response.refusal.delta	empty turn	rendered as text
openAIResponsesAdapter	response.incomplete (max_output_tokens, content_filter)	truncated answer looks complete	RUN_ERROR
openAIResponsesAdapter	file_search_call, code_interpreter_call, image_generation_call	no activity at all	tool card with args + result (isError when failed)
openAIResponsesAdapter	web_search_call with status: "failed"	card shows a successful search	isError set, like the other server-run tools
vercelAIAdapter	abort chunk; finish with finishReason length / content-filter	partial answer looks complete	RUN_ERROR
langGraphAdapter	CRLF line endings (valid SSE; some proxies and Windows hosts)	zero events, blank turn	parsed, including a CRLF split across two reads
langGraphAdapter	complete tool_calls with tool_call_chunks: [] (LangChain normalises a missing field to [])	no tool call; result orphaned	tool call announced
eveAdapter	action.result with a status other than completed	card shows success, result text is an error object	isError / error set, card shows the failure

Changes

• _shared/errorFrame.ts: errorFrameToRunError(record) maps a real error to RUN_ERROR. That means a non-empty string error, or an error object with a message or a non-empty code. A chunk whose error is false, "", 0, {} or {code: 0} is left alone.
• _shared/sseLines.ts:
  • sseData(line) accepts data: with or without the optional space.
  • sseDataPayloads(response) yields the data: payloads. When a body has no data: line at all and is a JSON error object of at most 64 KB, it yields that body once. Any other non-SSE body is ignored, as before.
  • Used by the AG-UI, Completions and Responses adapters, so the Responses adapter now shares the same line buffering instead of its own copy.
• _shared/chatCompletions.ts: the Chat Completions chunk mapping, previously duplicated in openai-completions.ts and openai-readable-stream.ts, now lives in one place. Both adapters now differ only in framing. Repeated tool IDs start one call and continue appending arguments without resetting its name.
• _shared/truncation.ts:
  • isTruncationReason() covers the Completions, Responses and AI SDK spellings.
  • truncatedRunError(reason) builds one message per reason family, with the provider's reason as code.
• Responses:
  • Hosted tool calls use their own item id. When a backend omits it, a unique stand-in id bridges the added and done events by output_index. A done item without a matching added event still starts its call, and interleaved or id-less items cannot swap results.
  • Refusal deltas share the output-text case.
• vercel-ai-sdk.ts, langgraph.ts, eve.ts: the cases in the table. LangGraph handles null or empty tool-call chunks without crashing.
• openai-message-format.ts: stored refusals survive reload and combine with text consistently with the streaming adapter.
• Every adapter stops emitting at its first RUN_ERROR. The consumer already stopped there; this keeps the event stream valid for other AG-UI consumers. eveAdapter still reads to the turn boundary so onEvent sees the rest of the turn.
• Docs and changeset:
  • adapters-and-formats.mdx: the callout and the per-adapter bullets describe the new behaviour.
  • Changeset: patch for @openuidev/react-headless.

Decisions worth a look

• Truncation and abort are RUN_ERROR.
  • AG-UI has no warning event, so this is the only signal the UI can show.
  • The consumer keeps the text that already streamed and shows the callout under it.
  • code carries the provider's reason (length, content_filter, max_output_tokens, content-filter) or abort, so an app can treat them differently.
  • Tool calls left open by a truncation are not ended, because their arguments may be cut off; the RUN_ERROR clears them.
  • If you'd rather surface these another way, it is one helper to change.
• Patch or minor? A truncated answer used to end a turn normally and now ends it with an error callout. I marked this as a patch because it fixes a silent failure; say if you'd rather call it minor.
• Refusals render as plain text, matching what the model returned. openAIConversationMessageFormat.fromApi still prefixes a stored refusal with [Refusal]: on reload; I left that alone.
• Every TEXT_MESSAGE_START now has its TEXT_MESSAGE_END. Completions tool turns end their message, and text after a finished step opens a new one. The bundled consumer ignores the event.
• A tool call with no result shows "streaming" once the run ends. createChatStore clears executingToolCallIds when a run finishes, so any call without a TOOL_CALL_RESULT goes back to "streaming". That includes a normal tool_calls turn on main, and a call cut off by truncation. A "finished arguments, no result" or "interrupted" state would need a new ToolCallStatus value and react-ui rendering, so it isn't part of this change. Worth a decision.
• No closing at stream end. A stream that stops without any finish_reason is left as it is rather than "closed", because it may have been cut off.
• image_generation_call reports {status, image: "generated"} as the tool result instead of copying the base64 image into the tool message.
• Not in this PR: custom_tool_call and computer_call. They would need openAIConversationMessageFormat to send their outputs back as custom_tool_call_output / computer_call_output first, so they're left for a follow-up.

Tests

• sseAdapters.test.ts, covering Completions, Responses and AG-UI. It includes the review edge cases:
  • a falsy error field;
  • a non-streamed chat.completion body;
  • error bodies over 64 KB;
  • a half-written tool call cut off by length;
  • a stream with no finish_reason;
  • hosted-tool id fallbacks and interleaved ids;
  • text after a finished step;
  • a null record or a malformed tool_calls value is skipped and the answer after it still renders (both framings; these guard a regression and pass on main too);
  • repeated tool IDs through SSE and NDJSON, including consumer state and parallel calls;
  • a terminal RUN_ERROR.
• The Eve, LangGraph and Vercel cases sit in each adapter's existing test file, including Eve's onEvent after turn.failed and LangGraph's error event stopping the stream.
• errorFrames.test.ts: cases built from Gateway frames.
• Shared helpers are in streamTestHelpers.ts (flushPromises, a consumer runner).
• Follow-up regression tests: null LangGraph chunks with following text and complete tool calls; six stored-message conversion cases, including refusal round trips. The new bug cases failed before these fixes.
• Package: 304 tests passing in 25 files, ci (lint + format), typecheck and build (tsdown) all clean.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openui-docs	Ready	Preview	Oct 7, 2026 12:24pm UTC

[ankit-thesys]

Basically, talking about how errors are handled in our adapters, if we dont need it we can skip this part