mixdog 1.2.1 → 1.2.3

package/src/runtime/agent/orchestrator/providers/custom-reasoning.mjs

@@ -4,6 +4,8 @@
 // effort to a supported level and serializes it for the provider protocol.
 // First-party providers never route through here.
 
+import { isTogetherBaseURL } from './openai-compat-reasoning-field.mjs';
+
 export const CUSTOM_EFFORT_LEVELS = Object.freeze(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 const RANK = new Map(CUSTOM_EFFORT_LEVELS.map((level, index) => [level, index]));
 
@@ -63,16 +65,30 @@ export function snapCustomEffort(levels, effort) {
 }
 
 const EMPTY = Object.freeze({ level: null, fields: {}, thinking: null, replay: false });
+// Chat-only extensions on top of the standard `reasoning_effort`.
+const CHAT_ONLY_WIRE_FORMATS = new Set(['deepseek', 'together', 'vllm']);
+
+/**
+ * The effective wire format of a row: its declared format, else `together`
+ * when the provider's own base URL is Together AI (whose hybrid models toggle
+ * reasoning with a `reasoning.enabled` flag), else `standard`.
+ */
+export function customWireFormat(model, baseURL) {
+  const declared = model?.customReasoning?.wireFormat;
+  if (CHAT_ONLY_WIRE_FORMATS.has(declared)) return declared;
+  return isTogetherBaseURL(baseURL) ? 'together' : 'standard';
+}
 
 /**
- * @param {{ protocol: 'openai-chat'|'openai-responses'|'anthropic', model: object|null, effort: string|null|undefined }} input
+ * @param {{ protocol: 'openai-chat'|'openai-responses'|'anthropic', model: object|null, effort: string|null|undefined, baseURL?: string }} input
  * @returns {{ level: string|null, fields: object, thinking: 'on'|'off'|null, replay: boolean }}
  */
-export function resolveCustomReasoning({ protocol, model, effort } = {}) {
+export function resolveCustomReasoning({ protocol, model, effort, baseURL } = {}) {
   const custom = model?.customReasoning || {};
-  const wireFormat = custom.wireFormat === 'deepseek' ? 'deepseek' : 'standard';
-  // DeepSeek's `thinking` extension exists only on the Chat wire.
-  if (wireFormat === 'deepseek' && protocol !== 'openai-chat') return { ...EMPTY, fields: {} };
+  const wireFormat = protocol === 'openai-chat' ? customWireFormat(model, baseURL) : 'standard';
+  // The `thinking` / `reasoning.enabled` / chat_template_kwargs extensions
+  // exist only on the Chat wire.
+  if (CHAT_ONLY_WIRE_FORMATS.has(custom.wireFormat) && protocol !== 'openai-chat') return { ...EMPTY, fields: {} };
   const level = snapCustomEffort(customEffortLevels(model), effort);
   let thinking = null;
   if (level !== null) thinking = level === 'none' ? 'off' : 'on';
@@ -86,6 +102,18 @@ export function resolveCustomReasoning({ protocol, model, effort } = {}) {
           level === 'none'
             ? { thinking: { type: 'disabled' } }
             : { thinking: { type: 'enabled' }, reasoning_effort: value };
+      } else if (wireFormat === 'together') {
+        // Together: `reasoning.enabled` toggles hybrid models (those that can
+        // be turned off); `reasoning_effort` sets the depth of the others.
+        if (level === 'none') fields = { reasoning: { enabled: false } };
+        else {
+          fields = { reasoning_effort: value };
+          if (customEffortLevels(model)?.includes('none')) fields.reasoning = { enabled: true };
+        }
+      } else if (wireFormat === 'vllm') {
+        // vLLM switches thinking through the chat template.
+        fields = { chat_template_kwargs: { enable_thinking: level !== 'none' } };
+        if (level !== 'none') fields.reasoning_effort = value;
       } else {
         fields = { reasoning_effort: value };
       }
@@ -101,7 +129,6 @@ export function resolveCustomReasoning({ protocol, model, effort } = {}) {
   // An explicit replay flag wins over the catalog's reasoning_content field.
   const replayFlag =
     typeof custom.replay === 'boolean' ? custom.replay : model?.reasoningContentField === 'reasoning_content';
-  const replay =
-    protocol === 'openai-chat' && replayFlag && thinking !== 'off' && !/reasoner/i.test(String(model?.id || ''));
+  const replay = protocol === 'openai-chat' && replayFlag && thinking !== 'off';
   return { level, fields, thinking, replay };
 }

package/src/runtime/agent/orchestrator/providers/custom-tool-wire.mjs

@@ -42,17 +42,43 @@ function customToolArgumentsFromInput(name, input) {
   return { input: text };
 }
 
+// Responses calls of a tool loaded from a declared namespace carry
+// `namespace` beside `name`. Mixdog declares no namespaces today, so this is
+// parse-side preservation only: a call that carries one keeps it on its
+// record (and in replay), and its dispatch dedupe identity is qualified, so it
+// is never conflated with a same-named top-level tool.
+export function toolCallNamespace(item) {
+  return typeof item?.namespace === 'string' && item.namespace ? item.namespace : '';
+}
+
+/** Copy the source item's namespace onto a call record (mutates; returns it). */
+export function withToolCallNamespace(call, source) {
+  const namespace = toolCallNamespace(source);
+  if (call && namespace && !call.namespace) call.namespace = namespace;
+  return call;
+}
+
+/** Dispatch dedupe identity: the namespace-qualified tool name. */
+export function qualifiedToolCallName(call) {
+  const namespace = toolCallNamespace(call);
+  const name = call?.name || '';
+  return namespace ? `${namespace}.${name}` : name;
+}
+
 export function customToolCallFromResponseItem(item) {
   if (item?.type !== 'custom_tool_call') return null;
   const id = item.call_id || item.id || '';
   const name = item.name || '';
   if (!id || !name) return null;
-  return {
-    id,
-    name,
-    arguments: customToolArgumentsFromInput(name, item.input ?? ''),
-    nativeType: 'custom_tool_call',
-  };
+  return withToolCallNamespace(
+    {
+      id,
+      name,
+      arguments: customToolArgumentsFromInput(name, item.input ?? ''),
+      nativeType: 'custom_tool_call',
+    },
+    item
+  );
 }
 
 export function isCustomToolCallRecord(call) {

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

@@ -0,0 +1,67 @@
+/**
+ * DeepSeek: Chat Completions at https://api.deepseek.com plus the Anthropic
+ * Messages endpoint at https://api.deepseek.com/anthropic (the SDK appends
+ * /v1/messages). Per DeepSeek's Anthropic API docs that endpoint carries
+ * thinking and tool_use/tool_result blocks and ignores cache_control and
+ * anthropic-beta; agent/tool sessions use it, tool-less one-shot requests stay
+ * on Chat (wire-route.mjs). DeepSeek has no Responses endpoint.
+ */
+import { WireGatewayProvider, messagesBaseFromOpenAIBase } from './wire-gateway.mjs';
+import { OPENAI_COMPAT_PRESETS } from './openai-compat-presets.mjs';
+
+export function deepSeekMessagesBaseURL(configuredBaseURL) {
+  return `${messagesBaseFromOpenAIBase(configuredBaseURL || OPENAI_COMPAT_PRESETS.deepseek.baseURL)}/anthropic`;
+}
+
+// Requested effort → output_config.effort (thinking_mode docs: minimal/low →
+// low, medium/high/xhigh → high, max/ultra → max).
+const DEEPSEEK_EFFORT = Object.freeze({
+  minimal: 'low',
+  low: 'low',
+  medium: 'high',
+  high: 'high',
+  xhigh: 'high',
+  max: 'max',
+  ultra: 'max',
+});
+const DEEPSEEK_OFF = new Set(['none', 'off', 'disabled']);
+
+/**
+ * DeepSeek's own effort contract on its Messages endpoint: thinking is on by
+ * default and `budget_tokens` is ignored, so an effort goes in
+ * `output_config.effort`; off is `thinking:{type:'disabled'}` together with the
+ * documented Anthropic-format toggle `reasoning:{effort:'none'}`. No effort
+ * leaves the default (thinking on, effort high). Always handles the request.
+ */
+export function deepSeekEffortProjection(body, { effort } = {}) {
+  const level = String(effort ?? '')
+    .trim()
+    .toLowerCase();
+  if (DEEPSEEK_OFF.has(level)) {
+    body.thinking = { type: 'disabled' };
+    body.reasoning = { effort: 'none' };
+    return true;
+  }
+  const mapped = DEEPSEEK_EFFORT[level];
+  if (mapped) {
+    const existing = body.output_config && typeof body.output_config === 'object' ? body.output_config : {};
+    body.output_config = { ...existing, effort: mapped };
+  }
+  return true;
+}
+
+export class DeepSeekProvider extends WireGatewayProvider {
+  constructor(config = {}) {
+    super('deepseek', config, {
+      baseURL: deepSeekMessagesBaseURL(config.baseURL),
+      // The endpoint has no document block of any kind (PDFs included).
+      nativePdf: false,
+      nativeDocuments: false,
+      // disable_parallel_tool_use is ignored on every tool_choice.
+      supportsDisableParallelToolUse: false,
+      // Image `source.type: file` needs the Files API beta, on those requests only.
+      fileIdImageBeta: 'files-api-2025-04-14',
+      messagesEffortProjection: deepSeekEffortProjection,
+    });
+  }
+}

package/src/runtime/agent/orchestrator/providers/effort-configuration.mjs

@@ -7,6 +7,9 @@ export const EFFORT_CONFIGURATION_BETA = 'mid-conversation-output-config-2026-07
 // first version checked on the wire (update accepted, prompt cache kept), and
 // every later version of that family. A model that turns out to reject the
 // update is switched off at runtime (markEffortConfigurationUnsupported).
+// The Anthropic catalogs publish no per-model flag for it, so a measured
+// floor is kept for the families already checked: below it the rejection is
+// certain, and every request would pay a failed attempt first.
 const ANTHROPIC_MIN_VERSION = Object.freeze({
   opus: [5, 0],
   sonnet: [5, 5],
@@ -14,6 +17,10 @@ const ANTHROPIC_MIN_VERSION = Object.freeze({
   fable: [5, 1],
   mythos: [5, 1],
 });
+// A family not measured yet starts at the earliest checked major, on the
+// routes that replay a rejected update (the rest cannot recover from one).
+const ANTHROPIC_FIRST_MAJOR = Math.min(...Object.values(ANTHROPIC_MIN_VERSION).map(([major]) => major));
+const ANTHROPIC_REPLAYING_PROVIDERS = new Set(['anthropic-oauth']);
 // https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation
 // — GPT-6 and later, standard single-agent mode. The public API publishes no
 // per-model flag, so the version is its whole answer; the OAuth backend's
@@ -25,14 +32,19 @@ function versionAtLeast([major, minor], [minMajor, minMinor]) {
   return major > minMajor || (major === minMajor && minor >= minMinor);
 }
 
-function anthropicVersionSupported(id) {
+function anthropicVersionSupported(provider, id) {
   const m = id.match(/^claude-([a-z]+)-(\d+)(?:-(\d{1,2}))?$/);
-  const floor = m && ANTHROPIC_MIN_VERSION[m[1]];
-  return Boolean(floor) && versionAtLeast([Number(m[2]), Number(m[3] || 0)], floor);
+  if (!m) return false;
+  const version = [Number(m[2]), Number(m[3] || 0)];
+  const floor = ANTHROPIC_MIN_VERSION[m[1]];
+  if (floor) return versionAtLeast(version, floor);
+  return ANTHROPIC_REPLAYING_PROVIDERS.has(provider) && version[0] >= ANTHROPIC_FIRST_MAJOR;
 }
 
+// Any `gpt-<major>` id, whatever follows the major (tier names, minors,
+// snapshots), so a later naming scheme needs no edit.
 function openAiVersionSupported(id) {
-  const m = id.match(/^gpt-(\d+)(?:-\d+)?(?:-[a-z]+)?$/);
+  const m = id.match(/^gpt-(\d+)(?:-|$)/);
   return Boolean(m) && Number(m[1]) >= OPENAI_MIN_MAJOR;
 }
 
@@ -110,11 +122,25 @@ function openAiSupportsEffortUpdates(provider, model, id) {
   return declared ?? openAiVersionSupported(id);
 }
 
+// A custom route on the Responses wire (`opts.protocol`) serving GPT-6 or
+// later takes the same update as the official routes. The version is read
+// from the id's last `/` segment, so gateway ids like `openai/gpt-6.1-sol` count.
+function customResponsesSupportsEffortUpdates(provider, opts, id) {
+  return (
+    isCustomProviderName(provider) &&
+    opts.protocol === 'openai-responses' &&
+    openAiVersionSupported(id.slice(id.lastIndexOf('/') + 1))
+  );
+}
+
 export function effortConfigurationMode(provider, model, opts = {}) {
   const id = modelKey(model);
   if (opts.effortConfigurationEnabled === false || Number(opts.thinkingBudgetTokens) > 0) return null;
   if (unsupportedModels.has(`${provider}:${id}`)) return null;
-  if (OPENAI_PROVIDERS.has(provider) && openAiSupportsEffortUpdates(provider, model, id)) {
+  if (
+    (OPENAI_PROVIDERS.has(provider) && openAiSupportsEffortUpdates(provider, model, id)) ||
+    customResponsesSupportsEffortUpdates(provider, opts, id)
+  ) {
     const parameters = opts.modelParameters || {};
     const mode = opts.reasoning?.mode ?? parameters.reasoning_mode ?? parameters.mode ?? 'standard';
     if (mode !== 'standard' || opts.multiAgent === true || parameters.multi_agent === true) return null;
@@ -122,7 +148,7 @@ export function effortConfigurationMode(provider, model, opts = {}) {
   }
   if (
     ANTHROPIC_PROVIDERS.has(provider) &&
-    anthropicVersionSupported(id) &&
+    anthropicVersionSupported(provider, id) &&
     opts.disableBetaHeaders !== true &&
     (!opts.baseURL || /^https:\/\/api\.anthropic\.com(?:\/|$)/.test(opts.baseURL))
   )
@@ -132,7 +158,8 @@ export function effortConfigurationMode(provider, model, opts = {}) {
 
 // Custom providers on the Chat and Responses wires take a fresh effort with
 // every request, so auto effort sends a turn's or step's effort as that
-// request's own effort: no mid-conversation update, no beta header. A custom
+// request's own effort: no mid-conversation update, no beta header (except a
+// Responses-wire GPT-6+ model, which takes the 'responses' update). A custom
 // Anthropic-wire provider keeps auto effort off.
 const CUSTOM_AUTO_EFFORT_PROTOCOLS = new Set(['openai-chat', 'openai-responses']);
 
@@ -156,22 +183,31 @@ export function autoEffortModel(providerName, providerImpl, model) {
     // list from falling back to a family ladder.
     return { id: model, reasoningLevels: anthropicEffortLevelsFor(model), customReasoning: true };
   }
-  if (!isCustomProviderName(providerName)) return { id: model };
+  // Every other route reads the provider's own cached model row, the source
+  // route resolution (lookupModelMeta) uses; a bare id has no levels and
+  // skips the judge.
   return { ...(providerImpl?.getCachedModelInfo?.(model) || {}), id: model };
 }
 
 /** The effort-change mode of a session's route: 'responses' / 'anthropic'
- *  (mid-conversation update), 'custom' (per-request effort), or null. */
+ *  (mid-conversation update), 'custom' (per-request effort), or null. A
+ *  custom route takes an update mode only when its model declares levels. */
 export function turnEffortConfigurationMode(session, provider) {
-  const opts = { ...(provider?.config || {}), modelParameters: session.modelParameters || {} };
+  const protocol = provider?.customConfig?.protocol;
+  const opts = { ...(provider?.config || {}), modelParameters: session.modelParameters || {}, protocol };
+  const custom = customAutoEffortCapable(
+    session.provider,
+    protocol,
+    autoEffortModel(session.provider, provider, session.model)
+  );
   const mode = effortConfigurationMode(session.provider, session.model, opts);
-  if (mode) return mode;
-  const model = autoEffortModel(session.provider, provider, session.model);
-  return customAutoEffortCapable(session.provider, provider?.customConfig?.protocol, model) ? 'custom' : null;
+  if (mode && (custom || !isCustomProviderName(session.provider))) return mode;
+  return custom ? 'custom' : null;
 }
 
 const CUSTOM_EFFORTS = new Set(CUSTOM_EFFORT_LEVELS);
-const effortsFor = (mode) => (mode === 'custom' ? CUSTOM_EFFORTS : EFFORTS);
+// A custom route keeps its own levels (including `none`) in either mode.
+const effortsFor = (mode, provider) => (mode === 'custom' || isCustomProviderName(provider) ? CUSTOM_EFFORTS : EFFORTS);
 
 function normalizedEffort(provider, model, effort) {
   if (ANTHROPIC_PROVIDERS.has(provider)) return normalizeAnthropicEffortInput(effort, model) || null;
@@ -187,8 +223,8 @@ function validSnapshot(value, provider, model, mode) {
     value.provider === provider &&
     value.model === modelKey(model) &&
     value.mode === mode &&
-    effortsFor(mode).has(value.initialEffort) &&
-    effortsFor(mode).has(value.effort)
+    effortsFor(mode, provider).has(value.initialEffort) &&
+    effortsFor(mode, provider).has(value.effort)
   );
 }
 
@@ -199,7 +235,7 @@ function validSnapshot(value, provider, model, mode) {
 export function prepareTurnEffortConfiguration(session, provider, turnEffort) {
   const mode = turnEffortConfigurationMode(session, provider);
   const effort = normalizedEffort(session.provider, session.model, turnEffort ?? session.effort);
-  if (!mode || !effortsFor(mode).has(effort)) return null;
+  if (!mode || !effortsFor(mode, session.provider).has(effort)) return null;
   const first = (session.messages || []).find((message) =>
     validSnapshot(message?.meta?.[META_KEY], session.provider, session.model, mode)
   )?.meta?.[META_KEY];
@@ -221,7 +257,7 @@ export function prepareTurnEffortConfiguration(session, provider, turnEffort) {
 // step), or null when that effort is not valid for the model.
 export function stepEffortConfiguration(snapshot, provider, model, effort) {
   const value = normalizedEffort(provider, model, effort);
-  if (!snapshot || !EFFORTS.has(value)) return null;
+  if (!snapshot || !effortsFor(snapshot.mode, provider).has(value)) return null;
   return { ...snapshot, effort: value };
 }
 
@@ -256,6 +292,32 @@ export function projectEffortConfiguration(messages, provider, model, opts = {})
   return { mode, initialEffort: seed.initialEffort, effort: current, updates };
 }
 
+/**
+ * Responses-wire placement of a projection's updates while a history is
+ * lowered in order: `before(message)` gives the items to emit ahead of a
+ * message, `end()` those after the last one. An update on a tool result
+ * applies after its whole batch; one on a user message before it. Adjacent
+ * updates are rejected, so a batch update that a user message directly
+ * follows yields to that message's own.
+ */
+export function responsesEffortUpdates(projection) {
+  let afterBatch = null;
+  const items = (effort) => (effort ? [{ type: 'configuration_update', reasoning: { effort } }] : []);
+  return {
+    before(message) {
+      const effort = projection?.updates.get(message);
+      if (message.role === 'tool') {
+        if (effort) afterBatch = effort;
+        return [];
+      }
+      const value = effort || afterBatch;
+      afterBatch = null;
+      return items(value);
+    },
+    end: () => items(afterBatch),
+  };
+}
+
 // Split only before a user message or after a whole tool-result batch.
 // Sanitizing each segment before inserting the trusted empty system control
 // avoids losing it as empty text, and never separates a tool call from its

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

@@ -14,7 +14,7 @@
 import { appendAgentTrace } from '../agent-trace.mjs';
 import {
   _estimateGeminiCacheTokens,
-  _geminiCacheMinTokens,
+  geminiExplicitCacheMinTokens,
   _geminiCachePrefixCount,
   _geminiCachePrefixContents,
   _geminiCachePrefixHash,
@@ -146,6 +146,12 @@ export function awaitSharedCreate(task, signal) {
 // role='user' or 'model'; generateContent uses role='function' for
 // tool_result turns, so that is collapsed to 'user' (functionResponse parts
 // remain inside).
+// The model id without its `models/` resource prefix; every URL and body that
+// adds the prefix itself starts from this.
+export function geminiBareModelId(model) {
+  return String(model || '').replace(/^models\//i, '');
+}
+
 export function geminiCacheCreateBody({
   model,
   ttlSeconds,
@@ -157,7 +163,7 @@ export function geminiCacheCreateBody({
 }) {
   const cachePrefixContents = _geminiCachePrefixContents(contents, cachePrefixContentCount);
   const body = {
-    model: `models/${model}`,
+    model: `models/${geminiBareModelId(model)}`,
     ttl: `${ttlSeconds}s`,
   };
   if (systemInstruction) {
@@ -252,9 +258,10 @@ export function dropRejectedGeminiCache(cachedContent, opts) {
 // the model-specific minimum. Skip the POST entirely when the estimate
 // is under threshold so we don't spam 400 responses turn-after-turn.
 export function geminiPrefixBelowMinimum({ model, systemInstruction, geminiTools, contents, opts, currentIter }) {
-  const minTokens = _geminiCacheMinTokens(model);
+  // null: the model is excluded from explicit caching, so never create one.
+  const minTokens = geminiExplicitCacheMinTokens(model);
   const estimatedTokens = _estimateGeminiCacheTokens(systemInstruction, geminiTools, contents);
-  if (estimatedTokens >= minTokens) return false;
+  if (minTokens !== null && estimatedTokens >= minTokens) return false;
   traceGeminiCache(opts, currentIter, 'gemini_cache_skip', {
     reason: 'prefix_below_min',
     estimatedTokens,

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

@@ -43,12 +43,11 @@ function summarizeTraceContents(contents) {
   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).
+// Gemini cachedContents API rejects prefixes below a model-specific minimum
+// 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;
@@ -67,8 +66,26 @@ export function _estimateGeminiCacheTokens(systemInstruction, geminiTools, conte
   return Math.ceil(chars / 4);
 }
 
+// Explicit-cache eligibility and minimum prefix size per model, from the
+// caching docs: explicit caching works on Gemini 3 and 2.5 and is not supported
+// from Gemini 4 onward; documented minimums are 4096 for Gemini 3.x and 2048
+// for 2.5 Flash/Pro. Other ids keep the conservative 4096 floor (skipping a
+// small prefix only falls back to the implicit cache, whereas a floor that is
+// too low would POST a create the server rejects every turn).
+const GEMINI_CACHE_MIN_TOKENS = 4096;
+
+// Minimum prefix tokens for an explicit cache, or null when the docs exclude
+// the model from explicit caching.
+export function geminiExplicitCacheMinTokens(model) {
+  const bare = String(model || '').replace(/^models\//i, '').toLowerCase();
+  const major = /^gemini-(\d+)/.exec(bare);
+  if (major && Number(major[1]) >= 4) return null;
+  if (/^gemini-2\.5-(?:pro|flash)(?!-lite)(?:-|$)/.test(bare)) return 2048;
+  return GEMINI_CACHE_MIN_TOKENS;
+}
+
 export function _geminiCacheMinTokens(model) {
-  return /^gemini-3/i.test(String(model || '')) ? 4096 : 2048;
+  return geminiExplicitCacheMinTokens(model) ?? GEMINI_CACHE_MIN_TOKENS;
 }
 
 export function _geminiCachePrefixCount(contents) {
@@ -110,6 +127,23 @@ const GEMINI_GLOBAL_CACHE_MAX_ENTRIES = 128;
 export const GEMINI_GLOBAL_CACHE_DELETE_GRACE_MS = 2 * 60 * 1000;
 const geminiGlobalCaches = new Map();
 export const geminiGlobalCacheCreates = new Map();
+// Models whose cachedContents.create the server refused as unsupported (not
+// a prefix or quota failure). No catalog publishes explicit-cache support, so
+// the server's own answer decides, once per process.
+const geminiExplicitCacheRefusedModels = new Set();
+
+export function markGeminiExplicitCacheRefused(model, err) {
+  if (err?.status !== 400) return false;
+  if (!/explicit caching is not supported/i.test(String(err?.message || ''))) return false;
+  geminiExplicitCacheRefusedModels.add(String(model || ''));
+  return true;
+}
+
+// True when explicit cache creates must not be attempted: the docs exclude the
+// model, or the server already refused it.
+export function geminiExplicitCacheRefused(model) {
+  return geminiExplicitCacheMinTokens(model) === null || geminiExplicitCacheRefusedModels.has(String(model || ''));
+}
 
 export function _geminiCredentialFingerprint(apiKey) {
   return traceHash(String(apiKey || ''));
@@ -224,7 +258,11 @@ export function _resolveGeminiCacheUsage({ usageMetadata, cachedContent, provide
     firstFinite(usageMetadata?.thoughtsTokenCount, usageMetadata?.thoughts_token_count);
   const hasExplicitPromptTokens =
     Object.hasOwn(usageMetadata || {}, 'promptTokenCount') || Object.hasOwn(usageMetadata || {}, 'prompt_token_count');
-  const inputTokens = hasExplicitPromptTokens ? promptTokens : Math.max(0, totalTokens - outputTokens);
+  // toolUsePromptTokenCount (tool-result prompt tokens) is billed as input and
+  // reported separately from promptTokenCount; cached tokens stay a subset of
+  // the prompt portion.
+  const toolUseTokens = firstFinite(usageMetadata?.toolUsePromptTokenCount, usageMetadata?.tool_use_prompt_token_count);
+  const inputTokens = hasExplicitPromptTokens ? promptTokens + toolUseTokens : Math.max(0, totalTokens - outputTokens);
   const reportedCachedTokens = firstFinite(
     // generateContent UsageMetadata field.
     usageMetadata?.cachedContentTokenCount,