@llumiverse/drivers 1.3.0 → 1.4.0-dev.20260629.090753Z

package/src/vertexai/models/claude.ts

@@ -1,42 +1,46 @@
 import {
-    type AIModel, type Completion, type CompletionChunkObject, type ExecutionOptions, type LlumiverseError,
+    type AIModel,
+    type Completion,
+    type CompletionChunkObject,
+    type ExecutionOptions,
+    type LlumiverseError,
     type LlumiverseErrorContext,
     ModelType,
     type PromptSegment,
     type VertexAIClaudeOptions,
-} from "@llumiverse/core";
-import type { ClaudePrompt } from "../../shared/claude-messages.js";
+} from '@llumiverse/core';
+import type { ClaudePrompt } from '../../shared/claude-messages.js';
 import {
     executeClaudeCompletion,
     formatAnthropicLlumiverseError,
     formatClaudePrompt,
     isClaudeErrorRetryable,
     streamClaudeCompletion,
-} from "../../shared/claude-messages.js";
+} from '../../shared/claude-messages.js';
 
-
-import type { VertexAIDriver } from "../index.js";
-import type { ModelDefinition } from "../models.js";
+import type { VertexAIDriver } from '../index.js';
+import type { ModelDefinition } from '../models.js';
 
 export const ANTHROPIC_REGIONS: Record<string, string> = {
-    us: "us-east5",
-    europe: "europe-west1",
-    global: "global",
-}
+    us: 'us-east5',
+    europe: 'europe-west1',
+    global: 'global',
+};
 
-export const NON_GLOBAL_ANTHROPIC_MODELS = [
-    "claude-3-5",
-    "claude-3",
-];
+export const NON_GLOBAL_ANTHROPIC_MODELS = ['claude-3-5', 'claude-3'];
 
 /**
  * Parse a VertexAI model path (e.g. "locations/us-east5/claude-3-5-sonnet") into
  * its region and model name components.
  */
-function resolveVertexAIModelPath(options: ExecutionOptions): { modelName: string; region: string | undefined; options: ExecutionOptions } {
-    const splits = options.model.split("/");
+function resolveVertexAIModelPath(options: ExecutionOptions): {
+    modelName: string;
+    region: string | undefined;
+    options: ExecutionOptions;
+} {
+    const splits = options.model.split('/');
     let region: string | undefined;
-    if (splits[0] === "locations" && splits.length >= 2) {
+    if (splits[0] === 'locations' && splits.length >= 2) {
         region = splits[1];
     }
     const modelName = splits[splits.length - 1];
@@ -44,8 +48,7 @@ function resolveVertexAIModelPath(options: ExecutionOptions): { modelName: strin
 }
 
 export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
-
-    model: AIModel
+    model: AIModel;
 
     constructor(modelId: string) {
         this.model = {
@@ -57,30 +60,46 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
         } satisfies AIModel;
     }
 
-    async createPrompt(_driver: VertexAIDriver, segments: PromptSegment[], options: ExecutionOptions): Promise<ClaudePrompt> {
-        return formatClaudePrompt(segments, options);
+    async createPrompt(
+        _driver: VertexAIDriver,
+        segments: PromptSegment[],
+        options: ExecutionOptions,
+    ): Promise<ClaudePrompt> {
+        return formatClaudePrompt(segments, options, _driver.logger);
     }
 
-    async requestTextCompletion(driver: VertexAIDriver, prompt: ClaudePrompt, options: ExecutionOptions): Promise<Completion> {
+    async requestTextCompletion(
+        driver: VertexAIDriver,
+        prompt: ClaudePrompt,
+        options: ExecutionOptions,
+    ): Promise<Completion> {
         const { region, options: resolvedOptions } = resolveVertexAIModelPath(options);
-        const client = await driver.getAnthropicClient(region);
+        const client = await driver.getAnthropicClient(region, resolvedOptions.httpTimeout);
         const model_options = resolvedOptions.model_options as VertexAIClaudeOptions | undefined;
-        if (model_options?._option_id !== undefined &&
-            model_options?._option_id !== "vertexai-claude" &&
-            model_options?._option_id !== "text-fallback") {
-            driver.logger.debug({ options: resolvedOptions.model_options }, "Unexpected option id");
+        if (
+            model_options?._option_id !== undefined &&
+            model_options?._option_id !== 'vertexai-claude' &&
+            model_options?._option_id !== 'text-fallback'
+        ) {
+            driver.logger.debug({ options: resolvedOptions.model_options }, 'Unexpected option id');
         }
         return executeClaudeCompletion(client, prompt, resolvedOptions);
     }
 
-    async requestTextCompletionStream(driver: VertexAIDriver, prompt: ClaudePrompt, options: ExecutionOptions): Promise<AsyncIterable<CompletionChunkObject>> {
+    async requestTextCompletionStream(
+        driver: VertexAIDriver,
+        prompt: ClaudePrompt,
+        options: ExecutionOptions,
+    ): Promise<AsyncIterable<CompletionChunkObject>> {
         const { region, options: resolvedOptions } = resolveVertexAIModelPath(options);
-        const client = await driver.getAnthropicClient(region);
+        const client = await driver.getAnthropicClient(region, resolvedOptions.httpTimeout);
         const model_options = resolvedOptions.model_options as VertexAIClaudeOptions | undefined;
-        if (model_options?._option_id !== undefined &&
-            model_options?._option_id !== "vertexai-claude" &&
-            model_options?._option_id !== "text-fallback") {
-            driver.logger.debug({ options: resolvedOptions.model_options }, "Unexpected option id");
+        if (
+            model_options?._option_id !== undefined &&
+            model_options?._option_id !== 'vertexai-claude' &&
+            model_options?._option_id !== 'text-fallback'
+        ) {
+            driver.logger.debug({ options: resolvedOptions.model_options }, 'Unexpected option id');
         }
         return streamClaudeCompletion(client, prompt, resolvedOptions);
     }
@@ -88,16 +107,12 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
     isClaudeErrorRetryable(
         error: unknown,
         httpStatusCode: number | undefined,
-        errorType: string | undefined
+        errorType: string | undefined,
     ): boolean | undefined {
         return isClaudeErrorRetryable(error, httpStatusCode, errorType);
     }
 
-    formatLlumiverseError(
-        _driver: VertexAIDriver,
-        error: unknown,
-        context: LlumiverseErrorContext
-    ): LlumiverseError {
+    formatLlumiverseError(_driver: VertexAIDriver, error: unknown, context: LlumiverseErrorContext): LlumiverseError {
         return formatAnthropicLlumiverseError(error, context);
     }
 }

package/src/vertexai/models/gemini-conversation-mutation.test.ts

@@ -13,10 +13,10 @@
  * Fix: use a local `payloadContents` variable so the caller's conversation is never mutated.
  */
 
-import { ExecutionOptions } from '@llumiverse/core';
 import { FinishReason } from '@google/genai';
-import { describe, expect, it } from 'vitest';
-import { VertexAIDriver } from '../index.js';
+import { type DataSource, type ExecutionOptions, PromptRole, type PromptSegment } from '@llumiverse/core';
+import { describe, expect, it, vi } from 'vitest';
+import type { GenerateContentPrompt, VertexAIDriver } from '../index.js';
 import { convertGeminiFunctionPartsToText, GeminiModelDefinition } from './gemini.js';
 
 // ---------------------------------------------------------------------------
@@ -35,8 +35,8 @@ describe('convertGeminiFunctionPartsToText', () => {
                 parts: [{ functionResponse: { name: 'plan', response: { output: 'done' } } }],
             },
         ];
-        const originalItemRefs = original.map(c => c);
-        const originalPartRefs = original.map(c => c.parts[0]);
+        const originalItemRefs = original.map((c) => c);
+        const originalPartRefs = original.map((c) => c.parts[0]);
 
         const result = convertGeminiFunctionPartsToText(original);
 
@@ -64,7 +64,7 @@ describe('convertGeminiFunctionPartsToText', () => {
 
         const result = convertGeminiFunctionPartsToText(contents);
 
-        expect(result[0].parts![0]).toEqual({
+        expect(result[0].parts?.[0]).toEqual({
             text: '[Tool call: get_weather({"location":"Paris"})]',
         });
     });
@@ -79,7 +79,7 @@ describe('convertGeminiFunctionPartsToText', () => {
 
         const result = convertGeminiFunctionPartsToText(contents);
 
-        expect(result[0].parts![0]).toEqual({
+        expect(result[0].parts?.[0]).toEqual({
             text: '[Tool result for get_weather: {"temperature":"15°C"}]',
         });
     });
@@ -90,7 +90,7 @@ describe('convertGeminiFunctionPartsToText', () => {
 
         const result = convertGeminiFunctionPartsToText(contents);
 
-        expect(result[0].parts![0]).toBe(textPart);
+        expect(result[0].parts?.[0]).toBe(textPart);
     });
 });
 
@@ -105,7 +105,10 @@ function makeContentsWithFunctionParts() {
     ];
 }
 
-function makeDriver(overrides: { generateContent?: () => Promise<any>; generateContentStream?: () => Promise<AsyncIterable<any>> }) {
+function makeDriver(overrides: {
+    generateContent?: () => Promise<unknown>;
+    generateContentStream?: () => Promise<AsyncIterable<unknown>>;
+}) {
     return {
         logger: { warn: () => {}, info: () => {}, error: () => {} },
         getGoogleGenAIClient: () => ({
@@ -119,30 +122,64 @@ function makeDriver(overrides: { generateContent?: () => Promise<any>; generateC
 
 const mockNonStreamingResponse = {
     usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5, totalTokenCount: 15 },
-    candidates: [{
-        finishReason: FinishReason.STOP,
-        content: { role: 'model', parts: [{ text: 'Summary.' }] },
-        safetyRatings: [],
-    }],
+    candidates: [
+        {
+            finishReason: FinishReason.STOP,
+            content: { role: 'model', parts: [{ text: 'Summary.' }] },
+            safetyRatings: [],
+        },
+    ],
 };
 
 const mockStreamingChunk = {
     usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5, totalTokenCount: 15 },
-    candidates: [{
-        finishReason: FinishReason.STOP,
-        content: { role: 'model', parts: [{ text: 'Summary.' }] },
-        safetyRatings: [],
-    }],
+    candidates: [
+        {
+            finishReason: FinishReason.STOP,
+            content: { role: 'model', parts: [{ text: 'Summary.' }] },
+            safetyRatings: [],
+        },
+    ],
 };
 
 describe('GeminiModelDefinition - no conversation mutation', () => {
+    it('createPrompt uses DataSource URIs directly for Gemini file data', async () => {
+        const modelDef = new GeminiModelDefinition('gemini-2.0-flash');
+        const file: DataSource = {
+            name: 'doc.pdf',
+            mime_type: 'application/pdf',
+            getURI: vi.fn().mockResolvedValue('gs://test-bucket/doc.pdf'),
+            getURL: vi.fn().mockResolvedValue('https://signed.example/doc.pdf'),
+            getStream: vi.fn().mockResolvedValue(new ReadableStream()),
+        };
+        const segments: PromptSegment[] = [
+            {
+                role: PromptRole.user,
+                files: [file],
+            } as PromptSegment,
+        ];
+        const options: ExecutionOptions = { model: 'publishers/google/models/gemini-2.0-flash' };
+
+        const prompt = await modelDef.createPrompt({} as VertexAIDriver, segments, options);
+
+        expect(file.getURI).toHaveBeenCalledTimes(1);
+        expect(file.getURL).not.toHaveBeenCalled();
+        expect(file.getStream).not.toHaveBeenCalled();
+        expect(prompt.contents[0].parts?.[0]).toEqual({
+            fileData: {
+                fileUri: 'gs://test-bucket/doc.pdf',
+                mimeType: 'application/pdf',
+            },
+        });
+    });
+
     it('requestTextCompletion: does not mutate prompt.contents when tools=[] and conversation has function parts', async () => {
         const modelDef = new GeminiModelDefinition('gemini-2.0-flash');
         const originalContents = makeContentsWithFunctionParts();
         const contentsSnapshot = JSON.stringify(originalContents);
 
         const driver = makeDriver({ generateContent: async () => mockNonStreamingResponse });
-        const prompt = { contents: originalContents, system: undefined } as any;
+        const prompt = { contents: originalContents, system: undefined } as unknown as GenerateContentPrompt;
         const options: ExecutionOptions = { model: 'publishers/google/models/gemini-2.0-flash', tools: [] };
 
         await modelDef.requestTextCompletion(driver, prompt, options);
@@ -158,14 +195,19 @@ describe('GeminiModelDefinition - no conversation mutation', () => {
         const contentsSnapshot = JSON.stringify(originalContents);
 
         const driver = makeDriver({
-            generateContentStream: async () => (async function* () { yield mockStreamingChunk; })(),
+            generateContentStream: async () =>
+                (async function* () {
+                    yield mockStreamingChunk;
+                })(),
         });
-        const prompt = { contents: originalContents, system: undefined } as any;
+        const prompt = { contents: originalContents, system: undefined } as unknown as GenerateContentPrompt;
         const options: ExecutionOptions = { model: 'publishers/google/models/gemini-2.0-flash', tools: [] };
 
         const stream = await modelDef.requestTextCompletionStream(driver, prompt, options);
         // Drain the stream to trigger all processing
-        for await (const _chunk of stream) { /* noop */ }
+        for await (const _chunk of stream) {
+            /* noop */
+        }
 
         expect(JSON.stringify(originalContents)).toBe(contentsSnapshot);
         expect(originalContents[0].parts[0]).toHaveProperty('functionCall');

package/src/vertexai/models/gemini-error-handling.test.ts

@@ -1,8 +1,13 @@
 import { LlumiverseError } from '@llumiverse/core';
 import { beforeEach, describe, expect, it } from 'vitest';
+import { exposePrivate, getProp } from '../../../test/__helpers__/test-utils.js';
 import { VertexAIDriver } from '../index.js';
 import { GeminiModelDefinition } from './gemini.js';
 
+type GeminiModelInternals = {
+    isGeminiErrorRetryable: (httpStatusCode: number, message?: string) => boolean | undefined;
+};
+
 describe('GeminiModelDefinition Error Handling', () => {
     let driver: VertexAIDriver;
     let modelDef: GeminiModelDefinition;
@@ -88,6 +93,33 @@ describe('GeminiModelDefinition Error Handling', () => {
             expect(error.name).toBe('NOT_FOUND');
         });
 
+        it('should mark a client-closed/aborted request (499) as retryable despite the 4xx status', () => {
+            const error = modelDef.formatLlumiverseError(
+                driver,
+                { status: 499, message: 'This operation was aborted' },
+                { provider: 'vertexai', model: 'gemini-2.0-flash', operation: 'execute' },
+            );
+            expect(error.retryable).toBe(true);
+        });
+
+        it('should mark a client-closed/cancelled request (499) as retryable despite the 4xx status', () => {
+            const error = modelDef.formatLlumiverseError(
+                driver,
+                { status: 499, message: 'Client Closed Request: The operation was cancelled.' },
+                { provider: 'vertexai', model: 'gemini-2.0-flash', operation: 'execute' },
+            );
+            expect(error.retryable).toBe(true);
+        });
+
+        it('should mark DEADLINE_EXCEEDED as retryable even under a 4xx status', () => {
+            const error = modelDef.formatLlumiverseError(
+                driver,
+                { status: 400, message: 'DEADLINE_EXCEEDED: Deadline expired before operation could complete' },
+                { provider: 'vertexai', model: 'gemini-2.0-flash', operation: 'execute' },
+            );
+            expect(error.retryable).toBe(true);
+        });
+
         it('should handle RESOURCE_EXHAUSTED error (429) as retryable', () => {
             const googleError = {
                 status: 429,
@@ -202,7 +234,7 @@ describe('GeminiModelDefinition Error Handling', () => {
             });
 
             expect(error.originalError).toBe(googleError);
-            expect((error.originalError as any).status).toBe(429);
+            expect(getProp<number>(error.originalError, 'status')).toBe(429);
         });
 
         it('should throw for non-Google API errors', () => {
@@ -247,6 +279,29 @@ describe('GeminiModelDefinition Error Handling', () => {
             expect(error.name).toBe('ValidationError');
         });
 
+        it('should mark URL_REJECTED-REJECTED_CLIENT_THROTTLED 400s as retryable', () => {
+            // Reproduces a real Vertex AI failure: passing an audio file by URL
+            // (sys:AnalyzeAudio) sometimes 400s with INVALID_ARGUMENT whose
+            // message contains URL_REJECTED-REJECTED_CLIENT_THROTTLED — that's
+            // really a transient throttle on Google's URL fetcher.
+            const googleError = {
+                status: 400,
+                message:
+                    'Cannot fetch content from the provided URL. Please ensure the URL is valid ' +
+                    'and accessible by Vertex AI. Vertex AI respects robots.txt rules, so confirm ' +
+                    'the URL is allowed to be crawled. Status: URL_REJECTED-REJECTED_CLIENT_THROTTLED',
+            };
+
+            const error = modelDef.formatLlumiverseError(driver, googleError, {
+                provider: 'vertexai',
+                model: 'gemini-2.5-flash',
+                operation: 'execute',
+            });
+
+            expect(error.code).toBe(400);
+            expect(error.retryable).toBe(true);
+        });
+
         it('should handle errors without extractable name', () => {
             const googleError = {
                 status: 500,
@@ -263,14 +318,44 @@ describe('GeminiModelDefinition Error Handling', () => {
             expect(error.name).toBe('LlumiverseError');
             expect(error.code).toBe(500);
         });
+
+        it('should treat invalid_grant credential issuer failures as non-retryable', () => {
+            const authError = new Error("Error code invalid_grant: Error connecting to the given credential's issuer.");
+
+            const error = driver.formatLlumiverseError(authError, {
+                provider: 'vertexai',
+                model: 'gemini-2.5-flash',
+                operation: 'execute',
+            });
+
+            expect(error.retryable).toBe(false);
+            expect(error.code).toBeUndefined();
+        });
+
+        it('should preserve invalid_grant from Google API errors', () => {
+            const googleError = {
+                status: 400,
+                message: "Error code invalid_grant: Error connecting to the given credential's issuer.",
+            };
+
+            const error = modelDef.formatLlumiverseError(driver, googleError, {
+                provider: 'vertexai',
+                model: 'locations/global/publishers/google/models/gemini-2.5-flash',
+                operation: 'execute',
+            });
+
+            expect(error.retryable).toBe(false);
+            expect(error.code).toBe(400);
+            expect(error.name).toBe('invalid_grant');
+        });
     });
 
     describe('isGeminiErrorRetryable', () => {
         it('should classify retryable status codes correctly', () => {
-            const retryableStatusCodes = [408, 429, 500, 502, 503, 504];
+            const retryableStatusCodes = [408, 429, 499, 500, 502, 503, 504];
 
             retryableStatusCodes.forEach((statusCode) => {
-                const result = (modelDef as any).isGeminiErrorRetryable(statusCode);
+                const result = exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(statusCode);
                 expect(result, `Status code ${statusCode} should be retryable`).toBe(true);
             });
         });
@@ -279,21 +364,52 @@ describe('GeminiModelDefinition Error Handling', () => {
             const nonRetryableStatusCodes = [400, 401, 403, 404, 409];
 
             nonRetryableStatusCodes.forEach((statusCode) => {
-                const result = (modelDef as any).isGeminiErrorRetryable(statusCode);
+                const result = exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(statusCode);
                 expect(result, `Status code ${statusCode} should not be retryable`).toBe(false);
             });
         });
 
         it('should classify other 5xx errors as retryable', () => {
-            expect((modelDef as any).isGeminiErrorRetryable(501)).toBe(true);
-            expect((modelDef as any).isGeminiErrorRetryable(505)).toBe(true);
-            expect((modelDef as any).isGeminiErrorRetryable(599)).toBe(true);
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(501)).toBe(true);
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(505)).toBe(true);
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(599)).toBe(true);
         });
 
         it('should classify other 4xx errors as non-retryable', () => {
-            expect((modelDef as any).isGeminiErrorRetryable(402)).toBe(false);
-            expect((modelDef as any).isGeminiErrorRetryable(405)).toBe(false);
-            expect((modelDef as any).isGeminiErrorRetryable(499)).toBe(false);
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(402)).toBe(false);
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(405)).toBe(false);
+        });
+
+        it('should treat 400 URL_REJECTED-REJECTED_CLIENT_THROTTLED as retryable', () => {
+            // Vertex AI surfaces inline-URL-fetcher throttling as 400 INVALID_ARGUMENT.
+            // The status is misleading — it's a transient Google-side throttle.
+            const message =
+                'Cannot fetch content from the provided URL. ' + 'Status: URL_REJECTED-REJECTED_CLIENT_THROTTLED';
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(400, message)).toBe(true);
+        });
+
+        it('should treat 400 URL_REJECTED-REJECTED_RATE_LIMITED as retryable', () => {
+            const message =
+                'Cannot fetch content from the provided URL. ' + 'Status: URL_REJECTED-REJECTED_RATE_LIMITED';
+            expect(exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(400, message)).toBe(true);
+        });
+
+        it('should still treat plain 400 INVALID_ARGUMENT as non-retryable', () => {
+            expect(
+                exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(
+                    400,
+                    'INVALID_ARGUMENT: bad input',
+                ),
+            ).toBe(false);
+        });
+
+        it('should treat invalid_grant as non-retryable before status-based retry rules', () => {
+            expect(
+                exposePrivate<GeminiModelInternals>(modelDef).isGeminiErrorRetryable(
+                    503,
+                    "Error code invalid_grant: Error connecting to the given credential's issuer.",
+                ),
+            ).toBe(false);
         });
     });
 

package/src/vertexai/models/gemini-orphaned-tool-result.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Unit tests for fixOrphanedToolResults (Gemini).
+ *
+ * Gemini pairs a `functionResponse` part to its `functionCall` part by name. A
+ * functionResponse left dangling after its functionCall was dropped — e.g. by
+ * conversation compaction trimming the model tool-call turn, or an unmergeable
+ * parallel batch — causes the Gemini/Vertex API to reject the request. This is
+ * the same class of bug fixed in the Claude, Bedrock, and OpenAI drivers.
+ */
+
+import type { Content } from '@google/genai';
+import type { ExecutionOptions } from '@llumiverse/core';
+import { describe, expect, test } from 'vitest';
+import { fixOrphanedToolResults, getGeminiPayload } from './gemini.js';
+
+const OPTIONS_WITH_TOOLS = {
+    model: 'gemini-2.5-flash',
+    tools: [
+        { name: 'a', description: '', input_schema: { type: 'object', properties: {} } },
+        { name: 'b', description: '', input_schema: { type: 'object', properties: {} } },
+    ],
+} as unknown as ExecutionOptions;
+
+function functionResponseNames(contents: Content[]): string[] {
+    return contents.flatMap((content) =>
+        (content.parts ?? []).flatMap((part) => (part.functionResponse?.name ? [part.functionResponse.name] : [])),
+    );
+}
+
+describe('fixOrphanedToolResults - Gemini', () => {
+    test('returns empty array for empty input', () => {
+        expect(fixOrphanedToolResults([])).toEqual([]);
+    });
+
+    test('keeps a functionResponse that has a matching functionCall in the previous model content', () => {
+        const contents: Content[] = [
+            { role: 'model', parts: [{ functionCall: { name: 'search', args: {} } }] },
+            { role: 'user', parts: [{ functionResponse: { name: 'search', response: { ok: true } } }] },
+        ];
+        expect(fixOrphanedToolResults(contents)).toEqual(contents);
+    });
+
+    test('keeps all responses of a parallel batch when both calls are present', () => {
+        const contents: Content[] = [
+            {
+                role: 'model',
+                parts: [{ functionCall: { name: 'a', args: {} } }, { functionCall: { name: 'b', args: {} } }],
+            },
+            {
+                role: 'user',
+                parts: [
+                    { functionResponse: { name: 'a', response: {} } },
+                    { functionResponse: { name: 'b', response: {} } },
+                ],
+            },
+        ];
+        expect(fixOrphanedToolResults(contents)).toEqual(contents);
+    });
+
+    test('drops a functionResponse whose functionCall is absent from the previous content', () => {
+        const contents: Content[] = [
+            { role: 'model', parts: [{ functionCall: { name: 'a', args: {} } }] },
+            {
+                role: 'user',
+                parts: [
+                    { functionResponse: { name: 'a', response: {} } },
+                    { functionResponse: { name: 'gone', response: {} } },
+                ],
+            },
+        ];
+
+        const result = fixOrphanedToolResults(contents);
+        expect(result[1].parts).toHaveLength(1);
+        expect(result[1].parts?.[0].functionResponse?.name).toBe('a');
+    });
+
+    test('drops a content that becomes empty after removing orphaned responses', () => {
+        const contents: Content[] = [
+            { role: 'user', parts: [{ text: '[summary of prior work]' }] },
+            { role: 'user', parts: [{ functionResponse: { name: 'gone', response: {} } }] },
+        ];
+
+        const result = fixOrphanedToolResults(contents);
+        expect(result).toHaveLength(1);
+        expect(result[0].parts?.[0].text).toBe('[summary of prior work]');
+    });
+
+    test('preserves non-functionResponse parts while dropping the orphan', () => {
+        const contents: Content[] = [
+            { role: 'model', parts: [{ text: 'thinking' }] },
+            {
+                role: 'user',
+                parts: [{ functionResponse: { name: 'gone', response: {} } }, { text: 'continue please' }],
+            },
+        ];
+
+        const result = fixOrphanedToolResults(contents);
+        expect(result[1].parts).toHaveLength(1);
+        expect(result[1].parts?.[0].text).toBe('continue please');
+    });
+});
+
+describe('getGeminiPayload - orphaned tool results', () => {
+    test('retains split parallel functionResponses by merging consecutive user contents before cleanup', () => {
+        const contents: Content[] = [
+            {
+                role: 'model',
+                parts: [{ functionCall: { name: 'a', args: {} } }, { functionCall: { name: 'b', args: {} } }],
+            },
+            { role: 'user', parts: [{ functionResponse: { name: 'a', response: { ok: true } } }] },
+            { role: 'user', parts: [{ functionResponse: { name: 'b', response: { ok: true } } }] },
+        ];
+
+        const payload = getGeminiPayload(OPTIONS_WITH_TOOLS, { contents });
+
+        expect(functionResponseNames(payload.contents as Content[])).toEqual(['a', 'b']);
+    });
+});