fix: harden Interactions collapser tool-call assembly from PR review

Address review findings on the SDK 2.x migration:
- Flag assembled arguments_delta fragments that don't concatenate into valid
  JSON by step.stop via droppedChunks/firstDroppedSample, instead of silently
  writing a corrupt tool call into a recorded fixture.
- Preserve the identity of a function_call step.start that arrives without an
  index by minting a synthetic key (matches the sibling collapsers) rather
  than dropping it silently.
- Reword the emitter's arguments_delta comment: the mock emits one whole
  fragment (a valid degenerate case), it does not itself concatenate.
- Add tests: multiple/interleaved tool calls collapse in step-index order,
  emitter assigns sequential step indices, invalid-JSON assembly is flagged,
  and an index-less function_call step.start keeps its identity.

Author: tombeckenham

src/__tests__/gemini-interactions.test.ts

@@ -870,6 +870,28 @@ describe("SSE event builders", () => {
     expect(JSON.parse(delta.arguments as string)).toEqual({ city: "NYC" });
   });
 
+  it("assigns sequential step indices for multiple tool calls (SDK 2.x)", () => {
+    const events = buildInteractionsToolCallSSEEvents(
+      [
+        { name: "get_weather", arguments: '{"city":"NYC"}', id: "call_1" },
+        { name: "get_time", arguments: '{"tz":"UTC"}', id: "call_2" },
+      ],
+      "aimock-int-0",
+      logger,
+    );
+    const stepStarts = events.filter((e) => e.event_type === "step.start");
+    expect(stepStarts.map((e) => e.index)).toEqual([0, 1]);
+    expect((stepStarts[0].step as Record<string, unknown>).name).toBe("get_weather");
+    expect((stepStarts[1].step as Record<string, unknown>).name).toBe("get_time");
+    // Each call's arguments_delta is keyed to its own index.
+    const argDeltas = events.filter(
+      (e) =>
+        e.event_type === "step.delta" &&
+        (e.delta as Record<string, unknown>).type === "arguments_delta",
+    );
+    expect(argDeltas.map((e) => e.index)).toEqual([0, 1]);
+  });
+
   it("builds content+tools SSE with correct indices (SDK 2.x)", () => {
     const events = buildInteractionsContentWithToolCallsSSEEvents(
       "Text",
@@ -1349,6 +1371,58 @@ describe("collapseGeminiInteractionsSSE", () => {
     expect(result.toolCalls![0].id).toBe("call_1");
   });
 
+  it("collapses multiple interleaved tool calls in step-index order (SDK 2.x)", () => {
+    const sse = [
+      'data: {"event_type":"step.start","index":1,"step":{"type":"function_call","id":"call_a","name":"get_weather","arguments":{}},"event_id":"evt_1"}',
+      'data: {"event_type":"step.start","index":2,"step":{"type":"function_call","id":"call_b","name":"get_time","arguments":{}},"event_id":"evt_2"}',
+      // Interleaved argument fragments for both calls.
+      'data: {"event_type":"step.delta","index":2,"delta":{"type":"arguments_delta","arguments":"{\\"tz\\":"},"event_id":"evt_3"}',
+      'data: {"event_type":"step.delta","index":1,"delta":{"type":"arguments_delta","arguments":"{\\"city\\":\\"NYC\\"}"},"event_id":"evt_4"}',
+      'data: {"event_type":"step.delta","index":2,"delta":{"type":"arguments_delta","arguments":"\\"UTC\\"}"},"event_id":"evt_5"}',
+      'data: {"event_type":"step.stop","index":1,"event_id":"evt_6"}',
+      'data: {"event_type":"step.stop","index":2,"event_id":"evt_7"}',
+    ].join("\n\n");
+    const result = collapseGeminiInteractionsSSE(sse);
+    expect(result.toolCalls).toHaveLength(2);
+    // Sorted by step index regardless of step.stop / delta arrival order.
+    expect(result.toolCalls![0]).toEqual({
+      name: "get_weather",
+      arguments: '{"city":"NYC"}',
+      id: "call_a",
+    });
+    expect(result.toolCalls![1]).toEqual({
+      name: "get_time",
+      arguments: '{"tz":"UTC"}',
+      id: "call_b",
+    });
+  });
+
+  it("flags assembled arguments_delta that is not valid JSON by step.stop", () => {
+    const sse = [
+      'data: {"event_type":"step.start","index":0,"step":{"type":"function_call","id":"call_1","name":"fn","arguments":{}},"event_id":"evt_1"}',
+      // Truncated/interrupted stream — fragment never closes into valid JSON.
+      'data: {"event_type":"step.delta","index":0,"delta":{"type":"arguments_delta","arguments":"{\\"city\\":\\"NY"},"event_id":"evt_2"}',
+      'data: {"event_type":"step.stop","index":0,"event_id":"evt_3"}',
+    ].join("\n\n");
+    const result = collapseGeminiInteractionsSSE(sse);
+    // The (corrupt) call is still surfaced, but flagged so the recorder warns.
+    expect(result.toolCalls).toHaveLength(1);
+    expect(result.toolCalls![0].arguments).toBe('{"city":"NY');
+    expect(result.droppedChunks).toBe(1);
+    expect(result.firstDroppedSample).toMatch(/not valid JSON/);
+  });
+
+  it("preserves identity of a function_call step.start that arrives without an index", () => {
+    const sse = [
+      'data: {"event_type":"step.start","step":{"type":"function_call","id":"call_1","name":"fn","arguments":{"x":1}},"event_id":"evt_1"}',
+      'data: {"event_type":"step.stop","event_id":"evt_2"}',
+    ].join("\n\n");
+    const result = collapseGeminiInteractionsSSE(sse);
+    expect(result.toolCalls).toHaveLength(1);
+    expect(result.toolCalls![0].name).toBe("fn");
+    expect(result.toolCalls![0].arguments).toBe('{"x":1}');
+  });
+
   it("uses step.start arguments object when no arguments_delta streams (SDK 2.x)", () => {
     const sse = [
       'data: {"event_type":"step.start","index":0,"step":{"type":"function_call","id":"call_1","name":"fn","arguments":{"x":1}},"event_id":"evt_1"}',

src/gemini-interactions.ts

@@ -545,8 +545,10 @@ export function buildInteractionsToolCallSSEEvents(
       event_id: nextEventId(),
     });
 
-    // arguments_delta.arguments is a string fragment; emitting the full
-    // serialized object as one fragment keeps the concatenation valid JSON.
+    // arguments_delta.arguments is a string fragment. The real SDK may split
+    // the args across several fragments that concatenate into valid JSON; the
+    // mock emits the whole serialized object as one fragment (a valid
+    // degenerate case the collapser handles identically).
     events.push({
       event_type: "step.delta",
       index: idx,

src/stream-collapse.ts

@@ -1215,6 +1215,10 @@ export function collapseGeminiInteractionsSSE(body: string): CollapseResult {
     number,
     { id?: string; name: string; argsObj?: unknown; argsStr: string }
   >();
+  // Synthetic keys for function_call step.start events that arrive without an
+  // index (matches the sibling collapsers); seeded high to avoid colliding with
+  // real step indices.
+  let nextSyntheticStepIndex = 1_000_000;
 
   for (const line of lines) {
     const data = extractSSEData(splitSSELines(line));
@@ -1242,8 +1246,12 @@ export function collapseGeminiInteractionsSSE(body: string): CollapseResult {
     if (eventType === "step.start") {
       // 2.x — tool-call identity lives on step.start, not in a delta.
       const step = parsed.step as Record<string, unknown> | undefined;
-      if (step && step.type === "function_call" && index !== undefined) {
-        stepToolCalls.set(index, {
+      if (step && step.type === "function_call") {
+        // An index-less start can't correlate later arguments_delta fragments,
+        // but minting a synthetic key preserves the call's identity instead of
+        // dropping it silently.
+        const key = index ?? nextSyntheticStepIndex++;
+        stepToolCalls.set(key, {
           id: step.id ? String(step.id) : undefined,
           name: String(step.name ?? ""),
           // step.start may carry a fully-populated `arguments` object (non-
@@ -1298,12 +1306,27 @@ export function collapseGeminiInteractionsSSE(body: string): CollapseResult {
 
   // Finalize 2.x tool calls in step-index order.
   for (const [, tc] of Array.from(stepToolCalls.entries()).sort(([a], [b]) => a - b)) {
-    const args =
-      tc.argsStr !== ""
-        ? tc.argsStr
-        : typeof tc.argsObj === "string"
-          ? tc.argsObj
-          : JSON.stringify(tc.argsObj ?? {});
+    let args: string;
+    if (tc.argsStr !== "") {
+      args = tc.argsStr;
+      // The arguments_delta fragments must concatenate into valid JSON by
+      // step.stop. A truncated/interrupted stream can leave them malformed;
+      // surface that via droppedChunks rather than writing a corrupt fixture
+      // silently (mirrors the per-chunk parse guard above).
+      try {
+        JSON.parse(args);
+      } catch {
+        droppedChunks++;
+        if (droppedChunks === 1) {
+          firstDroppedSample = `assembled arguments_delta not valid JSON for "${tc.name}": ${surrogateSafeSlice(
+            args,
+            200,
+          )}`;
+        }
+      }
+    } else {
+      args = typeof tc.argsObj === "string" ? tc.argsObj : JSON.stringify(tc.argsObj ?? {});
+    }
     toolCalls.push({ name: tc.name, arguments: args, ...(tc.id ? { id: tc.id } : {}) });
   }