@llumiverse/drivers 1.0.0 → 1.1.0-dev.20260427.054520Z

package/src/vertexai/index.ts

@@ -59,6 +59,8 @@ export class VertexAIDriver extends AbstractDriver<VertexAIDriverOptions, Vertex
     anthropicClient: AnthropicVertex | undefined;
     fetchClient: FetchClient | undefined;
     googleGenAI: GoogleGenAI | undefined;
+    googleGenAIRegion: string | undefined;
+    googleGenAIFlex: boolean | undefined;
     llamaClient: FetchClient & { region?: string } | undefined;
     modelGarden: v1beta1.ModelGardenServiceClient | undefined;
     imagenClient: PredictionServiceClient | undefined;
@@ -73,6 +75,8 @@ export class VertexAIDriver extends AbstractDriver<VertexAIDriverOptions, Vertex
         this.anthropicClient = undefined;
         this.fetchClient = undefined
         this.googleGenAI = undefined;
+        this.googleGenAIRegion = undefined;
+        this.googleGenAIFlex = undefined;
         this.modelGarden = undefined;
         this.llamaClient = undefined;
         this.imagenClient = undefined;
@@ -88,32 +92,38 @@ export class VertexAIDriver extends AbstractDriver<VertexAIDriverOptions, Vertex
         return this.authClientPromise;
     }
 
-    public getGoogleGenAIClient(region: string = this.options.region): GoogleGenAI {
-        //Lazy initialization
-        if (region !== this.options.region) {
-            //Get one off client for different region
-            return new GoogleGenAI({
-                project: this.options.project,
-                location: region,
-                vertexai: true,
-                googleAuthOptions: this.options.googleAuthOptions || {
-                    scopes: ["https://www.googleapis.com/auth/cloud-platform"],
-                }
-            });
-        }
-        if (!this.googleGenAI) {
-            this.googleGenAI = new GoogleGenAI({
-                project: this.options.project,
-                location: region,
-                vertexai: true,
-                googleAuthOptions: this.options.googleAuthOptions || {
-                    scopes: ["https://www.googleapis.com/auth/cloud-platform"],
-                }
-            });
+    public getGoogleGenAIClient(region: string = this.options.region, flex: boolean = false): GoogleGenAI {
+        if (this.googleGenAI && 
+            this.googleGenAIRegion === region && 
+            this.googleGenAIFlex === flex) {
+            // Return existing client if region and flex settings match
+            return this.googleGenAI;
         }
+        this.googleGenAI = this.buildGoogleGenAIClient(region, flex);
+        this.googleGenAIRegion = region;
+        this.googleGenAIFlex = flex;
         return this.googleGenAI;
     }
 
+    private buildGoogleGenAIClient(region: string, flex: boolean): GoogleGenAI {
+        return new GoogleGenAI({
+            project: this.options.project,
+            location: region,
+            vertexai: true,
+            googleAuthOptions: this.options.googleAuthOptions || {
+                scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+            },
+            ...(flex ? {
+                httpOptions: {
+                    headers: {
+                        "X-Vertex-AI-LLM-Request-Type": "shared",
+                        "X-Vertex-AI-LLM-Shared-Request-Type": "flex",
+                    }
+                }
+            } : {}),
+        });
+    }
+
     public getFetchClient(): FetchClient {
         //Lazy initialization
         if (!this.fetchClient) {

package/src/vertexai/models/claude-streaming-spacing.test.ts

@@ -0,0 +1,174 @@
+import { ExecutionOptions } from '@llumiverse/core';
+import { describe, expect, it } from 'vitest';
+import { VertexAIDriver } from '../index.js';
+import { ClaudeModelDefinition } from './claude.js';
+
+function createAsyncStream(events: any[]): AsyncIterable<any> {
+    return (async function* () {
+        for (const event of events) {
+            yield event;
+        }
+    })();
+}
+
+async function collectChunks(stream: AsyncIterable<any>) {
+    const chunks: any[] = [];
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+    }
+    return chunks;
+}
+
+describe('ClaudeModelDefinition streaming spacing', () => {
+    it('does not leak deferred spacing when tool use follows thinking', async () => {
+        const modelDef = new ClaudeModelDefinition('claude-sonnet-4-5');
+        const driver = {
+            logger: { warn: () => { }, info: () => { }, error: () => { } },
+            getAnthropicClient: async () => ({
+                messages: {
+                    stream: async () => createAsyncStream([
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'thinking_delta', thinking: 'Thinking...' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'signature_delta' },
+                        },
+                        {
+                            type: 'content_block_start',
+                            content_block: { type: 'tool_use', id: 'tool-1', name: 'get_weather' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'input_json_delta', partial_json: '{"city":"Paris"}' },
+                        },
+                        {
+                            type: 'content_block_stop',
+                        },
+                    ]),
+                },
+            }),
+        } as unknown as VertexAIDriver;
+
+        const prompt = {
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Weather?' }] }],
+        } as any;
+
+        const options = {
+            model: 'publishers/anthropic/models/claude-sonnet-4-5',
+            model_options: {
+                _option_id: 'vertexai-claude',
+                include_thoughts: true,
+            },
+        } as ExecutionOptions;
+
+        const stream = await modelDef.requestTextCompletionStream(driver, prompt, options);
+        const chunks = await collectChunks(stream);
+
+        const textOutput = chunks.flatMap(chunk => chunk.result ?? []).map(part => part.value).join('');
+        const toolChunks = chunks.flatMap(chunk => chunk.tool_use ?? []);
+
+        expect(textOutput).toBe('Thinking...');
+        expect(toolChunks).toHaveLength(2);
+        expect(toolChunks[0]).toMatchObject({ id: 'tool-1', tool_name: 'get_weather', tool_input: '' });
+        expect(toolChunks[1]).toMatchObject({ id: 'tool-1', tool_name: '', tool_input: '{"city":"Paris"}' });
+    });
+
+    it('flushes deferred spacing into the first text delta after thinking', async () => {
+        const modelDef = new ClaudeModelDefinition('claude-sonnet-4-5');
+        const driver = {
+            logger: { warn: () => { }, info: () => { }, error: () => { } },
+            getAnthropicClient: async () => ({
+                messages: {
+                    stream: async () => createAsyncStream([
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'thinking_delta', thinking: 'Thinking...' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'signature_delta' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'text_delta', text: 'Answer' },
+                        },
+                    ]),
+                },
+            }),
+        } as unknown as VertexAIDriver;
+
+        const prompt = {
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Question?' }] }],
+        } as any;
+
+        const options = {
+            model: 'publishers/anthropic/models/claude-sonnet-4-5',
+            model_options: {
+                _option_id: 'vertexai-claude',
+                include_thoughts: true,
+            },
+        } as ExecutionOptions;
+
+        const stream = await modelDef.requestTextCompletionStream(driver, prompt, options);
+        const chunks = await collectChunks(stream);
+
+        const textParts = chunks.flatMap(chunk => chunk.result ?? []).map(part => part.value);
+        expect(textParts).toEqual(['Thinking...', '\n\nAnswer']);
+    });
+
+    it('does not reintroduce deferred spacing when text arrives after a tool call', async () => {
+        const modelDef = new ClaudeModelDefinition('claude-sonnet-4-5');
+        const driver = {
+            logger: { warn: () => { }, info: () => { }, error: () => { } },
+            getAnthropicClient: async () => ({
+                messages: {
+                    stream: async () => createAsyncStream([
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'thinking_delta', thinking: 'Thinking...' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'signature_delta' },
+                        },
+                        {
+                            type: 'content_block_start',
+                            content_block: { type: 'tool_use', id: 'tool-1', name: 'get_weather' },
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'input_json_delta', partial_json: '{"city":"Paris"}' },
+                        },
+                        {
+                            type: 'content_block_stop',
+                        },
+                        {
+                            type: 'content_block_delta',
+                            delta: { type: 'text_delta', text: 'Answer after tool' },
+                        },
+                    ]),
+                },
+            }),
+        } as unknown as VertexAIDriver;
+
+        const prompt = {
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Weather?' }] }],
+        } as any;
+
+        const options = {
+            model: 'publishers/anthropic/models/claude-sonnet-4-5',
+            model_options: {
+                _option_id: 'vertexai-claude',
+                include_thoughts: true,
+            },
+        } as ExecutionOptions;
+
+        const stream = await modelDef.requestTextCompletionStream(driver, prompt, options);
+        const chunks = await collectChunks(stream);
+
+        const textParts = chunks.flatMap(chunk => chunk.result ?? []).map(part => part.value);
+        expect(textParts).toEqual(['Thinking...', 'Answer after tool']);
+    });
+});

package/src/vertexai/models/claude.ts

@@ -15,7 +15,7 @@ import { ContentBlock, ContentBlockParam, DocumentBlockParam, ImageBlockParam, M
 import { MessageStreamParams } from "@anthropic-ai/sdk/resources/index.mjs";
 import { MessageCreateParamsBase, MessageCreateParamsNonStreaming, RawMessageStreamEvent } from "@anthropic-ai/sdk/resources/messages.js";
 import {
-    AIModel, Completion, CompletionChunkObject, ExecutionOptions,
+    AIModel, Completion, CompletionChunkObject, ExecutionOptions, ExecutionTokenUsage,
     getConversationMeta,
     getMaxTokensLimitVertexAi,
     incrementConversationTurn,
@@ -49,6 +49,26 @@ interface ClaudePrompt {
     system?: TextBlockParam[];
 }
 
+interface AnthropicUsageLike {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+}
+
+function anthropicUsageToTokenUsage(usage: AnthropicUsageLike): ExecutionTokenUsage {
+    const cacheRead = usage.cache_read_input_tokens ?? 0;
+    const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+    return {
+        prompt_new: usage.input_tokens,
+        prompt: usage.input_tokens + cacheRead + cacheWrite,
+        result: usage.output_tokens,
+        total: usage.input_tokens + usage.output_tokens + cacheRead + cacheWrite,
+        prompt_cached: usage.cache_read_input_tokens ?? undefined,
+        prompt_cache_write: usage.cache_creation_input_tokens ?? undefined,
+    };
+}
+
 function claudeFinishReason(reason: string | undefined) {
     if (!reason) return undefined;
     switch (reason) {
@@ -332,11 +352,7 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
         return {
             result: text ? [{ type: "text", value: text }] : [{ type: "text", value: '' }],
             tool_use,
-            token_usage: {
-                prompt: result.usage.input_tokens,
-                result: result.usage.output_tokens,
-                total: result.usage.input_tokens + result.usage.output_tokens
-            },
+            token_usage: anthropicUsageToTokenUsage(result.usage),
             // make sure we set finish_reason to the correct value (claude is normally setting this by itself)
             finish_reason: tool_use ? "tool_use" : claudeFinishReason(result?.stop_reason ?? ''),
             conversation: processedConversation
@@ -369,16 +385,16 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
 
         // Track current tool use being built from streaming
         let currentToolUse: { id: string; name: string; inputJson: string } | null = null;
+        // Deferred spacing after a thinking block — emitted only when real text follows,
+        // so it doesn't leak into the output when a tool call comes after thinking.
+        let pendingSpacing = false;
 
         const stream = asyncMap(response_stream, async (streamEvent: RawMessageStreamEvent) => {
             switch (streamEvent.type) {
                 case "message_start":
                     return {
                         result: [{ type: "text", value: '' }],
-                        token_usage: {
-                            prompt: streamEvent.message.usage.input_tokens,
-                            result: streamEvent.message.usage.output_tokens
-                        }
+                        token_usage: anthropicUsageToTokenUsage(streamEvent.message.usage as AnthropicUsageLike),
                     } satisfies CompletionChunkObject;
                 case "message_delta":
                     return {
@@ -415,10 +431,13 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
                 case "content_block_delta":
                     // Handle different delta types
                     switch (streamEvent.delta.type) {
-                        case "text_delta":
+                        case "text_delta": {
+                            const prefix = pendingSpacing ? '\n\n' : '';
+                            pendingSpacing = false;
                             return {
-                                result: streamEvent.delta.text ? [{ type: "text", value: streamEvent.delta.text }] : []
+                                result: streamEvent.delta.text ? [{ type: "text", value: prefix + streamEvent.delta.text }] : []
                             } satisfies CompletionChunkObject;
+                        }
                         case "input_json_delta":
                             // Accumulate tool input JSON
                             if (currentToolUse && streamEvent.delta.partial_json) {
@@ -440,25 +459,20 @@ export class ClaudeModelDefinition implements ModelDefinition<ClaudePrompt> {
                             }
                             break;
                         case "signature_delta":
-                            // Signature deltas, signify the end of the thoughts.
+                            // End of thinking block — defer spacing until real text follows,
+                            // so it doesn't leak when a tool call comes next.
                             if (model_options?.include_thoughts) {
-                                return {
-                                    result: [{ type: "text", value: '\n\n' }], // Double newline for more spacing
-                                } satisfies CompletionChunkObject;
+                                pendingSpacing = true;
                             }
                             break;
                     }
                     break;
                 case "content_block_stop":
-                    // Reset current tool use tracking when block ends
+                    // Reset tool use tracking; spacing is handled via pendingSpacing
                     if (currentToolUse) {
                         currentToolUse = null;
-                    }
-                    // Handle the end of content blocks, for redacted thinking blocks
-                    if (model_options?.include_thoughts) {
-                        return {
-                            result: [{ type: "text", value: '\n\n' }] // Add double newline for spacing
-                        } satisfies CompletionChunkObject;
+                        // Tool call followed thinking — discard any pending spacing so it doesn't leak
+                        pendingSpacing = false;
                     }
                     break;
             }
@@ -707,12 +721,18 @@ export function mergeConsecutiveUserMessages(messages: MessageParam[]): MessageP
  * @param response
  * @returns
  */
-function updateConversation(conversation: ClaudePrompt | undefined | null, prompt: ClaudePrompt): ClaudePrompt {
+export function updateConversation(conversation: ClaudePrompt | undefined | null, prompt: ClaudePrompt): ClaudePrompt {
     const baseSystemMessages = conversation?.system || [];
     const baseMessages = conversation?.messages || [];
     const system = baseSystemMessages.concat(prompt.system || []);
-    // Merge consecutive user messages to ensure tool_result blocks are properly grouped
-    const mergedMessages = mergeConsecutiveUserMessages(baseMessages.concat(prompt.messages || []));
+    // Sanitize first, then merge. Order matters: an empty assistant message (e.g. from interrupted
+    // streaming) between two tool-result user messages acts as a false separator. If merge runs
+    // first, those messages look non-consecutive and fixOrphanedToolUse injects a synthetic result
+    // into the first one; when sanitize later removes the empty assistant, the second user message
+    // ends up with an orphaned tool_result that Vertex AI rejects:
+    // "unexpected tool_use_id found in tool_result blocks".
+    const combined = sanitizeMessages(baseMessages.concat(prompt.messages || []));
+    const mergedMessages = mergeConsecutiveUserMessages(combined);
     return {
         messages: mergedMessages,
         system: system.length > 0 ? system : undefined // If system is empty, set to undefined
@@ -727,7 +747,7 @@ function updateConversation(conversation: ClaudePrompt | undefined | null, promp
  * - Filters out empty text blocks from each message's content
  * - Removes messages entirely if they have no content after filtering
  */
-function sanitizeMessages(messages: MessageParam[]): MessageParam[] {
+export function sanitizeMessages(messages: MessageParam[]): MessageParam[] {
     const result: MessageParam[] = [];
 
     for (const message of messages) {
@@ -852,6 +872,42 @@ interface RequestOptions {
     headers?: Record<string, string>;
 }
 
+type ClaudeTool = NonNullable<MessageCreateParamsBase['tools']>[number];
+
+function stripClaudeCacheControlFromMessages(messages: MessageParam[]): MessageParam[] {
+    return messages.map(message => {
+        if (typeof message.content === 'string') {
+            return message;
+        }
+
+        return {
+            ...message,
+            content: message.content.map(block => stripClaudeCacheControlFromBlock(block)),
+        };
+    });
+}
+
+function stripClaudeCacheControlFromBlock<T extends ContentBlockParam>(block: T): T {
+    const cloned = { ...block } as T & { cache_control?: unknown };
+    delete cloned.cache_control;
+    return cloned as T;
+}
+
+function stripClaudeCacheControlFromSystem(system?: TextBlockParam[]): TextBlockParam[] | undefined {
+    return system?.map(block => {
+        const { cache_control: _cacheControl, ...rest } = block as TextBlockParam & { cache_control?: unknown };
+        return rest as TextBlockParam;
+    });
+}
+
+function stripClaudeCacheControlFromTools(tools?: MessageCreateParamsBase['tools']): MessageCreateParamsBase['tools'] | undefined {
+    return tools?.map(tool => {
+        const cloned = { ...tool } as ClaudeTool & { cache_control?: unknown };
+        delete cloned.cache_control;
+        return cloned as ClaudeTool;
+    });
+}
+
 function getClaudePayload(options: ExecutionOptions, prompt: ClaudePrompt): { payload: MessageCreateParamsBase, requestOptions: RequestOptions | undefined } {
     const modelName = options.model; // Model name is already extracted in the calling methods
     const model_options = options.model_options as VertexAIClaudeOptions;
@@ -888,10 +944,45 @@ function getClaudePayload(options: ExecutionOptions, prompt: ClaudePrompt): { pa
         sanitizedMessages = convertClaudeToolBlocksToText(sanitizedMessages);
     }
 
+    sanitizedMessages = stripClaudeCacheControlFromMessages(sanitizedMessages);
+    const sanitizedSystem = stripClaudeCacheControlFromSystem(prompt.system);
+    const sanitizedTools = hasTools
+        ? stripClaudeCacheControlFromTools(options.tools as MessageCreateParamsBase['tools'])
+        : undefined;
+
+    // Prompt caching: use three breakpoints so stable system prompt, tool definitions,
+    // and the conversation history prefix can all be reused across calls.
+    const cacheEnabled = model_options?.cache_enabled === true;
+    if (cacheEnabled) {
+        const cacheTtl = model_options?.cache_ttl;
+        const cacheControl = { type: 'ephemeral' as const, ...(cacheTtl && { ttl: cacheTtl }) };
+
+        if (sanitizedSystem && sanitizedSystem.length > 0) {
+            const lastSystemBlock = sanitizedSystem[sanitizedSystem.length - 1] as TextBlockParam & { cache_control?: unknown };
+            lastSystemBlock.cache_control = cacheControl;
+        }
+
+        if (sanitizedTools && sanitizedTools.length > 0) {
+            const lastTool = sanitizedTools[sanitizedTools.length - 1] as ClaudeTool & { cache_control?: unknown };
+            lastTool.cache_control = cacheControl;
+        }
+
+        if (sanitizedMessages.length >= 4) {
+            const pivotMsg = sanitizedMessages[sanitizedMessages.length - 2];
+            if (Array.isArray(pivotMsg.content) && pivotMsg.content.length > 0) {
+                const lastBlock = pivotMsg.content[pivotMsg.content.length - 1];
+                if (typeof lastBlock === 'object' && lastBlock !== null &&
+                    'type' in lastBlock && lastBlock.type !== 'thinking' && lastBlock.type !== 'redacted_thinking') {
+                    (lastBlock as TextBlockParam).cache_control = cacheControl;
+                }
+            }
+        }
+    }
+
     const payload = {
         messages: sanitizedMessages,
-        system: prompt.system,
-        tools: hasTools ? options.tools as MessageCreateParamsBase['tools'] : undefined,
+        system: sanitizedSystem,
+        tools: sanitizedTools,
         temperature: model_options?.temperature,
         model: modelName,
         max_tokens: maxToken(options),

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

@@ -0,0 +1,174 @@
+/**
+ * Unit tests for the Gemini conversation mutation bug fix.
+ *
+ * Bug: When tools=[] is passed but the conversation contains functionCall/functionResponse
+ * parts from prior turns, getGeminiPayload() was doing:
+ *
+ *   prompt.contents = convertGeminiFunctionPartsToText(prompt.contents);
+ *
+ * Since prompt.contents is the same object reference as the caller's conversation array,
+ * this permanently corrupted the stored conversation with "[Tool call: ...]" text markers.
+ * On the next turn the model would see those markers in context and echo them as literal output.
+ *
+ * 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 { convertGeminiFunctionPartsToText, GeminiModelDefinition } from './gemini.js';
+
+// ---------------------------------------------------------------------------
+// Pure function tests — no driver needed
+// ---------------------------------------------------------------------------
+
+describe('convertGeminiFunctionPartsToText', () => {
+    it('does not mutate the input array', () => {
+        const original = [
+            {
+                role: 'model',
+                parts: [{ functionCall: { name: 'plan', args: { task: 'write tests' } } }],
+            },
+            {
+                role: 'user',
+                parts: [{ functionResponse: { name: 'plan', response: { output: 'done' } } }],
+            },
+        ];
+        const originalItemRefs = original.map(c => c);
+        const originalPartRefs = original.map(c => c.parts[0]);
+
+        const result = convertGeminiFunctionPartsToText(original);
+
+        // Result must be a different array
+        expect(result).not.toBe(original);
+        // Original items must be unchanged (same references, not mutated)
+        original.forEach((item, i) => {
+            expect(item).toBe(originalItemRefs[i]);
+            expect(item.parts[0]).toBe(originalPartRefs[i]);
+        });
+        // Original functionCall part must still be a functionCall, not text
+        expect(original[0].parts[0]).toHaveProperty('functionCall');
+        expect(original[0].parts[0]).not.toHaveProperty('text');
+        expect(original[1].parts[0]).toHaveProperty('functionResponse');
+        expect(original[1].parts[0]).not.toHaveProperty('text');
+    });
+
+    it('converts functionCall parts to the expected text format', () => {
+        const contents = [
+            {
+                role: 'model',
+                parts: [{ functionCall: { name: 'get_weather', args: { location: 'Paris' } } }],
+            },
+        ];
+
+        const result = convertGeminiFunctionPartsToText(contents);
+
+        expect(result[0].parts![0]).toEqual({
+            text: '[Tool call: get_weather({"location":"Paris"})]',
+        });
+    });
+
+    it('converts functionResponse parts to the expected text format', () => {
+        const contents = [
+            {
+                role: 'user',
+                parts: [{ functionResponse: { name: 'get_weather', response: { temperature: '15°C' } } }],
+            },
+        ];
+
+        const result = convertGeminiFunctionPartsToText(contents);
+
+        expect(result[0].parts![0]).toEqual({
+            text: '[Tool result for get_weather: {"temperature":"15°C"}]',
+        });
+    });
+
+    it('leaves non-function parts intact', () => {
+        const textPart = { text: 'Hello world' };
+        const contents = [{ role: 'user', parts: [textPart] }];
+
+        const result = convertGeminiFunctionPartsToText(contents);
+
+        expect(result[0].parts![0]).toBe(textPart);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Integration-level tests — verify the driver does not mutate the conversation
+// ---------------------------------------------------------------------------
+
+function makeContentsWithFunctionParts() {
+    return [
+        { role: 'model', parts: [{ functionCall: { name: 'plan', args: { task: 'test' } } }] },
+        { role: 'user', parts: [{ functionResponse: { name: 'plan', response: { result: 'ok' } } }] },
+    ];
+}
+
+function makeDriver(overrides: { generateContent?: () => Promise<any>; generateContentStream?: () => Promise<AsyncIterable<any>> }) {
+    return {
+        logger: { warn: () => {}, info: () => {}, error: () => {} },
+        getGoogleGenAIClient: () => ({
+            models: {
+                generateContent: overrides.generateContent ?? (async () => ({})),
+                generateContentStream: overrides.generateContentStream ?? (async () => (async function* () {})()),
+            },
+        }),
+    } as unknown as VertexAIDriver;
+}
+
+const mockNonStreamingResponse = {
+    usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5, totalTokenCount: 15 },
+    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: [],
+    }],
+};
+
+describe('GeminiModelDefinition - no conversation mutation', () => {
+    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 options: ExecutionOptions = { model: 'publishers/google/models/gemini-2.0-flash', tools: [] };
+
+        await modelDef.requestTextCompletion(driver, prompt, options);
+
+        expect(JSON.stringify(originalContents)).toBe(contentsSnapshot);
+        expect(originalContents[0].parts[0]).toHaveProperty('functionCall');
+        expect(originalContents[1].parts[0]).toHaveProperty('functionResponse');
+    });
+
+    it('requestTextCompletionStream: 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({
+            generateContentStream: async () => (async function* () { yield mockStreamingChunk; })(),
+        });
+        const prompt = { contents: originalContents, system: undefined } as any;
+        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 */ }
+
+        expect(JSON.stringify(originalContents)).toBe(contentsSnapshot);
+        expect(originalContents[0].parts[0]).toHaveProperty('functionCall');
+        expect(originalContents[1].parts[0]).toHaveProperty('functionResponse');
+    });
+});