mixdog 1.2.2 → 1.2.4

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

@@ -1,3 +1,4 @@
+import { isVisibleStreamProgress } from '../../../shared/stream-progress.mjs';
 import { anthropicEffortLevelsFor, normalizeAnthropicEffortInput } from './anthropic-effort.mjs';
 import { CUSTOM_EFFORT_LEVELS, customEffortLevels, isCustomProviderName } from './custom-reasoning.mjs';
 import { codexModelSupportsEffortUpdates } from './openai-oauth-catalog.mjs';
@@ -72,19 +73,40 @@ export function isEffortConfigurationRejection(status, text) {
 /**
  * Runs `send(opts)`; when the model rejects the mid-conversation effort
  * update, switches the updates off for it and replays the request once
- * without them. The rejection happens before any output streams.
+ * without them. Never replay after output reached the caller, cancellation,
+ * or an explicit opt-out; a late error is not evidence of missing support.
  */
 export async function withEffortConfigurationFallback(provider, model, opts, send) {
+  let streamed = false;
+  const track =
+    (callback, isProgress = false) =>
+    (...args) => {
+      if (!isProgress || isVisibleStreamProgress(args[0])) streamed = true;
+      return callback(...args);
+    };
+  const tracked = { ...opts };
+  if (typeof opts?.onStreamDelta === 'function') tracked.onStreamDelta = track(opts.onStreamDelta, true);
+  if (typeof opts?.onTextDelta === 'function') tracked.onTextDelta = track(opts.onTextDelta);
+  if (typeof opts?.onToolCall === 'function') tracked.onToolCall = track(opts.onToolCall);
   try {
-    return await send(opts);
+    return await send(tracked);
   } catch (error) {
     const status = error?.status ?? error?.httpStatus;
-    if (opts?._effortConfigurationRetry || !isEffortConfigurationRejection(status, error?.message)) throw error;
+    const emitted =
+      streamed || error?.liveTextEmitted === true || error?.emittedToolCall === true || error?.unsafeToRetry === true;
+    if (
+      opts?._effortConfigurationRetry ||
+      opts?.effortConfigurationEnabled === false ||
+      opts?.signal?.aborted ||
+      emitted ||
+      !isEffortConfigurationRejection(status, error?.message)
+    )
+      throw error;
     markEffortConfigurationUnsupported(provider, model);
     process.stderr.write(
       `[${provider}] ${model} rejected the mid-conversation effort update; retrying once without it\n`
     );
-    return send({ ...opts, effortConfigurationEnabled: false, _effortConfigurationRetry: true });
+    return send({ ...tracked, effortConfigurationEnabled: false, _effortConfigurationRetry: true });
   }
 }
 const OPENAI_PROVIDERS = new Set(['openai', 'openai-oauth']);
@@ -183,7 +205,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,30 @@ 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 +141,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,20 +260,28 @@ 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);
-  const reportedCachedTokens = firstFinite(
+  // 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 reportedCachedCount = [
     // generateContent UsageMetadata field.
     usageMetadata?.cachedContentTokenCount,
     usageMetadata?.cached_content_token_count,
     // Newer SDK convenience alias documented for implicit cache hits.
     usageMetadata?.totalCachedTokens,
-    usageMetadata?.total_cached_tokens
-  );
+    usageMetadata?.total_cached_tokens,
+  ]
+    .map((value) => (value == null ? NaN : Number(value)))
+    .find((value) => Number.isFinite(value) && value >= 0);
+  const reportedCachedTokens = reportedCachedCount ?? 0;
   const cachedFallbackTokens = cachedContent ? Number(providerState?.gemini?.cacheTokenSize || 0) || 0 : 0;
-  const rawCachedTokens = reportedCachedTokens > 0 ? reportedCachedTokens : cachedFallbackTokens;
+  // An explicit zero is a measured miss, not missing usage metadata.
+  const rawCachedTokens = reportedCachedCount ?? cachedFallbackTokens;
   const cachedTokens = inputTokens > 0 ? Math.min(rawCachedTokens, inputTokens) : rawCachedTokens;
   let cacheTokenSource = 'none';
-  if (reportedCachedTokens > 0) cacheTokenSource = 'usage_metadata';
+  if (reportedCachedCount !== undefined) cacheTokenSource = 'usage_metadata';
   else if (cachedFallbackTokens > 0) cacheTokenSource = 'cache_create_fallback';
   return {
     inputTokens,

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

@@ -97,7 +97,10 @@ export function geminiErrorContract({ details, errorDetails, googleStatus, messa
         const scope = scopeOf(String(violation?.quotaId || ''));
         if (scope) scopes.add(scope);
         // A spent allowance is named by the typed violation, not by prose.
-        if (String(violation?.quotaValue ?? '').trim() === '0' || LIMIT_ZERO_RE.test(String(violation?.description || ''))) {
+        if (
+          String(violation?.quotaValue ?? '').trim() === '0' ||
+          LIMIT_ZERO_RE.test(String(violation?.description || ''))
+        ) {
           zeroLimit = true;
         }
       }
@@ -121,7 +124,9 @@ export function geminiErrorContract({ details, errorDetails, googleStatus, messa
     CAPACITY_REASONS.has(reason) ||
     (!reason && scopes.size === 0 && retryAfterMs === undefined && CAPACITY_MESSAGE_RE.test(text));
   // A per-day violation outlasts any per-minute one reported with it.
-  let quotaScope = scopes.has('day') ? 'day' : scopes.has('minute') ? 'minute' : undefined;
+  let quotaScope;
+  if (scopes.has('day')) quotaScope = 'day';
+  else if (scopes.has('minute')) quotaScope = 'minute';
   if (retryAfterMs === undefined) {
     const named = MESSAGE_DELAY_RE.exec(text);
     if (named) retryAfterMs = adviceMs(named[1]);
@@ -158,10 +163,13 @@ export function geminiInBandError(chunk, label) {
   if (!detail || (typeof detail !== 'object' && typeof detail !== 'string')) return null;
   const body = typeof detail === 'object' ? detail : { message: detail };
   const googleStatus = typeof body.status === 'string' ? body.status : '';
-  const status = Number.isFinite(Number(body.code)) && Number(body.code) > 0
-    ? Number(body.code)
-    : GOOGLE_STATUS_HTTP[googleStatus.toUpperCase()];
-  const err = new Error(`${label} in-band error${status ? ` ${status}` : ''}: ${String(body.message || googleStatus || 'unknown').slice(0, 300)}`);
+  const status =
+    Number.isFinite(Number(body.code)) && Number(body.code) > 0
+      ? Number(body.code)
+      : GOOGLE_STATUS_HTTP[googleStatus.toUpperCase()];
+  const err = new Error(
+    `${label} in-band error${status ? ` ${status}` : ''}: ${String(body.message || googleStatus || 'unknown').slice(0, 300)}`
+  );
   err.name = 'GeminiInBandError';
   if (status) {
     err.status = status;
@@ -180,12 +188,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',
+  });
 }

package/src/runtime/agent/orchestrator/providers/gemini-request-body.mjs

@@ -12,6 +12,30 @@ import { geminiThinkingConfig } from './gemini-thinking.mjs';
 import { toGeminiContents, toGeminiRequestTools, toGeminiToolConfig } from './gemini-schema.mjs';
 
 // Request pieces shared by the cached REST path and the SDK path.
+// Caller-supplied generation controls the wire carries in generationConfig.
+// maxOutputTokens counts thought tokens too (see the thinking docs). Anything
+// invalid is rejected here instead of being dropped. (safetySettings is a
+// request-level field, forwarded separately.)
+function geminiGenerationControls(opts) {
+  const controls = {};
+  const maxRaw = opts.maxOutputTokens ?? opts.max_output_tokens;
+  if (maxRaw !== undefined && maxRaw !== null) {
+    const max = Number(maxRaw);
+    if (!Number.isInteger(max) || max <= 0) {
+      throw new TypeError('maxOutputTokens must be a positive integer (it includes thinking tokens).');
+    }
+    controls.maxOutputTokens = max;
+  }
+  if (opts.temperature !== undefined && opts.temperature !== null) {
+    const temperature = Number(opts.temperature);
+    if (!Number.isFinite(temperature) || temperature < 0 || temperature > 2) {
+      throw new TypeError('temperature must be a number between 0 and 2.');
+    }
+    controls.temperature = temperature;
+  }
+  return controls;
+}
+
 export function buildGeminiRequest(messages, useModel, tools, opts) {
   // Gemini returns thought summaries only when the request asks for them.
   // Without this the reasoning channel stays empty for the whole turn and
@@ -19,7 +43,11 @@ export function buildGeminiRequest(messages, useModel, tools, opts) {
   // round reads as another preamble. On by default for every model; an
   // explicit opts.includeThoughts still wins.
   const thinkingConfig = geminiThinkingConfig(useModel, opts, { includeThoughts: true });
-  const generationConfig = thinkingConfig ? { thinkingConfig } : undefined;
+  const controls = geminiGenerationControls(opts);
+  let generationConfig;
+  if (thinkingConfig || Object.keys(controls).length) {
+    generationConfig = { ...(thinkingConfig ? { thinkingConfig } : {}), ...controls };
+  }
   const systemInstruction =
     messages
       .filter((m) => m.role === 'system')
@@ -29,17 +57,24 @@ export function buildGeminiRequest(messages, useModel, tools, opts) {
   const contents = toGeminiContents(chatMsgs, useModel);
   if (!contents.length) throw new Error('No messages to send');
 
-  const requestTools = toGeminiRequestTools(tools, opts.nativeTools);
+  const requestTools = toGeminiRequestTools(tools, opts.nativeTools, { onToolExcluded: opts.onToolExcluded });
   const geminiTools = requestTools.length ? requestTools : undefined;
-  const toolConfig = tools?.length ? toGeminiToolConfig(opts.toolChoice) : undefined;
-  return { generationConfig, systemInstruction, contents, geminiTools, toolConfig };
+  // Tool config only accompanies function declarations that were kept.
+  const toolConfig = requestTools.some((entry) => entry.functionDeclarations?.length)
+    ? toGeminiToolConfig(opts.toolChoice)
+    : undefined;
+  if (opts.safetySettings !== undefined && opts.safetySettings !== null && !Array.isArray(opts.safetySettings)) {
+    throw new TypeError('safetySettings must be an array of { category, threshold } entries.');
+  }
+  const safetySettings = opts.safetySettings?.length ? opts.safetySettings : undefined;
+  return { generationConfig, systemInstruction, contents, geminiTools, toolConfig, safetySettings };
 }
 
 // The generateContent body for a cached prefix. The cache carries the
 // recorded prefix; every uncached tail turn is sent, not just the last
 // message, so reused cachedContents preserve full conversation context
 // between periodic refreshes.
-export function geminiCachedRestBody({ opts, contents, cachedContent, generationConfig }) {
+export function geminiCachedRestBody({ opts, contents, cachedContent, generationConfig, safetySettings }) {
   const cachedPrefixContentCount = Number.isFinite(Number(opts.providerState?.gemini?.cachePrefixContentCount))
     ? Math.max(0, Math.min(contents.length, Math.trunc(Number(opts.providerState.gemini.cachePrefixContentCount))))
     : 0;
@@ -48,5 +83,6 @@ export function geminiCachedRestBody({ opts, contents, cachedContent, generation
     contents: deltaContents.length ? deltaContents : contents.slice(-1),
     cachedContent,
     ...(generationConfig ? { generationConfig } : {}),
+    ...(safetySettings ? { safetySettings } : {}),
   };
 }

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

@@ -149,6 +149,7 @@ export function resolveGeminiUsage(response, opts, cachedContent, useModel) {
 }
 
 export function geminiSendResult(parsed, useModel, opts, resolvedUsage) {
+  if (parsed.providerReplay) parsed.providerReplay.requestContext = { model: useModel };
   return {
     content: parsed.content,
     model: useModel,

package/src/runtime/agent/orchestrator/providers/gemini-rest-stream/watchdogs.mjs

@@ -1,7 +1,11 @@
 // First-byte and idle watchdogs of one Gemini REST SSE body. Either timeout
 // cancels the reader and fails the pending read, so the caller surfaces a typed
-// timeout instead of waiting on a stalled socket.
-import { PROVIDER_SSE_IDLE_TIMEOUT_MS, PROVIDER_SSE_IDLE_WATCHDOG_ENABLED } from '../../stall-policy.mjs';
+// timeout instead of waiting on a stalled socket. The idle timer re-arms only
+// on decoded payloads (semantic progress), so it uses the semantic window.
+// Each timeout names its phase (`timeoutPhase`): 'first-chunk' before any
+// payload, 'idle' after one.
+import { PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS, PROVIDER_SSE_IDLE_WATCHDOG_ENABLED } from '../../stall-policy.mjs';
+import { TIMEOUT_PHASE } from '../../../../shared/provider-timeout-phase.mjs';
 
 export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, timeoutError }) {
   let idleTimedOut = false;
@@ -19,11 +23,18 @@ export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, t
     pendingReject = null;
     reject(err);
   };
-  const idleError = () => timeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
+  const idleError = () =>
+    Object.assign(timeoutError(`${label} SSE idle`, PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS), {
+      timeoutPhase: TIMEOUT_PHASE.IDLE,
+    });
 
   let firstByteTimer = setTimeout(() => {
     cancelReader('first byte timeout');
-    failPending(timeoutError(`${label} first byte`, firstByteTimeoutMs));
+    failPending(
+      Object.assign(timeoutError(`${label} first byte`, firstByteTimeoutMs), {
+        timeoutPhase: TIMEOUT_PHASE.FIRST_CHUNK,
+      })
+    );
   }, firstByteTimeoutMs);
   firstByteTimer.unref?.();
   const clearFirstByte = () => {
@@ -46,7 +57,7 @@ export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, t
         idleTimedOut = true;
         cancelReader('SSE idle timeout');
         failPending(idleError());
-      }, PROVIDER_SSE_IDLE_TIMEOUT_MS);
+      }, PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS);
       idleTimer.unref?.();
     },
     // One reader.read() with its reject handle registered for the watchdogs;

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

@@ -11,8 +11,9 @@
  *                     re-issues the whole request up to 4 attempts total at
  *                     1s / 2s / 4s. A response that finished with no finish
  *                     reason is never judged here, and right after a tool
- *                     result an empty response (no finish reason or no text)
- *                     is accepted as the model's answer. An empty answer that
+ *                     result an empty STOP answer is accepted as the model's
+ *                     answer (an empty stream with no finish reason is still
+ *                     unfinished). An empty answer that
  *                     survives all 4 attempts throws a typed, provider-terminal
  *                     invalid-stream error instead of returning nothing.
  *   long advice       a server wait over 300s ends recovery on both phases
@@ -25,6 +26,7 @@
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { DETERMINISTIC_KINDS, providerErrorKind, typedCodeKind } from './provider-error-kind.mjs';
 import { midstreamRetryDelayMs } from './retry-backoff.mjs';
+import { geminiFinishReasonKind, geminiNormalizeFinishReason } from './gemini-error-contract.mjs';
 import { classifyError, markProviderRecoveryExhausted, sleepWithAbort, withRetry } from './retry-classifier.mjs';
 
 export const GEMINI_REQUEST_RETRY = Object.freeze({
@@ -80,16 +82,13 @@ export function geminiMidstreamDelayMs(err, streamAttempt, signal = null) {
 
 const statusOf = (err) => Number(err?.httpStatus || err?.status || 0);
 
-const INVALID_TOOL_CALL_FINISH = new Set(['MALFORMED_FUNCTION_CALL', 'UNEXPECTED_TOOL_CALL']);
-// Empty-text finishes that are deterministic refusals or output-limit stops,
-// owned by the policy / incomplete handling instead of a re-ask.
-const EMPTY_TEXT_TERMINAL_FINISH = new Set(['MAX_TOKENS', 'SAFETY', 'RECITATION']);
-
 /**
  * Invalid stream: the reason a finished response is unusable
- * ('MALFORMED_FUNCTION_CALL' | 'UNEXPECTED_TOOL_CALL' | 'NO_RESPONSE_TEXT'),
- * or null. A response that carried a tool call, or whose text was already
- * relayed, is never invalid (and never replayed).
+ * ('MALFORMED_FUNCTION_CALL' | 'UNEXPECTED_TOOL_CALL' | 'MALFORMED_RESPONSE' |
+ * 'NO_RESPONSE_TEXT'), or null. A response that carried a tool call, or whose
+ * text was already relayed, is never invalid (and never replayed). Only a
+ * STOP with no text is "no text"; every other documented finish (policy,
+ * output limit, continuation, OTHER, ...) is owned by the incomplete handling.
  */
 export function geminiInvalidStreamReason(response, textLeakGuard = null, { afterToolResult = false } = {}) {
   const candidate = response?.candidates?.[0];
@@ -97,9 +96,10 @@ export function geminiInvalidStreamReason(response, textLeakGuard = null, { afte
   if (parts.some((part) => part?.functionCall)) return null;
   if ((textLeakGuard?.getLeakedToolCalls?.() || []).length > 0) return null;
   if ((textLeakGuard?.getRelayedText?.() || '').length > 0) return null;
-  const finish = String(candidate?.finishReason || '').replace(/^FINISH_REASON_/, '');
-  if (INVALID_TOOL_CALL_FINISH.has(finish)) return finish;
-  if (!finish || EMPTY_TEXT_TERMINAL_FINISH.has(finish)) return null;
+  const finish = geminiNormalizeFinishReason(candidate?.finishReason);
+  const kind = geminiFinishReasonKind(finish);
+  if (kind === 'invalid_tool_call') return finish;
+  if (kind !== 'complete') return null;
   // Right after a tool result the model may legitimately answer with nothing.
   if (afterToolResult) return null;
   const text = parts
@@ -148,7 +148,12 @@ export async function runGeminiStreamAttempts({ run, signal, onRetry, sleepFn, a
     } catch (err) {
       const waitMs = connected ? geminiMidstreamDelayMs(err, streamAttempt, signal) : null;
       if (waitMs == null) throw err;
-      onRetry?.({ attempt: streamAttempt + 1, maxAttempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS, lastErr: err, delayMs: waitMs });
+      onRetry?.({
+        attempt: streamAttempt + 1,
+        maxAttempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS,
+        lastErr: err,
+        delayMs: waitMs,
+      });
       await sleepWithAbort(waitMs, signal, sleepFn, 'Gemini stream retry wait aborted');
       continue;
     }