mixdog 1.2.2 → 1.2.3

package/src/runtime/agent/orchestrator/providers/custom-provider-config.mjs

@@ -9,7 +9,7 @@ export const CUSTOM_PROVIDER_PROTOCOLS = Object.freeze(['openai-chat', 'openai-r
 export const CUSTOM_PROVIDER_SCHEMA_VERSION = 2;
 // Ranked weakest → strongest.
 export const CUSTOM_REASONING_LEVELS = CUSTOM_EFFORT_LEVELS;
-export const CUSTOM_REASONING_WIRE_FORMATS = Object.freeze(['standard', 'deepseek']);
+export const CUSTOM_REASONING_WIRE_FORMATS = Object.freeze(['standard', 'deepseek', 'together', 'vllm']);
 export const CUSTOM_PROVIDER_AUTH_MODES = Object.freeze(['key', 'none']);
 export const CUSTOM_MODEL_OVERRIDE_LIMIT = 500;
 
@@ -74,10 +74,22 @@ const V2_TOP_LEVEL_KEYS = new Set([
   'auth',
   'discovery',
   'modelOverrides',
+  'wires',
+  'modelWires',
   'id',
   'apiKey',
+  'apiKeyEnv',
   'preconnect',
 ]);
+export const CUSTOM_API_KEY_ENV_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+// Env var name that supplies the key, or '' when unset (undefined / null).
+function normalizeApiKeyEnv(raw) {
+  if (raw === undefined || raw === null) return '';
+  if (typeof raw !== 'string' || !CUSTOM_API_KEY_ENV_RE.test(raw))
+    fail('apiKeyEnv must be a valid environment variable name');
+  return raw;
+}
 const MAX_BASE_URL = 2048;
 
 function onlyKnownKeys(value, allowed, label) {
@@ -229,6 +241,49 @@ function normalizeOverrides(raw, protocol, legacy) {
   return out;
 }
 
+// The wire each OpenAI-compatible protocol speaks (wire-route.mjs WIRES).
+export const CUSTOM_PROTOCOL_WIRES = Object.freeze({
+  'openai-chat': 'chat',
+  'openai-responses': 'responses',
+  anthropic: 'messages',
+});
+// Wires a user-defined OpenAI-compatible endpoint can be declared to serve.
+export const CUSTOM_PROVIDER_WIRES = Object.freeze(['chat', 'responses', 'messages']);
+
+// `wires`: the wires the endpoint serves (the protocol's own wire included);
+// absent = the protocol's wire only. Anthropic-protocol providers speak one wire.
+function normalizeWires(raw, protocol) {
+  if (raw === undefined) return null;
+  if (protocol === 'anthropic') fail("wires requires an 'openai-chat' or 'openai-responses' protocol");
+  if (!Array.isArray(raw) || raw.length === 0) fail('wires must be a non-empty array');
+  const seen = new Set();
+  for (const wire of raw) {
+    if (!CUSTOM_PROVIDER_WIRES.includes(wire)) fail(`wires has unsupported wire: ${String(wire)}`);
+    if (seen.has(wire)) fail(`wires has duplicate wire: ${wire}`);
+    seen.add(wire);
+  }
+  if (!seen.has(CUSTOM_PROTOCOL_WIRES[protocol]))
+    fail(`wires must include the protocol wire: ${CUSTOM_PROTOCOL_WIRES[protocol]}`);
+  return CUSTOM_PROVIDER_WIRES.filter((wire) => seen.has(wire));
+}
+
+// `modelWires`: per-model wire override, each one of the served wires.
+function normalizeModelWires(raw, protocol, wires) {
+  if (raw === undefined) return {};
+  if (protocol === 'anthropic') fail("modelWires requires an 'openai-chat' or 'openai-responses' protocol");
+  if (!isPlainObject(raw)) fail('modelWires must be an object');
+  const keys = Object.keys(raw);
+  if (keys.length > CUSTOM_MODEL_OVERRIDE_LIMIT) fail(`at most ${CUSTOM_MODEL_OVERRIDE_LIMIT} model wires are allowed`);
+  const served = wires || [CUSTOM_PROTOCOL_WIRES[protocol]];
+  const out = {};
+  for (const key of keys) {
+    const id = modelIdKey(key, 'modelWires key');
+    if (!served.includes(raw[key])) fail(`modelWires[${id}] must be one of the served wires: ${served.join(', ')}`);
+    out[id] = raw[key];
+  }
+  return out;
+}
+
 // Legacy (pre-v2) `models: [{ id, name?, contextWindow?, maxOutputTokens? }]`
 // become manual, visible overrides; their presence hides newly discovered ids.
 function migrateLegacy(input) {
@@ -268,6 +323,8 @@ export function normalizeCustomProviderConfig(input) {
     // v2 fields without the version would be silently dropped by migration.
     if (input.modelOverrides !== undefined || input.discovery !== undefined)
       fail('modelOverrides and discovery require schemaVersion 2');
+    if (input.wires !== undefined || input.modelWires !== undefined)
+      fail('wires and modelWires require schemaVersion 2');
     source = migrateLegacy(input);
   } else if (Number.isInteger(version) && version > CUSTOM_PROVIDER_SCHEMA_VERSION)
     fail(`unsupported schemaVersion ${version}; update mixdog to use this provider`);
@@ -293,10 +350,13 @@ export function normalizeCustomProviderConfig(input) {
   if (!CUSTOM_PROVIDER_PROTOCOLS.includes(protocol)) fail(`unsupported protocol: ${protocol}`);
   const auth = source.auth === undefined || source.auth === null ? 'key' : text(source.auth);
   if (!CUSTOM_PROVIDER_AUTH_MODES.includes(auth)) fail(`invalid auth: ${String(source.auth)}`);
+  const apiKeyEnv = normalizeApiKeyEnv(source.apiKeyEnv);
   const discovery = source.discovery === undefined ? {} : source.discovery;
   if (!isPlainObject(discovery)) fail('discovery must be an object');
   onlyKnownKeys(discovery, DISCOVERY_KEYS, 'discovery');
   const newModelsHidden = optionalBoolean(discovery.newModelsHidden, 'discovery.newModelsHidden') ?? false;
+  const wires = normalizeWires(source.wires, protocol);
+  const modelWires = normalizeModelWires(source.modelWires, protocol, wires);
   return {
     type: 'custom',
     schemaVersion: CUSTOM_PROVIDER_SCHEMA_VERSION,
@@ -305,8 +365,11 @@ export function normalizeCustomProviderConfig(input) {
     baseURL: normalizeBaseURL(source.baseURL),
     enabled: source.enabled !== false,
     auth,
+    ...(apiKeyEnv && auth === 'key' ? { apiKeyEnv } : {}),
     discovery: { newModelsHidden },
     modelOverrides: normalizeOverrides(source.modelOverrides, protocol, legacy),
+    ...(wires ? { wires } : {}),
+    ...(Object.keys(modelWires).length ? { modelWires } : {}),
   };
 }
 

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

@@ -5,7 +5,19 @@
 // under the custom id so model routes and provider identity stay `custom-…`.
 
 import { resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
-import { effectiveCustomModelRows, normalizeCustomProviderConfig } from './custom-provider-config.mjs';
+import {
+  CUSTOM_PROTOCOL_WIRES,
+  effectiveCustomModelRows,
+  normalizeCustomProviderConfig,
+} from './custom-provider-config.mjs';
+import {
+  customWireProfile,
+  providerOffersWire,
+  registerWireProfile,
+  resolveWireRoute,
+  sendOnRoute,
+} from './wire-route.mjs';
+import { withInclusiveUsage } from './lib/inclusive-usage.mjs';
 import { ANTHROPIC_VERSION } from './lib/anthropic-models.mjs';
 import { enrichModels } from './model-catalog.mjs';
 import { fetchCompatModelItems, listCompatModels } from './openai-compat-models.mjs';
@@ -45,6 +57,22 @@ function withCustomModels(Base, discover) {
     _customKey() {
       return this._customKeyless ? '' : resolveProviderApiKey(this.name, this.config);
     }
+    // Env mode with the variable unset: fail before any request is sent.
+    _assertCustomKey() {
+      const name = this.customConfig?.apiKeyEnv;
+      if (name && !this._customKeyless && !resolveProviderApiKey(this.name, this.config))
+        throw new Error(`API key environment variable ${name} is not set`);
+    }
+    // A 401 reload must not fall back to the stale key once the variable is
+    // gone; with a new value the base reload picks it up for the retry.
+    reloadApiKey() {
+      this._assertCustomKey();
+      return super.reloadApiKey();
+    }
+    async send(...args) {
+      this._assertCustomKey();
+      return super.send(...args);
+    }
     _customRows() {
       return effectiveCustomModelRows(this.customConfig, this._customDiscovered || [], { providerId: this.name });
     }
@@ -57,6 +85,7 @@ function withCustomModels(Base, discover) {
     async listModels({ signal = null, throwOnError = false } = {}) {
       let failure = null;
       try {
+        this._assertCustomKey();
         this._customDiscovered = await discover(this, signal);
         this.customDiscoveryError = null;
       } catch (error) {
@@ -112,10 +141,14 @@ export async function createCustomProvider(id, config) {
   // `auth: 'none'` is authoritative: a supplied/injected key is ignored and
   // `keyless` makes the engine omit every credential header.
   const keyless = cfg.auth === 'none';
-  const apiKey = keyless ? '' : config.apiKey || '';
+  // Env mode: the named variable is the only key source.
+  let apiKey = '';
+  if (cfg.apiKeyEnv) apiKey = process.env[cfg.apiKeyEnv] || '';
+  else if (!keyless) apiKey = config.apiKey || '';
   const engine = {
     baseURL: cfg.baseURL,
     apiKey: apiKey || undefined,
+    ...(cfg.apiKeyEnv ? { apiKeyEnv: cfg.apiKeyEnv } : {}),
     ...(keyless ? { keyless: true } : {}),
     ...(config.preconnect === false ? { preconnect: false } : {}),
   };
@@ -129,14 +162,41 @@ export async function createCustomProvider(id, config) {
     provider.nativePdf = false;
   } else {
     const { OpenAICompatProvider } = await import('./openai-compat.mjs');
-    const responses = cfg.protocol === 'openai-responses';
+    // The wires the endpoint is declared to serve (default: the protocol's
+    // own) and the per-model `modelWires` override pick each model's wire
+    // through the shared wire-route table, pinned per session like a gateway.
+    registerWireProfile(
+      providerId,
+      customWireProfile({ protocolWire: CUSTOM_PROTOCOL_WIRES[cfg.protocol], wires: cfg.wires })
+    );
+    let messagesEngine = null;
+    if (providerOffersWire(providerId, 'messages')) {
+      const { AnthropicProvider } = await import('./anthropic.mjs');
+      // The Anthropic SDK appends /v1/messages itself; the endpoint's /v1 base maps to it.
+      messagesEngine = new AnthropicProvider({ ...engine, name: providerId, baseURL: cfg.baseURL.replace(/\/v1$/i, '') });
+      messagesEngine.nativePdf = false;
+    }
     class CompatBase extends OpenAICompatProvider {
+      messagesEngine = messagesEngine;
       _fetchModelItems({ signal = null } = {}) {
         return fetchCompatModelItems(this, { signal, keyless: this._customKeyless });
       }
-      _doSend(messages, model, tools, sendOpts) {
-        if (!responses) return super._doSend(messages, model, tools, sendOpts);
-        return super._doSend(messages, model, tools, { ...(sendOpts || {}), compatWireApi: 'responses' });
+      resolveWireRoute(model, ctx = {}) {
+        return resolveWireRoute(this.name, model, { ...ctx, override: cfg.modelWires?.[model] ?? null });
+      }
+      send(messages, model, tools, sendOpts) {
+        const useModel = model || this.defaultModel;
+        // The resolved route is the only wire authority: a caller's own wire
+        // switches never reach the engine. A custom provider declares the
+        // wires its endpoint serves, so a clear "unsupported" refusal moves
+        // the send to another declared wire once (sendOnRoute).
+        return sendOnRoute(this, useModel, tools, sendOpts, messages, (wire, history, opts) => {
+          if (wire === 'messages' && this.messagesEngine) {
+            return withInclusiveUsage(() => this.messagesEngine.send(history, useModel, tools, opts));
+          }
+          if (wire === 'responses') return super.send(history, model, tools, { ...opts, compatWireApi: 'responses' });
+          return super.send(history, model, tools, opts);
+        });
       }
     }
     const Custom = withCustomModels(CompatBase, (self, signal) =>
@@ -144,6 +204,10 @@ export async function createCustomProvider(id, config) {
     );
     provider = new Custom(providerId, engine);
   }
+  // The bound Messages engine reads the parent's model rows, so a routed
+  // Messages request carries the same row-driven thinking/effort as the
+  // Anthropic protocol.
+  if (provider.messagesEngine) provider.messagesEngine.getCachedModelInfo = (model) => provider.getCachedModelInfo(model);
   provider.customConfig = cfg;
   provider._customKeyless = keyless;
   provider._applyCustomRows(provider._customRows());

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

@@ -183,7 +183,9 @@ 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 };
 }
 

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();
+  // 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

@@ -66,17 +66,28 @@ export function _estimateGeminiCacheTokens(systemInstruction, geminiTools, conte
   return Math.ceil(chars / 4);
 }
 
-// No catalog publishes the cachedContents floor and the published minimums
-// differ per model and change between releases, so one floor serves every id:
-// the highest published minimum. Skipping a small prefix only falls back to the
-// implicit cache, whereas a floor that is too low would POST a create that the
-// server rejects on every turn.
+// 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;
 
-export function _geminiCacheMinTokens() {
+// 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 geminiExplicitCacheMinTokens(model) ?? GEMINI_CACHE_MIN_TOKENS;
+}
+
 export function _geminiCachePrefixCount(contents) {
   return Array.isArray(contents) && contents.length > 1 ? contents.length - 1 : 0;
 }
@@ -128,8 +139,10 @@ export function markGeminiExplicitCacheRefused(model, err) {
   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 geminiExplicitCacheRefusedModels.has(String(model || ''));
+  return geminiExplicitCacheMinTokens(model) === null || geminiExplicitCacheRefusedModels.has(String(model || ''));
 }
 
 export function _geminiCredentialFingerprint(apiKey) {
@@ -245,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,

package/src/runtime/agent/orchestrator/providers/gemini-error-contract.mjs

@@ -180,12 +180,94 @@ export function assertNoGeminiInBandError(chunk, label) {
   if (err) throw err;
 }
 
-const SAFETY_FINISH = /^(?:PROMPT_)?(?:SAFETY|IMAGE_SAFETY|BLOCKLIST|PROHIBITED_CONTENT|SPII|IMAGE_PROHIBITED_CONTENT)$/;
+const FINISH_KINDS = new Map(
+  Object.entries({
+    complete: ['STOP'],
+    output_limit: ['MAX_TOKENS'],
+    // Content refused by policy: deterministic, never re-asked.
+    policy: [
+      'SAFETY',
+      'BLOCKLIST',
+      'PROHIBITED_CONTENT',
+      'SPII',
+      'IMAGE_SAFETY',
+      'IMAGE_PROHIBITED_CONTENT',
+      'ESCALATION',
+      'PUP_LIMITED_DISABLED',
+    ],
+    language: ['LANGUAGE'],
+    recitation: ['RECITATION', 'IMAGE_RECITATION'],
+    // The model produced no usable call: the same request is re-asked.
+    invalid_tool_call: ['MALFORMED_FUNCTION_CALL', 'UNEXPECTED_TOOL_CALL', 'MALFORMED_RESPONSE'],
+    // Tool-call terminals a re-ask cannot fix.
+    tool_call: ['TOO_MANY_TOOL_CALLS', 'MISSING_THOUGHT_SIGNATURE'],
+    continuation: ['CONTINUATION'],
+    other: ['OTHER', 'IMAGE_OTHER', 'NO_IMAGE'],
+  }).flatMap(([kind, reasons]) => reasons.map((reason) => [reason, kind]))
+);
+
+/** Finish (or `PROMPT_`-prefixed block) reason without wire prefixes. */
+export function geminiNormalizeFinishReason(finishReason) {
+  return String(finishReason || '')
+    .replace(/^FINISH_REASON_/, '')
+    .replace(/^PROMPT_/, '')
+    .replace(/^BLOCK_REASON_/, '');
+}
+
+/**
+ * Kind of a documented finishReason / blockReason: 'none' (absent or
+ * UNSPECIFIED: the stream is unfinished), 'complete', 'output_limit',
+ * 'policy', 'language', 'recitation', 'invalid_tool_call', 'tool_call',
+ * 'continuation' or 'other' (OTHER and any undocumented future reason).
+ */
+export function geminiFinishReasonKind(finishReason) {
+  const reason = geminiNormalizeFinishReason(finishReason);
+  if (!reason || reason === 'UNSPECIFIED') return 'none';
+  return FINISH_KINDS.get(reason) || 'other';
+}
 
 /** Policy-refusal code for a finishReason, or null for any other reason. */
 export function geminiPolicyFinishCode(finishReason) {
-  const reason = String(finishReason || '').replace(/^FINISH_REASON_/, '');
-  if (SAFETY_FINISH.test(reason)) return 'safety';
-  if (/^(?:PROMPT_)?RECITATION$/.test(reason)) return 'recitation';
-  return null;
+  switch (geminiFinishReasonKind(finishReason)) {
+    case 'policy':
+      return 'safety';
+    case 'recitation':
+      return 'recitation';
+    case 'language':
+      return 'content_filter';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Evidence a terminal response carries beyond its finishReason: candidate and
+ * prompt safety ratings, the finish message, the prompt block reason and any
+ * continuation token. Only present fields are returned.
+ */
+export function geminiFinishErrorFields(response) {
+  const candidate = response?.candidates?.[0];
+  const feedback = response?.promptFeedback;
+  const fields = {
+    finishMessage: candidate?.finishMessage,
+    safetyRatings: candidate?.safetyRatings,
+    blockReason: feedback?.blockReason,
+    promptSafetyRatings: feedback?.safetyRatings,
+    continuationToken: candidate?.continuationToken,
+  };
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * Typed result for a CONTINUATION finish, which this client cannot resume
+ * (Gemini direct only). Keeps the original error's partial turn and the
+ * token so a caller can continue it out of band.
+ */
+export function geminiContinuationUnsupportedError(incomplete, response) {
+  return Object.assign(incomplete, geminiFinishErrorFields(response), {
+    name: 'GeminiContinuationUnsupportedError',
+    code: 'CONTINUATION_UNSUPPORTED',
+    continuationUnsupported: true,
+    message: 'Gemini response stopped with finishReason=CONTINUATION; continuation is not supported by this client',
+  });
 }