fix: defer tool-input-start until real tool call ID is available (#103)

* fix: defer tool-input-start until real tool call ID is available

When streaming tool calls from Gemini-on-Vertex, the function name and
tool call ID may arrive in separate chunks. Previously, tool-input-start
was emitted with a placeholder ID (tool_0) as soon as the function name
was known, causing a mismatch with subsequent tool-input-delta events
that carried the real ID.

This fix:
- Makes ToolCallInProgress.id optional (undefined until real ID arrives)
- Gates tool-input-start emission on both toolName AND id being present
- Makes the ID immutable once set (first real value wins)
- Falls back to generateToolCallId() (UUID) in flush/finishReason paths

Aligns with the Vercel AI SDK StreamingToolCallTracker pattern where the
ID is set once and never mutated.

Closes #93

* test: assert tool-input-delta count and content in Vertex regression test

Strengthen the regression test to verify that tool-input-delta events
are actually emitted (not vacuously passing via empty loop) and that
concatenated deltas match the expected tool call input.

* fix: replay buffered arguments as tool-input-delta after deferred start

When arguments arrive on a chunk before the tool call ID, they are
buffered but not emitted as tool-input-delta. After tool-input-start is
finally emitted (once the ID arrives), replay any accumulated arguments
as a single tool-input-delta to ensure streaming consumers see all
intermediate argument data.

* test: add coverage for buffered-arguments replay path

Exercise the code path where arguments arrive before the tool call ID,
verifying that buffered arguments are replayed as tool-input-delta
immediately after the deferred tool-input-start is emitted.

* test: add coverage for fallback UUID generation when API provides no id

Verify that when the API never provides a tool call ID across any chunk,
the provider generates a valid UUID and uses it consistently across
tool-input-start and tool-call events.

* test: update existing test to reflect deferred tool-input-start behavior

The test 'should flush tool calls that never received input-start' now
exercises a different code path with the fix: tool-input-start IS emitted
during streaming (when toolName arrives on chunk 2 and id was already set
on chunk 1). Rename and strengthen assertions to match actual behavior:
verify tool-input-start, buffered args replay as deltas, and tool-call.

* fix: replay buffered arguments in flush and finishReason paths

For protocol completeness, emit buffered arguments as tool-input-delta
between tool-input-start and tool-input-end in finalization paths (flush
and finishReason handler), matching the behavior of the streaming path.

* refactor: extract emitToolInputStart helper and guard against empty string IDs

Address review comments:
- Extract repeated tool-input-start + buffered replay pattern into a
  single helper to prevent drift between the 3 emission sites
- Guard against empty string IDs (consistent with existing toolName
  guard that checks length > 0)
- Strengthen UUID fallback test to assert tool-input-delta emission

Author: jerome-benoit

src/sap-ai-language-model.test.ts

@@ -2401,6 +2401,186 @@ describe("SAPAILanguageModel", () => {
       expect(parsed2.query).toHaveLength(5000);
     });
 
+    it("should emit consistent tool call IDs when id arrives on a later chunk than function name (Vertex pattern)", async () => {
+      const realId = "vertex_tool_be5b294b-ece3-46f0-8b0d-22cd00000000";
+
+      await setStreamChunksForApi(api, [
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { name: "query_bookings" },
+              index: 0,
+            },
+          ],
+        }),
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { arguments: '{"customer":' },
+              id: realId,
+              index: 0,
+            },
+          ],
+        }),
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { arguments: '"Acme"}' },
+              index: 0,
+            },
+          ],
+          finishReason: "tool_calls",
+          usage: { completion_tokens: 10, prompt_tokens: 5, total_tokens: 15 },
+        }),
+      ]);
+
+      const model = createModelForApi(api);
+      const prompt = createPrompt("show bookings");
+
+      const { stream } = await model.doStream({ prompt });
+      const parts = await readAllStreamParts(stream);
+
+      const toolInputStart = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-start" }> =>
+          p.type === "tool-input-start",
+      );
+      const toolInputDeltas = parts.filter(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-delta" }> =>
+          p.type === "tool-input-delta",
+      );
+      const toolCall = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-call" }> =>
+          p.type === "tool-call",
+      );
+
+      expect(toolInputStart).toBeDefined();
+      expect(toolInputStart?.id).toBe(realId);
+      expect(toolInputStart?.toolName).toBe("query_bookings");
+
+      expect(toolInputDeltas).toHaveLength(2);
+      for (const delta of toolInputDeltas) {
+        expect(delta.id).toBe(realId);
+      }
+      const concatenatedDeltas = toolInputDeltas.map((d) => d.delta).join("");
+      expect(concatenatedDeltas).toBe('{"customer":"Acme"}');
+
+      expect(toolCall).toBeDefined();
+      expect(toolCall?.toolCallId).toBe(realId);
+      expect(toolCall?.toolName).toBe("query_bookings");
+      expect(toolCall?.input).toBe('{"customer":"Acme"}');
+    });
+
+    it("should replay buffered arguments as tool-input-delta when id arrives after arguments", async () => {
+      const realId = "vertex_tool_buffered_args_test";
+
+      await setStreamChunksForApi(api, [
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { arguments: '{"a":', name: "buffered_fn" },
+              index: 0,
+            },
+          ],
+        }),
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { arguments: '"b"}' },
+              id: realId,
+              index: 0,
+            },
+          ],
+          finishReason: "tool_calls",
+          usage: { completion_tokens: 5, prompt_tokens: 3, total_tokens: 8 },
+        }),
+      ]);
+
+      const model = createModelForApi(api);
+      const prompt = createPrompt("test buffered args");
+
+      const { stream } = await model.doStream({ prompt });
+      const parts = await readAllStreamParts(stream);
+
+      const toolInputStart = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-start" }> =>
+          p.type === "tool-input-start",
+      );
+      const toolInputDeltas = parts.filter(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-delta" }> =>
+          p.type === "tool-input-delta",
+      );
+      const toolCall = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-call" }> =>
+          p.type === "tool-call",
+      );
+
+      expect(toolInputStart).toBeDefined();
+      expect(toolInputStart?.id).toBe(realId);
+      expect(toolInputStart?.toolName).toBe("buffered_fn");
+
+      expect(toolInputDeltas).toHaveLength(2);
+      expect(toolInputDeltas[0]?.id).toBe(realId);
+      expect(toolInputDeltas[0]?.delta).toBe('{"a":');
+      expect(toolInputDeltas[1]?.id).toBe(realId);
+      expect(toolInputDeltas[1]?.delta).toBe('"b"}');
+
+      const concatenatedDeltas = toolInputDeltas.map((d) => d.delta).join("");
+      expect(concatenatedDeltas).toBe('{"a":"b"}');
+
+      expect(toolCall).toBeDefined();
+      expect(toolCall?.toolCallId).toBe(realId);
+      expect(toolCall?.input).toBe('{"a":"b"}');
+    });
+
+    it("should generate a fallback UUID when tool call id is never provided by the API", async () => {
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+      await setStreamChunksForApi(api, [
+        createMockStreamChunk({
+          deltaToolCalls: [
+            {
+              function: { arguments: '{"x":1}', name: "no_id_tool" },
+              index: 0,
+            },
+          ],
+          finishReason: "tool_calls",
+          usage: { completion_tokens: 5, prompt_tokens: 3, total_tokens: 8 },
+        }),
+      ]);
+
+      const model = createModelForApi(api);
+      const prompt = createPrompt("test fallback id");
+
+      const { stream } = await model.doStream({ prompt });
+      const parts = await readAllStreamParts(stream);
+
+      const toolInputStart = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-start" }> =>
+          p.type === "tool-input-start",
+      );
+      const toolInputDeltas = parts.filter(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-delta" }> =>
+          p.type === "tool-input-delta",
+      );
+      const toolCall = parts.find(
+        (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-call" }> =>
+          p.type === "tool-call",
+      );
+
+      expect(toolInputStart).toBeDefined();
+      expect(toolInputStart?.id).toMatch(uuidRegex);
+      expect(toolInputStart?.toolName).toBe("no_id_tool");
+
+      expect(toolInputDeltas).toHaveLength(1);
+      expect(toolInputDeltas[0]?.id).toBe(toolInputStart?.id);
+      expect(toolInputDeltas[0]?.delta).toBe('{"x":1}');
+
+      expect(toolCall).toBeDefined();
+      expect(toolCall?.toolCallId).toMatch(uuidRegex);
+      expect(toolCall?.toolCallId).toBe(toolInputStart?.id);
+      expect(toolCall?.input).toBe('{"x":1}');
+    });
+
     it("should handle Unicode and multi-byte characters in large streams without corruption", async () => {
       const unicodeContent =
         "Hello 世界! 🌍🌎🌏 Привет мир! مرحبا بالعالم " +
@@ -2727,7 +2907,7 @@ describe("SAPAILanguageModel", () => {
         });
       });
 
-      it("should flush tool calls that never received input-start", async () => {
+      it("should emit tool-input-start when toolName arrives on a later chunk than id", async () => {
         await setStreamChunksForApi(api, [
           createMockStreamChunk({
             deltaToolCalls: [
@@ -2760,7 +2940,24 @@ describe("SAPAILanguageModel", () => {
         const { stream } = await model.doStream({ prompt });
         const parts = await readAllStreamParts(stream);
 
+        const toolInputStart = parts.find(
+          (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-start" }> =>
+            p.type === "tool-input-start",
+        );
+        const toolInputDeltas = parts.filter(
+          (p): p is Extract<LanguageModelV3StreamPart, { type: "tool-input-delta" }> =>
+            p.type === "tool-input-delta",
+        );
         const toolCall = parts.find((p) => p.type === "tool-call");
+
+        expect(toolInputStart).toBeDefined();
+        expect(toolInputStart?.id).toBe("call_no_start");
+        expect(toolInputStart?.toolName).toBe("delayed_name");
+
+        expect(toolInputDeltas).toHaveLength(2);
+        expect(toolInputDeltas[0]?.delta).toBe('{"partial":');
+        expect(toolInputDeltas[1]?.delta).toBe('"value"}');
+
         expect(toolCall).toBeDefined();
         expect(toolCall).toEqual({
           input: '{"partial":"value"}',

src/strategy-utils.ts

@@ -332,7 +332,7 @@ export interface ToolCallInProgress {
   arguments: string;
   didEmitCall: boolean;
   didEmitInputStart: boolean;
-  id: string;
+  id: string | undefined;
   toolName?: string;
 }
 
@@ -353,6 +353,13 @@ export class StreamIdGenerator {
   generateTextBlockId(): string {
     return crypto.randomUUID();
   }
+
+  /**
+   * @returns A UUID string for identifying a tool call when the API does not provide one.
+   */
+  generateToolCallId(): string {
+    return crypto.randomUUID();
+  }
 }
 
 /**
@@ -782,6 +789,31 @@ export function createStreamTransformer(
   const streamState = createInitialStreamState();
   const toolCallsInProgress = new Map<number, ToolCallInProgress>();
 
+  /**
+   * Emits tool-input-start and replays any buffered arguments as a delta.
+   * @param tc - The in-progress tool call state.
+   * @param controller - The transform stream controller to enqueue events into.
+   */
+  function emitToolInputStart(
+    tc: ToolCallInProgress,
+    controller: TransformStreamDefaultController<LanguageModelV3StreamPart>,
+  ): void {
+    if (tc.didEmitInputStart || tc.id == null) return;
+    tc.didEmitInputStart = true;
+    controller.enqueue({
+      id: tc.id,
+      toolName: tc.toolName ?? "",
+      type: "tool-input-start",
+    });
+    if (tc.arguments.length > 0) {
+      controller.enqueue({
+        delta: tc.arguments,
+        id: tc.id,
+        type: "tool-input-delta",
+      });
+    }
+  }
+
   return convertAsyncIteratorToReadableStream(
     safeIterate(sdkStream)[Symbol.asyncIterator](),
   ).pipeThrough(
@@ -795,14 +827,8 @@ export function createStreamTransformer(
             continue;
           }
 
-          if (!tc.didEmitInputStart) {
-            tc.didEmitInputStart = true;
-            controller.enqueue({
-              id: tc.id,
-              toolName: tc.toolName ?? "",
-              type: "tool-input-start",
-            });
-          }
+          tc.id ??= idGenerator.generateToolCallId();
+          emitToolInputStart(tc, controller);
 
           didEmitAnyToolCalls = true;
           tc.didEmitCall = true;
@@ -952,15 +978,22 @@ export function createStreamTransformer(
                 arguments: "",
                 didEmitCall: false,
                 didEmitInputStart: false,
-                id: toolCallChunk.id ?? `tool_${String(index)}`,
+                id:
+                  typeof toolCallChunk.id === "string" && toolCallChunk.id.length > 0
+                    ? toolCallChunk.id
+                    : undefined,
                 toolName: toolCallChunk.function?.name,
               });
             }
 
             const tc = toolCallsInProgress.get(index);
             if (!tc) continue;
 
-            if (toolCallChunk.id) {
+            if (
+              typeof toolCallChunk.id === "string" &&
+              toolCallChunk.id.length > 0 &&
+              tc.id === undefined
+            ) {
               tc.id = toolCallChunk.id;
             }
 
@@ -969,20 +1002,15 @@ export function createStreamTransformer(
               tc.toolName = nextToolName;
             }
 
-            if (!tc.didEmitInputStart && tc.toolName) {
-              tc.didEmitInputStart = true;
-              controller.enqueue({
-                id: tc.id,
-                toolName: tc.toolName,
-                type: "tool-input-start",
-              });
+            if (!tc.didEmitInputStart && tc.toolName != null && tc.id != null) {
+              emitToolInputStart(tc, controller);
             }
 
             const argumentsDelta = toolCallChunk.function?.arguments;
             if (typeof argumentsDelta === "string" && argumentsDelta.length > 0) {
               tc.arguments += argumentsDelta;
 
-              if (tc.didEmitInputStart) {
+              if (tc.didEmitInputStart && tc.id != null) {
                 controller.enqueue({
                   delta: argumentsDelta,
                   id: tc.id,
@@ -1003,14 +1031,9 @@ export function createStreamTransformer(
               if (tc.didEmitCall) {
                 continue;
               }
-              if (!tc.didEmitInputStart) {
-                tc.didEmitInputStart = true;
-                controller.enqueue({
-                  id: tc.id,
-                  toolName: tc.toolName ?? "",
-                  type: "tool-input-start",
-                });
-              }
+
+              tc.id ??= idGenerator.generateToolCallId();
+              emitToolInputStart(tc, controller);
 
               tc.didEmitCall = true;
               controller.enqueue({ id: tc.id, type: "tool-input-end" });