PR #66949: agents/google: round-trip Gemini 3 thoughtSignature on tool calls to unblock Gemini 3.x tool-calling

• Repository: openclaw/openclaw
• Author: dkaygithub
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/66949

Description (problem / solution / changelog)

Summary

Impact: enables Gemini 3.x for openclaw tool-calling. Without this, any tool-calling turn on gemini-3-flash-preview (or Gemini 3.1 Pro Preview) via openclaw's native google-generative-ai transport softlocks on turn two — the model emits a tool call, openclaw executes it, and the follow-up request 400s because the signature was dropped in transit.

• Problem: src/agents/google-transport-stream.ts parses thoughtSignature off thinking/text parts but not off tool-call parts. Google rejects any subsequent request whose functionCall parts are missing the signature that was attached on the way in: Function call is missing a thought_signature in functionCall parts. ... function call <namespace>:<tool>, position N.
• Why it matters: Gemini 3 is unusable for tool calling through openclaw today. Agents on gemini-3-flash-preview show typing indicators and never reply. This blocks any MCP integration or tool-catalog plugin that guarantees a tool-call turn.
• What changed: Capture part.thoughtSignature at the tool-call construction site in the SSE parser, and plumb it through GoogleTransportContentBlock.toolCall so the existing serializer (which already re-emits signatures byte-exact on same-provider-and-model replay) has data to emit.
• What did NOT change (scope boundary): Only the native google-generative-ai transport. The OpenAI-compat path (#53658, #58235) has a structurally equivalent bug and is intentionally not bundled here — separate PR, separate concern. Cross-model replay still strips thoughtSignature via the existing transport-message-transform.ts logic (unchanged and verified).

Change Type

• Bug fix

Scope

• Integrations
• API / contracts

Linked Issue/PR

• Closes #63397 (Vertex AI Gemini — native path, exact match)
• Related #34008 (Gemini 3 via Ollama Cloud — same missing-signature symptom, different transport)
• Related #53658 (Google OpenAI-compat fallback — parallel bug on the compat path, intentionally out of scope here)
• Related #58235 (Gemini 3.1 Pro Preview via OpenAI-compat API — same, compat path)
• Context #5001, #841 (prior thought-signature-related reports)
• This PR fixes a bug or regression

Root Cause

• Root cause: Parser/serializer asymmetry. The serializer at src/agents/google-transport-stream.ts:355 already emits thoughtSignature when present on a tool-call block under same-provider-and-model replay. The parser at src/agents/google-transport-stream.ts:709 constructed the tool-call block without reading part.thoughtSignature, so the field was never set and the serializer had nothing to emit. The SSE chunk type already declared the field as a sibling to functionCall, so the wire model was correct — only the in-memory content block lost it.
• Missing detection / guardrail: No regression test exercised round-tripping a thoughtSignature on a tool-call part. Thinking-block signatures were covered; tool-call signatures were not.
• Contributing context (if known): Gemini 3 was the first generation where the signature became mandatory on tool-call replay. Gemini 2.5 and earlier tolerated missing signatures, so the gap hid until Gemini 3 preview models started rejecting those requests.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/agents/google-transport-stream.test.ts
• Scenario the test should lock in: byte-exact thoughtSignature round-trip on tool-call parts across same-provider replay; stripped on cross-provider replay; parallel-call first-only preservation; absence stays absent.
• Why this is the smallest reliable guardrail: the bug is a one-field data-flow failure between parser and serializer. A provider-level unit test is the tightest surface that reproduces it without needing a live model.
• Existing test that already covers this (if any): none for tool-call signatures specifically. The existing "uses the guarded fetch transport and parses Gemini SSE output" case covered thinking-block signatures but asserted nothing about tool-call parts.

Five new tests added in this PR:

1. Parser captures thoughtSignature on tool-call SSE parts
2. Serializer emits it byte-exact on same-provider replay
3. Serializer omits the field when the tool call carried no signature
4. Serializer strips the field when replaying across providers (regression guard for cross-model leakage)
5. Parallel tool calls: signature preserved only on the parts that had one (mirrors Google's documented emission rule — only the first functionCall in a parallel batch carries a signature)

User-visible / Behavior Changes

None on the happy path for non-Gemini-3 users — the field is absent end-to-end for models that don't emit it, and same-provider replay for Gemini 2.5 and below is byte-identical. Gemini 3.x users gain working tool-calling where previously every multi-turn tool conversation failed.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (same endpoints; adds one optional field to the request body that Google itself produced on the prior response)
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux x86_64, Node 22.22.1
• Model/provider: gemini-3-flash-preview via google-generative-ai native transport
• Integration/channel: any MCP server whose tool catalog guarantees a tool-call turn

Steps

1. Configure an openclaw-driven agent on gemini-3-flash-preview with at least one tool plugin or MCP server.
2. Send a query that routes through a tool.
3. Observe the gateway emit two inference POSTs and zero outbound reply to the calling channel.

Expected

• Agent replies. /v1beta/models/gemini-3-flash-preview:streamGenerateContent returns 200 on every turn of a multi-turn tool-calling conversation.

Actual (before fix)

• Turn one succeeds (initial tool call). Turn two 400s with Function call is missing a thought_signature in functionCall parts. Please remove the thought signature from the previous Part.part at content[...] ... function call <namespace>:<tool>, position N. The agent never posts a reply.

Actual (after fix)

• Both turns 200. Agent replies. Fetch-level 4xx/5xx capture stays empty across a multi-turn tool exchange.

Evidence

• Failing test/log before + passing after
• Trace/log snippets

Captured 400 response body before the fix (via a fetch-level preload):

Function call is missing a thought_signature in functionCall parts.
Please remove the thought signature from the previous Part.part at content[...].parts
function call <namespace>:<tool>, position 44

Test suite after the fix:

 Test Files  1 passed (1)
      Tests  10 passed (10)

Full src/agents/**/*.test.ts run: 365 files, 3799 passed, 4 skipped, 0 failed (144s).

End-to-end verified against a multi-tool-call conversation on gemini-3-flash-preview: every turn returned 200, the fetch-level error log stayed empty, and the agent completed the exchange normally.

Changed files

• src/agents/google-transport-stream.test.ts (modified, +181/-0)
• src/agents/google-transport-stream.ts (modified, +10/-1)
• src/agents/openai-transport-stream.test.ts (modified, +247/-0)
• src/agents/openai-transport-stream.ts (modified, +95/-0)