Skip to content

[BUG] OpenAIModel (Responses, TypeScript) reports toolUse instead of maxTokens when a function call is cut off by max_output_tokens #4158

Open

Description

@BlueX888

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:

  • OpenAIModel with api: 'chat' reports maxTokens for the same scenario: chat-adapter.ts maps finish_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.
  • MaxTokensError is documented as the error for "when the model reaches its maximum token limit" (model.ts streamAggregated docstring), and [BUG] SyntaxError instead of MaxTokensError when tool_use JSON is truncated #2451 (closed) established that a truncated tool-use JSON should surface as MaxTokensError, not as a JSON SyntaxError.
  • The OpenAI SDK documents incomplete_details.reason as '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=maxTokens already asserts maxTokens for 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).

Activity

  1. added
    typescriptPull requests that update typescript code
    bugSomething isn't working
    on Sep 4, 2026
  2. BlueX888 commented on Sep 4, 2026

    @BlueX888
    ContributorAuthor

    Opened #4159 with the fix and a regression test.

  3. canblmz1 commented on Oct 23, 2026

    @canblmz1

    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: native MaxTokensError versus a PSJ refusal wrapped as ModelError.

    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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-modelRelated to models or model providersarea-toolTool behavior/apibugSomething isn't workingready for contributionPull requests welcometypescriptPull requests that update typescript code

    Type

    Fields

    Language

    TypeScript

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions