Repository navigation
Description
Checks
- I have updated to the lastest minor and patch version of Strands
- I have checked the documentation and this is not expected behavior
- I have searched ./issues and there are no duplicates of my issue
SDK Language
TypeScript
Strands Version
@strands-agents/sdk 1.16.0 (npm) — same code on main @ 24bc5c3
Language Runtime Version
Node.js 22.23.2
Operating System
macOS 26.2
Installation Method
git clone
Steps to Reproduce
This is the TypeScript counterpart of #4135 (fixed for Python in #4139). The Responses adapter in strands-ts has the same stop-reason precedence, so it was left out of that PR to keep it focused.
When the Responses API stream emits response.incomplete with incomplete_details.reason === 'max_output_tokens' after a function_call output item has started, finalizeResponsesStream reports stopReason: 'toolUse' instead of 'maxTokens'. Downstream, Model.streamAggregated then either throws a generic ModelError('unable to parse tool input JSON') (if some argument bytes streamed) or executes the tool with input: {} (if the cut-off happened before any argument bytes), instead of raising MaxTokensError.
Minimal reproduction as a vitest file (no network; the client is mocked the same way src/models/openai/__tests__/responses.test.ts does). Drop it into strands-ts/src/models/openai/__tests__/ and run npx vitest run --project unit-node <file>:
import { describe, it, vi } from 'vitest'
import { z } from 'zod'
import { OpenAIModel } from '../index.js'
import { Agent } from '../../../agent/agent.js'
import { tool } from '../../../tools/tool-factory.js'
import { Message, TextBlock } from '../../../types/messages.js'
import { collectIterator } from '../../../__fixtures__/model-test-helpers.js'
// A response whose function_call arguments are cut off by max_output_tokens.
const TRUNCATED = [
{ type: 'response.created', response: { id: 'resp_1' } },
{ type: 'response.output_item.added', item: { type: 'function_call', id: 'fc_1', call_id: 'call_1', name: 'write_file' } },
{ type: 'response.function_call_arguments.delta', item_id: 'fc_1', delta: '{"path": "notes.md", "content": "Lorem ipsum dol' },
{ type: 'response.incomplete', response: { incomplete_details: { reason: 'max_output_tokens' }, usage: { input_tokens: 10, output_tokens: 50, total_tokens: 60 } } },
]
// Same, but cut off before any argument bytes streamed.
const TRUNCATED_NO_ARGS = [TRUNCATED[0], TRUNCATED[1], TRUNCATED[3]]
const SECOND = [
{ type: 'response.created', response: { id: 'resp_2' } },
{ type: 'response.output_text.delta', delta: 'Done.' },
{ type: 'response.completed', response: { usage: { input_tokens: 20, output_tokens: 2, total_tokens: 22 } } },
]
function mockClient(...streams: any[][]) {
let i = 0
return {
responses: {
create: vi.fn(async () => {
const items = streams[Math.min(i++, streams.length - 1)]
return (async function* () { for (const it of items) yield it })()
}),
},
} as any
}
function makeAgent(client: any, calls: unknown[]) {
const writeFile = tool({
name: 'write_file',
description: 'Write content to a file.',
inputSchema: z.object({ path: z.string().optional(), content: z.string().optional() }),
callback: (input) => { calls.push(input); return `wrote ${input.content?.length ?? 0} bytes to ${input.path}` },
})
const model = new OpenAIModel({ api: 'responses', client, maxTokens: 50 })
return new Agent({ model, tools: [writeFile], printer: false })
}
describe('repro', () => {
it('1) model-level stopReason', async () => {
const model = new OpenAIModel({ api: 'responses', client: mockClient(TRUNCATED), maxTokens: 50 })
const events = await collectIterator(model.stream([new Message({ role: 'user', content: [new TextBlock('save my notes')] })]))
console.log('modelMessageStopEvent:', JSON.stringify(events.find((e: any) => e.type === 'modelMessageStopEvent')))
})
for (const [label, stream] of [['partial args', TRUNCATED], ['no args yet', TRUNCATED_NO_ARGS]] as const) {
it(`2) agent-level effect (${label})`, async () => {
const calls: unknown[] = []
const agent = makeAgent(mockClient(stream, SECOND), calls)
try {
const result = await agent.invoke('save my notes')
console.log('agent stopReason:', result.stopReason, '| tool invoked with:', JSON.stringify(calls))
for (const m of agent.messages) console.log(m.role, JSON.stringify(m.content))
} catch (e: any) {
console.log('threw:', e.name, '-', e.message)
}
})
}
})Expected Behavior
modelMessageStopEvent should carry stopReason: 'maxTokens', so Model.streamAggregated throws MaxTokensError (src/models/model.ts, if (finalStopReason === 'maxTokens') throw new MaxTokensError(...)) and the truncated tool call is never executed.
Basis:
OpenAIModelwithapi: 'chat'reportsmaxTokensfor the same scenario:chat-adapter.tsmapsfinish_reason: 'length'→'maxTokens'regardless of accumulated tool-call deltas.- The Python Responses model was changed to exactly this precedence in fix(openai): report max_tokens when a Responses function call is cut off #4139 (merged 2026-09-03); the two adapters now disagree.
MaxTokensErroris documented as the error for "when the model reaches its maximum token limit" (model.tsstreamAggregateddocstring), and [BUG] SyntaxError instead of MaxTokensError when tool_use JSON is truncated #2451 (closed) established that a truncated tool-use JSON should surface asMaxTokensError, not as a JSONSyntaxError.- The OpenAI SDK documents
incomplete_details.reasonas'max_output_tokens' | 'content_filter'— a function call whose arguments were cut off is by definition incomplete. - The existing test
maps response.incomplete with max_output_tokens to stopReason=maxTokensalready assertsmaxTokensfor the text-only case; the tool-call case is just not covered.
Actual Behavior
Output on main @ 24bc5c3 (the compiled dist/src/models/openai/responses-adapter.js in @strands-agents/[email protected] has the same if (state.toolCalls.size > 0) stopReason = 'toolUse'):
modelMessageStopEvent: {"type":"modelMessageStopEvent","stopReason":"toolUse"}
Agent-level, partial arguments streamed:
unable to parse tool input JSON SyntaxError: Unterminated string in JSON at position 48 (line 1 column 49)
at JSON.parse (<anonymous>)
at OpenAIModel.streamAggregated (.../strands-ts/src/models/model.ts:520:54)
threw: ModelError - unable to parse tool input JSON
Agent-level, cut off before any argument bytes:
agent stopReason: endTurn | tool invoked with: [{}]
user [{"text":"save my notes"}]
assistant [{"toolUse":{"name":"write_file","toolUseId":"call_1","input":{}}}]
user [{"toolResult":{"toolUseId":"call_1","status":"success","content":[{"text":"wrote 0 bytes to undefined"}]}}]
assistant [{"text":"Done."}]
So the truncation is never surfaced as MaxTokensError: callers either get a generic ModelError about JSON, or the tool actually runs with empty input and the run ends with endTurn.
Root cause: src/models/openai/responses-adapter.ts, finalizeResponsesStream:
let stopReason = state.stopReason
if (state.toolCalls.size > 0) {
stopReason = 'toolUse'
}state.toolCalls is populated on response.output_item.added, i.e. before any arguments have streamed, so any function call in flight when the response is cut off overrides the 'maxTokens' set by the response.incomplete handler.
Additional Context
#3170 (port of the max-tokens partial-message recovery) is the follow-on that decides what the agent does after MaxTokensError; this issue is only about the adapter reporting the wrong stop reason in the first place, which blocks that path entirely.
I'm happy to open the PR (same shape as #4139: keep 'maxTokens' when it was set from incomplete_details, plus a regression test for the truncated-tool-call case). Verified locally that this makes the repro print stopReason: 'maxTokens' / throw MaxTokensError and that the existing 60 tests in responses.test.ts still pass.
Possible Solution
In finalizeResponsesStream, only override with 'toolUse' when state.stopReason !== 'maxTokens'.
Related Issues
#4135 / #4139 (Python fix for the same precedence), #3170 (TS max-tokens recovery port, downstream of this), #2451 (truncated tool JSON should be MaxTokensError).
Metadata
Metadata
Assignees
Labels
Type
Fields
Language
Activity
BlueX888 commentedon Sep 4, 2026
Opened #4159 with the fix and a regression test.
canblmz1 commentedon Oct 23, 2026
I maintain Prefix-Safe JSON. Thanks for the reproduction and approved native fix #4159; I would leave that PR untouched.
I checked released
@strands-agents/[email protected]in a clean consumer using your two cutoff fixtures plus a healthy control. The no-argument cutoff still invokes the optional-schema callback once with{}and continues with a success result. Ordinary partial JSON is already refused natively.The small development-only reference and raw results compare the released SDK, a public subclass applying only #4159's precedence condition, and published
[email protected]checking the original Responses events. The native control and PSJ both prevent the cutoff callbacks; healthy calls preserve the original ID and continuation. This does not test the installed PR itself. Their error contracts differ: nativeMaxTokensErrorversus a PSJ refusal wrapped asModelError.These are scripted, memory-only callbacks, not file writes or a production integration. PSJ shows no additional callback protection over your native fix here.
Would you retain an optional raw-response reference check for SDK upgrades, or does the native regression fully cover what you want to maintain?