mixdog 0.7.1

package/src/agent/orchestrator/providers/gemini.mjs

@@ -0,0 +1,1175 @@
+import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
+import { createHash } from 'crypto';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { loadConfig, getPluginData } from '../config.mjs';
+import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+import { withRetry } from './retry-classifier.mjs';
+import { traceBridgeUsage, appendBridgeTrace } from '../bridge-trace.mjs';
+import {
+    PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+    PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
+    PROVIDER_MAX_BEFORE_WARN_MS,
+    providerTimeoutError,
+    resolveTimeoutMs,
+} from '../stall-policy.mjs';
+import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
+
+const MODELS = [
+    { id: 'gemini-3-flash-preview', name: 'Gemini 3 Flash Preview', provider: 'gemini', contextWindow: 1048576 },
+    { id: 'gemini-3.1-pro-preview', name: 'Gemini 3.1 Pro Preview', provider: 'gemini', contextWindow: 1048576 },
+    { id: 'gemini-3-pro-preview', name: 'Gemini 3 Pro Preview', provider: 'gemini', contextWindow: 1048576 },
+    { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash', provider: 'gemini', contextWindow: 1048576 },
+    { id: 'gemini-2.5-pro', name: 'Gemini 2.5 Pro', provider: 'gemini', contextWindow: 1048576 },
+];
+
+const DEFAULT_MODEL = MODELS[0].id;
+
+// --- Model catalog cache (24h disk TTL) ---
+// Gemini's /models has no `created` timestamp, so latest-resolution is
+// VERSION-based (parse gemini-X.Y) rather than release-date based.
+const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
+
+// De-dupes concurrent force-refreshes so they share one HTTP round-trip,
+// mirroring anthropic-oauth's _modelRefreshInFlight.
+let _modelRefreshInFlight = null;
+
+function _modelCachePath() {
+    return join(getPluginData(), 'gemini-models.json');
+}
+
+function _loadModelCache() {
+    const path = _modelCachePath();
+    if (!existsSync(path)) return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!raw?.fetchedAt || !Array.isArray(raw.models)) return null;
+        if (Date.now() - raw.fetchedAt > MODEL_CACHE_TTL_MS) return null;
+        return raw.models;
+    } catch { return null; }
+}
+
+function _saveModelCache(models) {
+    try {
+        writeJsonAtomicSync(_modelCachePath(), { fetchedAt: Date.now(), models }, { lock: true, fsyncDir: true });
+    } catch { /* best-effort */ }
+}
+
+// Mirror of anthropic-oauth.mjs _compareVersion: compare two gemini ids by the
+// X.Y version embedded in the id (gemini-3.5-flash -> [3, 5]). Falls back to a
+// lexicographic tiebreak so ordering is total.
+function _compareVersion(a, b) {
+    const na = (a.match(/gemini-(\d+)(?:\.(\d+))?/) || []).slice(1).map(Number);
+    const nb = (b.match(/gemini-(\d+)(?:\.(\d+))?/) || []).slice(1).map(Number);
+    for (let i = 0; i < Math.max(na.length, nb.length); i++) {
+        if ((na[i] || 0) !== (nb[i] || 0)) return (na[i] || 0) - (nb[i] || 0);
+    }
+    return a.localeCompare(b);
+}
+
+// Per family, mark the highest-version model as latest:true.
+function _markLatestGemini(models) {
+    const byFamily = new Map();
+    for (const m of models) {
+        if (!m?.id) continue;
+        const cur = byFamily.get(m.family);
+        if (!cur || _compareVersion(m.id, cur.id) > 0) {
+            byFamily.set(m.family, m);
+        }
+    }
+    for (const m of byFamily.values()) m.latest = true;
+}
+
+// Newest chat model by VERSION in the 'gemini-flash' family, read from the
+// on-disk catalog cache. Returns null until cached; callers warm via
+// ensureLatestGeminiModel when null.
+export function resolveLatestGeminiModel() {
+    const cached = _loadModelCache();
+    if (!Array.isArray(cached)) return null;
+    let best = null;
+    for (const m of cached) {
+        if (!m?.id || m.family !== 'gemini-flash') continue;
+        if (!best || _compareVersion(m.id, best.id) > 0) best = m;
+    }
+    return best?.id || null;
+}
+
+export async function ensureLatestGeminiModel(provider) {
+    let m = resolveLatestGeminiModel();
+    if (m) return m;
+    await provider._refreshModelCache();
+    m = resolveLatestGeminiModel();
+    if (m) return m;
+    throw new Error('[gemini] model catalog unavailable after warmup — cannot resolve default model');
+}
+
+const GEMINI_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_GEMINI_FIRST_BYTE_TIMEOUT_MS',
+    PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+    { minMs: 30_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+const GEMINI_GENERATE_TOTAL_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_GEMINI_GENERATE_TOTAL_TIMEOUT_MS',
+    PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
+    { minMs: 30_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+function traceHash(value) {
+    return createHash('sha256')
+        .update(String(value ?? ''))
+        .digest('hex')
+        .slice(0, 16);
+}
+
+function stableTraceStringify(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object') {
+        if (typeof value === 'bigint') return JSON.stringify(String(value));
+        if (typeof value === 'undefined' || typeof value === 'function') return 'null';
+        return JSON.stringify(value);
+    }
+    if (seen.has(value)) return JSON.stringify('[Circular]');
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const serialized = '[' + value.map(v => stableTraceStringify(v, seen)).join(',') + ']';
+        seen.delete(value);
+        return serialized;
+    }
+    const parts = [];
+    for (const key of Object.keys(value).sort()) {
+        const v = value[key];
+        if (typeof v === 'undefined' || typeof v === 'function') continue;
+        parts.push(JSON.stringify(key) + ':' + stableTraceStringify(v, seen));
+    }
+    seen.delete(value);
+    return '{' + parts.join(',') + '}';
+}
+
+function traceTextShape(text) {
+    const value = String(text ?? '');
+    return { chars: value.length, hash: traceHash(value) };
+}
+
+function summarizeTracePart(part) {
+    if (!part || typeof part !== 'object') return { type: typeof part };
+    if ('text' in part) {
+        return { type: 'text', ...traceTextShape(part.text) };
+    }
+    if (part.functionCall) {
+        return {
+            type: 'functionCall',
+            name: part.functionCall.name || null,
+            argsHash: traceHash(stableTraceStringify(part.functionCall.args || {})),
+        };
+    }
+    if (part.functionResponse) {
+        const response = part.functionResponse.response || {};
+        const responseShape = stableTraceStringify(response);
+        return {
+            type: 'functionResponse',
+            name: part.functionResponse.name || null,
+            responseChars: responseShape.length,
+            responseHash: traceHash(responseShape),
+        };
+    }
+    return { type: Object.keys(part).sort().join('|') || 'unknown' };
+}
+
+function summarizeTraceContents(contents) {
+    const summaries = (contents || []).map((content, index) => ({
+        index,
+        role: content?.role || null,
+        parts: Array.isArray(content?.parts) ? content.parts.map(summarizeTracePart) : [],
+    }));
+    if (summaries.length <= 12) return summaries;
+    return [
+        ...summaries.slice(0, 8),
+        { omittedTurns: summaries.length - 12 },
+        ...summaries.slice(-4),
+    ];
+}
+
+function summarizeTraceTools(tools) {
+    return (tools || []).map(t => ({
+        name: t?.name || null,
+        description: t?.description || '',
+        inputSchema: t?.inputSchema || null,
+    }));
+}
+
+// Gemini cachedContents API rejects prefixes below the model-specific minimum
+// (Gemini 2.0/2.5 = 2048 tokens, Gemini 3.x = 4096 tokens) with HTTP 400
+// "Cached content is too small". Estimating chars/4 ≈ tokens lets us skip the
+// roundtrip when the prefix cannot satisfy the invariant. Estimate undercount
+// is harmless (we attempt and get the same 400 we would have skipped); overcount
+// is harmless (we skip, fall back to implicit cache).
+function _estimateGeminiCacheTokens(systemInstruction, geminiTools, contents) {
+    let chars = 0;
+    if (typeof systemInstruction === 'string') chars += systemInstruction.length;
+    if (Array.isArray(geminiTools) && geminiTools.length) {
+        try { chars += JSON.stringify(geminiTools).length; } catch {}
+    }
+    if (Array.isArray(contents) && contents.length > 1) {
+        for (let i = 0; i < contents.length - 1; i++) {
+            try { chars += JSON.stringify(contents[i]?.parts ?? '').length; } catch {}
+        }
+    }
+    return Math.ceil(chars / 4);
+}
+
+function _geminiCacheMinTokens(model) {
+    return /^gemini-3/i.test(String(model || '')) ? 4096 : 2048;
+}
+
+function _geminiCachePrefixCount(contents) {
+    return Array.isArray(contents) && contents.length > 1 ? contents.length - 1 : 0;
+}
+
+function _geminiCachePrefixContents(contents, prefixCount) {
+    if (!Array.isArray(contents) || prefixCount <= 0) return [];
+    return contents.slice(0, prefixCount).map(c => {
+        const r = c?.role;
+        const safeRole = (r === 'model' || r === 'user') ? r : 'user';
+        return {
+            role: safeRole,
+            parts: Array.isArray(c?.parts) ? c.parts : [],
+        };
+    });
+}
+
+function _geminiCachePrefixHash({ model, systemInstruction, geminiTools, contents, prefixCount }) {
+    return traceHash(stableTraceStringify({
+        model: model || null,
+        systemInstruction: systemInstruction || '',
+        tools: geminiTools || [],
+        contents: _geminiCachePrefixContents(contents, prefixCount),
+    }));
+}
+
+function _resolveGeminiCacheUsage({ usageMetadata, cachedContent, providerState }) {
+    const inputTokens = Number(usageMetadata?.promptTokenCount || usageMetadata?.totalTokenCount || 0) || 0;
+    const reportedCachedTokens = Number(usageMetadata?.cachedContentTokenCount || 0) || 0;
+    const cachedFallbackTokens = cachedContent
+        ? Number(providerState?.gemini?.cacheTokenSize || 0) || 0
+        : 0;
+    const rawCachedTokens = reportedCachedTokens > 0 ? reportedCachedTokens : cachedFallbackTokens;
+    const cachedTokens = inputTokens > 0 ? Math.min(rawCachedTokens, inputTokens) : rawCachedTokens;
+    const cacheTokenSource = reportedCachedTokens > 0
+        ? 'usage_metadata'
+        : (cachedFallbackTokens > 0 ? 'cache_create_fallback' : 'none');
+    return {
+        inputTokens,
+        reportedCachedTokens,
+        cachedFallbackTokens,
+        cachedTokens,
+        cacheTokenSource,
+    };
+}
+
+function writeGeminiCacheTrace({ opts, model, systemInstruction, tools, contents, usageMetadata, cachedContent }) {
+    if (process.env.MIXDOG_GEMINI_CACHE_TRACE !== '1') return;
+    try {
+        const session = opts?.session || {};
+        const {
+            inputTokens,
+            reportedCachedTokens,
+            cachedFallbackTokens,
+            cachedTokens,
+            cacheTokenSource,
+        } = _resolveGeminiCacheUsage({
+            usageMetadata,
+            cachedContent,
+            providerState: opts?.providerState,
+        });
+        const toolShape = summarizeTraceTools(tools);
+        const trace = {
+            event: 'generate',
+            provider: 'gemini',
+            model,
+            owner: session.owner || null,
+            role: session.role || null,
+            permission: session.permission || null,
+            toolPermission: session.toolPermission || null,
+            profileId: session.profileId || null,
+            sourceType: session.sourceType || null,
+            sourceName: session.sourceName || null,
+            sessionIdHash: opts?.sessionId ? traceHash(opts.sessionId) : null,
+            providerCacheKeyHash: opts?.providerCacheKey ? traceHash(opts.providerCacheKey) : null,
+            promptCacheKeyHash: opts?.promptCacheKey ? traceHash(opts.promptCacheKey) : null,
+            systemChars: systemInstruction ? systemInstruction.length : 0,
+            systemHash: systemInstruction ? traceHash(systemInstruction) : null,
+            toolCount: Array.isArray(tools) ? tools.length : 0,
+            toolSchemaHash: traceHash(stableTraceStringify(toolShape)),
+            contentTurnCount: Array.isArray(contents) ? contents.length : 0,
+            contents: summarizeTraceContents(contents),
+            inputTokens,
+            cachedTokens,
+            reportedCachedTokens,
+            cachedFallbackTokens,
+            cacheTokenSource,
+            cacheAttached: !!cachedContent,
+            cachePrefixContentCount: opts?.providerState?.gemini?.cachePrefixContentCount ?? null,
+            cacheHitRate: inputTokens > 0 ? Number((cachedTokens / inputTokens).toFixed(6)) : null,
+        };
+        process.stderr.write(`[gemini-cache-trace] ${JSON.stringify(trace)}\n`);
+    } catch (err) {
+        process.stderr.write(`[gemini-cache-trace] failed: ${err?.message || err}\n`);
+    }
+}
+
+function geminiTimeoutError(label, timeoutMs) {
+    const err = providerTimeoutError(label, timeoutMs);
+    err.name = 'GeminiTimeoutError';
+    err.code = 'EGEMINITIMEOUT';
+    return err;
+}
+
+function runGeminiOperationWithTimeout({ label, timeoutMs, signal, run }) {
+    const ac = new AbortController();
+    let settled = false;
+    let timer = null;
+    let abortListener = null;
+    return new Promise((resolve, reject) => {
+        const finish = (fn, value) => {
+            if (settled) return;
+            settled = true;
+            if (timer) clearTimeout(timer);
+            if (abortListener && signal) {
+                try { signal.removeEventListener('abort', abortListener); } catch {}
+            }
+            fn(value);
+        };
+        const abort = (reason) => {
+            try { ac.abort(reason); } catch {}
+            finish(reject, reason instanceof Error ? reason : new Error(String(reason || `${label} aborted`)));
+        };
+        if (signal) {
+            abortListener = () => abort(signal.reason);
+            if (signal.aborted) { abortListener(); return; }
+            signal.addEventListener('abort', abortListener, { once: true });
+        }
+        timer = setTimeout(() => {
+            abort(geminiTimeoutError(label, timeoutMs));
+        }, timeoutMs);
+        if (timer.unref) timer.unref();
+        Promise.resolve()
+            .then(() => run(ac.signal))
+            .then((value) => finish(resolve, value), (err) => finish(reject, err));
+    });
+}
+
+/**
+ * Convert JSON Schema type string to Gemini SchemaType.
+ * Gemini SDK uses its own enum instead of plain strings.
+ */
+function toSchemaType(t) {
+    const map = {
+        string: SchemaType.STRING,
+        number: SchemaType.NUMBER,
+        integer: SchemaType.INTEGER,
+        boolean: SchemaType.BOOLEAN,
+        array: SchemaType.ARRAY,
+        object: SchemaType.OBJECT,
+    };
+    return map[t] ?? SchemaType.STRING;
+}
+
+/**
+ * Recursively convert a JSON Schema object to Gemini's FunctionDeclarationSchema.
+ * Gemini requires `type` to be a SchemaType enum, not a plain string, and
+ * rejects several JSON Schema fields the API does not understand
+ * (additionalProperties, $schema, $ref, const, examples, definitions,
+ * patternProperties). We strip those at every level.
+ */
+const GEMINI_SCHEMA_STRIP = new Set([
+    'additionalProperties',
+    '$schema',
+    '$ref',
+    'const',
+    'examples',
+    'definitions',
+    'patternProperties',
+]);
+function convertSchema(schema) {
+    if (!schema || typeof schema !== 'object') return schema;
+    const result = {};
+    for (const [k, v] of Object.entries(schema)) {
+        if (GEMINI_SCHEMA_STRIP.has(k)) continue;
+        result[k] = v;
+    }
+    // Gemini's Schema validator requires every `enum` entry to be a string,
+    // even when the parent `type` is integer/number/boolean. Drop the enum in
+    // that case rather than emit an invalid typed enum — `type` plus the
+    // description still guides the model, and the tool handler revalidates.
+    const rawType = typeof result.type === 'string' ? result.type : undefined;
+    if (Array.isArray(result.enum) && (rawType === 'integer' || rawType === 'number' || rawType === 'boolean')) {
+        if (result.enum.some((item) => typeof item !== 'string')) {
+            delete result.enum;
+        }
+    }
+    // Gemini rejects array schemas that omit `items`; fill a permissive
+    // default so the declaration validates.
+    if (rawType === 'array' && (!result.items || typeof result.items !== 'object')) {
+        result.items = { type: 'string' };
+    }
+    if (typeof result.type === 'string') {
+        result.type = toSchemaType(result.type);
+    }
+    if (result.properties && typeof result.properties === 'object') {
+        const props = {};
+        for (const [key, val] of Object.entries(result.properties)) {
+            props[key] = convertSchema(val);
+        }
+        result.properties = props;
+    }
+    if (result.items && typeof result.items === 'object') {
+        result.items = convertSchema(result.items);
+    }
+    // Recurse into JSON Schema combinator keys so disallowed fields
+    // (additionalProperties, $schema, etc.) get stripped at every nesting
+    // level. Without this, schemas using anyOf/oneOf/allOf/not pass the
+    // shallow strip but fail Gemini validation at depth.
+    //
+    // Two Gemini-specific normalizations are also applied per combinator
+    // subschema:
+    //   1. Inject `type: OBJECT` when a subschema uses object-only keys
+    //      (`required` / `properties`) without an explicit type — Gemini
+    //      rejects `required` outside of OBJECT type.
+    //   2. Materialize a local `properties` map from the parent's properties
+    //      when the subschema only carries `required: [names]` — Gemini
+    //      validates that every name in `required` exists in *this*
+    //      subschema's `properties` (it does not inherit from the parent
+    //      the way JSON Schema's compositional model does).
+    for (const combinator of ['anyOf', 'oneOf', 'allOf']) {
+        if (Array.isArray(result[combinator])) {
+            result[combinator] = result[combinator].map((s) => {
+                const sub = convertSchema(s);
+                if (sub && typeof sub === 'object') {
+                    const usesObjectKeys = sub.required !== undefined || sub.properties !== undefined;
+                    if (usesObjectKeys && sub.type === undefined) {
+                        sub.type = toSchemaType('object');
+                    }
+                    if (Array.isArray(sub.required) && !sub.properties && result.properties) {
+                        const projected = {};
+                        for (const k of sub.required) {
+                            if (result.properties[k]) projected[k] = result.properties[k];
+                        }
+                        if (Object.keys(projected).length > 0) sub.properties = projected;
+                    }
+                }
+                return sub;
+            });
+        }
+    }
+    if (result.not && typeof result.not === 'object') {
+        result.not = convertSchema(result.not);
+    }
+    return result;
+}
+
+function toGeminiTools(tools) {
+    return {
+        functionDeclarations: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: convertSchema(t.inputSchema),
+        })),
+    };
+}
+
+// Map the orchestrator-level toolChoice to Gemini's functionCallingConfig.
+//   auto      -> AUTO
+//   required  -> ANY
+//   none      -> NONE
+//   { name }  -> ANY + allowedFunctionNames:[name]   (specific tool)
+function toGeminiToolConfig(toolChoice) {
+    if (toolChoice == null) return undefined;
+    if (typeof toolChoice === 'string') {
+        if (toolChoice === 'auto') return { functionCallingConfig: { mode: 'AUTO' } };
+        if (toolChoice === 'required') return { functionCallingConfig: { mode: 'ANY' } };
+        if (toolChoice === 'none') return { functionCallingConfig: { mode: 'NONE' } };
+        return undefined;
+    }
+    if (typeof toolChoice === 'object') {
+        const name = toolChoice.name || toolChoice.function?.name;
+        if (typeof name === 'string' && name) {
+            return { functionCallingConfig: { mode: 'ANY', allowedFunctionNames: [name] } };
+        }
+    }
+    return undefined;
+}
+
+function toGeminiContent(message, toolNameByCallId) {
+    if (!message || message.role === 'system') return null;
+    if (message.role === 'assistant' && message.toolCalls?.length) {
+        const parts = [];
+        if (message.content) parts.push({ text: message.content });
+        for (const tc of message.toolCalls) {
+            // Gemini 3 thinking models require the original thoughtSignature
+            // echoed back on every prior functionCall so the cached thinking
+            // prefix stays valid. v1beta places the field at the Part level
+            // (sibling of functionCall) — putting it inside functionCall returns
+            // 400 "Unknown name". Older models / first turn have no signature.
+            const part = { functionCall: { name: tc.name, args: tc.arguments } };
+            if (tc.thoughtSignature) part.thoughtSignature = tc.thoughtSignature;
+            parts.push(part);
+        }
+        return { role: 'model', parts };
+    }
+    if (message.role === 'tool') {
+        // Tool result content stays byte-identical for cache prefix stability.
+        // Gemini accepts functionResponse parts under role 'user' (per docs).
+        // Using 'user' keeps tool_result entries byte-identical between
+        // cachedContents.create (which rejects role:'function') and
+        // generateContent, so the cached prefix actually matches at runtime.
+        // functionResponse.name must be the FUNCTION name, not the synthetic
+        // toolCallId. Resolve it from the toolCallId->functionName map built
+        // from prior assistant tool_calls; fall back to the raw id only when
+        // no mapping exists.
+        const functionName = (toolNameByCallId && toolNameByCallId.get(message.toolCallId))
+            || message.toolCallId
+            || '';
+        return {
+            role: 'user',
+            parts: [{ functionResponse: { name: functionName, response: { result: message.content } } }],
+        };
+    }
+    return {
+        role: message.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: message.content }],
+    };
+}
+
+function toGeminiContents(messages) {
+    const contents = [];
+    // Map synthetic toolCallId -> function name from prior assistant
+    // tool_calls so each functionResponse part carries the real function name.
+    const toolNameByCallId = new Map();
+    for (const m of messages) {
+        if (m?.role === 'assistant' && Array.isArray(m.toolCalls)) {
+            for (const tc of m.toolCalls) {
+                if (tc?.id && tc?.name) toolNameByCallId.set(tc.id, tc.name);
+            }
+        }
+    }
+    for (const message of messages) {
+        const content = toGeminiContent(message, toolNameByCallId);
+        if (content) contents.push(content);
+    }
+    return contents;
+}
+
+function parseToolCalls(parts) {
+    const calls = parts.filter((p) => 'functionCall' in p && !!p.functionCall);
+    if (!calls.length)
+        return undefined;
+    // The @google/generative-ai 0.24.1 SDK predates Gemini 3 thinking — its
+    // FunctionCall type only declares { name, args }. The runtime object,
+    // however, retains whatever the wire response carried, which means the
+    // signature may sit under any of:
+    //   • part.functionCall.thoughtSignature   (camelCase, expected)
+    //   • part.functionCall.thought_signature  (snake_case, raw protobuf)
+    //   • part.thoughtSignature / part.thought_signature (sibling on Part)
+    // Read all four and use the first non-empty hit. Set MIXDOG_DEBUG_GEMINI=1
+    // to dump the raw parts so we can confirm the actual key location on the
+    // next session and harden the parser.
+    if (process.env.MIXDOG_DEBUG_GEMINI === '1') {
+        try { process.stderr.write(`[gemini fc raw] ${JSON.stringify(parts)}\n`); } catch {}
+    }
+    return calls.map((p, i) => {
+        const fc = p.functionCall;
+        const sig = fc.thoughtSignature
+            || fc.thought_signature
+            || p.thoughtSignature
+            || p.thought_signature
+            || null;
+        const call = {
+            id: `gemini_${Date.now()}_${i}`,
+            name: fc.name,
+            arguments: (fc.args ?? {}),
+        };
+        if (sig) call.thoughtSignature = sig;
+        return call;
+    });
+}
+
+export class GeminiProvider {
+    // promptTokenCount is the total (cachedContentTokenCount is a subset), so
+    // input already includes cache. See registry.mjs.
+    static inputExcludesCache = false;
+    name = 'gemini';
+    genAI;
+    config;
+
+    constructor(config) {
+        this.config = config;
+        const apiKey = config.apiKey || process.env.GEMINI_API_KEY || '';
+        this.genAI = new GoogleGenerativeAI(apiKey);
+        // Warm a kept-alive socket to the Gemini REST API so the first cache/
+        // generateContent request skips the cold TLS handshake. Best-effort.
+        preconnect('https://generativelanguage.googleapis.com');
+    }
+
+    reloadApiKey() {
+        try {
+            const freshConfig = loadConfig();
+            const cfg = freshConfig.providers?.gemini;
+            const newKey = cfg?.apiKey || process.env.GEMINI_API_KEY;
+            if (newKey) {
+                this.genAI = new GoogleGenerativeAI(newKey);
+            }
+        } catch { /* best effort */ }
+    }
+
+    _getApiKey() {
+        return this.config?.apiKey || process.env.GEMINI_API_KEY || '';
+    }
+
+    // Explicit cachedContents API. The implicit cache layer on Gemini 3.x
+    // does not surface cachedContentTokenCount in usageMetadata, so the only
+    // way to obtain measurable + billable cache savings is to register the
+    // stable prefix (system + tools) as a CachedContent and pass its name on
+    // every generateContent call. TTL is 1h so a single worker session keeps
+    // one cache slot warm without re-creation overhead; storage cost (~$0.5/M
+    // tokens/hour) is dwarfed by the 75% input-price discount on hits beyond
+    // a few iterations.
+    async _ensureGeminiCache({ apiKey, model, systemInstruction, geminiTools, contents, opts }) {
+        const state = opts.providerState?.gemini || null;
+        const now = Date.now();
+        const currentIter = Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : 1;
+        const refreshEveryN = Number(process.env.MIXDOG_GEMINI_CACHE_REFRESH_EVERY) > 0
+            ? Number(process.env.MIXDOG_GEMINI_CACHE_REFRESH_EVERY)
+            : 4;
+        const cacheLiveMs = state?.cacheExpiresAt ? state.cacheExpiresAt - now : 0;
+        const itersSinceCreate = state?.cacheCreatedAtIter != null
+            ? currentIter - state.cacheCreatedAtIter
+            : Infinity;
+        const statePrefixContentCount = Number.isFinite(Number(state?.cachePrefixContentCount))
+            ? Math.max(0, Math.trunc(Number(state.cachePrefixContentCount)))
+            : null;
+        const currentStatePrefixHash = statePrefixContentCount != null
+            ? _geminiCachePrefixHash({
+                model,
+                systemInstruction,
+                geminiTools,
+                contents,
+                prefixCount: statePrefixContentCount,
+            })
+            : null;
+        const modelMatches = !!state?.cacheName && state?.cacheModel === model;
+        const prefixMatches = !!state?.cacheName
+            && statePrefixContentCount != null
+            && statePrefixContentCount <= (Array.isArray(contents) ? contents.length : 0)
+            && !!state?.cachePrefixHash
+            && state.cachePrefixHash === currentStatePrefixHash;
+        const canAttachState = !!state?.cacheName && cacheLiveMs > 0 && modelMatches && prefixMatches;
+        const canReuseState = canAttachState && cacheLiveMs > 6 * 60 * 1000 && itersSinceCreate < refreshEveryN;
+        try {
+            appendBridgeTrace({
+                sessionId: opts.sessionId || opts.session?.id || null,
+                iteration: currentIter,
+                kind: 'gemini_cache_decision',
+                payload: {
+                    hasState: !!state?.cacheName,
+                    stateCacheName: state?.cacheName || null,
+                    stateCreatedAtIter: state?.cacheCreatedAtIter ?? null,
+                    stateCacheModel: state?.cacheModel || null,
+                    statePrefixContentCount,
+                    statePrefixHash: state?.cachePrefixHash || null,
+                    currentStatePrefixHash,
+                    modelMatches,
+                    prefixMatches,
+                    canAttachState,
+                    cacheLiveMs,
+                    itersSinceCreate,
+                    refreshEveryN,
+                    decision: canReuseState ? 'reuse' : 'rebuild',
+                    contentsLen: Array.isArray(contents) ? contents.length : 0,
+                },
+            });
+        } catch {}
+        if (canReuseState) {
+            return state.cacheName;
+        }
+        if (!apiKey) return null;
+        // Pre-flight invariant: cachedContents.create rejects prefixes below
+        // the model-specific minimum. Skip the POST entirely when the estimate
+        // is under threshold so we don't spam 400 responses turn-after-turn.
+        const minTokens = _geminiCacheMinTokens(model);
+        const estimatedTokens = _estimateGeminiCacheTokens(systemInstruction, geminiTools, contents);
+        if (estimatedTokens < minTokens) {
+            try {
+                appendBridgeTrace({
+                    sessionId: opts.sessionId || opts.session?.id || null,
+                    iteration: currentIter,
+                    kind: 'gemini_cache_skip',
+                    payload: {
+                        reason: 'prefix_below_min',
+                        estimatedTokens,
+                        minTokens,
+                        model,
+                    },
+                });
+            } catch {}
+            return canAttachState ? state.cacheName : null;
+        }
+        try {
+            const ttlSeconds = 3600;
+            const cachePrefixContentCount = _geminiCachePrefixCount(contents);
+            const cachePrefixHash = _geminiCachePrefixHash({
+                model,
+                systemInstruction,
+                geminiTools,
+                contents,
+                prefixCount: cachePrefixContentCount,
+            });
+            const cachePrefixContents = _geminiCachePrefixContents(contents, cachePrefixContentCount);
+            const body = {
+                model: `models/${model}`,
+                ttl: `${ttlSeconds}s`,
+            };
+            if (systemInstruction) {
+                body.systemInstruction = { parts: [{ text: systemInstruction }] };
+            }
+            if (Array.isArray(geminiTools) && geminiTools.length) {
+                body.tools = geminiTools;
+            }
+            // Capture conversation prefix (everything except the latest user/
+            // tool input that the generateContent call will carry) inside the
+            // cache. cachedContents only accepts role='user' or 'model';
+            // generateContent uses role='function' for tool_result turns, so
+            // collapse that to 'user' (functionResponse parts remain inside).
+            if (cachePrefixContents.length) {
+                body.contents = cachePrefixContents;
+            }
+            const url = `https://generativelanguage.googleapis.com/v1beta/cachedContents?key=${encodeURIComponent(apiKey)}`;
+            // Honor the external session abort signal during cache creation, not
+            // only the 20s ceiling. Without merging opts.signal a session that is
+            // aborted (stall-watchdog / closeSession) mid-cache-create leaves this
+            // preflight request running until its own timeout fires.
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: opts.signal
+                    ? AbortSignal.any([opts.signal, AbortSignal.timeout(20_000)])
+                    : AbortSignal.timeout(20_000),
+                dispatcher: getLlmDispatcher(),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                try {
+                    appendBridgeTrace({
+                        sessionId: opts.sessionId || opts.session?.id || null,
+                        iteration: currentIter,
+                        kind: 'gemini_cache_create_fail',
+                        payload: {
+                            status: res.status,
+                            body: text.slice(0, 500),
+                            contentsLen: Array.isArray(contents) ? contents.length : 0,
+                            cachePrefixContentCount,
+                            canAttachState,
+                        },
+                    });
+                } catch {}
+                return canAttachState ? state.cacheName : null;
+            }
+            const data = await res.json();
+            const cacheName = data?.name || null;
+            if (!cacheName) return canAttachState ? state.cacheName : null;
+            const cacheTokenSize = Number(data?.usageMetadata?.totalTokenCount || 0) || 0;
+            try {
+                appendBridgeTrace({
+                    sessionId: opts.sessionId || opts.session?.id || null,
+                    iteration: currentIter,
+                    kind: 'gemini_cache_create_ok',
+                    payload: {
+                        cacheName,
+                        cacheTokenSize,
+                        contentsLen: Array.isArray(contents) ? contents.length : 0,
+                        cachePrefixContentCount,
+                        cachePrefixHash,
+                    },
+                });
+            } catch {}
+            // Best-effort cleanup of the previous cache so storage cost only
+            // accrues on the live revision. Fire-and-forget; TTL expiry covers
+            // any delete failures.
+            const priorCacheName = state?.cacheName || null;
+            if (priorCacheName && priorCacheName !== cacheName) {
+                const delUrl = `https://generativelanguage.googleapis.com/v1beta/${priorCacheName}?key=${encodeURIComponent(apiKey)}`;
+                fetch(delUrl, { method: 'DELETE', signal: AbortSignal.timeout(10_000), dispatcher: getLlmDispatcher() })
+                    .catch(() => { /* TTL expiry will reclaim it */ });
+            }
+            opts.providerState = {
+                ...(opts.providerState || {}),
+                gemini: {
+                    cacheName,
+                    cacheCreatedAt: now,
+                    cacheCreatedAtIter: currentIter,
+                    cacheExpiresAt: now + ttlSeconds * 1000,
+                    cacheModel: model,
+                    cacheTokenSize,
+                    cachePrefixContentCount,
+                    cachePrefixHash,
+                },
+            };
+            return cacheName;
+        } catch (err) {
+            process.stderr.write(`[gemini] cachedContents.create error: ${err?.message || err}\n`);
+            return canAttachState ? state.cacheName : null;
+        }
+    }
+
+    async send(messages, model, tools, sendOpts) {
+        try {
+            return await this._doSend(messages, model, tools, sendOpts);
+        } catch (err) {
+            if (err.message && (err.message.includes('401') || err.message.includes('403'))) {
+                process.stderr.write(`[provider] Auth error, re-reading config...\n`);
+                this.reloadApiKey();
+                return await this._doSend(messages, model, tools, sendOpts);
+            }
+            throw err;
+        }
+    }
+
+    async _doSend(messages, model, tools, sendOpts) {
+        const opts = sendOpts || {};
+        const signal = opts.signal || null;
+        if (signal?.aborted) {
+            const reason = signal.reason;
+            throw reason instanceof Error ? reason : new Error('Gemini request aborted by session close');
+        }
+
+        const useModel = model || await ensureLatestGeminiModel(this);
+        const systemInstruction = messages
+            .filter(m => m.role === 'system')
+            .map(m => m.content)
+            .join('\n\n') || undefined;
+        const chatMsgs = messages.filter(m => m.role !== 'system');
+        const contents = toGeminiContents(chatMsgs);
+        if (!contents.length)
+            throw new Error('No messages to send');
+
+        const geminiTools = tools?.length ? [toGeminiTools(tools)] : undefined;
+        const toolConfig = geminiTools ? toGeminiToolConfig(opts.toolChoice) : undefined;
+        try { opts.onStageChange?.('requesting'); } catch {}
+
+        // Explicit cachedContents (system + tools + prior-turn transcript).
+        // Per Google docs, `tools` must be supplied on BOTH the cache create
+        // call AND every subsequent generate_content call — the cache stores
+        // the schema for prompt-token credit but the runtime model still
+        // needs the tool schema to actually emit function calls. Sending
+        // cachedContent without tools yields an empty completion (function
+        // calling silently disabled). The contents payload captures the
+        // accumulated prefix; we refresh the cache every N iterations so
+        // recent turns also enter the cached prefix instead of being billed
+        // at full input rates.
+        const cachedContent = await this._ensureGeminiCache({
+            apiKey: this._getApiKey(),
+            model: useModel,
+            systemInstruction,
+            geminiTools,
+            contents,
+            opts,
+        });
+        try { opts.onStageChange?.('requesting'); } catch {}
+
+        // When cachedContent is attached we bypass @google/generative-ai
+        // (deprecated; v1beta v1.x docs explicitly forbid re-sending tools or
+        // systemInstruction once a cache carries them, but the bundled SDK
+        // can't actually issue a tool-less generateContent call). REST direct
+        // sends the v1beta payload Google's new genai client uses, so the
+        // cache owns system/tools and the runtime gets a clean cache hit.
+        let response;
+        if (cachedContent) {
+            const apiKey = this._getApiKey();
+            const genUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(useModel)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+            const cachedPrefixContentCount = Number.isFinite(Number(opts.providerState?.gemini?.cachePrefixContentCount))
+                ? Math.max(0, Math.min(contents.length, Math.trunc(Number(opts.providerState.gemini.cachePrefixContentCount))))
+                : 0;
+            const deltaContents = contents.slice(cachedPrefixContentCount);
+            // Cache carries the recorded prefix. Send every uncached tail turn,
+            // not just the last message, so reused cachedContents preserve
+            // full conversation context between periodic refreshes.
+            const body = {
+                contents: deltaContents.length ? deltaContents : contents.slice(-1),
+                cachedContent,
+            };
+            if (toolConfig) body.toolConfig = toolConfig;
+            const fetchResult = await runGeminiOperationWithTimeout({
+                label: 'Gemini REST generateContent total',
+                timeoutMs: GEMINI_GENERATE_TOTAL_TIMEOUT_MS,
+                signal,
+                run: (totalSignal) => withRetry(
+                    () => runGeminiOperationWithTimeout({
+                        label: 'Gemini REST generateContent first byte',
+                        timeoutMs: GEMINI_FIRST_BYTE_TIMEOUT_MS,
+                        signal: totalSignal,
+                        run: async (opSignal) => {
+                            const res = await fetch(genUrl, {
+                                method: 'POST',
+                                headers: { 'Content-Type': 'application/json' },
+                                body: JSON.stringify(body),
+                                signal: opSignal,
+                                dispatcher: getLlmDispatcher(),
+                            });
+                            if (!res.ok) {
+                                const text = await res.text().catch(() => '');
+                                const err = new Error(`Gemini REST generateContent ${res.status}: ${text.slice(0, 300)}`);
+                                err.status = res.status;
+                                throw err;
+                            }
+                            return await res.json();
+                        },
+                    }),
+                    {
+                        signal: totalSignal,
+                        onRetry: ({ attempt, lastErr }) => {
+                            try { opts.onStageChange?.('requesting'); } catch {}
+                            process.stderr.write(`[gemini-rest] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}\n`);
+                        },
+                    },
+                ),
+            });
+            response = fetchResult;
+        } else {
+            const genModel = this.genAI.getGenerativeModel({
+                model: useModel,
+                systemInstruction,
+                tools: geminiTools,
+                ...(toolConfig ? { toolConfig } : {}),
+            });
+            const result = await runGeminiOperationWithTimeout({
+                label: 'Gemini generateContent total',
+                timeoutMs: GEMINI_GENERATE_TOTAL_TIMEOUT_MS,
+                signal,
+                run: (totalSignal) => withRetry(
+                    () => runGeminiOperationWithTimeout({
+                        label: 'Gemini generateContent first byte',
+                        timeoutMs: GEMINI_FIRST_BYTE_TIMEOUT_MS,
+                        signal: totalSignal,
+                        run: (opSignal) => genModel.generateContent({ contents }, { signal: opSignal }),
+                    }),
+                    {
+                        signal: totalSignal,
+                        onRetry: ({ attempt, lastErr }) => {
+                            try { opts.onStageChange?.('requesting'); } catch {}
+                            process.stderr.write(`[gemini] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}\n`);
+                        },
+                    },
+                ),
+            });
+            response = result.response;
+        }
+        writeGeminiCacheTrace({
+            opts,
+            model: useModel,
+            systemInstruction,
+            tools,
+            contents,
+            usageMetadata: response.usageMetadata,
+            cachedContent,
+        });
+        const candidate = response.candidates?.[0] || null;
+        const textParts = candidate?.content?.parts?.filter(p => 'text' in p) ?? [];
+        const content = textParts.map(p => 'text' in p ? p.text : '').join('');
+        const toolCalls = parseToolCalls(candidate?.content?.parts ?? []);
+        // Inspect candidate.finishReason — Gemini reports terminal status here.
+        // Only STOP (and the legacy "FINISH_REASON_STOP") plus tool/function-
+        // call paths represent a fully delivered turn. MAX_TOKENS / SAFETY /
+        // RECITATION / OTHER all mean the candidate was cut off before the
+        // model finished, and surfacing the partial text as final would
+        // silently accept a truncated answer. Convert those into a typed
+        // provider-incomplete error so the loop can decide whether to retry,
+        // nudge, or surface to the user. Missing finishReason (still
+        // streaming / unknown) is left alone — existing success paths for
+        // genuinely complete responses keep working.
+        const finishReason = candidate?.finishReason || null;
+        const incompleteFinishReasons = new Set([
+            'MAX_TOKENS',
+            'SAFETY',
+            'RECITATION',
+            'OTHER',
+            'BLOCKLIST',
+            'PROHIBITED_CONTENT',
+            'SPII',
+            'MALFORMED_FUNCTION_CALL',
+        ]);
+        if (finishReason && incompleteFinishReasons.has(finishReason)) {
+            const err = Object.assign(
+                new Error(`Gemini response incomplete: finishReason=${finishReason}`),
+                {
+                    name: 'ProviderIncompleteError',
+                    code: 'PROVIDER_INCOMPLETE',
+                    providerIncomplete: true,
+                    finishReason,
+                    partialContent: content,
+                    partialToolCalls: toolCalls,
+                    model: useModel,
+                    rawUsage: response.usageMetadata || null,
+                },
+            );
+            throw err;
+        }
+        const um = response.usageMetadata || null;
+        // Hoist cachedTokens so the returned usage block can reuse the
+        // exact value the trace already recorded (including the
+        // cachedFallback when cachedContentTokenCount under-reports).
+        let cachedTokens = 0;
+        if (um) {
+            const {
+                inputTokens,
+                reportedCachedTokens,
+                cachedFallbackTokens,
+                cachedTokens: resolvedCachedTokens,
+                cacheTokenSource,
+            } = _resolveGeminiCacheUsage({
+                usageMetadata: um,
+                cachedContent,
+                providerState: opts.providerState,
+            });
+            cachedTokens = resolvedCachedTokens;
+            const outputTokens = (um.candidatesTokenCount || 0) + (um.thoughtsTokenCount || 0);
+            if (cachedContent && inputTokens > 0 && cachedTokens <= 0) {
+                try {
+                    appendBridgeTrace({
+                        sessionId: opts.sessionId || opts.session?.id || null,
+                        iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
+                        kind: 'gemini_cache_anomaly',
+                        payload: {
+                            reason: 'cached_content_attached_but_zero_cached_tokens',
+                            inputTokens,
+                            reportedCachedTokens,
+                            cachedFallbackTokens,
+                            cacheTokenSource,
+                            cacheName: opts.providerState?.gemini?.cacheName || null,
+                            cachePrefixContentCount: opts.providerState?.gemini?.cachePrefixContentCount ?? null,
+                        },
+                    });
+                } catch {}
+            }
+            traceBridgeUsage({
+                sessionId: opts.sessionId || opts.session?.id || null,
+                iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
+                inputTokens,
+                outputTokens,
+                cachedTokens,
+                cacheWriteTokens: 0,
+                promptTokens: inputTokens,
+                model: useModel,
+                modelDisplay: useModel,
+                rawUsage: um,
+                provider: 'gemini',
+            });
+        }
+        return {
+            content,
+            model: useModel,
+            toolCalls,
+            providerState: opts.providerState,
+            usage: um ? (() => {
+                const input = um.promptTokenCount || um.totalTokenCount || 0;
+                return {
+                    inputTokens: input,
+                    outputTokens: (um.candidatesTokenCount || 0) + (um.thoughtsTokenCount || 0),
+                    // Use the already-computed cachedTokens (with
+                    // cache-create fallback applied) rather than the raw
+                    // metadata field, so the returned usage matches what
+                    // traceBridgeUsage recorded for this same call.
+                    cachedTokens,
+                    // Gemini promptTokenCount is total (cachedContentTokenCount
+                    // is a subset). Alias directly into promptTokens.
+                    promptTokens: input,
+                };
+            })() : undefined,
+        };
+    }
+
+    async listModels() {
+        const cached = _loadModelCache();
+        if (cached) return cached;
+        // Dynamic lookup via Gemini v1beta /models. Requires API key.
+        const apiKey = this.config.apiKey || process.env.GEMINI_API_KEY;
+        if (!apiKey) return MODELS; // no key — return minimal static list
+        try {
+            return await this._fetchAndCacheModels(apiKey);
+        } catch (err) {
+            process.stderr.write(`[gemini] listModels fetch failed (${err.message})\n`);
+            return MODELS;
+        }
+    }
+
+    // Shared fetch+normalize+enrich+write used by both listModels() (after the
+    // TTL check) and _refreshModelCache() (bypassing it). Throws on failure so
+    // each caller applies its own fallback/logging.
+    async _fetchAndCacheModels(apiKey) {
+        const url = `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}`;
+        const listSignal = AbortSignal.timeout(60_000);
+        const res = await fetch(url, { signal: listSignal, dispatcher: getLlmDispatcher() });
+        if (!res.ok) throw new Error(`gemini list_models ${res.status}`);
+        const data = await res.json();
+        const items = Array.isArray(data?.models) ? data.models : [];
+        // Filter to Gemini family; skip embedding/imagen endpoints.
+        const normalized = items
+            .filter(m => (m?.name || '').includes('gemini'))
+            .filter(m => !/embedding|aqa|imagen/.test(m?.name || ''))
+            .map(m => {
+                const id = (m.name || '').replace(/^models\//, '');
+                const family = /flash-lite/.test(id) ? 'gemini-flash-lite'
+                    : /flash/.test(id) ? 'gemini-flash'
+                    : /pro/.test(id) ? 'gemini-pro'
+                    : 'gemini';
+                return {
+                    id,
+                    display: m.displayName || id,
+                    family,
+                    provider: 'gemini',
+                    contextWindow: m.inputTokenLimit || 1000000,
+                    outputTokens: m.outputTokenLimit || 8192,
+                    tier: 'version',
+                    latest: false,
+                    description: m.description || '',
+                };
+            });
+        _markLatestGemini(normalized);
+        // LiteLLM catalog overlays pricing and updated metadata.
+        const { enrichModels } = await import('./model-catalog.mjs');
+        const enriched = await enrichModels(normalized);
+        _saveModelCache(enriched);
+        return enriched;
+    }
+
+    // Force a catalog refresh (ignores the 24h disk TTL). De-duped via
+    // _modelRefreshInFlight so concurrent callers share one HTTP round-trip.
+    // Fire-and-forget context: failures are caught/logged, returning null.
+    async _refreshModelCache() {
+        if (_modelRefreshInFlight) return _modelRefreshInFlight;
+        _modelRefreshInFlight = (async () => {
+            try {
+                const apiKey = this.config.apiKey || process.env.GEMINI_API_KEY;
+                if (!apiKey) return null; // no key — nothing to refresh
+                const enriched = await this._fetchAndCacheModels(apiKey);
+                process.stderr.write(`[gemini] catalog refreshed (${enriched.length} models)\n`);
+                return enriched;
+            } catch (err) {
+                process.stderr.write(`[gemini] catalog refresh failed (${err.message})\n`);
+                return null;
+            } finally {
+                _modelRefreshInFlight = null;
+            }
+        })();
+        return _modelRefreshInFlight;
+    }
+
+    async isAvailable() {
+        try {
+            const model = this.genAI.getGenerativeModel({ model: DEFAULT_MODEL });
+            await model.generateContent('hi');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}