Skip to content

Commit 95439a0

Browse files
committed
fix: streaming tool-call argument loss in NativeToolCallParser (#695)
1 parent e8acc6a commit 95439a0

5 files changed

Lines changed: 216 additions & 23 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"zoo-code": patch
3+
---
4+
5+
Fix streaming tool-call arguments being dropped when argument deltas arrive before the tool-call id, which caused spurious "missing required parameter" errors (affects LiteLLM, OpenAI-compatible, and DeepSeek providers).
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
### Related GitHub Issue
2+
3+
Closes: #695
4+
5+
### Description
6+
7+
When a provider streams a tool call whose first delta(s) arrive *before* the tool-call `id` is known, those leading argument bytes are silently discarded by `NativeToolCallParser.processRawChunk`. This causes downstream "missing required parameter" errors even when the model supplied the data.
8+
9+
This PR fixes the issue by centralizing the tracking of streaming tool calls in `NativeToolCallParser`. The `rawChunkTracker` is now initialized on the first sight of a stream `index`, independent of whether an `id` is present. All `arguments` deltas are buffered until both `id` and `name` are known, ensuring no data loss during streaming reassembly.
10+
11+
### Test Procedure
12+
13+
1. Ran the newly added unit test in `src/core/assistant-message/__tests__/NativeToolCallParser.spec.ts` which verifies that leading argument bytes arriving before the `id` are correctly preserved and finalized.
14+
2. Verified that existing provider tests in the same test file pass.
15+
16+
### Pre-Submission Checklist
17+
18+
- [x] **Issue Linked**: This PR is linked to an approved GitHub Issue.
19+
- [x] **Scope**: My changes are focused on the linked issue (one major feature/fix per PR).
20+
- [x] **Self-Review**: I have performed a thorough self-review of my code.
21+
- [x] **Testing**: New and/or updated tests have been added to cover my changes.
22+
- [x] **Documentation Impact**: I have considered if my changes require documentation updates.
23+
- [x] **Contribution Guidelines**: I have read and agree to the [Contributor Guidelines](/CONTRIBUTING.md).
24+
25+
### Screenshots / Videos
26+
27+
N/A
28+
29+
### Documentation Updates
30+
31+
- [x] No documentation updates are required.
32+
33+
### Additional Notes
34+
35+
N/A
36+
37+
### Get in Touch
38+
39+
@awschmeder

‎src/core/assistant-message/NativeToolCallParser.ts‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ export class NativeToolCallParser {
6666
private static rawChunkTracker = new Map<
6767
number,
6868
{
69-
id: string
69+
id?: string
7070
name: string
7171
hasStarted: boolean
7272
deltaBuffer: string[]
@@ -105,10 +105,11 @@ export class NativeToolCallParser {
105105
const events: ToolCallStreamEvent[] = []
106106
const { index, id, name, arguments: args } = chunk
107107

108+
// Create the tracker on first sight of this index, independent of whether
109+
// an id has arrived yet. Keying the lifecycle by index (not id) ensures any
110+
// `arguments` that stream before the id is known are buffered rather than dropped.
108111
let tracked = this.rawChunkTracker.get(index)
109-
110-
// Initialize new tool call tracking when we receive an id
111-
if (id && !tracked) {
112+
if (!tracked) {
112113
tracked = {
113114
id,
114115
name: name || "",
@@ -118,38 +119,39 @@ export class NativeToolCallParser {
118119
this.rawChunkTracker.set(index, tracked)
119120
}
120121

121-
if (!tracked) {
122-
return events
122+
// Record id and name as they arrive (they may come in separate chunks).
123+
if (id) {
124+
tracked.id = id
123125
}
124-
125-
// Update name if present in chunk and not yet set
126126
if (name) {
127127
tracked.name = name
128128
}
129129

130-
// Emit start event when we have the name
131-
if (!tracked.hasStarted && tracked.name) {
130+
// Emit start event only once both id and name are known. Using a local
131+
// non-null id keeps emitted events typed as id: string.
132+
if (!tracked.hasStarted && tracked.id && tracked.name) {
133+
const startedId = tracked.id
132134
events.push({
133135
type: "tool_call_start",
134-
id: tracked.id,
136+
id: startedId,
135137
name: tracked.name,
136138
})
137139
tracked.hasStarted = true
138140

139-
// Flush buffered deltas
141+
// Flush buffered deltas accumulated during the pre-start window.
140142
for (const bufferedDelta of tracked.deltaBuffer) {
141143
events.push({
142144
type: "tool_call_delta",
143-
id: tracked.id,
145+
id: startedId,
144146
delta: bufferedDelta,
145147
})
146148
}
147149
tracked.deltaBuffer = []
148150
}
149151

150-
// Emit delta event for argument chunks
152+
// Emit delta event for argument chunks, buffering until start is emitted.
151153
if (args) {
152-
if (tracked.hasStarted) {
154+
if (tracked.hasStarted && tracked.id) {
153155
events.push({
154156
type: "tool_call_delta",
155157
id: tracked.id,
@@ -172,10 +174,15 @@ export class NativeToolCallParser {
172174

173175
if (finishReason === "tool_calls" && this.rawChunkTracker.size > 0) {
174176
for (const [, tracked] of this.rawChunkTracker.entries()) {
175-
events.push({
176-
type: "tool_call_end",
177-
id: tracked.id,
178-
})
177+
// Only emit an end for trackers that actually started. A tracker that
178+
// never received an id/name (malformed stream) must not emit a phantom
179+
// end; since start requires an id, hasStarted implies tracked.id is set.
180+
if (tracked.hasStarted && tracked.id) {
181+
events.push({
182+
type: "tool_call_end",
183+
id: tracked.id,
184+
})
185+
}
179186
}
180187
}
181188

@@ -191,7 +198,7 @@ export class NativeToolCallParser {
191198

192199
if (this.rawChunkTracker.size > 0) {
193200
for (const [, tracked] of this.rawChunkTracker.entries()) {
194-
if (tracked.hasStarted) {
201+
if (tracked.hasStarted && tracked.id) {
195202
events.push({
196203
type: "tool_call_end",
197204
id: tracked.id,

‎src/core/assistant-message/__tests__/NativeToolCallParser.spec.ts‎

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { NativeToolCallParser } from "../NativeToolCallParser"
1+
import { NativeToolCallParser, type ToolCallStreamEvent } from "../NativeToolCallParser"
22

33
describe("NativeToolCallParser", () => {
44
beforeEach(() => {
@@ -343,4 +343,146 @@ describe("NativeToolCallParser", () => {
343343
})
344344
})
345345
})
346+
347+
describe("processRawChunk streaming reassembly", () => {
348+
// Mirror the sequencing Task.ts performs: feed each raw chunk through
349+
// processRawChunk, drive startStreamingToolCall on tool_call_start, feed
350+
// tool_call_delta into processStreamingChunk, and finalize at the end.
351+
// Returns the ordered event types/ids plus the finalized tool uses by id.
352+
const drive = (
353+
rawChunks: Array<{ index: number; id?: string; name?: string; arguments?: string }>,
354+
finishReason: string | null = "tool_calls",
355+
) => {
356+
const events: ToolCallStreamEvent[] = []
357+
358+
const handleEvent = (event: ToolCallStreamEvent) => {
359+
events.push(event)
360+
if (event.type === "tool_call_start") {
361+
NativeToolCallParser.startStreamingToolCall(event.id, event.name)
362+
} else if (event.type === "tool_call_delta") {
363+
NativeToolCallParser.processStreamingChunk(event.id, event.delta)
364+
}
365+
}
366+
367+
for (const chunk of rawChunks) {
368+
for (const event of NativeToolCallParser.processRawChunk(chunk)) {
369+
handleEvent(event)
370+
}
371+
}
372+
373+
// Task.ts emits ends via processFinishReason on finish_reason: "tool_calls".
374+
// Use clearRawChunkState (not finalizeRawChunks) for cleanup so we don't
375+
// double-count the end events both paths would produce.
376+
for (const event of NativeToolCallParser.processFinishReason(finishReason)) {
377+
handleEvent(event)
378+
}
379+
NativeToolCallParser.clearRawChunkState()
380+
381+
const finalized = new Map<string, ReturnType<typeof NativeToolCallParser.finalizeStreamingToolCall>>()
382+
const startIds = events.filter((e) => e.type === "tool_call_start").map((e) => e.id)
383+
for (const id of startIds) {
384+
finalized.set(id, NativeToolCallParser.finalizeStreamingToolCall(id))
385+
}
386+
387+
return { events, finalized }
388+
}
389+
390+
it("preserves leading argument bytes that arrive before the id", () => {
391+
// First chunk carries arguments but NO id; id+name arrive later, then more args.
392+
const fullArgs = JSON.stringify({ path: "src/leading.ts", mode: "slice" })
393+
const firstHalf = fullArgs.slice(0, 10)
394+
const secondHalf = fullArgs.slice(10)
395+
396+
const { events, finalized } = drive([
397+
{ index: 0, arguments: firstHalf },
398+
{ index: 0, id: "call_late_id", name: "read_file" },
399+
{ index: 0, arguments: secondHalf },
400+
])
401+
402+
// Exactly one start, in the right order, with the late id.
403+
const starts = events.filter((e) => e.type === "tool_call_start")
404+
expect(starts).toHaveLength(1)
405+
expect(starts[0].id).toBe("call_late_id")
406+
407+
// The finalized arguments must contain the complete, uncorrupted payload.
408+
const result = finalized.get("call_late_id")
409+
expect(result).not.toBeNull()
410+
expect(result?.type).toBe("tool_use")
411+
if (result?.type === "tool_use") {
412+
const nativeArgs = result.nativeArgs as { path: string; mode?: string }
413+
expect(nativeArgs.path).toBe("src/leading.ts")
414+
expect(nativeArgs.mode).toBe("slice")
415+
}
416+
})
417+
418+
it("handles id and name arriving in separate chunks (issue #218)", () => {
419+
const fullArgs = JSON.stringify({ path: "src/split.ts" })
420+
421+
const { events, finalized } = drive([
422+
{ index: 0, id: "call_split" },
423+
{ index: 0, name: "read_file" },
424+
{ index: 0, arguments: fullArgs },
425+
])
426+
427+
const starts = events.filter((e) => e.type === "tool_call_start")
428+
expect(starts).toHaveLength(1)
429+
expect(starts[0].id).toBe("call_split")
430+
431+
const result = finalized.get("call_split")
432+
expect(result?.type).toBe("tool_use")
433+
if (result?.type === "tool_use") {
434+
const nativeArgs = result.nativeArgs as { path: string }
435+
expect(nativeArgs.path).toBe("src/split.ts")
436+
}
437+
})
438+
439+
it("keeps two parallel tool calls on distinct indices isolated", () => {
440+
const argsA = JSON.stringify({ path: "src/a.ts" })
441+
const argsB = JSON.stringify({ path: "src/b.ts" })
442+
443+
const { events, finalized } = drive([
444+
{ index: 0, arguments: argsA.slice(0, 8) },
445+
{ index: 1, arguments: argsB.slice(0, 8) },
446+
{ index: 0, id: "call_a", name: "read_file" },
447+
{ index: 1, id: "call_b", name: "read_file" },
448+
{ index: 0, arguments: argsA.slice(8) },
449+
{ index: 1, arguments: argsB.slice(8) },
450+
])
451+
452+
const starts = events.filter((e) => e.type === "tool_call_start")
453+
expect(starts).toHaveLength(2)
454+
455+
const resultA = finalized.get("call_a")
456+
const resultB = finalized.get("call_b")
457+
if (resultA?.type === "tool_use") {
458+
expect((resultA.nativeArgs as { path: string }).path).toBe("src/a.ts")
459+
}
460+
if (resultB?.type === "tool_use") {
461+
expect((resultB.nativeArgs as { path: string }).path).toBe("src/b.ts")
462+
}
463+
})
464+
465+
it("emits the same event sequence for the single-chunk-with-id flow (regression guard)", () => {
466+
const fullArgs = JSON.stringify({ path: "src/single.ts" })
467+
468+
const { events, finalized } = drive([
469+
{ index: 0, id: "call_single", name: "read_file", arguments: fullArgs },
470+
])
471+
472+
expect(events.map((e) => e.type)).toEqual(["tool_call_start", "tool_call_delta", "tool_call_end"])
473+
expect(events.every((e) => e.id === "call_single")).toBe(true)
474+
475+
const result = finalized.get("call_single")
476+
if (result?.type === "tool_use") {
477+
expect((result.nativeArgs as { path: string }).path).toBe("src/single.ts")
478+
}
479+
})
480+
481+
it("does not emit a phantom tool_call_end for a tracker that never received an id", () => {
482+
const { events } = drive([{ index: 0, arguments: '{"path":"orphan.ts"}' }])
483+
484+
expect(events.filter((e) => e.type === "tool_call_start")).toHaveLength(0)
485+
expect(events.filter((e) => e.type === "tool_call_end")).toHaveLength(0)
486+
})
487+
})
346488
})

‎src/core/prompts/tools/native-tools/ask_followup_question.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ const ASK_FOLLOWUP_QUESTION_DESCRIPTION = `Ask the user a question to gather add
44
55
Parameters:
66
- question: (required) A clear, specific question addressing the information needed
7-
- follow_up: (required) A list of 2-4 suggested answers. Suggestions must be complete, actionable answers without placeholders. Optionally include mode to switch modes (code/architect/etc.)
7+
- follow_up: (required) An array of 1-4 suggested answers. Always provide this as an array, even when there is only one suggestion. Each suggestion must be a complete, actionable answer without placeholders. Suggestions optionally include mode to switch modes (code/architect/etc.)
88
99
Example: Asking for file path
1010
{ "question": "What is the path to the frontend-config.json file?", "follow_up": [{ "text": "./src/frontend-config.json", "mode": null }, { "text": "./config/frontend-config.json", "mode": null }, { "text": "./frontend-config.json", "mode": null }] }
@@ -14,7 +14,7 @@ Example: Asking with mode switch
1414

1515
const QUESTION_PARAMETER_DESCRIPTION = `Clear, specific question that captures the missing information you need`
1616

17-
const FOLLOW_UP_PARAMETER_DESCRIPTION = `Required list of 2-4 suggested responses; each suggestion must be a complete, actionable answer and may include a mode switch`
17+
const FOLLOW_UP_PARAMETER_DESCRIPTION = `Required array of 1-4 suggested responses, always an array even for a single suggestion; each suggestion must be a complete, actionable answer and may include a mode switch`
1818

1919
const FOLLOW_UP_TEXT_DESCRIPTION = `Suggested answer the user can pick`
2020

0 commit comments

Comments
 (0)