xonecas.io
64875
Mc

mini-coder / commit 5d728b7

fix(reasoning): gemini models not producing reasoning due to hacks in

the code

xonecas2026-03-12 5d728b7076ff30d87350ffc1c07a9b333600ccc9 parent ba47455

8 files changed

.agents/agents/orc.md+1−0
@@ -12,6 +12,7 @@ You are in **Orchestration** mode, behave like an expert orchestration agent. Yo
1212 - **Stay the coordinator.** You own the big picture. Subagents handle the details. Synthesise their results, resolve conflicts, and report back clearly.
1313 - **Parallelise when possible.** If two subtasks don't depend on each other, dispatch them concurrently.
1414 - **Fail fast.** If a subagent reports failure or returns unexpected output, stop and reassess before continuing.
15+- **Custom subagents**: Use these if appropriate, otherwise a normal subagent is preffered.
1516
1617 ## How to orchestrate
1718
gemini-reasoning-tools-implementation-plan.md+209−0
@@ -0,0 +1,209 @@
1+# Gemini reasoning + tools fix implementation plan
2+
3+## Summary
4+
5+The goal is to fix Gemini reasoning + tool handling so reasoning stays visible to users while tool use continues to work correctly across turns. The current implementation treats Gemini 2.5/3 tool turns as broadly incompatible with reasoning and applies a history sanitizer that can remove valid assistant/tool messages. That is too blunt.
6+
7+The intended direction is to preserve Gemini thought signatures exactly, stop disabling reasoning for all Gemini tool turns, and narrow recovery logic to cases that are actually invalid. In practice, that means:
8+
9+- remove blanket reasoning disablement in `src/llm-api/providers.ts`
10+- rewrite Gemini history sanitization in `src/llm-api/turn.ts` so it validates only truly broken current-turn state
11+- respect official thought-signature rules, including parallel function-call cases where only the first `functionCall` part carries a signature
12+- keep full model-generated assistant/tool history intact whenever it is valid, so SDK-managed signature replay keeps working
13+- retain small, explicit recovery behavior for known integration bugs instead of silently truncating broad spans of history
14+
15+## Findings
16+
17+### What the docs and issue reports indicate
18+
19+- Official Gemini function-calling docs show Gemini 3 supports function calling/tools: https://ai.google.dev/gemini-api/docs/function-calling
20+- Official thinking docs do not say tool use requires reasoning to be disabled: https://ai.google.dev/gemini-api/docs/thinking
21+- Official thought-signature docs describe signatures as the key requirement for function calling across turns, and note that official SDKs handle them automatically when full responses are preserved exactly:
22+ - https://ai.google.dev/gemini-api/docs/thought-signatures
23+ - https://docs.cloud.google.com/vertex-ai/generative-ai/docs/thought-signatures
24+- Parallel function calls are valid even when only the first `functionCall` part has a thought signature. So “any tool-call part without `thoughtSignature` means corruption” is not a correct rule.
25+- Missing signatures do show up in real integrations and SDK bugs, which supports having narrow recovery logic:
26+ - https://github.com/vercel/ai/issues/10344
27+ - https://github.com/googleapis/python-genai/issues/2081
28+
29+### What the repo currently does
30+
31+- In `src/llm-api/providers.ts`, `shouldDisableGeminiThinkingForTools()` returns `true` for `/^gemini-(2.5|3)/`.
32+- In the same file, `getThinkingProviderOptions()` returns `null` when `hasTools` is true and the model matches that gate, which disables reasoning for Gemini tool turns.
33+- In `src/llm-api/turn.ts`, `sanitizeGeminiToolMessages()` only runs for models gated by `shouldDisableGeminiThinkingForTools()`.
34+- `assistantMessageHasUnsignedGeminiToolCall()` marks any tool-call part without `thoughtSignature` as broken.
35+- The sanitizer then truncates history back to the next user turn, or slices history at the broken point if there is no later user turn.
36+
37+## Verdict
38+
39+Disabling reasoning for all Gemini 2.5/3 tool turns is not a correct general fix. The official docs support Gemini tools with thinking, and they point to exact preservation of thought signatures rather than reasoning disablement as the compatibility requirement.
40+
41+The current sanitizer is also too aggressive. It assumes any unsigned tool-call part is corrupted, which is false for valid parallel-call responses. Because of that, it can delete healthy history and reduce model quality by removing assistant/tool state that should have been replayed unchanged.
42+
43+The right fix is to preserve and replay Gemini thought-signature-bearing content exactly, and only repair or drop history when there is strong evidence that the most recent tool turn is malformed in a way the provider will reject.
44+
45+## Proposed code changes
46+
47+### 1) Remove blanket Gemini reasoning disablement
48+
49+**Affected file:** `src/llm-api/providers.ts`
50+
51+Change `getThinkingProviderOptions()` so Gemini thinking options are still returned when tools are present. The simplest version is to remove the `hasTools && shouldDisableGeminiThinkingForTools(modelString)` early return entirely.
52+
53+Follow-up cleanup:
54+
55+- remove `GEMINI_TOOL_CALL_AFFECTED_MODELS` and `shouldDisableGeminiThinkingForTools()` if they are no longer needed
56+- or, if a model-specific workaround flag is still wanted, rename and repurpose it for narrow recovery behavior rather than provider-option suppression
57+
58+Expected behavior after change:
59+
60+- Gemini 2.5/3 tool turns can request thinking normally
61+- reasoning remains visible during the turn
62+- provider options are not silently stripped just because tools are enabled
63+
64+### 2) Rewrite Gemini sanitizer around actual invalidity rules
65+
66+**Affected file:** `src/llm-api/turn.ts`
67+
68+Replace the current `assistantMessageHasUnsignedGeminiToolCall()` heuristic with validation that reflects thought-signature semantics.
69+
70+Suggested behavior:
71+
72+- keep `normalizeMessageProviderOptions()` and `getPartProviderOptions()` as shared helpers
73+- add a helper that inspects a single assistant message and classifies Gemini tool-call structure, for example:
74+ - no tool calls
75+ - valid signed single-call turn
76+ - valid parallel-call turn where the first tool-call part has a signature and later sibling tool-call parts may not
77+ - invalid turn with tool calls but no signature anchor where one is required
78+- treat a tool-call assistant message as valid if at least one eligible tool-call part in that assistant response carries a thought signature and unsigned sibling calls follow within the same assistant message
79+- continue to accept legacy `providerMetadata` as an input alias, but preserve/export the effective data in `providerOptions`
80+
81+The sanitizer should only recover from truly invalid history, and only in the smallest safe scope.
82+
83+Recommended scope rule:
84+
85+- inspect only the most recent unresolved Gemini tool interaction, not arbitrary older turns
86+- if the latest assistant tool-call message is invalid, drop only the incomplete current-turn suffix starting at that assistant message, plus any following tool/result messages tied to it
87+- do not delete earlier valid turns just because a later integration bug produced malformed state
88+- do not truncate to the next user turn as a default recovery strategy
89+
90+This should turn the sanitizer from a broad history-pruning mechanism into a narrow “repair broken current turn if necessary” step.
91+
92+### 3) Preserve thought signatures exactly in persisted and replayed messages
93+
94+**Affected files:**
95+
96+- `src/llm-api/turn.ts`
97+- `src/agent/session-runner.ts`
98+- `src/session/db/message-repo.ts`
99+
100+The repo already accumulates `step.response.messages` / `step.messages` and persists `newMessages`. The implementation should explicitly verify that no transformation strips or rewrites Gemini signature-bearing provider metadata on assistant tool-call parts before those messages are stored and replayed.
101+
102+Concrete expectations:
103+
104+- preserve assistant message part ordering exactly
105+- preserve `providerOptions.google.thoughtSignature` and `providerOptions.vertex.thoughtSignature` byte-for-byte
106+- do not reconstitute tool-call messages from streamed events for persistence if authoritative step messages already exist
107+- avoid any compaction or sanitization pass that mutates valid assistant tool-call parts
108+
109+If a normalization step copies `providerMetadata` to `providerOptions`, it should be additive and lossless, not a rewrite that changes valid signature payloads.
110+
111+### 4) Improve observability for narrow recovery cases
112+
113+**Affected file:** `src/llm-api/turn.ts`
114+
115+Replace the current `"gemini tool history truncated"` logging with more specific diagnostics, for example:
116+
117+- `gemini tool history repaired`
118+- reason: `missing-signature-anchor`, `malformed-tool-call-part`, `orphaned-tool-result-after-repair`, etc.
119+- repairedFromIndex / droppedMessageCount
120+- whether the affected scope was only the current unresolved turn
121+
122+This makes rollout safer and gives evidence if the remaining recovery path is still firing often.
123+
124+## Detailed implementation steps
125+
126+1. Update `src/llm-api/providers.ts`:
127+ - remove the early return that disables thinking when `hasTools` is true for Gemini models
128+ - delete or deprecate `shouldDisableGeminiThinkingForTools()` and update imports/tests accordingly
129+
130+2. Refactor Gemini validation helpers in `src/llm-api/turn.ts`:
131+ - keep signature extraction helper support for both `providerOptions` and `providerMetadata`
132+ - replace `assistantMessageHasUnsignedGeminiToolCall()` with a helper that evaluates an assistant message as a whole, not part-by-part in isolation
133+ - encode the parallel-call rule explicitly: one signature can cover a multi-call assistant response
134+
135+3. Rewrite `sanitizeGeminiToolMessages()`:
136+ - run for Gemini tool histories based on provider/model family, not on the old “disable thinking” gate
137+ - scan backward from the tail to find the latest assistant tool-call message and any following related tool messages
138+ - if that tail segment is valid, return messages unchanged
139+ - if invalid, remove only that tail segment and keep earlier history intact
140+ - never remove valid earlier turns just because an older assistant message had unsigned sibling tool-call parts
141+
142+4. Verify persistence path:
143+ - confirm `partialState.messages` from `onStepFinish` remain the source of truth
144+ - confirm stored/replayed messages include the original assistant content parts with thought signatures unchanged
145+ - add comments near the persistence path explaining that full Gemini responses must be preserved exactly for signature replay correctness
146+
147+5. Update logging and comments to document the new invariant:
148+ - reasoning is allowed with Gemini tools
149+ - history repair exists only for malformed tail state caused by integration issues
150+
151+## Tests to add or update
152+
153+**Affected files:** `src/llm-api/providers.test.ts`, `src/llm-api/turn.test.ts`
154+
155+### Providers tests
156+
157+- remove tests that assert Gemini 2.5/3 tool turns disable reasoning
158+- add tests asserting `getThinkingProviderOptions()` still returns Gemini thinking options when `hasTools` is true
159+- if `shouldDisableGeminiThinkingForTools()` is removed, delete its test block; if retained as a narrower flag, rewrite tests to match its new semantics
160+
161+### Turn tests
162+
163+Replace current sanitizer expectations with cases that reflect valid signature behavior:
164+
165+- valid single Gemini tool call with signature is preserved unchanged
166+- valid parallel Gemini tool calls where only the first tool-call part has a signature are preserved unchanged
167+- legacy `providerMetadata` signatures are still recognized and normalized losslessly
168+- malformed latest Gemini tool-call turn with no signature anchor is repaired by dropping only the tail segment
169+- earlier valid turns remain intact when the latest turn is repaired
170+- non-Gemini models are unaffected
171+- sanitizer is a no-op when there are no Gemini tool-call assistant messages
172+
173+Optional but useful:
174+
175+- regression test proving sanitizer no longer deletes history up to the next user turn
176+- regression test proving exact `thoughtSignature` values survive round-trip storage/replay assumptions at the `CoreMessage` level
177+
178+## Rollout and risk notes
179+
180+- Main product risk: re-enabling reasoning for Gemini tools could expose any remaining SDK/provider incompatibilities that the blanket workaround used to hide.
181+- Main quality risk: if tail repair is too permissive, malformed history could still be replayed and trigger provider errors.
182+- Mitigation: keep recovery narrow, instrument it well, and verify with focused tests around single-call and parallel-call histories.
183+- Because the change is localized to provider options and history sanitation, it should be low-risk for non-Gemini providers.
184+
185+## Open questions and assumptions
186+
187+- Assumption: preserving the SDK-authored `step.response.messages` / `step.messages` is sufficient for correct thought-signature replay in this codebase.
188+- Assumption: Gemini invalid-history failures are primarily tail-state problems from integration bugs, not arbitrary deep-history corruption.
189+- Open question: should repair logic also validate matching tool-result coverage for repaired tails, or only signature anchoring on assistant tool-call messages?
190+- Open question: do any current upstream adapters place the signature anywhere other than `providerOptions.google|vertex.thoughtSignature` or legacy `providerMetadata`? If yes, add a compatibility helper rather than weakening validation globally.
191+
192+## Acceptance criteria
193+
194+- Gemini tool turns can use thinking without `getThinkingProviderOptions()` returning `null` solely because tools are present.
195+- Reasoning remains visible during Gemini tool turns.
196+- Valid Gemini tool-call histories, including parallel calls with only the first call signed, are preserved unchanged.
197+- Thought signatures are persisted and replayed exactly on assistant tool-call parts.
198+- Recovery logic only trims truly invalid current-tail Gemini history and never broad-truncates healthy earlier turns.
199+- Updated unit tests cover the new rules and pass.
200+- Existing non-Gemini behavior remains unchanged.
201+
202+## Sources
203+
204+- https://ai.google.dev/gemini-api/docs/function-calling
205+- https://ai.google.dev/gemini-api/docs/thinking
206+- https://ai.google.dev/gemini-api/docs/thought-signatures
207+- https://docs.cloud.google.com/vertex-ai/generative-ai/docs/thought-signatures
208+- https://github.com/vercel/ai/issues/10344
209+- https://github.com/googleapis/python-genai/issues/2081
src/agent/session-runner.ts+10−0
@@ -98,6 +98,11 @@ export class SessionRunner {
9898 this.session = newSession(this.currentModel, this.cwd);
9999 }
100100 this.turnIndex = getMaxTurnIndex(this.session.id) + 1;
101+ // Persistence invariant: load this history via lossless JSON serialization only.
102+ // Model-authored messages must remain byte-for-byte equivalent in structure
103+ // (including providerOptions/providerMetadata thought-signature fields and
104+ // part ordering); do not reconstruct tool-call history on resume.
105+
101106 this.coreHistory = [...this.session.messages];
102107 }
103108
@@ -190,6 +195,11 @@ export class SessionRunner {
190195 if (newMessages.length > 0) {
191196 this.coreHistory.push(...newMessages);
192197 this.session.messages.push(...newMessages);
198+ // Persistence invariant: save model-authored messages with lossless JSON
199+ // serialization and preserve exact shape/ordering (including
200+ // providerOptions/providerMetadata thought-signature fields). Never
201+ // reconstruct tool-call history during save/load.
202+
193203 saveMessages(this.session.id, newMessages, thisTurn);
194204 }
195205
src/llm-api/providers.test.ts+27−34
@@ -1,39 +1,6 @@
11 import { describe, expect, test } from "bun:test";
22
3-import {
4- getThinkingProviderOptions,
5- shouldDisableGeminiThinkingForTools,
6-} from "./providers.ts";
7-
8-describe("shouldDisableGeminiThinkingForTools", () => {
9- test("enables workaround for affected Gemini versions", () => {
10- expect(shouldDisableGeminiThinkingForTools("zen/gemini-3.1-pro")).toBe(
11- true,
12- );
13- expect(shouldDisableGeminiThinkingForTools("google/gemini-2.5-pro")).toBe(
14- true,
15- );
16- expect(
17- shouldDisableGeminiThinkingForTools("google/gemini-2.5-flash-preview"),
18- ).toBe(true);
19- });
20-
21- test("does not enable workaround for non-affected providers", () => {
22- expect(
23- shouldDisableGeminiThinkingForTools("anthropic/claude-4-sonnet"),
24- ).toBe(false);
25- expect(shouldDisableGeminiThinkingForTools("openai/gpt-4o")).toBe(false);
26- });
27-
28- test("does not enable workaround for unrelated Gemini models", () => {
29- expect(shouldDisableGeminiThinkingForTools("google/gemini-1.5-pro")).toBe(
30- false,
31- );
32- expect(shouldDisableGeminiThinkingForTools("zen/some-other-model")).toBe(
33- false,
34- );
35- });
36-});
3+import { getThinkingProviderOptions } from "./providers.ts";
374
385 describe("getThinkingProviderOptions", () => {
396 test("requests OpenAI reasoning summary for GPT reasoning models", () => {
@@ -48,4 +15,30 @@ describe("getThinkingProviderOptions", () => {
4815 openai: { reasoningEffort: "high", reasoningSummary: "auto" },
4916 });
5017 });
18+
19+ test("returns Gemini 2.5 thinking options even when tools are enabled", () => {
20+ expect(
21+ getThinkingProviderOptions("google/gemini-2.5-pro", "medium", true),
22+ ).toEqual({
23+ google: {
24+ thinkingConfig: {
25+ includeThoughts: true,
26+ thinkingBudget: 8_192,
27+ },
28+ },
29+ });
30+ });
31+
32+ test("returns Gemini 3 thinking options for zen models even when tools are enabled", () => {
33+ expect(
34+ getThinkingProviderOptions("zen/gemini-3.1-pro", "xhigh", true),
35+ ).toEqual({
36+ google: {
37+ thinkingConfig: {
38+ includeThoughts: true,
39+ thinkingLevel: "high",
40+ },
41+ },
42+ });
43+ });
5144 });
src/llm-api/providers.ts+1−15
@@ -200,27 +200,13 @@ function clampEffort(
200200 return ORDER[Math.min(i, m)] as ThinkingEffort;
201201 }
202202
203-const GEMINI_TOOL_CALL_AFFECTED_MODELS = /^gemini-(2\.5|3)/;
204-
205-export function shouldDisableGeminiThinkingForTools(
206- modelString: string,
207-): boolean {
208- const { provider, modelId } = parseModelString(modelString);
209- if (provider !== "google" && provider !== "zen") return false;
210- return GEMINI_TOOL_CALL_AFFECTED_MODELS.test(modelId);
211-}
212-
213203 export function getThinkingProviderOptions(
214204 modelString: string,
215205 effort: ThinkingEffort,
216- hasTools = false,
206+ _hasTools = false,
217207 ): Record<string, unknown> | null {
218208 if (!supportsThinking(modelString)) return null;
219209
220- if (hasTools && shouldDisableGeminiThinkingForTools(modelString)) {
221- return null;
222- }
223-
224210 const { provider, modelId } = parseModelString(modelString);
225211
226212 // Anthropic (direct or via Zen routing through @ai-sdk/anthropic)
src/llm-api/turn.test.ts+192−62
@@ -71,39 +71,42 @@ describe("getReasoningDeltaFromStreamChunk", () => {
7171 });
7272
7373 describe("sanitizeGeminiToolMessages", () => {
74- test("truncates the current Gemini tool turn when any tool call lacks a thought signature", () => {
75- const messages = [
76- { role: "user", content: "older turn" },
74+ const healthyGeminiToolTurn = (userContent: string): CoreMessage[] =>
75+ [
76+ { role: "user", content: userContent },
7777 {
7878 role: "assistant",
7979 content: [
8080 {
8181 type: "tool-call",
82- toolCallId: "old-call",
82+ toolCallId: "healthy-call",
8383 toolName: "read",
8484 input: {},
85- providerOptions: { google: { thoughtSignature: "sig-old" } },
85+ providerOptions: { google: { thoughtSignature: "sig-ok" } },
8686 },
8787 ],
8888 },
8989 {
9090 role: "tool",
91- content: [] as unknown as CoreMessage["content"],
92- },
93- { role: "user", content: "current turn" },
94- {
95- role: "assistant",
9691 content: [
9792 {
98- type: "tool-call",
99- toolCallId: "ok-call",
93+ type: "tool-result",
94+ toolCallId: "healthy-call",
10095 toolName: "read",
101- input: {},
102- providerOptions: { google: { thoughtSignature: "sig-ok" } },
96+ output: { type: "json", value: { ok: true } },
10397 },
98+ ],
99+ },
100+ ] as unknown as CoreMessage[];
101+
102+ const brokenGeminiToolTurn = (toolCallId = "broken-call"): CoreMessage[] =>
103+ [
104+ {
105+ role: "assistant",
106+ content: [
104107 {
105108 type: "tool-call",
106- toolCallId: "broken-call",
109+ toolCallId,
107110 toolName: "replace",
108111 input: {},
109112 },
@@ -114,89 +117,155 @@ describe("sanitizeGeminiToolMessages", () => {
114117 content: [
115118 {
116119 type: "tool-result",
117- toolCallId: "ok-call",
118- toolName: "read",
119- output: { type: "json", value: { ok: true } },
120- },
121- {
122- type: "tool-result",
123- toolCallId: "broken-call",
120+ toolCallId,
124121 toolName: "replace",
125- output: { type: "json", value: { ok: true } },
122+ output: { type: "json", value: { ok: false } },
126123 },
127124 ],
128125 },
129126 ] as unknown as CoreMessage[];
130127
131- const sanitized = sanitizeGeminiToolMessages(
132- messages,
133- "zen/gemini-3.1-pro",
134- true,
135- );
128+ test("valid signed single call preserved", () => {
129+ const messages: CoreMessage[] = [
130+ { role: "user", content: "current turn" },
131+ {
132+ role: "assistant",
133+ content: [
134+ {
135+ type: "tool-call",
136+ toolCallId: "call-1",
137+ toolName: "read",
138+ input: {},
139+ providerOptions: { google: { thoughtSignature: "sig-1" } },
140+ },
141+ ],
142+ } as unknown as CoreMessage,
143+ ];
136144
137- expect(sanitized).toEqual(messages.slice(0, 4));
145+ expect(
146+ sanitizeGeminiToolMessages(messages, "google/gemini-2.5-pro", true),
147+ ).toEqual(messages);
138148 });
139149
140- test("drops earlier broken Gemini tool turns and keeps the latest user turn", () => {
141- const messages = [
142- { role: "user", content: "healthy turn" },
143- { role: "assistant", content: "healthy response" },
144- { role: "user", content: "broken turn" },
150+ test("valid parallel calls with only first signed preserved", () => {
151+ const messages: CoreMessage[] = [
152+ { role: "user", content: "parallel call turn" },
145153 {
146154 role: "assistant",
147155 content: [
148156 {
149157 type: "tool-call",
150- toolCallId: "signed-call",
158+ toolCallId: "signed-anchor",
151159 toolName: "read",
152160 input: {},
153- providerOptions: { google: { thoughtSignature: "sig-1" } },
161+ providerOptions: { google: { thoughtSignature: "sig-anchor" } },
154162 },
155163 {
156164 type: "tool-call",
157- toolCallId: "unsigned-call",
165+ toolCallId: "unsigned-followup",
158166 toolName: "replace",
159167 input: {},
160168 },
161169 ],
162- },
163- {
164- role: "tool",
165- content: [] as unknown as CoreMessage["content"],
166- },
167- { role: "assistant", content: "done" },
168- { role: "user", content: "latest turn" },
170+ } as unknown as CoreMessage,
171+ ];
172+
173+ expect(
174+ sanitizeGeminiToolMessages(messages, "zen/gemini-3.1-pro", true),
175+ ).toEqual(messages);
176+ });
177+
178+ test("legacy providerMetadata recognized and normalized into providerOptions", () => {
179+ const messages = [
180+ { role: "user", content: "current turn" },
169181 {
170182 role: "assistant",
171183 content: [
172184 {
173185 type: "tool-call",
174- toolCallId: "latest-call",
186+ toolCallId: "call-1",
175187 toolName: "read",
176188 input: {},
177- providerOptions: { google: { thoughtSignature: "sig-2" } },
189+ providerMetadata: { google: { thoughtSignature: "sig-legacy" } },
178190 },
179191 ],
180192 },
181193 ] as unknown as CoreMessage[];
182194
195+ const sanitized = sanitizeGeminiToolMessages(
196+ messages,
197+ "google/gemini-2.5-pro",
198+ true,
199+ );
200+ const assistant = sanitized[1] as {
201+ role: "assistant";
202+ content: Array<Record<string, unknown>>;
203+ };
204+ expect(assistant.content[0]?.providerOptions).toEqual({
205+ google: { thoughtSignature: "sig-legacy" },
206+ });
207+ });
208+
209+ test("malformed assistant/tool before current user preserves that user and later messages", () => {
210+ const messages = [
211+ ...healthyGeminiToolTurn("healthy turn"),
212+ ...brokenGeminiToolTurn(),
213+ { role: "user", content: "current prompt" },
214+ { role: "assistant", content: "plain response" },
215+ ] as unknown as CoreMessage[];
216+
183217 expect(
184218 sanitizeGeminiToolMessages(messages, "google/gemini-2.5-pro", true),
185- ).toEqual([...messages.slice(0, 3), ...messages.slice(6)]);
219+ ).toEqual([...messages.slice(0, 3), ...messages.slice(5)]);
186220 });
187221
188- test("copies legacy providerMetadata into providerOptions for Gemini tool calls", () => {
222+ test("malformed latest turn without trailing user still truncates tail from broken assistant onward", () => {
189223 const messages = [
190- { role: "user", content: "current turn" },
224+ ...healthyGeminiToolTurn("healthy turn"),
225+ { role: "user", content: "latest turn" },
226+ ...brokenGeminiToolTurn(),
227+ ] as unknown as CoreMessage[];
228+
229+ expect(
230+ sanitizeGeminiToolMessages(messages, "google/gemini-2.5-pro", true),
231+ ).toEqual(messages.slice(0, 4));
232+ });
233+
234+ test("earlier valid turns remain when latest turn repaired", () => {
235+ const messages = [
236+ { role: "user", content: "turn 1" },
191237 {
192238 role: "assistant",
193239 content: [
194240 {
195241 type: "tool-call",
196- toolCallId: "call-1",
242+ toolCallId: "turn1-call",
243+ toolName: "read",
244+ input: {},
245+ providerOptions: { google: { thoughtSignature: "sig-turn1" } },
246+ },
247+ ],
248+ },
249+ {
250+ role: "tool",
251+ content: [
252+ {
253+ type: "tool-result",
254+ toolCallId: "turn1-call",
197255 toolName: "read",
256+ output: { type: "json", value: { data: 1 } },
257+ },
258+ ],
259+ },
260+ { role: "user", content: "turn 2" },
261+ {
262+ role: "assistant",
263+ content: [
264+ {
265+ type: "tool-call",
266+ toolCallId: "turn2-broken",
267+ toolName: "replace",
198268 input: {},
199- providerMetadata: { google: { thoughtSignature: "sig-1" } },
200269 },
201270 ],
202271 },
@@ -204,20 +273,13 @@ describe("sanitizeGeminiToolMessages", () => {
204273
205274 const sanitized = sanitizeGeminiToolMessages(
206275 messages,
207- "google/gemini-2.5-pro",
276+ "zen/gemini-3.1-pro",
208277 true,
209278 );
210-
211- const assistant = sanitized[1] as {
212- role: "assistant";
213- content: Array<Record<string, unknown>>;
214- };
215- expect(assistant.content[0]?.providerOptions).toEqual({
216- google: { thoughtSignature: "sig-1" },
217- });
279+ expect(sanitized).toEqual(messages.slice(0, 4));
218280 });
219281
220- test("leaves non-Gemini models untouched", () => {
282+ test("non-Gemini untouched", () => {
221283 const messages: CoreMessage[] = [
222284 { role: "user", content: "go" },
223285 {
@@ -230,13 +292,81 @@ describe("sanitizeGeminiToolMessages", () => {
230292 input: {},
231293 },
232294 ],
233- },
295+ } as unknown as CoreMessage,
234296 ];
235297
236298 expect(sanitizeGeminiToolMessages(messages, "openai/gpt-4o", true)).toEqual(
237299 messages,
238300 );
239301 });
302+
303+ test("no Gemini tool-call assistant messages => no-op", () => {
304+ const messages: CoreMessage[] = [
305+ { role: "user", content: "hello" },
306+ { role: "assistant", content: "plain text response" },
307+ { role: "user", content: "next" },
308+ {
309+ role: "tool",
310+ content: [
311+ {
312+ type: "tool-result",
313+ toolCallId: "orphan",
314+ toolName: "read",
315+ output: { type: "text", value: "ok" },
316+ },
317+ ],
318+ } as unknown as CoreMessage,
319+ ];
320+
321+ expect(
322+ sanitizeGeminiToolMessages(messages, "google/gemini-2.5-pro", true),
323+ ).toEqual(messages);
324+ });
325+
326+ test("regression: sanitizer no longer removes up to next user turn for older broken turns", () => {
327+ const messages = [
328+ { role: "user", content: "older broken turn" },
329+ {
330+ role: "assistant",
331+ content: [
332+ {
333+ type: "tool-call",
334+ toolCallId: "older-broken",
335+ toolName: "replace",
336+ input: {},
337+ },
338+ ],
339+ },
340+ {
341+ role: "tool",
342+ content: [
343+ {
344+ type: "tool-result",
345+ toolCallId: "older-broken",
346+ toolName: "replace",
347+ output: { type: "json", value: { stale: true } },
348+ },
349+ ],
350+ },
351+ { role: "user", content: "latest turn" },
352+ {
353+ role: "assistant",
354+ content: [
355+ {
356+ type: "tool-call",
357+ toolCallId: "latest-valid",
358+ toolName: "read",
359+ input: {},
360+ providerOptions: { google: { thoughtSignature: "sig-latest" } },
361+ },
362+ ],
363+ },
364+ ] as unknown as CoreMessage[];
365+
366+ expect(
367+ sanitizeGeminiToolMessages(messages, "google/gemini-2.5-pro", true),
368+ ).toEqual(messages);
369+ });
240370 });
241371
242372 describe("stripGPTCommentaryFromHistory", () => {
src/llm-api/turn.ts+108−31
@@ -10,7 +10,6 @@ import { logApiEvent } from "./api-log.ts";
1010 import {
1111 getThinkingProviderOptions,
1212 parseModelString,
13- shouldDisableGeminiThinkingForTools,
1413 type ThinkingEffort,
1514 } from "./providers.ts";
1615 import type { ToolDef, TurnEvent } from "./types.ts";
@@ -408,53 +407,128 @@ function isToolCallPart(part: unknown): part is Record<string, unknown> {
408407 return isRecord(part) && part.type === "tool-call";
409408 }
410409
411-function assistantMessageHasUnsignedGeminiToolCall(
412- message: CoreMessage,
413-): boolean {
410+function isGeminiModelFamily(modelString: string): boolean {
411+ const { provider, modelId } = parseModelString(modelString);
412+ return (
413+ (provider === "google" || provider === "zen") &&
414+ modelId.startsWith("gemini-")
415+ );
416+}
417+
418+type GeminiToolHistoryRepairReason = "missing-signature-anchor";
419+
420+function validateGeminiAssistantToolCallMessage(message: CoreMessage): {
421+ valid: boolean;
422+ reason: GeminiToolHistoryRepairReason | null;
423+} {
414424 if (message.role !== "assistant" || !Array.isArray(message.content)) {
415- return false;
425+ return { valid: true, reason: null };
416426 }
417427
428+ let firstToolCallPartSeen = false;
418429 for (const part of message.content) {
419430 if (!isToolCallPart(part)) continue;
420- if (getGeminiThoughtSignature(part) === null) return true;
431+ if (firstToolCallPartSeen) continue;
432+ firstToolCallPartSeen = true;
433+ if (getGeminiThoughtSignature(part) === null) {
434+ return { valid: false, reason: "missing-signature-anchor" };
435+ }
421436 }
422437
423- return false;
438+ return { valid: true, reason: null };
424439 }
425440
426-export function sanitizeGeminiToolMessages(
441+function sanitizeGeminiToolMessagesWithMetadata(
427442 messages: CoreMessage[],
428443 modelString: string,
429444 hasTools: boolean,
430-): CoreMessage[] {
431- if (!hasTools || !shouldDisableGeminiThinkingForTools(modelString)) {
432- return messages;
445+): {
446+ messages: CoreMessage[];
447+ repaired: boolean;
448+ reason: GeminiToolHistoryRepairReason | null;
449+ repairedFromIndex: number;
450+ droppedMessageCount: number;
451+ tailOnlyAffected: boolean;
452+} {
453+ if (!hasTools || !isGeminiModelFamily(modelString)) {
454+ return {
455+ messages,
456+ repaired: false,
457+ reason: null,
458+ repairedFromIndex: -1,
459+ droppedMessageCount: 0,
460+ tailOnlyAffected: true,
461+ };
433462 }
434463
435- let sanitized = messages.map((message) =>
464+ const normalized = messages.map((message) =>
436465 normalizeMessageProviderOptions(message),
437466 );
438467
439- while (true) {
440- const brokenIndex = sanitized.findIndex((message) =>
441- assistantMessageHasUnsignedGeminiToolCall(message),
442- );
443- if (brokenIndex === -1) return sanitized;
468+ for (let index = normalized.length - 1; index >= 0; index -= 1) {
469+ const message = normalized[index];
470+ if (!message) continue;
471+ if (message.role !== "assistant" || !Array.isArray(message.content))
472+ continue;
473+ if (!message.content.some((part) => isToolCallPart(part))) continue;
474+
475+ const validation = validateGeminiAssistantToolCallMessage(message);
476+ if (validation.valid) {
477+ return {
478+ messages: normalized,
479+ repaired: false,
480+ reason: null,
481+ repairedFromIndex: -1,
482+ droppedMessageCount: 0,
483+ tailOnlyAffected: true,
484+ };
485+ }
444486
445- const nextUserIndex = sanitized.findIndex(
446- (message, index) => index > brokenIndex && message.role === "user",
487+ const nextUserIndex = normalized.findIndex(
488+ (candidate, candidateIndex) =>
489+ candidateIndex > index && candidate?.role === "user",
447490 );
448- if (nextUserIndex !== -1) {
449- sanitized = [
450- ...sanitized.slice(0, brokenIndex),
451- ...sanitized.slice(nextUserIndex),
452- ];
453- continue;
491+ if (nextUserIndex === -1) {
492+ return {
493+ messages: normalized.slice(0, index),
494+ repaired: true,
495+ reason: validation.reason,
496+ repairedFromIndex: index,
497+ droppedMessageCount: normalized.length - index,
498+ tailOnlyAffected: true,
499+ };
454500 }
455501
456- return sanitized.slice(0, brokenIndex);
502+ return {
503+ messages: [
504+ ...normalized.slice(0, index),
505+ ...normalized.slice(nextUserIndex),
506+ ],
507+ repaired: true,
508+ reason: validation.reason,
509+ repairedFromIndex: index,
510+ droppedMessageCount: nextUserIndex - index,
511+ tailOnlyAffected: false,
512+ };
457513 }
514+
515+ return {
516+ messages: normalized,
517+ repaired: false,
518+ reason: null,
519+ repairedFromIndex: -1,
520+ droppedMessageCount: 0,
521+ tailOnlyAffected: true,
522+ };
523+}
524+
525+export function sanitizeGeminiToolMessages(
526+ messages: CoreMessage[],
527+ modelString: string,
528+ hasTools: boolean,
529+): CoreMessage[] {
530+ return sanitizeGeminiToolMessagesWithMetadata(messages, modelString, hasTools)
531+ .messages;
458532 }
459533
460534 /**
@@ -616,16 +690,19 @@ export async function* runTurn(options: {
616690 toolResultPayloadCapBytes,
617691 });
618692
619- const geminiSanitizedMessages = sanitizeGeminiToolMessages(
693+ const geminiSanitizationResult = sanitizeGeminiToolMessagesWithMetadata(
620694 messages,
621695 modelString,
622696 toolCount > 0,
623697 );
624- if (geminiSanitizedMessages.length !== messages.length) {
625- logApiEvent("gemini tool history truncated", {
698+ const geminiSanitizedMessages = geminiSanitizationResult.messages;
699+ if (geminiSanitizationResult.repaired) {
700+ logApiEvent("gemini tool history repaired", {
626701 modelString,
627- originalMessages: messages.length,
628- sanitizedMessages: geminiSanitizedMessages.length,
702+ reason: geminiSanitizationResult.reason,
703+ repairedFromIndex: geminiSanitizationResult.repairedFromIndex,
704+ droppedMessageCount: geminiSanitizationResult.droppedMessageCount,
705+ tailOnlyAffected: geminiSanitizationResult.tailOnlyAffected,
629706 });
630707 }
631708
src/session/db/message-repo.ts+10−0
@@ -13,6 +13,11 @@ export function saveMessages(
1313 VALUES (?, ?, ?, ?)`,
1414 );
1515 const now = Date.now();
16+ // Persistence invariant: write CoreMessage as lossless JSON (no reshaping) so
17+ // model-authored payloads round-trip exactly, including providerOptions /
18+ // providerMetadata thought signatures and part ordering required for Gemini
19+ // tool-call replay correctness.
20+
1621 for (const msg of msgs) {
1722 stmt.run(sessionId, JSON.stringify(msg), turnIndex, now);
1823 }
@@ -54,6 +59,11 @@ export function loadMessages(sessionId: string): CoreMessage[] {
5459 .all(sessionId);
5560
5661 const messages: CoreMessage[] = [];
62+ // Persistence invariant: load by parsing stored JSON verbatim; do not
63+ // reconstruct tool-call history or normalize parts, because model-authored
64+ // messages must round-trip exactly (providerOptions / providerMetadata thought
65+ // signatures + part ordering) for Gemini replay correctness.
66+
5767 for (const row of rows) {
5868 try {
5969 messages.push(JSON.parse(row.payload) as CoreMessage);