What happens#
When a Responses stream hits max_output_tokens, it ends with response.incomplete (status: "incomplete", incomplete_details.reason: "max_output_tokens"), and that event carries the response's usage. The Responses adapter in @tanstack/openai-base turns it into RUN_ERROR (message: "max_output_tokens", code: "incomplete") and drops the usage:
https://github.com/TanStack/ai/blob/ae976552710726b13b524c307c1b5bbe78478eb0/packages/openai-base/src/adapters/responses-text.ts#L1748-L1806
So with the Responses adapter:
- the run ends in
onError, not onFinish, right after the partial text the user has already seen;
onUsage never fires, although the provider billed the tokens;
finishReason: 'length' never appears, so untilFinishReason(['length']) and the core stop-on-length path (#1874) never see a capped answer.
The response.completed branch already maps incomplete_details.reason (max_output_tokens → length, content_filter → content_filter), "mirroring the chat-completions adapter". A capped response does not arrive as response.completed, so that mapping is not reached for it:
https://github.com/TanStack/ai/blob/ae976552710726b13b524c307c1b5bbe78478eb0/packages/openai-base/src/adapters/responses-text.ts#L2442-L2473
The Chat Completions adapter reports the same cutoff as RUN_FINISHED with usage and finishReason: 'length'.
Repro#
@tanstack/ai 1.0.0, @tanstack/openai-base 1.0.0, @tanstack/ai-vercel-gateway 1.0.0, server-side chat() on Node 24
for await (const chunk of chat({
adapter: createVercelGatewayText('openai/gpt-4.1-nano', key),
messages: [{ role: 'user', content: 'Count from 1 to 300, separated by commas.' }],
threadId: 'repro',
modelOptions: { max_output_tokens: 16 },
middleware: [{ name: 'probe', onUsage, onFinish, onError }],
})) {
if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') console.log(chunk)
}
| Adapter | Terminal chunk | onUsage | Terminal hook |
|---|
| Responses (default) | RUN_ERROR { message: 'max_output_tokens', code: 'incomplete' } | not called | onError |
Chat Completions (api: 'chat', max_tokens: 16) | RUN_FINISHED, usage 19 / 16 | called once | onFinish, finishReason: 'length' |
On the Responses adapter the chunks arrive as RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT (62 characters), TEXT_MESSAGE_END, RUN_ERROR. anthropic/claude-sonnet-5.5 gives the same RUN_ERROR. A direct POST https://ai-gateway.vercel.sh/v1/responses with stream: true and max_output_tokens: 16 ends like this for both models (gpt-4.1-nano shown):
{
"type": "response.incomplete",
"response": {
"status": "incomplete",
"incomplete_details": { "reason": "max_output_tokens" },
"usage": { "input_tokens": 19, "output_tokens": 16, "…": "…" }
}
}
The openai SDK types describe response.incomplete as "An event that is emitted when a response finishes as incomplete", with incomplete_details.reason one of max_output_tokens, max_messages, content_filter, steered.
Expected#
response.incomplete with incomplete_details.reason max_output_tokens or content_filter ends the run the way the Chat Completions adapter does: RUN_FINISHED with the response's usage and finishReason: 'length' or 'content_filter'. response.failed, and an incomplete response without a known reason, stay RUN_ERROR.
Why#
We stop our agent loop with untilFinishReason(['length']) and record usage per model call. On the Responses adapter, a capped answer shows the user an error after a partial answer, and its tokens are not recorded.
Confirmed on
ae97655, the SHA your permalinks point at. The cause is thatresponse.incompleteis only ever handled by theresponse.failed || response.incompleteterminal branch, which unconditionally yieldsRUN_ERRORand never looks atchunk.response.usage. Theincomplete_details.reasontofinishReasonmapping exists only in theresponse.completedbranch, and a capped response never arrives asresponse.completed, so nothing maps it.I reproduced it offline with no API key, reusing the package's own stub-client pattern: one canned
response.incompletecarryingincomplete_details.reason: 'max_output_tokens'plususage, on the Responses adapter, against the equivalentfinish_reason: 'length'plus usage-tail chunk on the Chat Completions adapter. Both are driven throughchat()with anonUsage/onFinish/onErrormiddleware, and I also read the adapter's ownchatStream()output directly.That matches your report line for line. One detail worth knowing for the fix:
finishReasonis carried on the adapter's ownRUN_FINISHEDchunk and in theFinishInfopassed toonFinish, not on theRUN_FINISHEDchunkchat()re-emits, which is whatuntilFinishReasonreads through the agent-loop strategy.Fix#
In that branch, after the lifecycle close (
closeReasoning()and theTEXT_MESSAGE_ENDpair) and before theRUN_ERRORpayload is built, treat a knownincomplete_details.reasonas a completed-but-capped response:With only that applied, the two adapters produce identical output on the same cutoff:
And the whole package suite:
402 pass. The 2 failures are the tests that currently pin the old behaviour, so a fix is a deliberate behaviour change with a known footprint:
error handling > emits RUN_ERROR on response.incomplete event(its fixture is exactlymax_output_tokens)error handling > flushes completed web searches before RUN_ERROR on incomplete response— itsTOOL_CALL_START/TOOL_CALL_ENDflush still happens, becauseemitProviderWebSearchCallsruns earlier in the same branch; only the terminal chunk it asserts on changes.Two things the minimal patch above does not cover:
packages/ai-openrouter/src/adapters/responses-text.tsoverridesprocessStreamChunksand repeats this branch twice (at lines 630 and 1099), keyed on camelCaseincompleteDetails. OpenRouter keeps the currentRUN_ERRORbehaviour unless it is mirrored there.response.completedbranch also drainsfunction_call/ user-tool /shell_callitems and can resolvefinishReasonto'tool_calls'; the incomplete branch does not. A cutoff that interrupts a tool call probably wants to route into that shared path rather than duplicate theRUN_FINISHEDemission.response.failed, andresponse.incompletewith a missing or unrecognisedincomplete_details.reason, stayRUN_ERRORunder this patch, which is what you asked for.The repro file (
packages/openai-base/tests/repro-1916.test.ts, no API key needed)The usage half of this is a failure mode we have written up separately: a terminal error path that drops the usage record, so per-model token totals quietly under-count work the provider already billed. Our note on it is item 5 of our catalogue (ours): https://github.com/aron-intframe/agent-guards