fix(gemini): round-trip functionCall.id through tool-call response serialization (#199)

## Summary

`parseToolCallPart` in `src/gemini.ts` was dropping the fixture's
`tool_call.id` when constructing the Gemini response body. This silently
breaks any client that preserves the id across the round trip (real
Gemini's session correlator, ADK-style clients, any proxy that needs to
match a follow-up `functionResponse` back to the originating
`functionCall`).

The aimock `geminiToCompletionRequest` translator then has to fall back
to `call_gemini_<name>_<i>`, which means any fixture chain keyed on a
specific `toolCallId` never advances past the first leg — aimock
re-matches the same `userMessage`-keyed leg-1 fixture in a loop while
the client keeps sending what looks like the same context.

## Change

- Add the optional `id` field on `GeminiPart.functionCall` and
`GeminiPart.functionResponse` shapes.
- Emit `id` on `parseToolCallPart` when the fixture sets one.

Backward-compatible: fixtures without an id continue to serialize
without one.

## How this was found

While porting `showcase/google-adk` to D5 parity with
`langgraph-python`, the `tool-rendering-reasoning-chain` demo's three
chained pills (AAPL→MSFT, d20→d6, flights+weather) kept stalling after
the first tool call. Dumping the request body aimock received showed the
`model` content had `functionCall: { name, args }` with no `id`. Tracing
back through `parseToolCallPart` revealed the id was being dropped on
serialization.

## Test plan

- [ ] Existing aimock tests still pass.
- [ ] Curl probe with a multi-leg fixture chain (one fixture keyed on
`userMessage`, follow-up keyed on `toolCallId`) advances past leg 1 when
the client preserves and re-sends the id.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: AlemTuzlak

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [1.24.1] - 2026-05-14
+
+### Fixed
+
+- **Gemini tool-call response serializer dropped fixture-pinned `tool_call.id`** — `parseToolCallPart` emitted `{ functionCall: { name, args } }` and omitted the id even when the fixture pinned one. Pairs with v1.23.1's INGEST-direction fix ([#196](https://github.com/CopilotKit/aimock/pull/196)) which preserves `functionCall.id` when aimock parses an _incoming_ Gemini request — that fix only helps when the id is already in the response body. Without this EGRESS-direction fix, aimock never emits one for clients to preserve in the first place, so the round-trip silently breaks for any client that depends on `functionCall.id` to correlate follow-up `functionResponse` parts back to the originating call
+
 ## [1.24.0] - 2026-05-14
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.24.0",
+  "version": "1.24.1",
   "description": "Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, audio generation, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.",
   "license": "MIT",
   "keywords": [

src/__tests__/gemini.test.ts

@@ -112,6 +112,27 @@ const multiToolFixture: Fixture = {
   },
 };
 
+// Fixture with `id` pinned on the tool call. Exercises the egress
+// counterpart to #196's ingest fix: aimock must surface tc.id on the
+// Gemini `functionCall` so clients have an id to preserve across the
+// round trip.
+const toolFixtureWithId: Fixture = {
+  match: { userMessage: "pinned-id" },
+  response: {
+    toolCalls: [{ id: "call_test_pinned_001", name: "get_weather", arguments: '{"city":"Tokyo"}' }],
+  },
+};
+
+const multiToolFixtureWithIds: Fixture = {
+  match: { userMessage: "pinned-multi" },
+  response: {
+    toolCalls: [
+      { id: "call_test_a", name: "get_weather", arguments: '{"city":"NYC"}' },
+      { id: "call_test_b", name: "get_time", arguments: '{"tz":"EST"}' },
+    ],
+  },
+};
+
 const errorFixture: Fixture = {
   match: { userMessage: "fail" },
   response: {
@@ -133,6 +154,8 @@ const allFixtures: Fixture[] = [
   textFixture,
   toolFixture,
   multiToolFixture,
+  toolFixtureWithId,
+  multiToolFixtureWithIds,
   errorFixture,
   badResponseFixture,
 ];
@@ -511,7 +534,11 @@ describe("POST /v1beta/models/{model}:generateContent (non-streaming)", () => {
     expect(body.candidates[0].content.parts[1].functionCall.name).toBe("get_time");
   });
 
-  it("functionCall parts do NOT contain an id field", async () => {
+  it("omits functionCall.id when the fixture does not pin one (backward compatible)", async () => {
+    // Fixtures authored before id-preservation existed didn't set tc.id;
+    // those must continue to serialize without an id field so the
+    // ingest-side fallback generator (`call_gemini_<name>_<i>`) handles
+    // them on the next request. Pre-#196 fixtures rely on this.
     instance = await createServer(allFixtures);
     const res = await post(`${instance.url}/v1beta/models/gemini-2.0-flash:generateContent`, {
       contents: [{ role: "user", parts: [{ text: "weather" }] }],
@@ -521,9 +548,44 @@ describe("POST /v1beta/models/{model}:generateContent (non-streaming)", () => {
     const fc = body.candidates[0].content.parts[0].functionCall;
     expect(fc.name).toBe("get_weather");
     expect(fc.args).toEqual({ city: "NYC" });
-    // Gemini FunctionCall schema only has name + args — no id
     expect(fc).not.toHaveProperty("id");
   });
+
+  it("surfaces functionCall.id when the fixture pins tc.id", async () => {
+    // Egress counterpart to #196's INGEST-direction fix
+    // (v1.23.1 — preserve functionCall.id when aimock PARSES an
+    // incoming Gemini request). That fix only helps if there's an id in
+    // the response body to begin with; without this egress surfacing,
+    // aimock emits `{ functionCall: { name, args } }` and clients have
+    // nothing to round-trip. Any fixture chain that keys a follow-up on
+    // `toolCallId` then falls through to the first-leg `userMessage`
+    // matcher, creating an infinite loop on Gemini/ADK integrations.
+    instance = await createServer(allFixtures);
+    const res = await post(`${instance.url}/v1beta/models/gemini-2.0-flash:generateContent`, {
+      contents: [{ role: "user", parts: [{ text: "pinned-id" }] }],
+    });
+
+    const body = JSON.parse(res.body);
+    const fc = body.candidates[0].content.parts[0].functionCall;
+    expect(fc.name).toBe("get_weather");
+    expect(fc.args).toEqual({ city: "Tokyo" });
+    expect(fc.id).toBe("call_test_pinned_001");
+  });
+
+  it("surfaces functionCall.id on every tool call when multiple are pinned", async () => {
+    instance = await createServer(allFixtures);
+    const res = await post(`${instance.url}/v1beta/models/gemini-2.0-flash:generateContent`, {
+      contents: [{ role: "user", parts: [{ text: "pinned-multi" }] }],
+    });
+
+    const body = JSON.parse(res.body);
+    const parts = body.candidates[0].content.parts;
+    expect(parts).toHaveLength(2);
+    expect(parts[0].functionCall.name).toBe("get_weather");
+    expect(parts[0].functionCall.id).toBe("call_test_a");
+    expect(parts[1].functionCall.name).toBe("get_time");
+    expect(parts[1].functionCall.id).toBe("call_test_b");
+  });
 });
 
 // ─── Integration tests: Gemini streaming ────────────────────────────────────
@@ -583,7 +645,7 @@ describe("POST /v1beta/models/{model}:streamGenerateContent (streaming)", () =>
     const chunks = parseGeminiSSEChunks(res.body) as {
       candidates: {
         content: {
-          parts: { functionCall?: { name: string; args: unknown } }[];
+          parts: { functionCall?: { name: string; args: unknown; id?: string } }[];
         };
         finishReason?: string;
       }[];
@@ -596,9 +658,37 @@ describe("POST /v1beta/models/{model}:streamGenerateContent (streaming)", () =>
     expect(chunks[0].candidates[0].content.parts[0].functionCall!.args).toEqual({
       city: "NYC",
     });
+    // Fixture didn't pin an id, so the streamed functionCall should
+    // omit `id` too — same backward-compat contract as the buffered path.
+    expect(chunks[0].candidates[0].content.parts[0].functionCall!).not.toHaveProperty("id");
     expect(chunks[0].candidates[0].finishReason).toBe("FUNCTION_CALL");
   });
 
+  it("streams functionCall.id when the fixture pins tc.id", async () => {
+    // Streaming and buffered tool-call responses both flow through
+    // `parseToolCallPart`. This test guards against a future regression
+    // where streaming gets its own serializer that drops the id.
+    instance = await createServer(allFixtures);
+    const res = await post(`${instance.url}/v1beta/models/gemini-2.0-flash:streamGenerateContent`, {
+      contents: [{ role: "user", parts: [{ text: "pinned-id" }] }],
+    });
+
+    expect(res.status).toBe(200);
+
+    const chunks = parseGeminiSSEChunks(res.body) as {
+      candidates: {
+        content: {
+          parts: { functionCall?: { name: string; args: unknown; id?: string } }[];
+        };
+      }[];
+    }[];
+
+    expect(chunks).toHaveLength(1);
+    const fc = chunks[0].candidates[0].content.parts[0].functionCall;
+    expect(fc).toBeDefined();
+    expect(fc!.id).toBe("call_test_pinned_001");
+  });
+
   it("uses fixture chunkSize for text streaming", async () => {
     const bigChunkFixture: Fixture = {
       match: { userMessage: "bigchunk" },

src/gemini.ts

@@ -318,7 +318,25 @@ function parseToolCallPart(tc: ToolCall, logger: Logger): GeminiPart {
     logger.warn(`Malformed JSON in fixture tool call arguments for "${tc.name}": ${tc.arguments}`);
     argsObj = {};
   }
-  return { functionCall: { name: tc.name, args: argsObj } };
+  // Surface the fixture's tool_call.id on the Gemini functionCall response
+  // so clients can preserve it across the round-trip and any
+  // toolCallId-keyed follow-up fixtures match. Pairs with v1.23.1's
+  // INGEST-direction fix (#196) which preserves the id when aimock parses
+  // an incoming Gemini request — that fix only helps if the id was in the
+  // response body to begin with. Without this egress fix, aimock emits
+  // `{ functionCall: { name, args } }` (no id), so even clients that
+  // diligently preserve `functionCall.id` across the round-trip never see
+  // an id to preserve. Backward-compatible: fixtures that don't pin a
+  // tc.id continue to serialize without one (the ingest path's fallback
+  // generator handles those).
+  const functionCall: GeminiPart["functionCall"] = {
+    name: tc.name,
+    args: argsObj,
+  };
+  if (tc.id) {
+    functionCall.id = tc.id;
+  }
+  return { functionCall };
 }
 
 function buildGeminiToolCallStreamChunks(