@mate-academy/llm-gateway 8.8.2 → 8.8.4

package/dist/providers/LLMAPI/services/LLMAPIAssistance.service.js

@@ -0,0 +1,825 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAPIAssistanceService = void 0;
+const openai_1 = require("openai");
+const uuid_1 = require("uuid");
+const LLMService_typedefs_1 = require("../../../LLMService.typedefs");
+const LLMService_constants_1 = require("../../../LLMService.constants");
+const serializeError_1 = require("../../../utilities/serializeError");
+const services_1 = require("../../../services");
+const tools_1 = require("../../../utilities/tools");
+const LLMAPI_typedefs_1 = require("../../../providers/LLMAPI/LLMAPI.typedefs");
+const LLMAPI_entity_1 = require("../../../providers/LLMAPI/LLMAPI.entity");
+const utilities_1 = require("../../../providers/LLMAPI/utilities");
+const OpenAI_entity_1 = require("../../../providers/OpenAI/OpenAI.entity");
+const fileStorage_1 = require("../../../services/fileStorage");
+const chatState_1 = require("../../../services/chatState");
+const FILE_STORAGE_TOOL_NAMES = Object.values(fileStorage_1.FileStorageToolName);
+const GEMINI_THOUGHT_SIGNATURE_VALIDATOR_BYPASS = 'skip_thought_signature_validator';
+class LLMAPIAssistanceService extends services_1.LLMAssistanceService {
+    fileStorage = new fileStorage_1.InMemoryFileStorage();
+    chatState = new chatState_1.CompletionsChatState();
+    toolExecutor = new fileStorage_1.FileStorageToolExecutor(this.fileStorage);
+    fileContextInjectedChats = new Set();
+    constructor(logger, reporter, options) {
+        super(LLMService_typedefs_1.LLMProviders.LLMAPI, logger, reporter, options);
+    }
+    get instance() {
+        return this.getOrCreateInstance(() => new openai_1.OpenAI({
+            ...this.options,
+            baseURL: LLMAPI_typedefs_1.LLMAPI_BASE_URL,
+        }));
+    }
+    async uploadFile(fileOptions) {
+        const { path, name, mimeType, abortSignal, reporterContext, } = fileOptions;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const existingFile = this.fileStorage.getFileByPath(path);
+            if (existingFile) {
+                await this.writeSuccessMetrics({
+                    method: this.getMethodName(this.uploadFile),
+                    model: null,
+                    usage: {},
+                    writeMetrics,
+                });
+                return {
+                    fileId: existingFile.fileId,
+                    name: existingFile.name,
+                    path: existingFile.path,
+                    mimeType: existingFile.mimeType,
+                };
+            }
+            const storedFile = this.fileStorage.addFile(path, name, mimeType);
+            const uploadedFileInfo = {
+                fileId: storedFile.fileId,
+                name: storedFile.name,
+                path: storedFile.path,
+                mimeType: storedFile.mimeType,
+            };
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                usage: {},
+                writeMetrics,
+            });
+            return uploadedFileInfo;
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                writeMetrics,
+            });
+            this.logger?.child(this.getMethodName(this.uploadFile))
+                .error('Error uploading file', {
+                error: (0, serializeError_1.serializeError)(error),
+                file: fileOptions,
+            });
+            return {
+                error: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+            };
+        }
+    }
+    async getFile(path) {
+        const storedFile = this.fileStorage.getFileByPath(path);
+        if (!storedFile) {
+            return null;
+        }
+        return {
+            fileId: storedFile.fileId,
+            name: storedFile.name,
+            path: storedFile.path,
+            mimeType: storedFile.mimeType,
+        };
+    }
+    async deleteFile(fileId) {
+        this.fileStorage.removeFile(fileId);
+    }
+    async createFileStorage(options) {
+        const { uploadedFiles, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const storageId = this.fileStorage.createStorage(uploadedFiles.map((file) => file.fileId));
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model: null,
+                usage: {},
+                writeMetrics,
+            });
+            return { storageId };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model: null,
+                writeMetrics,
+            });
+            this.logger?.child(this.getMethodName(this.createFileStorage))
+                .error('Error creating file storage', {
+                error: (0, serializeError_1.serializeError)(error),
+                uploadedFiles,
+            });
+            return {
+                error: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+            };
+        }
+    }
+    async deleteFileStorage(storageId) {
+        this.fileStorage.removeStorage(storageId);
+    }
+    async createChat(options) {
+        const { model, instructions, history = [], storageId, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const chatId = (0, uuid_1.v4)();
+            const convertedHistory = LLMAPI_entity_1.LLMAPIEntity
+                .convertAssistanceHistoryToCompletions(history);
+            this.chatState.createChat(chatId, instructions, storageId, convertedHistory);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                usage: {},
+                writeMetrics,
+            });
+            return { chatId };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                writeMetrics,
+            });
+            this.logger?.child(this.getMethodName(this.createChat))
+                .error('Error creating chat', {
+                error: (0, serializeError_1.serializeError)(error),
+                options,
+            });
+            return {
+                error: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+            };
+        }
+    }
+    async deleteChat(chatId) {
+        this.chatState.deleteChat(chatId);
+        this.fileContextInjectedChats.delete(chatId);
+    }
+    async countTokens(messages) {
+        const countTokensFn = OpenAI_entity_1.OpenAIEntity.getCountTokensFn();
+        const messageContents = messages.flatMap((message) => message.content);
+        return countTokensFn(messageContents);
+    }
+    async assistInChatText(options) {
+        const { model, chatId, abortSignal, reporterContext, tools: customTools, maxToolIterations = LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS, 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 { storageId, tools, } = this.prepareChatForAssist(options);
+            const toolLoopResult = await this.executeToolLoop({
+                chatId,
+                model,
+                tools,
+                storageId,
+                customTools,
+                maxToolIterations,
+                abortSignal,
+                rounds,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            const text = toolLoopResult.text;
+            this.chatState.appendAssistantMessage(chatId, text);
+            await this.writeSuccessMetrics({
+                method,
+                model,
+                usage: this.buildToolLoopUsage(toolLoopResult),
+                writeMetrics,
+            });
+            return {
+                text,
+                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: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+            };
+        }
+    }
+    async assistInChatStructured(options) {
+        const { model, chatId, abortSignal, schema, reporterContext, tools: customTools, maxToolIterations = LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS, 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 { storageId, tools } = this.prepareChatForAssist(options);
+            const jsonSchema = schema._toProviderSchema(LLMService_typedefs_1.LLMProviders.LLMAPI);
+            const supportsStructuredOutputs = model.capabilities?.structuredOutputs === true;
+            const schemaRestore = supportsStructuredOutputs
+                ? undefined
+                : this.injectSchemaInstruction(chatId, jsonSchema);
+            const responseFormat = (0, utilities_1.buildLLMAPIResponseFormat)(model, jsonSchema);
+            const toolLoopResult = await this.executeToolLoop({
+                chatId,
+                model,
+                tools,
+                storageId,
+                customTools,
+                maxToolIterations,
+                abortSignal,
+                responseFormat,
+                rounds,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            const text = (0, utilities_1.stripThinkingTags)(toolLoopResult.text);
+            schemaRestore?.();
+            this.chatState.appendAssistantMessage(chatId, text);
+            const usage = this.buildToolLoopUsage(toolLoopResult);
+            if (toolLoopResult.terminalTool) {
+                await this.writeSuccessMetrics({
+                    method,
+                    model,
+                    usage,
+                    writeMetrics,
+                });
+                return {
+                    text,
+                    toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                    stopReason: toolLoopResult.stopReason,
+                    terminalTool: toolLoopResult.terminalTool,
+                };
+            }
+            const structuredResult = (0, utilities_1.validateStructuredResponse)({
+                content: text,
+                schema,
+                usage,
+            });
+            if ('parseError' in structuredResult) {
+                await this.writeErrorMetrics({
+                    method: this.getMethodName(this.assistInChatStructured),
+                    model,
+                    isAborted: abortSignal?.aborted,
+                    writeMetrics,
+                });
+                return structuredResult;
+            }
+            await this.writeSuccessMetrics({
+                method,
+                model,
+                usage,
+                writeMetrics,
+            });
+            if ('error' in structuredResult) {
+                return structuredResult;
+            }
+            return {
+                ...structuredResult,
+                toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                ...(toolLoopResult.toolIterationsExhausted && {
+                    toolIterationsExhausted: true,
+                }),
+                stopReason: toolLoopResult.stopReason,
+            };
+        }
+        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: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+                parseError: 'Failed to get structured response'
+                    + ' from LLMAPI',
+            };
+        }
+    }
+    prepareChatForAssist(options) {
+        const { chatId, message, storageId: optionsStorageId, tools: customTools, } = options;
+        const chat = this.chatState.getChat(chatId);
+        if (!chat) {
+            throw new Error('Chat session not found');
+        }
+        const storageId = chat.storageId ?? optionsStorageId;
+        this.appendUserMessageToChat(chatId, message);
+        this.injectFileContext(chatId, storageId);
+        const tools = this.buildToolsArray(storageId, customTools);
+        return { storageId, tools };
+    }
+    appendUserMessageToChat(chatId, message) {
+        const convertedMessage = LLMAPI_entity_1.LLMAPIEntity
+            .convertAssistanceMessageToCompletion(message);
+        const content = convertedMessage.content;
+        if (typeof content === 'string') {
+            this.chatState.appendUserMessage(chatId, [{ type: 'text', text: content }]);
+            return;
+        }
+        if (Array.isArray(content)) {
+            this.chatState.appendUserMessage(chatId, content);
+            return;
+        }
+        this.chatState.appendUserMessage(chatId, [{ type: 'text', text: '' }]);
+    }
+    injectSchemaInstruction(chatId, jsonSchema) {
+        const schemaInstruction = (0, utilities_1.buildSchemaInstruction)(jsonSchema);
+        const messages = this.chatState.getMessages(chatId);
+        const systemMessageIndex = messages.findIndex((msg) => msg.role === 'system');
+        if (systemMessageIndex >= 0) {
+            const originalMessage = messages[systemMessageIndex];
+            const existingContent = typeof originalMessage.content === 'string'
+                ? originalMessage.content
+                : '';
+            messages[systemMessageIndex] = {
+                role: 'system',
+                content: existingContent
+                    ? `${existingContent}\n\n`
+                        + schemaInstruction
+                    : schemaInstruction,
+            };
+            return () => {
+                messages[systemMessageIndex] = originalMessage;
+            };
+        }
+        messages.unshift({
+            role: 'system',
+            content: schemaInstruction,
+        });
+        return () => {
+            messages.shift();
+        };
+    }
+    /**
+     * One round's usage, mapped exactly as `buildToolLoopUsage` maps the run
+     * total, so the per-round generations add up to the single metrics point the
+     * run still writes.
+     */
+    buildRoundUsage(usage) {
+        return this.buildToolLoopUsage({
+            totalPromptTokens: usage?.prompt_tokens ?? 0,
+            totalCachedTokens: usage?.prompt_tokens_details?.cached_tokens ?? 0,
+            totalOutputTokens: usage?.completion_tokens ?? 0,
+            totalReasoningTokens: usage?.completion_tokens_details?.reasoning_tokens ?? 0,
+        });
+    }
+    buildToolLoopUsage(result) {
+        return {
+            inputTextTokens: result.totalPromptTokens
+                - result.totalCachedTokens,
+            inputCachedTextTokens: result.totalCachedTokens,
+            outputTextTokens: result.totalOutputTokens,
+            outputReasoningTokens: result.totalReasoningTokens,
+        };
+    }
+    injectFileContext(chatId, storageId) {
+        if (!storageId) {
+            return;
+        }
+        if (this.fileContextInjectedChats.has(chatId)) {
+            return;
+        }
+        const files = this.fileStorage.getStorageFiles(storageId);
+        if (files.length === 0) {
+            return;
+        }
+        const fileContents = files.map((file) => `--- File: ${file.name} ---\n`
+            + file.content
+            + '\n--- End of file ---').join('\n\n');
+        const fileContext = 'The following files have been uploaded'
+            + ' for reference:\n\n'
+            + fileContents;
+        const messages = this.chatState.getMessages(chatId);
+        const systemMessage = messages.find((msg) => msg.role === 'system');
+        if (systemMessage && 'content' in systemMessage) {
+            const existingContent = typeof systemMessage.content === 'string'
+                ? systemMessage.content
+                : '';
+            systemMessage.content = existingContent
+                ? `${existingContent}\n\n${fileContext}`
+                : fileContext;
+        }
+        else {
+            messages.unshift({
+                role: 'system',
+                content: fileContext,
+            });
+        }
+        this.fileContextInjectedChats.add(chatId);
+    }
+    buildToolsArray(storageId, customTools) {
+        const tools = [];
+        if (customTools?.length) {
+            this.validateToolDefinitions(customTools);
+            if (storageId) {
+                tools.push(...(0, fileStorage_1.getFileStorageToolsForChatCompletions)());
+            }
+            for (const tool of customTools) {
+                tools.push({
+                    type: 'function',
+                    function: {
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.parameters
+                            ._toProviderSchema(LLMService_typedefs_1.LLMProviders.LLMAPI),
+                    },
+                });
+            }
+        }
+        return tools;
+    }
+    async executeToolLoop(options) {
+        const { chatId, model, tools, storageId, customTools, maxToolIterations, abortSignal, rounds, responseFormat, onAssistantNarration, } = options;
+        let totalPromptTokens = 0;
+        let totalCachedTokens = 0;
+        let totalOutputTokens = 0;
+        let totalReasoningTokens = 0;
+        let lastResponseText = '';
+        let toolIterationsUsed = 0;
+        let toolIterationsExhausted = false;
+        let terminalTool;
+        for (let iteration = 0; iteration < maxToolIterations; iteration++) {
+            abortSignal?.throwIfAborted();
+            toolIterationsUsed = iteration + 1;
+            toolIterationsExhausted = toolIterationsUsed >= maxToolIterations;
+            const hasTools = tools.length > 0;
+            this.logOutgoingToolCalls(chatId, iteration);
+            const response = await rounds.run({
+                input: [...this.chatState.getMessages(chatId)],
+                call: () => this.createToolLoopCompletion({
+                    chatId,
+                    model,
+                    tools: hasTools ? tools : undefined,
+                    responseFormat,
+                    abortSignal,
+                }),
+                describeOutcome: (completion) => ({
+                    output: completion.choices[0]?.message,
+                    usage: this.buildRoundUsage(completion.usage),
+                }),
+            });
+            const choice = response.choices[0];
+            totalPromptTokens += response.usage?.prompt_tokens ?? 0;
+            totalCachedTokens +=
+                response.usage?.prompt_tokens_details?.cached_tokens ?? 0;
+            totalOutputTokens += response.usage?.completion_tokens ?? 0;
+            totalReasoningTokens +=
+                response.usage?.completion_tokens_details?.reasoning_tokens ?? 0;
+            const resolvedToolCalls = this.resolveToolCalls(choice);
+            if (resolvedToolCalls.toolCalls.length === 0) {
+                lastResponseText = resolvedToolCalls.assistantContent;
+                toolIterationsExhausted = false;
+                break;
+            }
+            const { toolCalls, assistantContent, reasoningContent } = resolvedToolCalls;
+            if (onAssistantNarration) {
+                onAssistantNarration(this.extractVisibleToolRoundText(choice, resolvedToolCalls));
+            }
+            const executedCalls = await Promise.all(toolCalls.map((toolCall) => this.dispatchToolCall(storageId, toolCall, customTools)));
+            const terminalCall = executedCalls.find((executed) => executed.isTerminal);
+            if (terminalCall) {
+                abortSignal?.throwIfAborted();
+                terminalTool = {
+                    name: terminalCall.toolName,
+                    output: terminalCall.output,
+                };
+                lastResponseText = this.extractVisibleToolRoundText(choice, resolvedToolCalls);
+                toolIterationsExhausted = false;
+                break;
+            }
+            const results = executedCalls.map((executed) => executed.result);
+            this.appendToolInteractionMessages({
+                chatId,
+                modelName: model.name,
+                toolCalls,
+                results,
+                reasoningContent,
+                assistantContent,
+            });
+            this.appendToolResultImages(chatId, results);
+        }
+        if (toolIterationsExhausted) {
+            this.logger?.child(this.getMethodName(this.executeToolLoop)).warn('Tool loop reached maxToolIterations', {
+                maxToolIterations,
+                toolIterationsUsed,
+            });
+        }
+        return {
+            text: lastResponseText,
+            totalPromptTokens,
+            totalCachedTokens,
+            totalOutputTokens,
+            totalReasoningTokens,
+            toolIterationsUsed,
+            toolIterationsExhausted,
+            stopReason: this.resolveToolLoopStopReason({
+                terminalTool,
+                toolIterationsExhausted,
+            }),
+            terminalTool,
+        };
+    }
+    /**
+     * Executes one tool-loop round trip. Gemini through the proxy occasionally
+     * rejects a previously-issued thought_signature on replay with HTTP 400
+     * "Corrupted thought signature."; the recovery downgrades every recorded
+     * signature to the documented validator-bypass marker and retries the same
+     * request once.
+     */
+    async createToolLoopCompletion(options) {
+        const { chatId, model, tools, responseFormat, abortSignal } = options;
+        const createCompletion = () => this.instance.chat.completions.create({
+            model: model.name,
+            messages: this.chatState.getMessages(chatId),
+            ...model.config,
+            ...(tools && { tools }),
+            ...(responseFormat && {
+                response_format: responseFormat,
+            }),
+        }, { signal: abortSignal });
+        try {
+            return await createCompletion();
+        }
+        catch (error) {
+            if (!this.isCorruptedThoughtSignatureError(error)) {
+                throw error;
+            }
+            this.logger?.child(this.getMethodName(this.executeToolLoop)).warn('Recovering from corrupted thought signature', {
+                chatId,
+                model: model.name,
+            });
+            this.chatState.replaceThoughtSignatures(chatId, GEMINI_THOUGHT_SIGNATURE_VALIDATOR_BYPASS);
+            return createCompletion();
+        }
+    }
+    isCorruptedThoughtSignatureError(error) {
+        if (!(error instanceof Error)) {
+            return false;
+        }
+        const status = error.status;
+        return status === 400
+            && error.message.includes('Corrupted thought signature');
+    }
+    resolveToolCalls(choice) {
+        const hasStandardToolCalls = choice?.finish_reason === 'tool_calls'
+            && choice.message.tool_calls?.length;
+        if (hasStandardToolCalls) {
+            const reasoningContent = choice.message
+                ?.reasoning_content;
+            return {
+                toolCalls: choice.message.tool_calls,
+                assistantContent: '',
+                reasoningContent,
+            };
+        }
+        const responseText = choice?.message.content ?? '';
+        const xmlParsed = (0, utilities_1.parseXmlToolCalls)(responseText);
+        if (xmlParsed.toolCalls.length === 0) {
+            return {
+                toolCalls: [],
+                assistantContent: responseText,
+                reasoningContent: undefined,
+            };
+        }
+        return {
+            toolCalls: xmlParsed.toolCalls,
+            assistantContent: xmlParsed.textWithoutToolCalls,
+            reasoningContent: undefined,
+        };
+    }
+    /**
+     * The visible assistant text a continuing tool-loop round produced, with
+     * thinking tags stripped. Standard tool-call turns carry prose in
+     * `message.content` alongside the calls; the XML fallback path already split
+     * prose from markup into `assistantContent`.
+     */
+    extractVisibleToolRoundText(choice, resolvedToolCalls) {
+        const isStandardToolCall = choice?.finish_reason === 'tool_calls'
+            && !!choice.message.tool_calls?.length;
+        const visibleText = isStandardToolCall
+            ? (choice?.message.content ?? '')
+            : resolvedToolCalls.assistantContent;
+        return (0, utilities_1.stripThinkingTags)(visibleText);
+    }
+    appendToolInteractionMessages(options) {
+        const { chatId, modelName, toolCalls, results, reasoningContent, assistantContent, } = options;
+        if (this.shouldSerializeToolHistory(modelName, toolCalls)) {
+            for (let index = 0; index < toolCalls.length; index++) {
+                this.chatState.appendToolCallMessages(chatId, [this.withThoughtSignatureFallback(toolCalls[index])], index === 0 ? reasoningContent : undefined, index === 0 ? assistantContent : '');
+                this.chatState.appendToolResult(chatId, toolCalls[index].id, results[index].content);
+            }
+            return;
+        }
+        this.chatState.appendToolCallMessages(chatId, toolCalls, reasoningContent, assistantContent);
+        for (let index = 0; index < toolCalls.length; index++) {
+            this.chatState.appendToolResult(chatId, toolCalls[index].id, results[index].content);
+        }
+    }
+    /**
+     * Gemini cannot re-pair the proxy-synthesized ids of multiple parallel tool
+     * calls replayed in one turn, so a Gemini multi-call turn is recorded as
+     * sequential single-call turns (so each function-call turn has exactly one
+     * matching response). Gemini also signs only the first parallel call, so the
+     * split turns that carry no signature get the documented validator-bypass
+     * marker; the first call keeps its real thought_signature verbatim.
+     */
+    shouldSerializeToolHistory(modelName, toolCalls) {
+        return toolCalls.length > 1 && modelName.includes('gemini-');
+    }
+    withThoughtSignatureFallback(toolCall) {
+        if (toolCall.extra_content?.google?.thought_signature) {
+            return toolCall;
+        }
+        return {
+            ...toolCall,
+            extra_content: {
+                ...toolCall.extra_content,
+                google: {
+                    ...toolCall.extra_content?.google,
+                    thought_signature: GEMINI_THOUGHT_SIGNATURE_VALIDATOR_BYPASS,
+                },
+            },
+        };
+    }
+    logOutgoingToolCalls(chatId, iteration) {
+        if (process.env.LLM_GATEWAY_DEBUG_TOOL_CALLS !== 'true') {
+            return;
+        }
+        const assistantToolTurns = this.chatState.getMessages(chatId)
+            .filter((message) => message.role === 'assistant'
+            && Array.isArray(message.tool_calls))
+            .map((message) => message.tool_calls.map((toolCall) => {
+            const signature = toolCall.extra_content?.google?.thought_signature;
+            return {
+                id: toolCall.id,
+                hasExtraContent: toolCall.extra_content !== undefined,
+                signatureLength: signature?.length ?? 0,
+            };
+        }));
+        this.logger?.child(this.getMethodName(this.executeToolLoop)).debug?.('Outgoing tool-call turns', {
+            iteration,
+            assistantToolTurns,
+        });
+    }
+    /**
+     * Chat Completions cannot carry images in a `tool`-role message, so any
+     * images a tool returned are surfaced to the model as a separate user
+     * message appended right after the batch of tool results.
+     */
+    appendToolResultImages(chatId, results) {
+        const images = results.flatMap((result) => result.images);
+        if (images.length === 0) {
+            return;
+        }
+        this.chatState.appendUserMessage(chatId, this.buildToolImageMessageParts(images));
+    }
+    buildToolImageMessageParts(images) {
+        return images.flatMap((image) => {
+            const imagePart = {
+                type: 'image_url',
+                image_url: {
+                    url: image.url,
+                    ...(image.detail && { detail: image.detail }),
+                },
+            };
+            if (!image.label) {
+                return [imagePart];
+            }
+            const labelPart = {
+                type: 'text',
+                text: image.label,
+            };
+            return [labelPart, imagePart];
+        });
+    }
+    async dispatchToolCall(storageId, toolCall, customTools) {
+        const toolName = toolCall.function.name;
+        const isFileStorageTool = FILE_STORAGE_TOOL_NAMES.includes(toolName);
+        if (isFileStorageTool && storageId) {
+            const fileStorageResult = await this.toolExecutor.execute(storageId, toolName, toolCall.function.arguments);
+            return {
+                toolName,
+                result: { content: fileStorageResult, images: [] },
+                output: fileStorageResult,
+                isTerminal: false,
+            };
+        }
+        const customTool = customTools?.find((tool) => tool.name === toolName);
+        if (!customTool) {
+            const unknownToolMessage = `Unknown tool: '${toolName}'`;
+            return {
+                toolName,
+                result: { content: unknownToolMessage, images: [] },
+                output: unknownToolMessage,
+                isTerminal: false,
+            };
+        }
+        const isTerminal = customTool.terminal === true;
+        try {
+            const parsedArguments = JSON.parse(toolCall.function.arguments);
+            const result = await this.getTracer().withToolObservation(`${this.serviceName}/tool:${toolName}`, parsedArguments, () => Promise.resolve(customTool.execute(parsedArguments)));
+            const normalized = (0, tools_1.normalizeToolResult)(result);
+            return {
+                toolName,
+                result: {
+                    content: normalized.content.length > 0
+                        ? normalized.content
+                        : `Tool '${toolName}' completed.`,
+                    images: normalized.images,
+                },
+                output: result,
+                isTerminal,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error
+                ? error.message
+                : String(error);
+            this.logger
+                ?.child(this.getMethodName(this.dispatchToolCall))
+                .error('Tool execution failed', {
+                toolName,
+                error: (0, serializeError_1.serializeError)(error),
+            });
+            const failureMessage = `Error executing tool '${toolName}':`
+                + ` ${errorMessage}`;
+            return {
+                toolName,
+                result: { content: failureMessage, images: [] },
+                output: failureMessage,
+                isTerminal,
+            };
+        }
+    }
+}
+exports.LLMAPIAssistanceService = LLMAPIAssistanceService;
+//# sourceMappingURL=LLMAPIAssistance.service.js.map