@mate-academy/llm-gateway 8.8.2 → 8.8.4

package/dist/providers/GoogleGenerativeAI/services/GoogleGenerativeAIAssistance.service.js

@@ -0,0 +1,876 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleGenerativeAIAssistanceService = void 0;
+const uuid_1 = require("uuid");
+const genai_1 = require("@google/genai");
+const LLMService_typedefs_1 = require("../../../LLMService.typedefs");
+const serializeError_1 = require("../../../utilities/serializeError");
+const tools_1 = require("../../../utilities/tools");
+const services_1 = require("../../../services");
+const GoogleGenerativeAI_typedefs_1 = require("../../../providers/GoogleGenerativeAI/GoogleGenerativeAI.typedefs");
+const GoogleGenerativeAI_entity_1 = require("../../../providers/GoogleGenerativeAI/GoogleGenerativeAI.entity");
+const GoogleGenerativeAI_constants_1 = require("../../../providers/GoogleGenerativeAI/GoogleGenerativeAI.constants");
+const LLMService_constants_1 = require("../../../LLMService.constants");
+class GoogleGenerativeAIAssistanceService extends services_1.LLMAssistanceService {
+    cachedContent = new Map();
+    chatSessions = new Map();
+    uploadedFiles = new Map();
+    uncachedFileStorages = new Map();
+    chatInstructions = new Map(); // chatId -> instructions
+    constructor(logger, reporter, options) {
+        super(LLMService_typedefs_1.LLMProviders.GoogleGenerativeAI, logger, reporter, options);
+    }
+    get instance() {
+        return this.getOrCreateInstance(() => new genai_1.GoogleGenAI(this.options ?? {}));
+    }
+    async uploadFile(fileOptions) {
+        const { path, mimeType, name, abortSignal, reporterContext, } = fileOptions;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            const existingFile = await this.getFile(path);
+            if (existingFile) {
+                return existingFile;
+            }
+            abortSignal?.throwIfAborted();
+            const uploadResult = await this.instance.files.upload({
+                file: path,
+                config: {
+                    mimeType,
+                    displayName: name,
+                    abortSignal,
+                },
+            });
+            abortSignal?.throwIfAborted();
+            if (!uploadResult.name) {
+                throw new Error('Upload result did not return a name');
+            }
+            if (!uploadResult.uri) {
+                throw new Error('Upload result did not return a uri');
+            }
+            if (uploadResult.error) {
+                throw uploadResult.error;
+            }
+            const uploadedFile = {
+                name,
+                mimeType,
+                fileId: uploadResult.name,
+                path: uploadResult.uri,
+            };
+            abortSignal?.throwIfAborted();
+            this.uploadedFiles.set(path, uploadedFile);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                usage: {},
+                writeMetrics,
+            });
+            return uploadedFile;
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.uploadFile),
+                message: 'Error uploading file',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { file: fileOptions },
+            });
+            return { error };
+        }
+    }
+    async getFile(path) {
+        return this.uploadedFiles.get(path) || null;
+    }
+    async deleteFile(fileId) {
+        this.uploadedFiles.delete(fileId);
+        await this.instance.files.delete({
+            name: fileId,
+        });
+    }
+    async createFileStorage(options) {
+        const { uploadedFiles, model, instructions, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const parts = GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getFileDataParts(uploadedFiles);
+            const countTokensFn = GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity
+                .getCountTokensFn(this.instance);
+            const tokenCount = await countTokensFn(parts, model);
+            abortSignal?.throwIfAborted();
+            if (tokenCount < GoogleGenerativeAI_constants_1.MIN_CACHE_CONTENT_LENGTH) {
+                /**
+                 * Note: For small files that can't be cached, store them in uncachedFileStorages
+                 * to be used directly in chat creation
+                 */
+                const storageId = (0, uuid_1.v4)();
+                this.uncachedFileStorages.set(storageId, uploadedFiles);
+                this.logger
+                    ?.child(this.getMethodName(this.createFileStorage))
+                    .info('File storage created without caching (content too small)', {
+                    storageId,
+                    tokenCount,
+                    minRequired: GoogleGenerativeAI_constants_1.MIN_CACHE_CONTENT_LENGTH,
+                });
+                abortSignal?.throwIfAborted();
+                await this.writeSuccessMetrics({
+                    method: this.getMethodName(this.createFileStorage),
+                    model,
+                    usage: {},
+                    writeMetrics,
+                });
+                return {
+                    storageId,
+                };
+            }
+            const cacheResult = await this.instance.caches.create({
+                model: model.name,
+                config: {
+                    contents: [
+                        {
+                            role: GoogleGenerativeAI_typedefs_1.GoogleGenerativeAIRoles.User,
+                            parts,
+                        },
+                    ],
+                    systemInstruction: instructions,
+                    ttl: '1h',
+                    abortSignal,
+                },
+            });
+            abortSignal?.throwIfAborted();
+            if (!cacheResult.name) {
+                throw new Error('Cache result did not return a name');
+            }
+            if (abortSignal?.aborted) {
+                throw new Error('File storage creation aborted');
+            }
+            abortSignal?.throwIfAborted();
+            this.cachedContent.set(cacheResult.name, cacheResult);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model,
+                usage: {},
+                writeMetrics,
+            });
+            return {
+                storageId: cacheResult.name,
+            };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.createFileStorage),
+                message: 'Error creating file storage',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { uploadedFiles, model },
+            });
+            return { error };
+        }
+    }
+    async deleteFileStorage(fileStorageId) {
+        if (fileStorageId === '') {
+            return;
+        }
+        const cachedContent = this.cachedContent.get(fileStorageId);
+        if (cachedContent) {
+            this.cachedContent.delete(fileStorageId);
+            await this.instance.caches.delete({
+                name: fileStorageId,
+            });
+        }
+        this.uncachedFileStorages.delete(fileStorageId);
+    }
+    async createChat(options) {
+        const { storageId, model, instructions, history: providedHistory, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            const cachedContent = storageId
+                ? this.cachedContent.get(storageId)
+                : undefined;
+            const uncachedFiles = storageId
+                ? this.uncachedFileStorages.get(storageId)
+                : undefined;
+            abortSignal?.throwIfAborted();
+            const history = providedHistory
+                ? await Promise.all(providedHistory.map((message) => (GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getContent(message, this.instance, this.logger))))
+                : [];
+            abortSignal?.throwIfAborted();
+            if (!cachedContent && uncachedFiles) {
+                const fileParts = GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getFileDataParts(uncachedFiles);
+                history.push({
+                    role: GoogleGenerativeAI_typedefs_1.GoogleGenerativeAIRoles.User,
+                    parts: fileParts,
+                });
+            }
+            const chatId = (0, uuid_1.v4)();
+            if (instructions) {
+                this.chatInstructions.set(chatId, instructions);
+            }
+            const chatSession = this.instance.chats.create({
+                model: model.name,
+                history,
+                config: {
+                    systemInstruction: instructions,
+                    temperature: model.config.temperature,
+                    abortSignal,
+                    ...(cachedContent && { cachedContent: cachedContent.name }),
+                },
+            });
+            abortSignal?.throwIfAborted();
+            this.chatSessions.set(chatId, chatSession);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                usage: {},
+                writeMetrics,
+            });
+            return Promise.resolve({ chatId });
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.createChat),
+                message: 'Error creating chat',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return Promise.resolve({ error });
+        }
+    }
+    deleteChat(chatId) {
+        this.chatSessions.delete(chatId);
+        this.chatInstructions.delete(chatId);
+        return Promise.resolve();
+    }
+    getStorageFileParts(storageId) {
+        if (!storageId) {
+            return [];
+        }
+        const uncachedFiles = this.uncachedFileStorages.get(storageId);
+        if (!uncachedFiles) {
+            return [];
+        }
+        return GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getFileDataParts(uncachedFiles);
+    }
+    async assistInChatText(options) {
+        const { model, reporterContext, abortSignal, traceContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        const method = this.getMethodName(this.assistInChatText);
+        const generationStartedAt = Date.now();
+        const rounds = this.openAgentRounds({
+            method,
+            model,
+            traceContext,
+            modelParameters: model.config,
+        });
+        try {
+            const { chatSession, messageParts, sendMessageConfig, } = await this.prepareChatMessage({
+                chatId: options.chatId,
+                message: options.message,
+                storageId: options.storageId,
+                tools: options.tools,
+                abortSignal,
+            });
+            const chatResponse = await rounds.run({
+                input: this.buildRoundConversation({
+                    chatSession,
+                    chatId: options.chatId,
+                    outgoingParts: messageParts,
+                }),
+                call: () => chatSession.sendMessage({
+                    message: messageParts,
+                    config: sendMessageConfig,
+                }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            abortSignal?.throwIfAborted();
+            const toolLoopResult = await this.executeGoogleToolLoop({
+                chatSession,
+                chatId: options.chatId,
+                response: chatResponse,
+                tools: options.tools ?? [],
+                maxIterations: options.maxToolIterations
+                    ?? LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS,
+                abortSignal,
+                config: sendMessageConfig,
+                multimodalToolResults: model.capabilities?.multimodalToolResults === true,
+                rounds,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            const responseText = toolLoopResult.response.text ?? '';
+            const { totalUsage } = toolLoopResult;
+            await this.writeSuccessMetrics({
+                method,
+                model,
+                usage: this.buildUsageMetrics(totalUsage),
+                writeMetrics,
+            });
+            return {
+                text: responseText,
+                toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                ...(toolLoopResult.toolIterationsExhausted && {
+                    toolIterationsExhausted: true,
+                }),
+                stopReason: toolLoopResult.stopReason,
+                ...(toolLoopResult.terminalTool && {
+                    terminalTool: toolLoopResult.terminalTool,
+                }),
+            };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method,
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+                error,
+                generationTrace: this.buildUnstartedRunTrace({
+                    rounds,
+                    method,
+                    traceContext,
+                    input: options.message,
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            this.logRequestFailure({
+                method,
+                message: 'Error assisting in chat',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return { error };
+        }
+    }
+    async assistInChatStructured(options) {
+        const { model, abortSignal, schema, reporterContext, traceContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        const method = this.getMethodName(this.assistInChatStructured);
+        const generationStartedAt = Date.now();
+        const rounds = this.openAgentRounds({
+            method,
+            model,
+            traceContext,
+            modelParameters: model.config,
+        });
+        try {
+            const googleSchema = schema._toProviderSchema(LLMService_typedefs_1.LLMProviders.GoogleGenerativeAI);
+            const { chatSession, messageParts, sendMessageConfig, } = await this.prepareChatMessage({
+                chatId: options.chatId,
+                message: options.message,
+                storageId: options.storageId,
+                tools: options.tools,
+                abortSignal,
+                structuredConfig: {
+                    ...(!options.tools?.length && {
+                        responseMimeType: 'application/json',
+                    }),
+                    responseSchema: googleSchema,
+                },
+            });
+            const chatResponse = await rounds.run({
+                input: this.buildRoundConversation({
+                    chatSession,
+                    chatId: options.chatId,
+                    outgoingParts: messageParts,
+                }),
+                call: () => chatSession.sendMessage({
+                    message: messageParts,
+                    config: sendMessageConfig,
+                }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            abortSignal?.throwIfAborted();
+            const toolLoopResult = await this.executeGoogleToolLoop({
+                chatSession,
+                chatId: options.chatId,
+                response: chatResponse,
+                tools: options.tools ?? [],
+                maxIterations: options.maxToolIterations
+                    ?? LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS,
+                abortSignal,
+                config: sendMessageConfig,
+                multimodalToolResults: model.capabilities?.multimodalToolResults === true,
+                rounds,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            if (toolLoopResult.terminalTool) {
+                await this.writeSuccessMetrics({
+                    method: this.getMethodName(this.assistInChatStructured),
+                    model,
+                    usage: this.buildUsageMetrics(toolLoopResult.totalUsage),
+                    writeMetrics,
+                });
+                return {
+                    text: toolLoopResult.response.text ?? '',
+                    toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                    stopReason: toolLoopResult.stopReason,
+                    terminalTool: toolLoopResult.terminalTool,
+                };
+            }
+            let finalResponseText;
+            let totalUsage = toolLoopResult.totalUsage;
+            if (options.tools?.length) {
+                const structuredFollowUp = await this.sendStructuredFollowUp({
+                    chatSession,
+                    chatId: options.chatId,
+                    googleSchema,
+                    abortSignal,
+                    rounds,
+                });
+                finalResponseText =
+                    structuredFollowUp.text;
+                totalUsage =
+                    this.combineUsage(totalUsage, structuredFollowUp.usage);
+            }
+            else {
+                finalResponseText =
+                    toolLoopResult.response.text ?? '';
+            }
+            if (!finalResponseText) {
+                throw new Error('Empty response from Google'
+                    + ' Generative AI Assistant');
+            }
+            try {
+                const parsed = JSON.parse(finalResponseText);
+                const validation = schema._parse(parsed);
+                await this.writeSuccessMetrics({
+                    method,
+                    model,
+                    usage: this.buildUsageMetrics(totalUsage),
+                    writeMetrics,
+                });
+                const structuredFollowUpRoundTrips = options.tools?.length ? 1 : 0;
+                return {
+                    text: finalResponseText,
+                    data: validation.data,
+                    parseError: validation.error,
+                    toolIterationsUsed: toolLoopResult.toolIterationsUsed
+                        + structuredFollowUpRoundTrips,
+                    ...(toolLoopResult.toolIterationsExhausted && {
+                        toolIterationsExhausted: true,
+                    }),
+                    stopReason: toolLoopResult.stopReason,
+                };
+            }
+            catch (parseError) {
+                this.logger
+                    ?.child(this.getMethodName(this.assistInChatStructured))
+                    .warn('Failed to parse JSON response', {
+                    content: finalResponseText,
+                    parseError: parseError.message,
+                });
+                throw parseError;
+            }
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method,
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+                error,
+                generationTrace: this.buildUnstartedRunTrace({
+                    rounds,
+                    method,
+                    traceContext,
+                    input: options.message,
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            this.logRequestFailure({
+                method,
+                message: 'Error assisting in chat with structured output',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return {
+                text: '',
+                error,
+                parseError: 'Failed to get structured response'
+                    + ' from Google Generative'
+                    + ' AI Assistant',
+            };
+        }
+    }
+    async prepareChatMessage(options) {
+        const chatSession = this.chatSessions.get(options.chatId);
+        if (!chatSession) {
+            throw new Error('Chat session not found');
+        }
+        options.abortSignal?.throwIfAborted();
+        const messageContent = await GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getContent(options.message, this.instance, this.logger);
+        options.abortSignal?.throwIfAborted();
+        if (!messageContent.parts) {
+            throw new Error('No message parts available');
+        }
+        const storageFileParts = this.getStorageFileParts(options.storageId);
+        if (options.tools?.length) {
+            this.validateToolDefinitions(options.tools);
+        }
+        const googleTools = options.tools?.length
+            ? this.convertCustomToolsToGoogle(options.tools)
+            : undefined;
+        const sendMessageConfig = {
+            systemInstruction: this.chatInstructions.get(options.chatId),
+            abortSignal: options.abortSignal,
+            ...(googleTools && {
+                tools: googleTools,
+            }),
+            ...options.structuredConfig,
+        };
+        return {
+            chatSession,
+            messageParts: [
+                ...storageFileParts,
+                ...messageContent.parts,
+            ],
+            sendMessageConfig,
+        };
+    }
+    async sendStructuredFollowUp(params) {
+        const structuredConfig = {
+            systemInstruction: this.chatInstructions.get(params.chatId),
+            responseMimeType: 'application/json',
+            responseSchema: params.googleSchema,
+            abortSignal: params.abortSignal,
+        };
+        const followUpParts = [
+            {
+                text: 'Now respond with the structured'
+                    + ' JSON output based on the'
+                    + ' information gathered.',
+            },
+        ];
+        const structuredResponse = await params.rounds.run({
+            input: this.buildRoundConversation({
+                chatSession: params.chatSession,
+                chatId: params.chatId,
+                outgoingParts: followUpParts,
+            }),
+            call: () => params.chatSession.sendMessage({
+                message: followUpParts,
+                config: structuredConfig,
+            }),
+            describeOutcome: this.buildRoundOutcome,
+        });
+        return {
+            text: structuredResponse.text ?? '',
+            usage: this.extractUsageFromResponse(structuredResponse),
+        };
+    }
+    /**
+     * The conversation one round was sent with: the chat's system instruction,
+     * the history the SDK holds for the session, and the parts this round adds.
+     * Built before the request goes out so a round that throws traces the same
+     * transcript a successful one does.
+     */
+    buildRoundConversation(params) {
+        const instructions = this.chatInstructions.get(params.chatId);
+        return [
+            ...(instructions
+                ? [{
+                        role: 'system',
+                        parts: [{ text: instructions }],
+                    }]
+                : []),
+            ...params.chatSession.getHistory(),
+            {
+                role: GoogleGenerativeAI_typedefs_1.GoogleGenerativeAIRoles.User,
+                parts: params.outgoingParts,
+            },
+        ];
+    }
+    /**
+     * One round's usage, mapped exactly as the run total is mapped for metrics,
+     * so the per-round generations add up to the single metrics point the run
+     * still writes.
+     */
+    buildUsageMetrics(usage) {
+        return {
+            inputTextTokens: usage.promptTokens - usage.cachedTokens,
+            inputCachedTextTokens: usage.cachedTokens,
+            outputTextTokens: usage.candidatesTokens,
+        };
+    }
+    buildRoundOutcome = (response) => ({
+        output: response.candidates?.[0]?.content,
+        usage: this.buildUsageMetrics(this.extractUsageFromResponse(response)),
+    });
+    extractUsageFromResponse(response) {
+        return {
+            promptTokens: response.usageMetadata
+                ?.promptTokenCount ?? 0,
+            cachedTokens: response.usageMetadata
+                ?.cachedContentTokenCount ?? 0,
+            candidatesTokens: response.usageMetadata
+                ?.candidatesTokenCount ?? 0,
+        };
+    }
+    combineUsage(first, second) {
+        return {
+            promptTokens: first.promptTokens
+                + second.promptTokens,
+            cachedTokens: first.cachedTokens
+                + second.cachedTokens,
+            candidatesTokens: first.candidatesTokens
+                + second.candidatesTokens,
+        };
+    }
+    convertCustomToolsToGoogle(tools) {
+        const functionDeclarations = tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters._toProviderSchema(LLMService_typedefs_1.LLMProviders.GoogleGenerativeAI),
+        }));
+        return [{ functionDeclarations }];
+    }
+    async executeGoogleToolLoop(params) {
+        const { chatSession, chatId, tools, maxIterations, abortSignal, config, multimodalToolResults, rounds, onAssistantNarration, } = params;
+        let currentResponse = params.response;
+        const totalUsage = this.extractUsageFromResponse(currentResponse);
+        let toolIterationsUsed = 1;
+        let terminalTool;
+        for (let iteration = 0; iteration < maxIterations; iteration++) {
+            const functionCallParts = (currentResponse.candidates?.[0]
+                ?.content?.parts ?? []).filter((part) => part.functionCall?.name);
+            if (functionCallParts.length === 0) {
+                break;
+            }
+            if (onAssistantNarration) {
+                onAssistantNarration(this.extractVisibleToolRoundText(currentResponse));
+            }
+            abortSignal?.throwIfAborted();
+            const calls = functionCallParts.map((part) => ({
+                name: part.functionCall?.name ?? '',
+                args: (part.functionCall?.args ?? {}),
+            }));
+            const executedCalls = await this.executeGoogleFunctionCalls(calls, tools);
+            const terminalCall = executedCalls.find((executed) => executed.isTerminal);
+            if (terminalCall) {
+                abortSignal?.throwIfAborted();
+                terminalTool = {
+                    name: terminalCall.name,
+                    output: terminalCall.output,
+                };
+                break;
+            }
+            const functionResponseParts = await this.buildFunctionResponseParts(executedCalls, multimodalToolResults);
+            abortSignal?.throwIfAborted();
+            currentResponse = await rounds.run({
+                input: this.buildRoundConversation({
+                    chatSession,
+                    chatId,
+                    outgoingParts: functionResponseParts,
+                }),
+                call: () => chatSession.sendMessage({
+                    message: functionResponseParts,
+                    config,
+                }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            toolIterationsUsed += 1;
+            const iterationUsage = this.extractUsageFromResponse(currentResponse);
+            totalUsage.promptTokens +=
+                iterationUsage.promptTokens;
+            totalUsage.cachedTokens +=
+                iterationUsage.cachedTokens;
+            totalUsage.candidatesTokens +=
+                iterationUsage.candidatesTokens;
+        }
+        const toolIterationsExhausted = !terminalTool && (currentResponse.candidates?.[0]
+            ?.content?.parts ?? []).some((part) => part.functionCall?.name);
+        if (toolIterationsExhausted) {
+            this.logger
+                ?.child(this.getMethodName(this.executeGoogleToolLoop))
+                .warn('Tool loop reached maxToolIterations', {
+                maxToolIterations: maxIterations,
+                toolIterationsUsed,
+            });
+        }
+        return {
+            response: currentResponse,
+            totalUsage,
+            toolIterationsUsed,
+            toolIterationsExhausted,
+            stopReason: this.resolveToolLoopStopReason({
+                terminalTool,
+                toolIterationsExhausted,
+            }),
+            terminalTool,
+        };
+    }
+    /**
+     * The visible assistant text a continuing tool-loop round produced, joined
+     * from the response's text parts. Thinking parts (`part.thought`) are
+     * excluded so only the visible narration channel is surfaced.
+     */
+    extractVisibleToolRoundText(response) {
+        return (response.candidates?.[0]?.content?.parts ?? [])
+            .filter((part) => typeof part.text === 'string' && part.thought !== true)
+            .map((part) => part.text)
+            .join('');
+    }
+    executeGoogleFunctionCalls(calls, tools) {
+        return Promise.all(calls.map((call) => this.executeSingleGoogleFunctionCall(call, tools)));
+    }
+    async buildFunctionResponseParts(executedCalls, multimodalToolResults) {
+        if (multimodalToolResults) {
+            return Promise.all(executedCalls.map((executedCall) => this.buildNativeFunctionResponsePart(executedCall)));
+        }
+        return this.buildAppendedFunctionResponseParts(executedCalls);
+    }
+    async executeSingleGoogleFunctionCall(call, tools) {
+        const matchingTool = tools.find((tool) => tool.name === call.name);
+        if (!matchingTool) {
+            const unknownToolMessage = `Error: Unknown tool "${call.name}"`;
+            return {
+                name: call.name,
+                result: {
+                    content: unknownToolMessage,
+                    images: [],
+                },
+                output: unknownToolMessage,
+                isTerminal: false,
+            };
+        }
+        const isTerminal = matchingTool.terminal === true;
+        try {
+            const rawResult = await this.getTracer().withToolObservation(`${this.serviceName}/tool:${call.name}`, call.args, () => Promise.resolve(matchingTool.execute(call.args)));
+            return {
+                name: call.name,
+                result: (0, tools_1.normalizeToolResult)(rawResult),
+                output: rawResult,
+                isTerminal,
+            };
+        }
+        catch (executionError) {
+            const message = executionError instanceof Error
+                ? executionError.message
+                : String(executionError);
+            this.logger
+                ?.child(this.getMethodName(this.executeSingleGoogleFunctionCall))
+                .error('Tool execution failed', {
+                toolName: call.name,
+                error: (0, serializeError_1.serializeError)(executionError),
+            });
+            const failureMessage = `Error: ${message}`;
+            return {
+                name: call.name,
+                result: {
+                    content: failureMessage,
+                    images: [],
+                },
+                output: failureMessage,
+                isTerminal,
+            };
+        }
+    }
+    /**
+     * Gemini 3 models accept image bytes inside `functionResponse.parts`. Each
+     * image blob carries a unique `displayName` the `response` payload then
+     * references via `{ $ref: displayName }`.
+     */
+    async buildNativeFunctionResponsePart(executedCall) {
+        const { name, result } = executedCall;
+        if (result.images.length === 0) {
+            return {
+                functionResponse: {
+                    name,
+                    response: { result: result.content },
+                },
+            };
+        }
+        const imageBlobs = await Promise.all(result.images.map((image, index) => this.fetchToolImageBlob(image, `${name}_image_${index + 1}`)));
+        return {
+            functionResponse: {
+                name,
+                response: {
+                    result: result.content,
+                    images: imageBlobs.map((blob) => ({
+                        ...(blob.label && { label: blob.label }),
+                        $ref: blob.displayName,
+                    })),
+                },
+                parts: imageBlobs.map((blob) => ({
+                    inlineData: {
+                        mimeType: blob.mimeType,
+                        data: blob.data,
+                        displayName: blob.displayName,
+                    },
+                })),
+            },
+        };
+    }
+    /**
+     * Gemini 2.5 models cannot carry images in a function response, so image
+     * bytes are appended as sibling user-content parts after every function
+     * response in the same message.
+     */
+    async buildAppendedFunctionResponseParts(executedCalls) {
+        const functionResponseParts = executedCalls.map(({ name, result }) => ({
+            functionResponse: {
+                name,
+                response: { result: result.content },
+            },
+        }));
+        const images = executedCalls.flatMap(({ result }) => result.images);
+        const imageParts = await Promise.all(images.map((image) => this.buildInlineImageParts(image)));
+        return [
+            ...functionResponseParts,
+            ...imageParts.flat(),
+        ];
+    }
+    async buildInlineImageParts(image) {
+        const blob = await this.fetchToolImageBlob(image);
+        const imagePart = {
+            inlineData: {
+                mimeType: blob.mimeType,
+                data: blob.data,
+            },
+        };
+        if (!blob.label) {
+            return [imagePart];
+        }
+        return [{ text: blob.label }, imagePart];
+    }
+    async fetchToolImageBlob(image, displayName) {
+        const response = await fetch(image.url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch tool image (${response.status}`
+                + ` ${response.statusText}): ${image.url}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return {
+            mimeType: image.mimeType ?? 'image/png',
+            data: Buffer.from(arrayBuffer).toString('base64'),
+            displayName,
+            label: image.label,
+        };
+    }
+    async countTokens(messages, model) {
+        const countTokensFn = GoogleGenerativeAI_entity_1.GoogleGenerativeAIEntity.getCountTokensFn(this.instance);
+        return countTokensFn(messages, model);
+    }
+}
+exports.GoogleGenerativeAIAssistanceService = GoogleGenerativeAIAssistanceService;
+//# sourceMappingURL=GoogleGenerativeAIAssistance.service.js.map