mixdog 0.9.3 → 0.9.5

package/src/runtime/agent/orchestrator/providers/codex-client-meta.mjs

@@ -0,0 +1,81 @@
+/**
+ * codex-client-meta.mjs — codex client identity headers for the OpenAI OAuth
+ * transports.
+ *
+ * codex-rs sends two client-identity headers on EVERY request including the
+ * WS handshake:
+ *  - `User-Agent: codex_cli_rs/<version> (<os> <ver>; <arch>) <terminal>`
+ *    (login/src/auth/default_client.rs get_codex_user_agent + default_headers)
+ *  - `version: <CARGO_PKG_VERSION>` via the built-in provider http_headers
+ *    (model-provider-info/src/lib.rs:339-343), merged into the WS handshake by
+ *    merge_request_headers (codex-api/src/endpoint/responses_websocket.rs).
+ * The backend uses these for client gating (model catalog visibility measured
+ * 2026-07-03) and plausibly for x-codex-turn-state issuance / sticky
+ * cache-node routing, so mixdog mirrors both.
+ */
+import os from 'node:os';
+
+// Offline fallback only; live value refreshes from npm (24h TTL, in-process).
+export const CODEX_CLIENT_VERSION_FLOOR = '0.142.5';
+const VERSION_TTL_MS = 24 * 60 * 60_000;
+let _cache = { value: null, fetchedAt: 0 };
+let _refreshInFlight = null;
+
+async function _refresh() {
+    try {
+        const res = await fetch('https://registry.npmjs.org/@openai/codex/latest', {
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (res.ok) {
+            const j = await res.json();
+            const v = String(j?.version || '').trim();
+            if (/^\d+\.\d+\.\d+/.test(v)) {
+                _cache = { value: v, fetchedAt: Date.now() };
+                return v;
+            }
+        }
+    } catch { /* offline — keep floor */ }
+    _cache = { value: CODEX_CLIENT_VERSION_FLOOR, fetchedAt: Date.now() };
+    return CODEX_CLIENT_VERSION_FLOOR;
+}
+
+/**
+ * Sync accessor for hot request paths: returns the cached npm version when
+ * fresh, otherwise kicks a background refresh and returns the floor. The
+ * handshake must never await a registry fetch.
+ */
+export function codexClientVersionSync() {
+    if (_cache.value && Date.now() - _cache.fetchedAt < VERSION_TTL_MS) return _cache.value;
+    if (!_refreshInFlight) {
+        _refreshInFlight = _refresh().finally(() => { _refreshInFlight = null; });
+    }
+    return _cache.value || CODEX_CLIENT_VERSION_FLOOR;
+}
+
+function _osType() {
+    // codex os_info reports "Windows"/"Mac OS"/"Linux"; node os.type() gives
+    // Windows_NT/Darwin/Linux. Map to codex's vocabulary.
+    const t = os.type();
+    if (t === 'Windows_NT') return 'Windows';
+    if (t === 'Darwin') return 'Mac OS';
+    return t;
+}
+
+function _arch() {
+    // codex reports rust-style arch tokens.
+    const a = os.arch();
+    if (a === 'x64') return 'x86_64';
+    if (a === 'arm64') return 'aarch64';
+    return a;
+}
+
+/** codex_cli_rs/<version> (<os> <ver>; <arch>) <terminal> */
+export function codexUserAgent() {
+    const terminal = String(process.env.TERM_PROGRAM || 'unknown').trim() || 'unknown';
+    return `codex_cli_rs/${codexClientVersionSync()} (${_osType()} ${os.release()}; ${_arch()}) ${terminal}`;
+}
+
+/** Bare version header value — codex built-in provider http_headers "version". */
+export function codexVersionHeader() {
+    return codexClientVersionSync();
+}

package/src/runtime/agent/orchestrator/providers/gemini-cache.mjs

@@ -0,0 +1,248 @@
+/**
+ * gemini-cache.mjs — Gemini explicit cachedContents prefix accounting:
+ * token estimation, prefix hashing, the process-global cache registry
+ * (create de-dupe + prune), cache-state attach, usage resolution, and the
+ * cache trace writer.
+ *
+ * Extracted from gemini.mjs (no behavior change). Owns the module-level
+ * geminiGlobalCaches / geminiGlobalCacheCreates maps. gemini.mjs imports
+ * these helpers; no re-export needed (all names are internal to the
+ * provider — none were part of the module's external surface).
+ */
+import { traceHash, stableTraceStringify, summarizeTraceTools, traceTextShape } from './trace-utils.mjs';
+
+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),
+    ];
+}
+
+// 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).
+export 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);
+}
+
+export function _geminiCacheMinTokens(model) {
+    return /^gemini-3/i.test(String(model || '')) ? 4096 : 2048;
+}
+
+export function _geminiCachePrefixCount(contents) {
+    return Array.isArray(contents) && contents.length > 1 ? contents.length - 1 : 0;
+}
+
+export 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 : [],
+        };
+    });
+}
+
+export function _geminiCachePrefixHash({ model, systemInstruction, geminiTools, contents, prefixCount }) {
+    return traceHash(stableTraceStringify({
+        model: model || null,
+        systemInstruction: systemInstruction || '',
+        tools: geminiTools || [],
+        contents: _geminiCachePrefixContents(contents, prefixCount),
+    }));
+}
+
+export const GEMINI_GLOBAL_CACHE_MIN_LIVE_MS = 6 * 60 * 1000;
+export const GEMINI_GLOBAL_CACHE_MAX_ENTRIES = 128;
+// Grace window before deleting a superseded cachedContents name (see the
+// cross-session race note at the delete call site in gemini.mjs). Long enough
+// that a concurrent session still mid-flight on the old name has time to finish.
+export const GEMINI_GLOBAL_CACHE_DELETE_GRACE_MS = 2 * 60 * 1000;
+export const geminiGlobalCaches = new Map();
+export const geminiGlobalCacheCreates = new Map();
+
+export function _geminiGlobalCacheKey({ apiKey, model, cachePrefixHash, cachePrefixContentCount }) {
+    return traceHash(stableTraceStringify({
+        apiKeyHash: traceHash(apiKey || ''),
+        model: model || null,
+        cachePrefixHash,
+        cachePrefixContentCount,
+    }));
+}
+
+export function _pruneGeminiGlobalCaches(now = Date.now()) {
+    for (const [key, entry] of geminiGlobalCaches) {
+        if (!entry?.cacheName || Number(entry.cacheExpiresAt || 0) <= now) {
+            geminiGlobalCaches.delete(key);
+        }
+    }
+    while (geminiGlobalCaches.size > GEMINI_GLOBAL_CACHE_MAX_ENTRIES) {
+        const oldest = geminiGlobalCaches.keys().next().value;
+        if (oldest === undefined) break;
+        geminiGlobalCaches.delete(oldest);
+    }
+}
+
+export function _getGeminiGlobalCache(key, now = Date.now()) {
+    _pruneGeminiGlobalCaches(now);
+    const entry = geminiGlobalCaches.get(key);
+    if (!entry?.cacheName) return null;
+    if ((entry.cacheExpiresAt || 0) - now <= GEMINI_GLOBAL_CACHE_MIN_LIVE_MS) {
+        geminiGlobalCaches.delete(key);
+        return null;
+    }
+    entry.lastUsedAt = now;
+    return entry;
+}
+
+export function _setGeminiGlobalCache(key, entry) {
+    if (!key || !entry?.cacheName) return;
+    geminiGlobalCaches.set(key, {
+        ...entry,
+        lastUsedAt: Date.now(),
+    });
+    _pruneGeminiGlobalCaches();
+}
+
+export function _geminiGlobalCacheNameIsLive(cacheName, now = Date.now()) {
+    if (!cacheName) return false;
+    for (const entry of geminiGlobalCaches.values()) {
+        if (entry?.cacheName === cacheName && Number(entry.cacheExpiresAt || 0) > now) return true;
+    }
+    return false;
+}
+
+export function _attachGeminiCacheState(opts, entry, currentIter) {
+    if (!entry?.cacheName) return;
+    opts.providerState = {
+        ...(opts.providerState || {}),
+        gemini: {
+            cacheName: entry.cacheName,
+            cacheCreatedAt: entry.cacheCreatedAt,
+            cacheCreatedAtIter: currentIter,
+            cacheExpiresAt: entry.cacheExpiresAt,
+            cacheModel: entry.cacheModel,
+            cacheTokenSize: entry.cacheTokenSize,
+            cachePrefixContentCount: entry.cachePrefixContentCount,
+            cachePrefixHash: entry.cachePrefixHash,
+        },
+    };
+}
+
+export 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,
+    };
+}
+
+export 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,
+            agent: session.agent || 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`);
+    }
+}

package/src/runtime/agent/orchestrator/providers/gemini-schema.mjs

@@ -0,0 +1,303 @@
+/**
+ * gemini-schema.mjs — Gemini request-shape conversion: JSON Schema → Gemini
+ * FunctionDeclarationSchema, tool/tool-config mapping, message → content
+ * mapping, tool-call parsing/emission, and grounding-source collection.
+ *
+ * Extracted from gemini.mjs (no behavior change). Pure functions only — no
+ * module state. gemini.mjs re-exports parseToolCalls / emitGeminiToolCalls /
+ * collectGeminiGroundingSources so existing importers (tests, gemini-stream)
+ * keep resolving through the facade.
+ */
+import { SchemaType } from '@google/generative-ai';
+import { traceHash, stableTraceStringify } from './trace-utils.mjs';
+import { normalizeContentForGeminiParts, splitToolContentForGemini } from './media-normalization.mjs';
+
+/**
+ * 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',
+]);
+export 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;
+}
+
+export function toGeminiTools(tools) {
+    return {
+        functionDeclarations: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: convertSchema(t.inputSchema),
+        })),
+    };
+}
+export function toGeminiNativeTools(nativeTools) {
+    if (!Array.isArray(nativeTools)) return [];
+    const out = [];
+    for (const tool of nativeTools) {
+        const type = String(tool?.type || '').trim().toLowerCase();
+        if (type === 'google_search' || type === 'google_search_retrieval') {
+            out.push({ googleSearch: {} });
+        }
+    }
+    return out;
+}
+
+// Exported for gemini-stream.mjs (stream consumers collect citations).
+export function collectGeminiGroundingSources(candidate) {
+    const out = [];
+    const seen = new Set();
+    const add = (source) => {
+        if (!source || typeof source !== 'object') return;
+        const web = source.web && typeof source.web === 'object' ? source.web : source;
+        const url = String(web.uri || web.url || source.uri || source.url || '').trim();
+        if (!url || seen.has(url)) return;
+        seen.add(url);
+        out.push({
+            title: String(web.title || source.title || url).trim(),
+            url,
+            snippet: '',
+            source: 'gemini-grounding',
+            provider: 'gemini',
+        });
+    };
+    const grounding = candidate?.groundingMetadata || {};
+    for (const chunk of Array.isArray(grounding.groundingChunks) ? grounding.groundingChunks : []) add(chunk);
+    const citationMetadata = candidate?.citationMetadata || {};
+    for (const source of Array.isArray(citationMetadata.citationSources) ? citationMetadata.citationSources : []) add(source);
+    return out;
+}
+
+// Map the orchestrator-level toolChoice to Gemini's functionCallingConfig.
+//   auto      -> AUTO
+//   required  -> ANY
+//   none      -> NONE
+//   { name }  -> ANY + allowedFunctionNames:[name]   (specific tool)
+export 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(...normalizeContentForGeminiParts(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
+            || '';
+        const { response, mediaParts } = splitToolContentForGemini(message.content);
+        const parts = [{ functionResponse: { name: functionName, response } }];
+        if (mediaParts.length) parts.push(...mediaParts);
+        return {
+            role: 'user',
+            parts,
+        };
+    }
+    return {
+        role: message.role === 'assistant' ? 'model' : 'user',
+        parts: normalizeContentForGeminiParts(message.content),
+    };
+}
+
+export 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;
+}
+
+export 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 idHash = traceHash(stableTraceStringify({
+            index: i,
+            name: fc.name || '',
+            args: fc.args ?? {},
+        })).slice(0, 16);
+        const call = {
+            id: `gemini_${idHash}`,
+            name: fc.name,
+            arguments: (fc.args ?? {}),
+        };
+        if (sig) call.thoughtSignature = sig;
+        return call;
+    });
+}
+
+// Exported for gemini-stream.mjs (leak-guard + stream consumers).
+export function emitGeminiToolCalls(toolCalls, onToolCall) {
+    if (typeof onToolCall !== 'function' || !Array.isArray(toolCalls)) return;
+    const emitted = new Set();
+    for (const call of toolCalls) {
+        if (!call?.id || !call?.name || emitted.has(call.id)) continue;
+        emitted.add(call.id);
+        try { onToolCall(call); } catch {}
+    }
+}