mixdog 0.9.50 → 0.9.52

package/src/runtime/agent/orchestrator/providers/anthropic-sse.mjs

@@ -49,8 +49,8 @@ function _captureMidstreamAbort(state, reason) {
 
 // Abort-aware mid-stream backoff sleep → shared sleepWithAbort
 // (retry-classifier.mjs). abortMessage preserves the prior fallback text.
-export function _midstreamSleepWithAbort(ms, signal) {
-    return sleepWithAbort(ms, signal, undefined, 'Anthropic OAuth mid-stream retry backoff aborted');
+export function _midstreamSleepWithAbort(ms, signal, sleepFn) {
+    return sleepWithAbort(ms, signal, sleepFn, 'Anthropic OAuth mid-stream retry backoff aborted');
 }
 
 function _statusForAnthropicSseError(type, message) {
@@ -83,9 +83,8 @@ function _anthropicSseError(event) {
 }
 
 export async function parseSSEStream(response, signal, abortStream, onStreamDelta, onToolCall, state, onTextDelta, knownToolNames) {
-    // parseSSEStream is entered only after Anthropic returned an HTTP response.
-    // Headers prove transport health, but are not a semantic model event.
-    try { onStreamDelta?.('transport'); } catch {}
+    // onStreamDelta is a semantic-progress callback. HTTP headers and raw SSE
+    // bytes prove transport health but must not refresh semantic watchdogs.
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     // SEMANTIC idle window: reset only by real model events (message/content/
@@ -287,17 +286,18 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
             if (_c && typeof _c.catch === 'function') _c.catch(() => {});
         } catch {}
     };
-    if (signal) {
-        if (signal.aborted) {
-            _captureMidstreamAbort(state, signal.reason);
-            throw signal.reason instanceof Error
-                ? signal.reason
-                : new Error('Anthropic OAuth SSE stream aborted');
-        }
-        signal.addEventListener('abort', onAbort, { once: true });
-    }
-
     try {
+        // Reader ownership begins at getReader() above, so even a signal that
+        // was already aborted must pass through this try/finally cleanup path.
+        if (signal) {
+            if (signal.aborted) {
+                _captureMidstreamAbort(state, signal.reason);
+                throw signal.reason instanceof Error
+                    ? signal.reason
+                    : new Error('Anthropic OAuth SSE stream aborted');
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
         // Part A / reviewer fix: do NOT arm the SEMANTIC idle timer before the
         // stream has produced its first event. A slow first response is governed
         // by armFirstMessageTimer() (first-byte window) alone; arming the
@@ -331,8 +331,6 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
             }
             const { done, value } = chunk;
             if (done) break;
-            try { onStreamDelta?.('transport'); } catch {}
-
             buffer += decoder.decode(value, { stream: true });
             const lines = buffer.split('\n');
             buffer = lines.pop() || '';
@@ -382,6 +380,12 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                     if (event.type === 'message_start' && event.message) {
                         clearFirstMessageTimer();
                         if (state) state.sawMessageStart = true;
+                        // The first protocol event proves the response transport
+                        // is live. Report it only here (never for raw bytes,
+                        // comments, or ping events), then separately report the
+                        // semantic message boundary. Content kinds remain
+                        // reasoning/text/tool-specific below.
+                        try { onStreamDelta?.('transport'); } catch {}
                         try { onStreamDelta?.('semantic'); } catch {}
                         if (event.message.model) model = event.message.model;
                         if (event.message.usage) {
@@ -395,6 +399,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                     if (event.type === 'content_block_start') {
                         const block = event.content_block;
                         if (block?.type === 'tool_use') {
+                            if (state) state.partialToolCall = true;
                             pendingToolInputs.set(event.index, {
                                 id: block.id || '',
                                 name: block.name || '',
@@ -402,6 +407,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                             });
                         }
                         if (block?.type === 'thinking' || block?.type === 'redacted_thinking') {
+                            if (state) state.emittedThinking = true;
                             if (block.type === 'redacted_thinking') {
                                 // Redacted blocks round-trip EXACTLY as
                                 // {type:'redacted_thinking',data} — no thinking/
@@ -463,6 +469,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                             }
                         }
                         if (delta?.type === 'thinking_delta' || delta?.type === 'signature_delta') {
+                            if (state) state.emittedThinking = true;
                             // Extended-thinking block: provider reasoning without
                             // user-visible text. Track presence so a final turn
                             // that emitted ONLY thinking (no text_delta, no
@@ -490,6 +497,7 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
                             }
                         }
                         if (delta?.type === 'input_json_delta') {
+                            if (state) state.partialToolCall = true;
                             const pending = pendingToolInputs.get(event.index);
                             if (pending) {
                                 pending.inputJson += delta.partial_json || '';
@@ -658,6 +666,10 @@ export async function parseSSEStream(response, signal, abortStream, onStreamDelt
         if (idleTimer) clearTimeout(idleTimer);
         clearFirstMessageTimer();
         if (signal) signal.removeEventListener('abort', onAbort);
+        // message_stop deliberately exits before EOF because Anthropic may keep
+        // sending pings. Cancel the reader so the successful response body and
+        // underlying keep-alive connection are not stranded.
+        try { await reader.cancel('Anthropic SSE complete'); } catch {}
         try { reader.releaseLock(); } catch (err) {
             try { process.stderr.write(`[anthropic-oauth] reader releaseLock failed: ${err?.message ?? String(err)}\n`); } catch {}
         }

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -1,7 +1,18 @@
 import { createRequire } from 'node:module';
 import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
 import { sanitizeToolPairs, sanitizeAnthropicContentPairs, foldUserTextIntoToolResultTail } from '../session/context-utils.mjs';
-import { classifyError, midstreamBackoffFor, sleepWithAbort, withRetry, retryAfterMsFromError } from './retry-classifier.mjs';
+import {
+    ANTHROPIC_RETRY_BACKOFF_MS,
+    ANTHROPIC_RETRY_JITTER_RATIO,
+    AnthropicFallbackTriggeredError,
+    anthropicMaxAttempts,
+    anthropicRequestTimeoutMs,
+    classifyError,
+    midstreamBackoffFor,
+    sleepWithAbort,
+    withRetry,
+    retryAfterMsFromError,
+} from './retry-classifier.mjs';
 import { traceAgentUsage } from '../agent-trace.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
@@ -23,9 +34,11 @@ import {
 import { normalizeContentForAnthropic } from './media-normalization.mjs';
 import { enrichModels } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
+import { providerNativeToolPrefixCount } from '../../../../session-runtime/provider-request-tools.mjs';
 import { makeModelCache } from './model-cache.mjs';
 import { resolveAnthropicMaxTokens } from './anthropic-max-tokens.mjs';
 import { getLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
+import { notifyCurrentAnthropicRateLimit } from './admission-scheduler.mjs';
 
 const require = createRequire(import.meta.url);
 let _Anthropic = null;
@@ -231,7 +244,12 @@ function resolveMaxTokens(model) {
 }
 
 // Test-only escape hatch for scripts/anthropic-maxtokens-test.mjs.
-export const _test = { resolveMaxTokens, deferredAnthropicTools, sanitizeInputSchema: _sanitizeInputSchema };
+export const _test = {
+    resolveMaxTokens,
+    deferredAnthropicTools,
+    requestAnthropicTools,
+    sanitizeInputSchema: _sanitizeInputSchema,
+};
 
 const MIN_THINKING_BUDGET = 1024;
 const THINKING_OUTPUT_RESERVE = 1024;
@@ -356,6 +374,24 @@ function deferredAnthropicTools(activeTools, messages, opts) {
         .filter((tool) => tool?.name && discovered.has(String(tool.name)) && !active.has(String(tool.name)))
         .map((tool) => ({ ...tool, deferLoading: true }));
 }
+function requestAnthropicTools(tools, messages, opts) {
+    const activeTools = Array.isArray(tools) ? tools : [];
+    if (opts?.providerToolSnapshotAuthoritative === true) {
+        const nativePrefixCount = providerNativeToolPrefixCount(
+            activeTools,
+            opts.providerNativeToolPrefixCount,
+        );
+        return [
+            ...activeTools.slice(0, nativePrefixCount),
+            ...toAnthropicTools(activeTools.slice(nativePrefixCount)),
+        ];
+    }
+    const deferredTools = deferredAnthropicTools(activeTools, messages, opts);
+    return [
+        ...nativeAnthropicTools(opts),
+        ...toAnthropicTools([...activeTools, ...deferredTools]),
+    ];
+}
 function toAnthropicMessages(messages) {
     // Marker-free lowering. cache_control is applied AFTER sanitization by
     // applyAnthropicCacheMarkers() so that block drops/inserts/reorders
@@ -409,6 +445,7 @@ function toAnthropicMessages(messages) {
                 content: references.length
                     ? references.map((tool_name) => ({ type: 'tool_reference', tool_name }))
                     : normalizeContentForAnthropic(m.content),
+                ...((m.toolKind === 'error' || m.isError === true) ? { is_error: true } : {}),
             };
             if (last?.role === 'user' && Array.isArray(last.content)) {
                 last.content.push(block);
@@ -549,15 +586,18 @@ export class AnthropicProvider {
     name = 'anthropic';
     client;
     config;
+    apiKey;
     fastModeBetaHeaderLatched = false;
     constructor(config) {
-        this.config = config;
-        this.name = config.name || 'anthropic';
-        const betaHeaders = config.disableBetaHeaders ? null : buildAnthropicBetaHeaders({ toolSearch: true });
+        this.config = config || {};
+        this.name = this.config.name || 'anthropic';
+        this.apiKey = this.config.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+        const betaHeaders = this.config.disableBetaHeaders ? null : buildAnthropicBetaHeaders();
         this.client = new (loadAnthropic())({
-            apiKey: config.apiKey || process.env.ANTHROPIC_API_KEY,
-            ...(config.baseURL ? { baseURL: config.baseURL } : {}),
-            defaultHeaders: { ...(betaHeaders ? { 'anthropic-beta': betaHeaders } : {}), ...(config.extraHeaders || {}) },
+            apiKey: this.apiKey,
+            ...(this.config.baseURL ? { baseURL: this.config.baseURL } : {}),
+            defaultHeaders: { ...(betaHeaders ? { 'anthropic-beta': betaHeaders } : {}), ...(this.config.extraHeaders || {}) },
+            maxRetries: 0,
         });
     }
     reloadApiKey() {
@@ -567,11 +607,16 @@ export class AnthropicProvider {
                 || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
             if (newKey) {
                 this.config = { ...(this.config || {}), apiKey: newKey };
-                const betaHeaders = this.config.disableBetaHeaders ? null : buildAnthropicBetaHeaders({ toolSearch: true });
+                this.apiKey = newKey;
+                // Tool-search is a request capability, not an account
+                // capability. Keep it off the client defaults and add it only
+                // on turns that actually serialize defer_loading tools.
+                const betaHeaders = this.config.disableBetaHeaders ? null : buildAnthropicBetaHeaders();
                 this.client = new (loadAnthropic())({
                     apiKey: newKey,
                     ...(this.config.baseURL ? { baseURL: this.config.baseURL } : {}),
                     defaultHeaders: { ...(betaHeaders ? { 'anthropic-beta': betaHeaders } : {}), ...(this.config.extraHeaders || {}) },
+                    maxRetries: 0,
                 });
             }
         } catch { /* best effort */ }
@@ -586,8 +631,16 @@ export class AnthropicProvider {
         try {
             return await this._doSend(messages, model, tools, sendOpts);
         } catch (err) {
-            if (err.message && (err.message.includes('401') || err.message.includes('403'))
-                && !err.liveTextEmitted && !err.emittedToolCall && !err.unsafeToRetry) {
+            const status = Number(err?.status || err?.httpStatus || err?.response?.status || 0);
+            const outputWasExposed = err?.liveTextEmitted === true
+                || err?.emittedText === true
+                || err?.emittedToolCall === true
+                || err?.toolCallEmitted === true
+                || err?.partialToolCall === true
+                || err?.emittedThinking === true
+                || err?.unsafeToRetry === true;
+            if (status === 401
+                && !outputWasExposed) {
                 process.stderr.write(`[provider] Auth error, re-reading provider authentication...\n`);
                 this.reloadApiKey();
                 return await this._doSend(messages, model, tools, sendOpts);
@@ -640,11 +693,11 @@ export class AnthropicProvider {
             system: systemBlocks.length ? systemBlocks : undefined,
             messages: anthropicMessages,
         };
-        const nativeTools = nativeAnthropicTools(opts);
-        if (tools?.length || nativeTools.length) {
+        const requestTools = requestAnthropicTools(tools, chatMsgs, opts);
+        if (requestTools.length) {
             // No cache_control on tools — the system BP covers tools via
             // Anthropic prefix semantics (order: tools → system → messages).
-            params.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredAnthropicTools(tools || [], chatMsgs, opts)])];
+            params.tools = requestTools;
         }
         // tool_choice only when tools are actually present (Anthropic rejects
         // tool_choice without tools). 'none' rides the hard-cap final turn to
@@ -653,6 +706,8 @@ export class AnthropicProvider {
             const toolChoice = toAnthropicToolChoice(opts.toolChoice);
             if (toolChoice) params.tool_choice = toolChoice;
         }
+        const hasDeferredTools = Array.isArray(params.tools)
+            && params.tools.some((tool) => tool?.defer_loading === true);
         // Known tool names for the shared parseSSEStream leaked-tool-call guard
         // (same guard fixes both Anthropic providers). Recovered leaked calls
         // are only synthesized when they name a tool actually offered here.
@@ -711,7 +766,7 @@ export class AnthropicProvider {
             : {
                 'anthropic-beta': buildAnthropicBetaHeaders({
                     fastMode: this.fastModeBetaHeaderLatched,
-                    toolSearch: true,
+                    toolSearch: hasDeferredTools,
                     effort: shouldIncludeEffortBeta(useModel, opts),
                 }),
             };
@@ -795,6 +850,8 @@ export class AnthropicProvider {
                     sawMessageStart: false,
                     sawCompleted: false,
                     emittedToolCall: false,
+                    partialToolCall: false,
+                    emittedThinking: false,
                     // Gateway live-text relay invariant: set by parseSSEStream
                     // once a non-empty text chunk has been forwarded. A later
                     // failure is non-retryable (rendered text cannot be
@@ -806,11 +863,12 @@ export class AnthropicProvider {
 
                 let firstBytePoll = null;
                 let firstByteTimeout = null;
+                let response = null;
 
                 try {
                     try { onStageChange?.('requesting'); } catch {}
 
-                    const response = await withRetry(
+                    response = await withRetry(
                         async ({ signal: attemptSignal }) => {
                             const res = await this.client.messages.create(params, {
                                 signal: attemptSignal,
@@ -821,13 +879,14 @@ export class AnthropicProvider {
                                 const err = new Error(`Anthropic API ${res.status}: ${text.slice(0, 200)}`);
                                 err.status = res.status;
                                 err.httpStatus = res.status;
+                                err.initialResponseError = true;
                                 // Carry response headers so withRetry can honor a
                                 // short Retry-After and upstream can read quota hints.
                                 err.headers = res.headers;
                                 err.response = { status: res.status, headers: res.headers };
-                                // 429: promote to a quota-style error equivalent to
-                                // anthropic-oauth's anthropicQuotaError so upstream
-                                // quota handling and unsafe-to-retry gating apply.
+                                // This is an initial-response 429, before SSE
+                                // output/tool exposure, so the request-local
+                                // withRetry loop may retry it with jitter.
                                 if (res.status === 429) {
                                     const retryAfterMs = retryAfterMsFromError({ headers: res.headers, response: { headers: res.headers } });
                                     err.name = 'ProviderQuotaError';
@@ -835,7 +894,6 @@ export class AnthropicProvider {
                                     err.retryAfterMs = retryAfterMs;
                                     err.providerQuota = true;
                                     err.quotaExceeded = true;
-                                    err.unsafeToRetry = true;
                                 }
                                 throw err;
                             }
@@ -846,9 +904,17 @@ export class AnthropicProvider {
                         },
                         {
                             signal: totalSignal,
-                            perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+                            maxAttempts: anthropicMaxAttempts(),
+                            backoffMs: ANTHROPIC_RETRY_BACKOFF_MS,
+                            retryJitterRatio: ANTHROPIC_RETRY_JITTER_RATIO,
+                            retryJitterMode: 'positive',
+                            perAttemptTimeoutMs: anthropicRequestTimeoutMs(),
                             perAttemptLabel: `${this.name} Anthropic streaming response`,
+                            model: useModel,
+                            fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
                             onRetry: ({ attempt, lastErr, delayMs, delayReason }) => {
+                                const status = Number(lastErr?.httpStatus || lastErr?.status || lastErr?.response?.status || 0);
+                                if (status === 429) notifyCurrentAnthropicRateLimit(lastErr);
                                 const delayLabel = Number.isFinite(Number(delayMs))
                                     ? `, delay ${delayMs}ms${delayReason ? ` (${delayReason})` : ''}`
                                     : '';
@@ -890,6 +956,7 @@ export class AnthropicProvider {
                         onTextDelta,
                         knownToolNames,
                     );
+                    try { streamController.abort?.('Anthropic SSE complete'); } catch {}
 
                     if (firstBytePoll) {
                         clearInterval(firstBytePoll);
@@ -913,6 +980,14 @@ export class AnthropicProvider {
 
                     return buildReturnFromParse(parseResult);
                 } catch (err) {
+                    if (err instanceof AnthropicFallbackTriggeredError) {
+                        process.stderr.write(`[${this.name}] ${err.message}\n`);
+                        return this._doSend(messages, err.fallbackModel, tools, {
+                            ...opts,
+                            fallbackModel: undefined,
+                            _fallbackTriggered: true,
+                        });
+                    }
                     // Live-text invariant: once a non-empty text chunk has been
                     // relayed to the client (gateway live mode), the rendered
                     // output cannot be withdrawn and re-issuing would concatenate
@@ -934,10 +1009,24 @@ export class AnthropicProvider {
                                 firstAttemptError.liveTextEmitted = true;
                                 firstAttemptError.unsafeToRetry = true;
                             } catch {}
-                            throw firstAttemptError;
+                            throw err;
                         }
                         throw err;
                     }
+                    if (midState.emittedToolCall || midState.partialToolCall || midState.emittedThinking) {
+                        try {
+                            err.emittedToolCall = !!midState.emittedToolCall;
+                            err.partialToolCall = !!midState.partialToolCall;
+                            err.emittedThinking = !!midState.emittedThinking;
+                            err.unsafeToRetry = true;
+                        } catch {}
+                        try { streamController.abort?.(err); } catch {}
+                        throw err;
+                    }
+                    // withRetry already exhausted the full request-level budget.
+                    // Do not accidentally grant an additional SSE retry budget
+                    // to an initial HTTP 429 that never produced a stream.
+                    if (err?.initialResponseError) throw err;
                     if (err?.isEmptyStream && attemptIndex < MAX_MIDSTREAM_RETRIES) {
                         firstAttemptError = err;
                         firstAttemptClassifier = 'empty_stream';
@@ -953,6 +1042,8 @@ export class AnthropicProvider {
                     if (classifyError(err) === 'transient'
                         && !midState.sawMessageStart
                         && !midState.emittedToolCall
+                        && !midState.partialToolCall
+                        && !midState.emittedThinking
                         && attemptIndex < MAX_MIDSTREAM_RETRIES) {
                         firstAttemptError = err;
                         firstAttemptClassifier = err?.providerErrorType || 'sse_transient';
@@ -968,6 +1059,8 @@ export class AnthropicProvider {
                     if ((err?.truncatedStream === true || err?.code === 'TRUNCATED_STREAM')
                         && classifyError(err) === 'transient'
                         && !midState.emittedToolCall
+                        && !midState.partialToolCall
+                        && !midState.emittedThinking
                         && attemptIndex < MAX_MIDSTREAM_RETRIES) {
                         firstAttemptError = err;
                         firstAttemptClassifier = 'truncated_stream';
@@ -984,19 +1077,31 @@ export class AnthropicProvider {
                     if (classifier && attemptIndex < MAX_MIDSTREAM_RETRIES) {
                         firstAttemptError = err;
                         firstAttemptClassifier = classifier;
+                        const status = Number(err?.httpStatus || err?.status || 0);
+                        let retryDelayMs = null;
+                        if (status === 429) {
+                            if (!err.headers && response?.headers) err.headers = response.headers;
+                            if (!err.response && response) err.response = { status, headers: response.headers };
+                            retryDelayMs = retryAfterMsFromError(err);
+                            if (retryDelayMs != null) err.retryAfterMs = retryDelayMs;
+                            notifyCurrentAnthropicRateLimit(err);
+                        }
                         try { streamController.abort?.(err); } catch {}
                         try {
                             process.stderr.write(
                                 `[${this.name}] mid-stream recovered: retry ${attemptIndex + 1}/${MAX_MIDSTREAM_RETRIES} (cause: ${classifier})\n`,
                             );
                         } catch {}
-                        await _midstreamSleepWithAbort(midstreamBackoffFor(attemptIndex + 1), totalSignal);
+                        await _midstreamSleepWithAbort(
+                            retryDelayMs ?? midstreamBackoffFor(attemptIndex + 1),
+                            totalSignal,
+                        );
                         continue;
                     }
                     if (attemptIndex > 0 && firstAttemptError) {
-                        try { firstAttemptError.midstreamRetries = attemptIndex; } catch {}
-                        try { firstAttemptError.midstreamClassifier = firstAttemptClassifier; } catch {}
-                        throw firstAttemptError;
+                        try { err.midstreamRetries = attemptIndex; } catch {}
+                        try { err.midstreamClassifier = firstAttemptClassifier; } catch {}
+                        throw err;
                     }
                     throw err;
                 } finally {
@@ -1011,7 +1116,7 @@ export class AnthropicProvider {
         }
     }
     async listModels() {
-        const apiKey = this.config?.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
+        const apiKey = this.apiKey || this.config?.apiKey || (this.name === 'anthropic' ? process.env.ANTHROPIC_API_KEY : null);
         if (!apiKey) return MODELS;
         try {
             const base = String(this.config?.baseURL || 'https://api.anthropic.com').replace(/\/+$/, '');
@@ -1043,16 +1148,9 @@ export class AnthropicProvider {
         }
     }
     async isAvailable() {
-        try {
-            await this.client.messages.create({
-                model: 'claude-haiku-4-5-20251001',
-                max_tokens: 1,
-                messages: [{ role: 'user', content: 'hi' }],
-            });
-            return true;
-        }
-        catch {
-            return false;
-        }
+        // Availability probes must not spend tokens or depend on a live
+        // network. Dispatch owns authentication validation and 401 reload.
+        return !!(this.apiKey || this.config?.apiKey
+            || (this.name === 'anthropic' && process.env.ANTHROPIC_API_KEY));
     }
 }

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

@@ -90,16 +90,20 @@ export function _geminiCachePrefixContents(contents, prefixCount) {
     });
 }
 
-export function _geminiCachePrefixHash({ model, systemInstruction, geminiTools, contents, prefixCount }) {
+export function _geminiCachePrefixHash({ model, systemInstruction, geminiTools, toolConfig, contents, prefixCount }) {
     return traceHash(stableTraceStringify({
         model: model || null,
         systemInstruction: systemInstruction || '',
         tools: geminiTools || [],
+        toolConfig: toolConfig || null,
         contents: _geminiCachePrefixContents(contents, prefixCount),
     }));
 }
 
-export const GEMINI_GLOBAL_CACHE_MIN_LIVE_MS = 6 * 60 * 1000;
+// The provider's default explicit-cache TTL is five minutes. A six-minute
+// global-cache floor made every freshly-created default cache ineligible for
+// cross-session reuse. Ten seconds matches the per-session minimum headroom.
+export const GEMINI_GLOBAL_CACHE_MIN_LIVE_MS = 10 * 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
@@ -108,15 +112,30 @@ 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 }) {
+export function _geminiCredentialFingerprint(apiKey) {
+    return traceHash(String(apiKey || ''));
+}
+
+export function _geminiGlobalCacheKey({ credentialFingerprint, model, cachePrefixHash, cachePrefixContentCount }) {
     return traceHash(stableTraceStringify({
-        apiKeyHash: traceHash(apiKey || ''),
+        credentialFingerprint: credentialFingerprint || null,
         model: model || null,
         cachePrefixHash,
         cachePrefixContentCount,
     }));
 }
 
+export function _invalidateGeminiCachesForCredentialFingerprint(credentialFingerprint) {
+    if (!credentialFingerprint) return 0;
+    let removed = 0;
+    for (const [key, entry] of geminiGlobalCaches) {
+        if (entry?.cacheCredentialFingerprint !== credentialFingerprint) continue;
+        geminiGlobalCaches.delete(key);
+        removed += 1;
+    }
+    return removed;
+}
+
 export function _pruneGeminiGlobalCaches(now = Date.now()) {
     for (const [key, entry] of geminiGlobalCaches) {
         if (!entry?.cacheName || Number(entry.cacheExpiresAt || 0) <= now) {
@@ -172,6 +191,7 @@ export function _attachGeminiCacheState(opts, entry, currentIter) {
             cacheTokenSize: entry.cacheTokenSize,
             cachePrefixContentCount: entry.cachePrefixContentCount,
             cachePrefixHash: entry.cachePrefixHash,
+            cacheCredentialFingerprint: entry.cacheCredentialFingerprint,
         },
     };
 }