🤖 fix: filter streamText's synthesized default finish in StreamManager

[ethanndickson]

Summary

Drop ai's synthesized-default finish part inside StreamManager so that PR #3415's missing-terminal-event guard turns a clean upstream EOF into a retryable stream_truncated error for both OpenAI and Anthropic providers, instead of silently committing partial output as if the assistant finished cleanly.

Background

PR #3415 added a receivedTerminalEvent guard in StreamManager that surfaces a missing terminal SSE event as a retryable stream_truncated error. That guard only fires when the SDK stream ends without emitting any finish part at all. Empirically that branch was unreachable: every real OpenAI and Anthropic stream ends with a finish part — but on truncated upstreams the part is a synthesized default, not a real terminal signal.

The synthesis originates inside the ai package's streamText. Its internal runStep TransformStream initializes:

let stepFinishReason = "other";
let stepRawFinishReason = void 0;

and unconditionally emits those values from its own flush() at end-of-stream — even when the upstream SSE closed before any terminal event arrived. So every adapter ends up looking, at the StreamManager boundary, like it cleanly finished with (other, undefined) regardless of whether it actually did.

Per-provider truncation behavior, observed in the installed source:

• OpenAI (@ai-sdk/openai): each adapter (Responses, Chat Completions, legacy Completions) initializes its own finishReason = { unified: "other", raw: undefined } and emits it from its own flush(). streamText normalizes that to (other, undefined) and forwards it.
• Anthropic (@ai-sdk/anthropic): the adapter has no flush() and only emits its finish part on a real message_stop. On a truncated stream there is no adapter-level finish at all — and streamText's runStep.flush() then synthesizes the same (other, undefined) part.

Same symptom at the StreamManager layer, two different SDK-internal causes.

Implementation

Filter the synthesized default at the streamText → StreamManager boundary — the layer that actually produces it. In StreamManager.processStreamWithCleanup's case "finish": handler, treat a part whose normalized finishReason === "other" and rawFinishReason === undefined as a non-event: do not set receivedTerminalEvent = true. The existing !receivedTerminalEvent branch below then routes the stream to handleTruncatedStreamCompletion, which writes a retryable stream_truncated partial with the streamed text preserved.

Why the discriminator is safe (empirical):

• OpenAI — mapOpenAIResponseFinishReason and mapOpenAIFinishReason only return unified: "other" from their default: branches, which are reached via isResponseFinishedChunk / isResponseFailedChunk, both of which carry a defined raw value. The (other, undefined) shape is therefore unreachable as a real OpenAI finish.
• Anthropic — mapAnthropicStopReason only returns "other" for the "compaction" case and the default: fallback. Both call sites in the adapter (message_delta and message_start handlers) pair the unified reason with raw: value.message.stop_reason (a defined string from the API). (other, undefined) is unreachable as a real Anthropic finish.
• streamText's own flush — the only path in this layer that produces (other, undefined) is the synthesized default in runStep's end-of-stream flush.

So the discriminator distinguishes precisely between "the SDK fabricated a finish to keep the type system happy" and "the model genuinely finished with other". A defensive test guards the false-positive surface: a real (other, "compaction") finish must pass through as a clean completion.

Risks

Behavioral change is localized to streams that previously committed partial output silently on a clean truncated EOF. After this change those surface as retryable stream_truncated errors — the UX PR #3415 originally intended.

Regression surface is the synthesized-default discriminator itself: a false positive would treat a legitimate (other, undefined) finish as truncated, triggering an unnecessary retry. We mitigate by:

1. Tying the discriminator to the empirically-unreachable (other, undefined) shape, verified against the OpenAI and Anthropic mappers (see Implementation).
2. A regression test that asserts real (other, <raw>) finishes (e.g. Anthropic's "compaction") still complete cleanly.

If a future provider adapter does emit (other, undefined) as a real terminal finish, the worst case is a retry — preferable to silently committing partial output as a clean completion.

Pains

The first revision moved this same heuristic into StreamManager and was correctly flagged by Codex as theoretically too broad — the public LanguageModelV2 contract permits any adapter to emit (other, undefined) as a legitimate terminal finish. The second revision scoped a similar filter to the @ai-sdk/openai adapter callsites, which was contract-safe but did not actually fix the bug: streamText's runStep.flush() re-synthesizes the identical part one layer up, and it produced no fix at all for Anthropic where the adapter has no flush() to filter in the first place.

This revision returns the fix to StreamManager but now with concrete evidence — gathered from reading node_modules/{ai,@ai-sdk/openai,@ai-sdk/anthropic}/dist/index.js — that the (other, undefined) shape is unreachable from the two real adapter mappers we care about, and is uniquely produced by streamText's own flush. The discriminator's safety is a property of the two SDKs in use, not a guarantee of the public V2 contract.

---

Generated with mux • Model: anthropic:claude-opus-4-7 • Thinking: xhigh • Cost: $60.15

[ethanndickson]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 34f0d47ac7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ethanndickson]

@codex review

Restructured the fix per your feedback. The discriminator is now scoped to the @ai-sdk/openai adapter boundary instead of living in StreamManager:

• StreamManager is reverted — it stays provider-agnostic.
• New src/node/services/openAISynthesizedFinishFilter.ts exposes wrapOpenAIModelToFilterSynthesizedFinish(model), which pipes doStream's output through a TransformStream that drops only the @ai-sdk/openai adapter family's uninitialized { unified: "other", raw: undefined } default finish part.
• The wrapper is applied at the two createOpenAI(...) callsites in providerModelFactory.ts (direct OpenAI + GitHub Copilot, which routes through the same adapter). No other providers are touched.
• Within this adapter family, the SDK's mapOpenAIResponseFinishReason / mapOpenAIFinishReason only return unified: "other" paired with a defined raw, so (other, undefined) is unreachable in legitimate code paths and dropping it is safe. The heuristic does not generalize to other providers' adapters, which the LanguageModelV2 contract permits to emit (other, undefined) legitimately.
• With the synthesized finish dropped, PR 🤖 fix: require provider stream terminal events #3415's existing !receivedTerminalEvent guard turns a clean upstream EOF into stream_truncated exactly as intended.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ethanndickson]

@codex review

Heads-up for this revision — the fix has moved back into StreamManager, which directly contradicts your earlier feedback on the first revision (resolved thread PRRT_kwDOPxxmWM6GVQKi). Bringing the empirical evidence up-front so we can short-circuit a re-litigation:

Why the in-StreamManager filter is now justified (the earlier objection was theoretical; this revision is grounded in two specific SDKs):

1. The previous adapter-boundary filter did not actually fix the bug. ai's streamText.runStep initializes stepFinishReason = "other" / stepRawFinishReason = void 0 and unconditionally emits those values from its own flush() at end-of-stream (node_modules/ai/dist/index.js line ~7361 init, line ~7670 emission). Even after dropping the OpenAI adapter's synthesized finish, an identical synthesized finish reappears one layer up. The wrapper produced zero behavior change.
2. The bug also exists for @ai-sdk/anthropic, where the adapter has no flush() at all (only message_stop emits a finish). A truncated stream produces no adapter-level finish, so streamText.runStep.flush() synthesizes (other, undefined). There is no Anthropic-adapter boundary to filter.
3. The (other, undefined) shape is unreachable from the two real adapter mappers in use:
   • @ai-sdk/openai's mapOpenAIResponseFinishReason / mapOpenAIFinishReason only return unified: "other" from default: branches reached via isResponseFinishedChunk / isResponseFailedChunk, both of which pair it with a defined raw.
   • @ai-sdk/anthropic's mapAnthropicStopReason returns "other" only for "compaction" and default:; both adapter call sites pair it with raw: value.message.stop_reason (a defined string from the API).
4. A regression test guards the false-positive surface: a real (other, "compaction") finish must still complete cleanly.

The LanguageModelV2 contract objection from the prior round is correct in the abstract, but is not currently realized by either real provider, and the alternative is silently committing partial output as a clean assistant message — which is the original bug. A false positive's worst case is one extra retry; the current behavior loses data.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".