mixdog 0.7.18 → 0.8.0

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

@@ -1,1530 +0,0 @@
-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_NONSTREAM_TOTAL_TIMEOUT_MS,
-    PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
-    PROVIDER_MAX_BEFORE_WARN_MS,
-    PROVIDER_SSE_IDLE_TIMEOUT_MS,
-    PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
-    providerTimeoutError,
-    resolveTimeoutMs,
-    createTimeoutSignal,
-} 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));
-    });
-}
-
-function geminiTruncatedStreamError(message) {
-    return Object.assign(
-        new Error(message),
-        { name: 'TruncatedStreamError', code: 'TRUNCATED_STREAM', truncatedStream: true },
-    );
-}
-
-/**
- * Aggregate streamed GenerateContentResponse chunks into one response object
- * (same shape as a non-streaming generateContent JSON body).
- * Mirrors @google/generative-ai aggregateResponses().
- */
-function aggregateGeminiStreamChunks(responses) {
-    const lastResponse = responses[responses.length - 1];
-    const aggregatedResponse = {
-        promptFeedback: lastResponse?.promptFeedback,
-    };
-    for (const response of responses) {
-        if (response?.candidates) {
-            let candidateIndex = 0;
-            for (const candidate of response.candidates) {
-                if (!aggregatedResponse.candidates) aggregatedResponse.candidates = [];
-                if (!aggregatedResponse.candidates[candidateIndex]) {
-                    aggregatedResponse.candidates[candidateIndex] = { index: candidateIndex };
-                }
-                const aggCand = aggregatedResponse.candidates[candidateIndex];
-                aggCand.citationMetadata = candidate.citationMetadata;
-                aggCand.groundingMetadata = candidate.groundingMetadata;
-                aggCand.finishReason = candidate.finishReason;
-                aggCand.finishMessage = candidate.finishMessage;
-                aggCand.safetyRatings = candidate.safetyRatings;
-                if (candidate.content?.parts) {
-                    if (!aggCand.content) {
-                        aggCand.content = {
-                            role: candidate.content.role || 'user',
-                            parts: [],
-                        };
-                    }
-                    for (const part of candidate.content.parts) {
-                        const newPart = {};
-                        if (part.text) newPart.text = part.text;
-                        if (part.functionCall) newPart.functionCall = part.functionCall;
-                        if (part.thoughtSignature) newPart.thoughtSignature = part.thoughtSignature;
-                        if (part.thought_signature) newPart.thought_signature = part.thought_signature;
-                        if (part.executableCode) newPart.executableCode = part.executableCode;
-                        if (part.codeExecutionResult) newPart.codeExecutionResult = part.codeExecutionResult;
-                        if (Object.keys(newPart).length === 0) newPart.text = '';
-                        aggCand.content.parts.push(newPart);
-                    }
-                }
-                candidateIndex++;
-            }
-        }
-        if (response?.usageMetadata) aggregatedResponse.usageMetadata = response.usageMetadata;
-    }
-    return aggregatedResponse;
-}
-
-function assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label }) {
-    if (!sawStreamChunk) {
-        throw geminiTruncatedStreamError(`${label} truncated: empty stream`);
-    }
-    if (!finishReason) {
-        throw geminiTruncatedStreamError(`${label} truncated: no finishReason`);
-    }
-}
-
-async function consumeGeminiRestStreamResponse(response, { signal, onStreamDelta, label }) {
-    if (!response?.body) throw new Error(`${label}: missing response body`);
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-    const allChunks = [];
-    let sawStreamChunk = false;
-    let idleTimedOut = false;
-    let idleTimer = null;
-    let idleReject = null;
-
-    let firstByteTimer = setTimeout(() => {
-        try { reader.cancel('first byte timeout'); } catch {}
-        if (idleReject) {
-            const e = geminiTimeoutError(`${label} first byte`, GEMINI_FIRST_BYTE_TIMEOUT_MS);
-            const r = idleReject; idleReject = null; r(e);
-        }
-    }, GEMINI_FIRST_BYTE_TIMEOUT_MS);
-    if (firstByteTimer.unref) firstByteTimer.unref();
-
-    const clearFirstByteTimer = () => {
-        if (firstByteTimer) {
-            clearTimeout(firstByteTimer);
-            firstByteTimer = null;
-        }
-    };
-
-    const resetIdleTimer = () => {
-        if (!PROVIDER_SSE_IDLE_WATCHDOG_ENABLED) return;
-        if (idleTimer) clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-            idleTimedOut = true;
-            try { reader.cancel('SSE idle timeout'); } catch {}
-            if (idleReject) {
-                const e = geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-                const r = idleReject; idleReject = null; r(e);
-            }
-        }, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-        if (idleTimer.unref) idleTimer.unref();
-    };
-
-    const onAbort = () => {
-        try {
-            const c = reader.cancel('aborted');
-            if (c && typeof c.catch === 'function') c.catch(() => {});
-        } catch {}
-    };
-
-    if (signal) {
-        if (signal.aborted) {
-            const reason = signal.reason;
-            throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-        }
-        signal.addEventListener('abort', onAbort, { once: true });
-    }
-
-    try {
-        resetIdleTimer();
-        while (true) {
-            let chunk;
-            try {
-                chunk = await new Promise((resolve, reject) => {
-                    idleReject = reject;
-                    reader.read().then(resolve, reject);
-                });
-            } catch (err) {
-                if (idleTimedOut) {
-                    throw geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-                }
-                if (signal?.aborted) {
-                    const reason = signal.reason;
-                    throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-                }
-                throw err;
-            } finally {
-                idleReject = null;
-            }
-            const { done, value } = chunk;
-            if (done) break;
-            resetIdleTimer();
-            buffer += decoder.decode(value, { stream: true });
-            let lineEnd;
-            while ((lineEnd = buffer.indexOf('\n')) >= 0) {
-                let line = buffer.slice(0, lineEnd);
-                buffer = buffer.slice(lineEnd + 1);
-                line = line.replace(/\r$/, '');
-                if (!line.startsWith('data: ')) continue;
-                const data = line.slice(6).trim();
-                if (!data || data === '[DONE]') continue;
-                let parsed;
-                try { parsed = JSON.parse(data); } catch { continue; }
-                if (!sawStreamChunk) {
-                    sawStreamChunk = true;
-                    clearFirstByteTimer();
-                }
-                allChunks.push(parsed);
-                try { onStreamDelta?.(); } catch {}
-            }
-        }
-        if (buffer.trim()) {
-            const line = buffer.trim().replace(/\r$/, '');
-            if (line.startsWith('data: ')) {
-                const data = line.slice(6).trim();
-                if (data && data !== '[DONE]') {
-                    try {
-                        const parsed = JSON.parse(data);
-                        if (!sawStreamChunk) {
-                            sawStreamChunk = true;
-                            clearFirstByteTimer();
-                        }
-                        allChunks.push(parsed);
-                        try { onStreamDelta?.(); } catch {}
-                    } catch { /* skip malformed tail */ }
-                }
-            }
-        }
-    } finally {
-        clearFirstByteTimer();
-        if (idleTimer) clearTimeout(idleTimer);
-        if (signal) signal.removeEventListener('abort', onAbort);
-        try { reader.releaseLock(); } catch {}
-    }
-
-    const aggregated = aggregateGeminiStreamChunks(allChunks);
-    const finishReason = aggregated.candidates?.[0]?.finishReason || null;
-    assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
-    return aggregated;
-}
-
-async function consumeGeminiSdkStream(streamResult, { signal, onStreamDelta, label }) {
-    let sawStreamChunk = false;
-    let idleTimedOut = false;
-    let idleTimer = null;
-    let firstByteReject = null;
-    let firstByteTimer = null;
-    let inFlightReject = null;
-
-    const armFirstByteTimer = () => {
-        if (firstByteTimer) clearTimeout(firstByteTimer);
-        firstByteTimer = setTimeout(() => {
-            if (firstByteReject) {
-                const e = geminiTimeoutError(`${label} first byte`, GEMINI_FIRST_BYTE_TIMEOUT_MS);
-                const r = firstByteReject; firstByteReject = null; r(e);
-            }
-        }, GEMINI_FIRST_BYTE_TIMEOUT_MS);
-        if (firstByteTimer.unref) firstByteTimer.unref();
-    };
-
-    const clearFirstByteTimer = () => {
-        if (firstByteTimer) {
-            clearTimeout(firstByteTimer);
-            firstByteTimer = null;
-        }
-        firstByteReject = null;
-    };
-
-    const resetIdleTimer = () => {
-        if (!PROVIDER_SSE_IDLE_WATCHDOG_ENABLED) return;
-        if (idleTimer) clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-            idleTimedOut = true;
-            if (inFlightReject) {
-                const e = geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-                const r = inFlightReject; inFlightReject = null; r(e);
-            }
-        }, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-        if (idleTimer.unref) idleTimer.unref();
-    };
-
-    if (signal?.aborted) {
-        const reason = signal.reason;
-        throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-    }
-
-    const iterator = streamResult.stream[Symbol.asyncIterator]();
-
-    try {
-        armFirstByteTimer();
-        resetIdleTimer();
-        while (true) {
-            if (idleTimedOut) {
-                throw geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-            }
-            let step;
-            try {
-                step = await new Promise((resolve, reject) => {
-                    inFlightReject = reject;
-                    if (!sawStreamChunk) firstByteReject = reject;
-                    iterator.next().then(
-                        (value) => {
-                            inFlightReject = null;
-                            firstByteReject = null;
-                            resolve(value);
-                        },
-                        (err) => {
-                            inFlightReject = null;
-                            firstByteReject = null;
-                            reject(err);
-                        },
-                    );
-                });
-            } catch (err) {
-                if (idleTimedOut) {
-                    throw geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-                }
-                if (signal?.aborted) {
-                    const reason = signal.reason;
-                    throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-                }
-                throw err;
-            }
-            if (step.done) break;
-            if (!sawStreamChunk) {
-                sawStreamChunk = true;
-                clearFirstByteTimer();
-            }
-            resetIdleTimer();
-            try { onStreamDelta?.(); } catch {}
-        }
-        if (idleTimedOut) {
-            throw geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
-        }
-    } catch (err) {
-        clearFirstByteTimer();
-        if (signal?.aborted) {
-            const reason = signal.reason;
-            throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-        }
-        throw err;
-    } finally {
-        clearFirstByteTimer();
-        if (idleTimer) clearTimeout(idleTimer);
-    }
-
-    let response;
-    try {
-        response = await streamResult.response;
-    } catch (err) {
-        if (signal?.aborted) {
-            const reason = signal.reason;
-            throw reason instanceof Error ? reason : new Error(`${label} aborted`);
-        }
-        throw err;
-    }
-    const raw = response?.candidates ? response : (response?.response || response);
-    const finishReason = raw?.candidates?.[0]?.finishReason || null;
-    assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
-    return raw;
-}
-
-/**
- * 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;
-        const onStreamDelta = typeof opts.onStreamDelta === 'function' ? opts.onStreamDelta : 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)}:streamGenerateContent?alt=sse&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;
-            response = await runGeminiOperationWithTimeout({
-                label: 'Gemini REST streamGenerateContent total',
-                timeoutMs: PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS,
-                signal,
-                run: (totalSignal) => withRetry(
-                    async ({ signal: attemptSignal }) => {
-                        try { opts.onStageChange?.('requesting'); } catch {}
-                        const openFirstByte = createTimeoutSignal(
-                            attemptSignal,
-                            GEMINI_FIRST_BYTE_TIMEOUT_MS,
-                            'Gemini REST first byte',
-                        );
-                        let res;
-                        try {
-                            res = await fetch(genUrl, {
-                                method: 'POST',
-                                headers: { 'Content-Type': 'application/json' },
-                                body: JSON.stringify(body),
-                                signal: openFirstByte.signal,
-                                dispatcher: getLlmDispatcher(),
-                            });
-                        } finally {
-                            openFirstByte.cleanup();
-                        }
-                        if (!res.ok) {
-                            const text = await res.text().catch(() => '');
-                            const err = new Error(`Gemini REST streamGenerateContent ${res.status}: ${text.slice(0, 300)}`);
-                            err.status = res.status;
-                            throw err;
-                        }
-                        return await consumeGeminiRestStreamResponse(res, {
-                            signal: attemptSignal,
-                            onStreamDelta,
-                            label: 'Gemini REST streamGenerateContent',
-                        });
-                    },
-                    {
-                        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`);
-                        },
-                    },
-                ),
-            });
-        } else {
-            const genModel = this.genAI.getGenerativeModel({
-                model: useModel,
-                systemInstruction,
-                tools: geminiTools,
-                ...(toolConfig ? { toolConfig } : {}),
-            });
-            response = await runGeminiOperationWithTimeout({
-                label: 'Gemini streamGenerateContent total',
-                timeoutMs: PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS,
-                signal,
-                run: (totalSignal) => withRetry(
-                    async ({ signal: attemptSignal }) => {
-                        try { opts.onStageChange?.('requesting'); } catch {}
-                        const openFirstByte = createTimeoutSignal(
-                            attemptSignal,
-                            GEMINI_FIRST_BYTE_TIMEOUT_MS,
-                            'Gemini SDK first byte',
-                        );
-                        let streamResult;
-                        try {
-                            try {
-                                streamResult = await genModel.generateContentStream(
-                                    { contents },
-                                    { signal: openFirstByte.signal },
-                                );
-                            } catch (err) {
-                                if (openFirstByte.signal.aborted) {
-                                    throw openFirstByte.signal.reason instanceof Error
-                                        ? openFirstByte.signal.reason
-                                        : err;
-                                }
-                                throw err;
-                            }
-                        } finally {
-                            openFirstByte.cleanup();
-                        }
-                        return await consumeGeminiSdkStream(streamResult, {
-                            signal: attemptSignal,
-                            onStreamDelta,
-                            label: 'Gemini SDK streamGenerateContent',
-                        });
-                    },
-                    {
-                        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`);
-                        },
-                    },
-                ),
-            });
-        }
-        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;
-        }
-    }
-}