@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/gemini-generatecontent.js

@@ -0,0 +1,688 @@
+/**
+ * Gemini generateContent TransportNative Gemini API streaming implementation.
+ *
+ * Targets Gemini 3 series exclusively (3.1 Pro, 3 Flash, 3.1 Flash-Lite).
+ * Uses the native Gemini REST API instead of the OpenAI compatibility layer,
+ * unlocking Gemini-exclusive features unavailable via the compat endpoint:
+ *   - thinkingConfig (thinkingLevelG3 native control)
+ *   - Google Search / Maps Grounding
+ *   - Code Execution
+ *   - Safety Settings fine-grained control
+ *   - Thought Signatures for multi-turn reasoning continuity
+ *   - URL Context / File Search
+ *   - systemInstruction top-level field
+ *
+ * Streaming endpoint: POST .../models/{model}:streamGenerateContent?alt=sse
+ * Non-streaming:      POST .../models/{model}:generateContent
+ * Auth: x-goog-api-key header
+ *
+ * Protocol reference: https://ai.google.dev/gemini-api/docs
+ * Aligned with gemini-ProviderMax.md native protocol strategy.
+ */
+import { MEDIA_MAX_UPLOAD_SIZE } from "../constants.js";
+import { isLocalUrl, resolveMediaUrlViaUpload } from "./media-resolve.js";
+import { DEFAULT_MAX_RETRIES, STREAM_IDLE_TIMEOUT_MS, retryDelay, retrySleep, extractHttpStatus, isTransientStatus, } from "../retry.js";
+import { cleanSchemaForGemini } from "../gemini-schema-utils.js";
+// 鈹€鈹€ Safety categories for Agent use (gemini-ProviderMax 鎼?) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+const AGENT_SAFETY_SETTINGS = [
+    { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_CIVIC_INTEGRITY", threshold: "BLOCK_ONLY_HIGH" },
+];
+// 鈹€鈹€ Thinking effort 閳?Gemini 3 thinkingLevel mapping 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+function mapEffortToThinkingLevel(effort) {
+    switch (effort) {
+        case "minimal": return "MINIMAL";
+        case "low": return "LOW";
+        case "medium": return "MEDIUM";
+        case "high": return "HIGH";
+        default: return "HIGH";
+    }
+}
+// 鈹€鈹€ Transport class 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+export class GeminiGenerateContentTransport {
+    baseUrl;
+    timeoutMs;
+    quirks;
+    fileUploadAdapter;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error("GeminiGenerateContentTransport: baseUrl is required");
+        }
+        this.baseUrl = config.baseUrl
+            .replace(/\/openai\/?$/, "")
+            .replace(/\/+$/, "");
+        this.timeoutMs = config.timeoutMs ?? 180_000;
+        this.quirks = config.quirks ?? {};
+        this.fileUploadAdapter = config.fileUploadAdapter;
+    }
+    async *stream(request, apiKey, signal) {
+        const streamUrl = `${this.baseUrl}/models/${encodeURIComponent(request.model)}:streamGenerateContent?alt=sse`;
+        const body = await this.buildRequestBody(request, apiKey, signal);
+        const headers = {
+            "Content-Type": "application/json",
+            "x-goog-api-key": apiKey,
+        };
+        // Retry loop with exponential backoff (CC parity)
+        let lastError = null;
+        for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+            if (signal?.aborted)
+                throw new Error("Request aborted");
+            if (attempt > 0 && lastError) {
+                await retrySleep(retryDelay(attempt), signal);
+            }
+            try {
+                yield* this.fetchAndStream(streamUrl, headers, body, signal);
+                return;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                const isIdleTimeout = lastError.message.includes("Stream idle timeout");
+                if (!isTransientStatus(extractHttpStatus(lastError)) && !isIdleTimeout)
+                    throw lastError;
+                if (attempt === DEFAULT_MAX_RETRIES) {
+                    // Last attempt: try non-streaming fallback
+                    if ((isIdleTimeout || isTransientStatus(extractHttpStatus(lastError))) && !request.streamRequired) {
+                        try {
+                            yield* this.nonStreamingFallback(request, apiKey, signal);
+                            return;
+                        }
+                        catch {
+                            throw lastError;
+                        }
+                    }
+                    throw lastError;
+                }
+            }
+        }
+    }
+    // 鈹€鈹€ Request Body Builder 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async buildRequestBody(request, apiKey, signal) {
+        const resolved = await resolveMessagesMediaForGemini(request.messages, this.fileUploadAdapter, apiKey, signal);
+        const { systemInstruction, contents } = convertMessages(resolved);
+        const body = { contents };
+        if (systemInstruction) {
+            body.system_instruction = systemInstruction;
+        }
+        // Tools: function declarations + native Gemini tools
+        const tools = this.buildTools(request);
+        if (tools.length > 0) {
+            body.tools = tools;
+        }
+        // Tool config (function calling mode)
+        if (request.tools && request.tools.length > 0 && request.toolChoice) {
+            body.toolConfig = this.buildToolConfig(request.toolChoice);
+        }
+        // Generation config
+        const generationConfig = this.buildGenerationConfig(request);
+        if (Object.keys(generationConfig).length > 0) {
+            body.generationConfig = generationConfig;
+        }
+        // Safety settings for agent use (gemini-ProviderMax 鎼?)
+        body.safetySettings = AGENT_SAFETY_SETTINGS;
+        // Explicit cache reference (gemini-ProviderMax 鎼?)
+        if (request.cachedContent) {
+            body.cachedContent = request.cachedContent;
+        }
+        return body;
+    }
+    buildTools(request) {
+        const tools = [];
+        // Function declarations
+        if (request.tools && request.tools.length > 0) {
+            const functionDeclarations = request.tools.map(convertToolDef);
+            tools.push({ functionDeclarations });
+        }
+        // Native Gemini tools (Google Search, Code Execution, URL Context, Maps, File Search)
+        if (!request.disableBuiltinTools) {
+            if (this.quirks.builtinWebSearch) {
+                tools.push({ googleSearch: {} });
+            }
+            if (this.quirks.builtinCodeInterpreter) {
+                tools.push({ codeExecution: {} });
+            }
+            if (this.quirks.builtinUrlContext) {
+                tools.push({ urlContext: {} });
+            }
+            if (this.quirks.builtinMapsGrounding) {
+                tools.push({ googleMaps: {} });
+            }
+            if (this.quirks.builtinFileSearch) {
+                tools.push({ fileSearch: {} });
+            }
+        }
+        return tools;
+    }
+    buildToolConfig(toolChoice) {
+        if (typeof toolChoice === "string") {
+            const modeMap = {
+                auto: "AUTO",
+                none: "NONE",
+                required: "ANY",
+            };
+            return {
+                functionCallingConfig: { mode: modeMap[toolChoice] ?? "AUTO" },
+            };
+        }
+        // Specific function
+        return {
+            functionCallingConfig: {
+                mode: "ANY",
+                allowedFunctionNames: [toolChoice.name],
+            },
+        };
+    }
+    buildGenerationConfig(request) {
+        const config = {};
+        // TemperatureG3 recommends keeping default 1.0
+        if (request.temperature !== undefined) {
+            config.temperature = request.temperature;
+        }
+        if (request.topP !== undefined) {
+            config.topP = request.topP;
+        }
+        if (request.maxTokens !== undefined) {
+            config.maxOutputTokens = request.maxTokens;
+        }
+        // Thinking configG3 thinkingLevel (gemini-ProviderMax 鎼?)
+        if (request.reasoning) {
+            let level = mapEffortToThinkingLevel(request.reasoning.effort);
+            // 3.1 Pro does not support MINIMALclamp to LOW
+            if (level === "MINIMAL" && request.model.includes("pro")) {
+                level = "LOW";
+            }
+            config.thinkingConfig = {
+                thinkingLevel: level,
+                includeThoughts: true,
+            };
+        }
+        // Structured output (gemini-ProviderMax 鎼?)
+        if (request.structuredOutput) {
+            if (request.structuredOutput.mode === "json_object") {
+                config.responseMimeType = "application/json";
+            }
+            else if (request.structuredOutput.mode === "json_schema") {
+                config.responseMimeType = "application/json";
+                config.responseSchema = request.structuredOutput.schema;
+            }
+        }
+        return config;
+    }
+    // 鈹€鈹€ Fetch + Stream 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async *fetchAndStream(url, headers, body, signal) {
+        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+        const combinedSignal = signal
+            ? AbortSignal.any([signal, timeoutSignal])
+            : timeoutSignal;
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: combinedSignal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            const err = new Error(`Gemini API error ${response.status}: ${errorBody.slice(0, 500)}`);
+            err.status = response.status;
+            throw err;
+        }
+        if (!response.body) {
+            throw new Error("Gemini API returned no response body");
+        }
+        // Gemini SSE format: same data: prefix as OpenAI
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json") && !contentType.includes("text/event-stream")) {
+            // Non-streaming response (shouldn't happen with streamGenerateContent, but handle gracefully)
+            const data = await response.json();
+            yield* this.processResponse(data);
+            return;
+        }
+        yield* this.parseSSEStreamWithWatchdog(response.body);
+    }
+    /**
+     * Parse SSE stream with 90s idle watchdog (CC parity).
+     */
+    async *parseSSEStreamWithWatchdog(body) {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let idleTimer = null;
+        const abortController = new AbortController();
+        const resetIdleTimer = () => {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                abortController.abort();
+            }, STREAM_IDLE_TIMEOUT_MS);
+        };
+        try {
+            resetIdleTimer();
+            const reader = body.getReader();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (abortController.signal.aborted) {
+                        throw new Error("Stream idle timeout");
+                    }
+                    resetIdleTimer();
+                    buffer += decoder.decode(value, { stream: true });
+                    let newlineIdx;
+                    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                        const line = buffer.slice(0, newlineIdx).trim();
+                        buffer = buffer.slice(newlineIdx + 1);
+                        if (!line)
+                            continue;
+                        if (line.startsWith(":"))
+                            continue;
+                        if (!line.startsWith("data: "))
+                            continue;
+                        const data = line.slice(6);
+                        if (data === "[DONE]")
+                            return;
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(data);
+                        }
+                        catch {
+                            continue;
+                        }
+                        yield* this.processResponse(parsed);
+                    }
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        finally {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+        }
+    }
+    /**
+     * Process a single Gemini response chunk, yielding LLMChunk events.
+     */
+    *processResponse(response) {
+        // Error check
+        if (response.error) {
+            yield { type: "error", message: `Gemini error ${response.error.code}: ${response.error.message}` };
+            return;
+        }
+        // Usage metadata
+        if (response.usageMetadata) {
+            const u = response.usageMetadata;
+            yield {
+                type: "usage",
+                promptTokens: u.promptTokenCount ?? 0,
+                completionTokens: u.candidatesTokenCount ?? 0,
+                reasoningTokens: u.thoughtsTokenCount,
+                cacheReadTokens: u.cachedContentTokenCount,
+            };
+        }
+        if (!response.candidates || response.candidates.length === 0)
+            return;
+        for (const candidate of response.candidates) {
+            // Safety block
+            if (candidate.finishReason === "SAFETY") {
+                yield { type: "error", message: "Response blocked by Gemini safety filters" };
+                yield { type: "done", finishReason: "content_filter" };
+                return;
+            }
+            const parts = candidate.content?.parts ?? [];
+            let toolCallIndex = 0;
+            for (const part of parts) {
+                // Thought / reasoning content
+                if (part.thought && part.text) {
+                    yield { type: "reasoning_delta", text: part.text };
+                    // If part has thoughtSignature, yield as reasoning_block_complete for passback
+                    if (part.thoughtSignature) {
+                        yield {
+                            type: "reasoning_block_complete",
+                            thinking: part.text,
+                            signature: part.thoughtSignature,
+                        };
+                    }
+                    continue;
+                }
+                // Text content
+                if (part.text && !part.thought) {
+                    yield { type: "delta", text: part.text };
+                    continue;
+                }
+                // Function call
+                if (part.functionCall) {
+                    const fc = part.functionCall;
+                    yield {
+                        type: "tool_call_delta",
+                        index: toolCallIndex,
+                        id: fc.id ?? `gemini-tc-${toolCallIndex}`,
+                        name: fc.name,
+                        arguments: JSON.stringify(fc.args ?? {}),
+                    };
+                    // If function call part has a thought signature, emit for passback
+                    if (part.thoughtSignature) {
+                        yield {
+                            type: "reasoning_block_complete",
+                            thinking: "",
+                            signature: part.thoughtSignature,
+                        };
+                    }
+                    toolCallIndex++;
+                    continue;
+                }
+                // Code execution result (from codeExecution tool)
+                if (part.codeExecutionResult) {
+                    const output = part.codeExecutionResult.output ?? "";
+                    yield { type: "delta", text: `\n\`\`\`output\n${output}\n\`\`\`\n` };
+                    continue;
+                }
+                // Executable code (from codeExecution tool)
+                if (part.executableCode) {
+                    const lang = part.executableCode.language ?? "python";
+                    yield { type: "delta", text: `\n\`\`\`${lang}\n${part.executableCode.code}\n\`\`\`\n` };
+                    continue;
+                }
+            }
+            // Grounding metadata 閳?annotations (Google Search / Maps citations)
+            if (candidate.groundingMetadata?.groundingChunks) {
+                const annotations = candidate.groundingMetadata.groundingChunks
+                    .filter((c) => c.web?.uri)
+                    .map((c) => ({
+                    type: "web_search",
+                    url: c.web.uri,
+                    title: c.web.title,
+                }));
+                if (annotations.length > 0) {
+                    yield { type: "annotations", annotations };
+                }
+            }
+            // Finish reason
+            if (candidate.finishReason) {
+                yield { type: "done", finishReason: mapGeminiFinishReason(candidate.finishReason) };
+            }
+        }
+    }
+    // 鈹€鈹€ Non-streaming fallback 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async *nonStreamingFallback(request, apiKey, signal) {
+        const url = `${this.baseUrl}/models/${encodeURIComponent(request.model)}:generateContent`;
+        const body = await this.buildRequestBody(request, apiKey, signal);
+        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+        const combinedSignal = signal
+            ? AbortSignal.any([signal, timeoutSignal])
+            : timeoutSignal;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-goog-api-key": apiKey,
+            },
+            body: JSON.stringify(body),
+            signal: combinedSignal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            throw new Error(`Gemini API error ${response.status}: ${errorBody.slice(0, 500)}`);
+        }
+        const data = await response.json();
+        yield* this.processResponse(data);
+    }
+}
+// 鈹€鈹€ Local media resolution for Gemini 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Pre-resolve local media URLs for Gemini.
+ * Gemini's fileData uses fileUri (must be publicly accessible or a Gemini File API URI).
+ * Local MediaStore URLs 閳?upload to Gemini File API when adapter available, otherwise data URLs.
+ */
+async function resolveMessagesMediaForGemini(messages, uploadAdapter, apiKey, signal) {
+    const needsResolution = messages.some((m) => m.imageUrls?.some(isLocalUrl) || m.videoUrls?.some(isLocalUrl) ||
+        m.audioUrls?.some(isLocalUrl) || m.fileIds?.some((f) => isLocalUrl(f.id)));
+    if (!needsResolution)
+        return messages;
+    const resolve = (url, _fallbackMime) => {
+        if (!isLocalUrl(url))
+            return Promise.resolve(url);
+        if (!uploadAdapter || !apiKey) {
+            throw new Error("FileUploadAdapter required for local media URLs. Configure OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET or QLOGICAGENT_HUB_URL.");
+        }
+        return resolveMediaUrlViaUpload(url, { uploadAdapter, apiKey, signal });
+    };
+    return Promise.all(messages.map(async (msg) => {
+        if (msg.role !== "user" && msg.role !== "tool")
+            return msg;
+        const patch = {};
+        if (msg.imageUrls?.some(isLocalUrl)) {
+            patch.imageUrls = await Promise.all(msg.imageUrls.map((url) => resolve(url)));
+        }
+        if (msg.role === "user" && msg.videoUrls?.some(isLocalUrl)) {
+            patch.videoUrls = await Promise.all(msg.videoUrls.map((url) => resolve(url)));
+        }
+        if (msg.role === "user" && msg.audioUrls?.some(isLocalUrl)) {
+            patch.audioUrls = await Promise.all(msg.audioUrls.map((url) => resolve(url)));
+        }
+        if (msg.role === "user" && msg.fileIds?.some((f) => isLocalUrl(f.id))) {
+            patch.fileIds = await Promise.all(msg.fileIds.map(async (f) => {
+                if (!isLocalUrl(f.id))
+                    return f;
+                const resolved = await resolve(f.id, f.mimeType);
+                return { ...f, id: resolved };
+            }));
+        }
+        return Object.keys(patch).length > 0 ? { ...msg, ...patch } : msg;
+    }));
+}
+// 鈹€鈹€ Message conversion: ChatMessage[] 閳?Gemini contents + systemInstruction 鈹€鈹€
+function convertMessages(messages) {
+    let systemInstruction = null;
+    const contents = [];
+    // Collect consecutive tool results to merge into a single user turn
+    let pendingToolResponses = [];
+    const flushToolResponses = () => {
+        if (pendingToolResponses.length > 0) {
+            contents.push({ role: "user", parts: pendingToolResponses });
+            pendingToolResponses = [];
+        }
+    };
+    for (const msg of messages) {
+        switch (msg.role) {
+            case "system": {
+                // Gemini: system instruction is a top-level field, not a content entry
+                systemInstruction = {
+                    parts: [{ text: msg.content ?? "" }],
+                };
+                break;
+            }
+            case "user": {
+                flushToolResponses();
+                const parts = [];
+                if (msg.content) {
+                    parts.push({ text: msg.content });
+                }
+                // Vision: image URLs 閳?inline_data or fileData parts
+                if (msg.imageUrls && msg.imageUrls.length > 0) {
+                    for (const url of msg.imageUrls) {
+                        if (url.startsWith("data:")) {
+                            // data URI 閳?inlineData
+                            const match = url.match(/^data:([^;]+);base64,(.+)$/);
+                            if (match) {
+                                parts.push({
+                                    inlineData: { mimeType: match[1], data: match[2] },
+                                });
+                            }
+                        }
+                        else {
+                            // Regular URL 閳?fileData (Gemini can fetch URLs)
+                            parts.push({
+                                fileData: { mimeType: "image/jpeg", fileUri: url },
+                            });
+                        }
+                    }
+                }
+                // Audio URLs
+                if (msg.audioUrls && msg.audioUrls.length > 0) {
+                    for (const url of msg.audioUrls) {
+                        const mimeType = msg.audioFormat
+                            ? `audio/${msg.audioFormat === "m4a" ? "mp4" : msg.audioFormat}`
+                            : "audio/mp3";
+                        parts.push({
+                            fileData: { mimeType, fileUri: url },
+                        });
+                    }
+                }
+                // Video URLs
+                if (msg.videoUrls && msg.videoUrls.length > 0) {
+                    for (const url of msg.videoUrls) {
+                        parts.push({
+                            fileData: { mimeType: "video/mp4", fileUri: url },
+                        });
+                    }
+                }
+                // File attachments (PDF, documents, etc.)
+                // Size-aware: files over 50MB degrade to text annotation
+                if (msg.fileIds && msg.fileIds.length > 0) {
+                    for (const f of msg.fileIds) {
+                        const tooLarge = f.size != null && f.size > MEDIA_MAX_UPLOAD_SIZE;
+                        if (tooLarge) {
+                            const mime = f.mimeType || "unknown";
+                            const sizeLabel = `${(f.size / (1024 * 1024)).toFixed(1)}MB`;
+                            parts.push({ text: `[Attached: ${f.id} (${mime}, ${sizeLabel})file too large for direct vision, use tools to process]` });
+                        }
+                        else if (f.id.startsWith("data:")) {
+                            // Pre-resolved base64 data URL 閳?inlineData
+                            const match = f.id.match(/^data:([^;]+);base64,(.+)$/);
+                            if (match) {
+                                parts.push({
+                                    inlineData: { mimeType: match[1], data: match[2] },
+                                });
+                            }
+                        }
+                        else if (f.id.startsWith("http://") || f.id.startsWith("https://")) {
+                            // Public URL 閳?fileData (Gemini fetches server-side)
+                            parts.push({
+                                fileData: { mimeType: f.mimeType ?? "application/octet-stream", fileUri: f.id },
+                            });
+                        }
+                        else {
+                            // Gemini File API URI or other reference
+                            parts.push({
+                                fileData: { mimeType: f.mimeType ?? "application/octet-stream", fileUri: f.id },
+                            });
+                        }
+                    }
+                }
+                if (parts.length > 0) {
+                    contents.push({ role: "user", parts });
+                }
+                break;
+            }
+            case "assistant": {
+                flushToolResponses();
+                const parts = [];
+                // Thinking blocks 閳?thought parts with signatures (Gemini thought signature passback)
+                if (msg.thinkingBlocks && msg.thinkingBlocks.length > 0) {
+                    for (const tb of msg.thinkingBlocks) {
+                        const thoughtPart = {
+                            text: tb.thinking,
+                            thought: true,
+                        };
+                        if (tb.signature) {
+                            thoughtPart.thoughtSignature = tb.signature;
+                        }
+                        parts.push(thoughtPart);
+                    }
+                }
+                if (msg.content) {
+                    parts.push({ text: msg.content });
+                }
+                // Tool calls 閳?functionCall parts
+                if (msg.tool_calls && msg.tool_calls.length > 0) {
+                    for (const tc of msg.tool_calls) {
+                        let args = {};
+                        try {
+                            args = JSON.parse(tc.function.arguments);
+                        }
+                        catch {
+                            // Keep empty args on parse failure
+                        }
+                        parts.push({
+                            functionCall: {
+                                name: tc.function.name,
+                                args,
+                                id: tc.id,
+                            },
+                        });
+                    }
+                }
+                if (parts.length > 0) {
+                    contents.push({ role: "model", parts });
+                }
+                break;
+            }
+            case "tool": {
+                // Tool results 閳?functionResponse parts, merged into a user turn
+                let responseContent;
+                try {
+                    responseContent = JSON.parse(msg.content ?? "{}");
+                }
+                catch {
+                    responseContent = { result: msg.content ?? "" };
+                }
+                pendingToolResponses.push({
+                    functionResponse: {
+                        name: msg.name ?? "",
+                        response: responseContent,
+                        id: msg.tool_call_id ?? "",
+                    },
+                });
+                // Images from tool results: add as inlineData/fileData parts in the same turn
+                if (msg.imageUrls && msg.imageUrls.length > 0) {
+                    for (const url of msg.imageUrls) {
+                        if (url.startsWith("data:")) {
+                            const match = /^data:([^;]+);base64,(.+)$/.exec(url);
+                            if (match) {
+                                pendingToolResponses.push({ inlineData: { mimeType: match[1], data: match[2] } });
+                            }
+                        }
+                        else {
+                            // Gemini uses fileData for public URLs (file_uri format)
+                            const mimeType = url.endsWith(".png") ? "image/png"
+                                : url.endsWith(".jpg") || url.endsWith(".jpeg") ? "image/jpeg"
+                                    : url.endsWith(".gif") ? "image/gif"
+                                        : url.endsWith(".webp") ? "image/webp"
+                                            : "image/png";
+                            pendingToolResponses.push({ fileData: { mimeType, fileUri: url } });
+                        }
+                    }
+                }
+                break;
+            }
+        }
+    }
+    flushToolResponses();
+    return { systemInstruction, contents };
+}
+// 鈹€鈹€ Tool definition conversion: OpenAI format 閳?Gemini functionDeclaration 鈹€鈹€
+function convertToolDef(tool) {
+    const decl = {
+        name: tool.function.name,
+        description: tool.function.description,
+    };
+    if (tool.function.parameters) {
+        decl.parameters = cleanSchemaForGemini(tool.function.parameters);
+    }
+    return decl;
+}
+// 鈹€鈹€ Gemini finishReason 閳?standard values 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+function mapGeminiFinishReason(reason) {
+    switch (reason) {
+        case "STOP": return "stop";
+        case "MAX_TOKENS": return "length";
+        case "SAFETY": return "content_filter";
+        case "RECITATION": return "content_filter";
+        case "LANGUAGE": return "content_filter";
+        case "FINISH_REASON_UNSPECIFIED": return "stop";
+        default: return reason.toLowerCase();
+    }
+}