mixdog 1.2.1 → 1.2.3

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

@@ -26,6 +26,11 @@ import { createSdkStreamReader } from './gemini-sdk-stream/reader.mjs';
 import { createRestStreamWatchdogs } from './gemini-rest-stream/watchdogs.mjs';
 import { drainSseDataLines, sseDataPayload } from './gemini-rest-stream/sse-lines.mjs';
 import { noteAbandonedUsage } from '../../../shared/llm/usage-context.mjs';
+import {
+  applyGeminiErrorContract,
+  assertNoGeminiInBandError,
+  geminiFinishReasonKind,
+} from './gemini-error-contract.mjs';
 
 export const GEMINI_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
   'MIXDOG_GEMINI_FIRST_BYTE_TIMEOUT_MS',
@@ -132,9 +137,16 @@ export function normalizeGeminiSdkError(err, label) {
   const transport = geminiSdkTransportError(err, label);
   if (transport) return transport;
   const stamped = stampGeminiRpcError(err);
-  return isGeminiSdkStreamParseError(stamped)
-    ? geminiStreamCorruptionError(`${label} corrupt SDK SSE JSON`, stamped)
-    : stamped;
+  if (isGeminiSdkStreamParseError(stamped)) {
+    return geminiStreamCorruptionError(`${label} corrupt SDK SSE JSON`, stamped);
+  }
+  if (!stamped || typeof stamped !== 'object') return stamped;
+  return applyGeminiErrorContract(stamped, {
+    details: stamped.details,
+    errorDetails: stamped.errorDetails,
+    googleStatus: stamped.geminiStatus,
+    message: stamped.message,
+  });
 }
 
 // CC-rule safety stamp for Gemini stream failures (provider-stall audit):
@@ -175,8 +187,10 @@ function stampGeminiStreamFailure(
   const visible = visibleText.length > 0;
   // Native functionCall chunks are only dispatched after successful stream
   // completion in gemini.mjs. Until then a reconnect is safe. Text-leaked
-  // calls are dispatched while parsing and remain a hard replay boundary.
-  const pendingTool = leaked;
+  // calls are dispatched while parsing and remain a hard replay boundary,
+  // unless the guard holds them back (`deferToolCalls`): a held call never
+  // runs when the stream fails, so a reconnect cannot double-execute it.
+  const pendingTool = leaked && textLeakGuard?.defersToolCalls !== true;
   try {
     if (visible) {
       err.liveTextEmitted = true;
@@ -225,25 +239,35 @@ export function geminiChunkProgressKind(chunk) {
  * (same shape as a non-streaming generateContent JSON body).
  * Mirrors @google/generative-ai aggregateResponses().
  */
-function aggregateGeminiStreamChunks(responses) {
-  const lastResponse = responses[responses.length - 1];
-  const aggregatedResponse = {
-    promptFeedback: lastResponse?.promptFeedback,
-  };
+function aggregateGeminiStreamChunks(responses, label = 'Gemini stream') {
+  // An error envelope anywhere in the stream — including after STOP — fails
+  // the turn instead of aggregating into a success.
+  for (const response of responses) assertNoGeminiInBandError(response, label);
+  const aggregatedResponse = {};
+  // Candidates are keyed by their own `index`; chunks that omit it fall back
+  // to the position inside that chunk's candidate list.
+  const candidatesByIndex = new Map();
   for (const response of responses) {
+    // Early block info must survive later chunks that carry none.
+    if (response?.promptFeedback) {
+      aggregatedResponse.promptFeedback = { ...aggregatedResponse.promptFeedback, ...response.promptFeedback };
+    }
     if (response?.candidates) {
-      let candidateIndex = 0;
-      for (const candidate of response.candidates) {
-        if (!aggregatedResponse.candidates) aggregatedResponse.candidates = [];
-        if (!aggregatedResponse.candidates[candidateIndex]) {
-          aggregatedResponse.candidates[candidateIndex] = { index: candidateIndex };
+      response.candidates.forEach((candidate, position) => {
+        const candidateIndex = Number.isInteger(candidate?.index) ? candidate.index : position;
+        if (!candidatesByIndex.has(candidateIndex)) candidatesByIndex.set(candidateIndex, { index: candidateIndex });
+        const aggCand = candidatesByIndex.get(candidateIndex);
+        // A later chunk that omits a field never erases an earlier value.
+        if (candidate.citationMetadata !== undefined) {
+          aggCand.citationMetadata = mergeStreamMetadata(aggCand.citationMetadata, candidate.citationMetadata);
         }
-        const aggCand = aggregatedResponse.candidates[candidateIndex];
-        aggCand.citationMetadata = candidate.citationMetadata;
-        aggCand.groundingMetadata = candidate.groundingMetadata;
-        aggCand.finishReason = candidate.finishReason;
-        aggCand.finishMessage = candidate.finishMessage;
-        aggCand.safetyRatings = candidate.safetyRatings;
+        if (candidate.groundingMetadata !== undefined) {
+          aggCand.groundingMetadata = mergeStreamMetadata(aggCand.groundingMetadata, candidate.groundingMetadata);
+        }
+        if (geminiFinishReasonKind(candidate.finishReason) !== 'none') aggCand.finishReason = candidate.finishReason;
+        if (candidate.finishMessage !== undefined) aggCand.finishMessage = candidate.finishMessage;
+        if (candidate.safetyRatings !== undefined) aggCand.safetyRatings = candidate.safetyRatings;
+        if (candidate.continuationToken !== undefined) aggCand.continuationToken = candidate.continuationToken;
         if (candidate.content?.parts) {
           if (!aggCand.content) {
             aggCand.content = {
@@ -262,19 +286,52 @@ function aggregateGeminiStreamChunks(responses) {
             aggCand.content.parts.push(newPart);
           }
         }
-        candidateIndex++;
-      }
+      });
     }
     if (response?.usageMetadata) aggregatedResponse.usageMetadata = response.usageMetadata;
   }
+  if (candidatesByIndex.size) {
+    aggregatedResponse.candidates = [...candidatesByIndex.values()].sort((a, b) => a.index - b.index);
+  }
   return aggregatedResponse;
 }
 
+// GroundingMetadata / CitationMetadata arrive in pieces while streaming and
+// are merged, not replaced: groundingChunks carry only the chunks not sent
+// before (appended as-is, so groundingSupports indices stay valid); every
+// other list is a de-duplicated union, nested objects merge, scalars take the
+// latest value.
+function mergeStreamMetadata(previous, next) {
+  if (!previous) return next;
+  if (!next || typeof next !== 'object') return previous;
+  const merged = { ...previous };
+  for (const [key, value] of Object.entries(next)) {
+    if (value === undefined || value === null) continue;
+    const before = previous[key];
+    if (Array.isArray(value)) {
+      if (key === 'groundingChunks') {
+        merged[key] = [...(before || []), ...value];
+      } else {
+        const seen = new Set((before || []).map((item) => JSON.stringify(item)));
+        merged[key] = [...(before || []), ...value.filter((item) => !seen.has(JSON.stringify(item)))];
+      }
+    } else if (typeof value === 'object' && before && typeof before === 'object') {
+      merged[key] = { ...before, ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+// A stream that ends with no finishReason is unfinished, whatever it carried
+// (thoughts only, an empty body, even right after a tool result); only a
+// STOP that carries no text is a completed, empty answer.
 function assertGeminiStreamCompleted({ sawStreamChunk, finishReason, promptBlockReason, label }) {
   if (!sawStreamChunk) {
     throw geminiTruncatedStreamError(`${label} truncated: empty stream`);
   }
-  if (!finishReason && !promptBlockReason) {
+  if (geminiFinishReasonKind(finishReason) === 'none' && geminiFinishReasonKind(promptBlockReason) === 'none') {
     throw geminiTruncatedStreamError(`${label} truncated: no finishReason`);
   }
 }
@@ -316,13 +373,23 @@ function relayGeminiStreamText(t, { onTextDelta, textLeakGuard }) {
  * `part.text` streams. Mirrors the Anthropic OAuth guard: suppress tags from
  * visible text, synthesize known-tool calls, dispatch via onToolCall.
  */
-export function createGeminiTextLeakGuard({ knownToolNames, onTextDelta, onToolCall, onStreamDelta }) {
+export function createGeminiTextLeakGuard({
+  knownToolNames,
+  onTextDelta,
+  onToolCall,
+  onStreamDelta,
+  deferToolCalls = false,
+}) {
   const _knownTools = knownToolNameSet(knownToolNames);
   const _enabled = _knownTools.size > 0;
   const _isKnownTool = (name) => _knownTools.has(name);
   let leakBuffer = '';
   let relayedText = '';
   const leakedCalls = [];
+  // With `deferToolCalls`, recovered calls wait here until the caller has seen
+  // the response finish cleanly (releaseDeferredToolCalls); a failed response
+  // never runs them.
+  const deferredCalls = [];
   const dispatchedFingerprints = new Set();
 
   const dispatchLeakedCall = (recovered) => {
@@ -344,9 +411,12 @@ export function createGeminiTextLeakGuard({ knownToolNames, onTextDelta, onToolC
       arguments: args,
     };
     leakedCalls.push(call);
-    try {
-      onToolCall?.(call);
-    } catch {}
+    if (deferToolCalls) deferredCalls.push(call);
+    else {
+      try {
+        onToolCall?.(call);
+      } catch {}
+    }
     try {
       onStreamDelta?.('tool');
     } catch {}
@@ -373,6 +443,9 @@ export function createGeminiTextLeakGuard({ knownToolNames, onTextDelta, onToolC
     get enabled() {
       return _enabled;
     },
+    get defersToolCalls() {
+      return deferToolCalls === true;
+    },
     feedText(text) {
       if (!text) return;
       if (!_enabled) {
@@ -411,6 +484,13 @@ export function createGeminiTextLeakGuard({ knownToolNames, onTextDelta, onToolC
     getLeakedToolCalls() {
       return [...leakedCalls];
     },
+    releaseDeferredToolCalls() {
+      for (const call of deferredCalls.splice(0)) {
+        try {
+          onToolCall?.(call);
+        } catch {}
+      }
+    },
     getRelayedText() {
       return relayedText;
     },
@@ -436,7 +516,16 @@ function createLeakGuardFinalizer(textLeakGuard) {
 // aggregation, leak guard, watchdogs — stays shared.
 export async function consumeGeminiRestStreamResponse(
   response,
-  { signal, onStreamDelta, onTextDelta, textLeakGuard, label, unwrapChunk = null, onChunk = null, failureUsage = null }
+  {
+    signal,
+    onStreamDelta,
+    onTextDelta,
+    textLeakGuard,
+    label,
+    unwrapChunk = null,
+    onChunk = null,
+    failureUsage = null,
+  }
 ) {
   const unwrap =
     typeof unwrapChunk === 'function'
@@ -464,7 +553,10 @@ export async function consumeGeminiRestStreamResponse(
   });
   // One decoded chunk: collected for aggregation and relayed to every sink.
   const relayChunk = (rawChunk) => {
+    // In-band errors stay top level even on a transport that nests payloads.
+    assertNoGeminiInBandError(rawChunk, label);
     const parsed = unwrap(rawChunk);
+    assertNoGeminiInBandError(parsed, label);
     if (!sawStreamChunk) {
       sawStreamChunk = true;
       watchdogs.clearFirstByte();
@@ -530,12 +622,13 @@ export async function consumeGeminiRestStreamResponse(
     }
     const tail = sseDataPayload(buffer.trim());
     if (tail) {
+      let rawTail;
       try {
-        const [rawTail] = await parseProviderJsonBatch([tail]);
-        relayChunk(rawTail);
+        [rawTail] = await parseProviderJsonBatch([tail]);
       } catch (cause) {
         throw geminiStreamCorruptionError(`${label} corrupt SSE tail JSON`, cause);
       }
+      relayChunk(rawTail);
     }
   } catch (err) {
     finalizeLeakGuard();
@@ -558,7 +651,7 @@ export async function consumeGeminiRestStreamResponse(
     finalizeLeakGuard();
   }
 
-  const aggregated = aggregateGeminiStreamChunks(allChunks);
+  const aggregated = aggregateGeminiStreamChunks(allChunks, label);
   const finishReason = aggregated.candidates?.[0]?.finishReason || null;
   const promptBlockReason = aggregated.promptFeedback?.blockReason || null;
   // Truncation (no finishReason) after visible output must carry the same
@@ -566,7 +659,12 @@ export async function consumeGeminiRestStreamResponse(
   // above, so stamp here too (review High: transient TRUNCATED_STREAM would
   // otherwise replay/double-render live text via withRetry).
   try {
-    assertGeminiStreamCompleted({ sawStreamChunk, finishReason, promptBlockReason, label });
+    assertGeminiStreamCompleted({
+      sawStreamChunk,
+      finishReason,
+      promptBlockReason,
+      label,
+    });
   } catch (err) {
     throw stampGeminiStreamFailure(err, { relayedText, textLeakGuard, chunks: allChunks, failureUsage });
   }
@@ -636,6 +734,7 @@ export async function consumeGeminiSdkStream(
       if (signal?.aborted) throw abortError();
       if (step.done) break;
       reader.noteChunk();
+      assertNoGeminiInBandError(step.value, label);
       if (step.value) collectedChunks.push(step.value);
       try {
         onStreamDelta?.(geminiChunkProgressKind(step.value));
@@ -652,7 +751,7 @@ export async function consumeGeminiSdkStream(
     // locally; retain the SDK response path only for an empty collection.
     let raw;
     if (collectedChunks.length > 0) {
-      raw = aggregateGeminiStreamChunks(collectedChunks);
+      raw = aggregateGeminiStreamChunks(collectedChunks, label);
     } else {
       let response;
       try {
@@ -661,10 +760,16 @@ export async function consumeGeminiSdkStream(
         throw normalizeGeminiSdkError(err, label);
       }
       raw = response?.candidates ? response : response?.response || response;
+      assertNoGeminiInBandError(raw, label);
     }
     const finishReason = raw?.candidates?.[0]?.finishReason || null;
     const promptBlockReason = raw?.promptFeedback?.blockReason || null;
-    assertGeminiStreamCompleted({ sawStreamChunk: reader.sawStreamChunk, finishReason, promptBlockReason, label });
+    assertGeminiStreamCompleted({
+      sawStreamChunk: reader.sawStreamChunk,
+      finishReason,
+      promptBlockReason,
+      label,
+    });
     return raw;
   } catch (err) {
     reader?.clearFirstByte();

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

@@ -1,11 +1,67 @@
+import { getModelMetadataSync } from '../../../shared/llm/model-catalog.mjs';
+
+// The thinkingLevel values the Gemini wire accepts.
 const LEVELS = ['minimal', 'low', 'medium', 'high'];
 
-// Only translate the public option names, not arbitrary effort-to-token ratios.
-// Omitting settings preserves the provider's model default.
-export function geminiThinkingConfig(model, opts = {}, { includeThoughts } = {}) {
-  const id = String(model || '').toLowerCase();
+// The thinkingLevel values the catalogs declare for the model (provider live
+// roster, then models.dev / LiteLLM rows, resolved by getModelMetadataSync),
+// limited to what the Gemini wire accepts. null when no catalog declares a ladder.
+function catalogThinkingLevels(model, provider) {
+  const bare = String(model || '').replace(/^models\//i, '');
+  const effort = getModelMetadataSync(bare, provider)?.reasoningOptions?.find((option) => option?.type === 'effort');
+  const declared = (Array.isArray(effort?.values) ? effort.values : [])
+    .map((value) => String(value).toLowerCase())
+    .filter((value) => LEVELS.includes(value));
+  return declared.length ? [...new Set(declared)] : null;
+}
+
+// Gemini 2.5 models take thinkingBudget only (thinkingLevel is unsupported).
+// Documented ranges: 2.5 Pro 128–32768 (cannot disable), 2.5 Flash 0–24576,
+// 2.5 Flash-Lite 0 or 512–24576; -1 is dynamic thinking for all of them.
+function budgetSpec(model) {
+  const bare = String(model || '').replace(/^models\//i, '').toLowerCase();
+  if (!/^gemini-2\.5(?:-|$)/.test(bare)) return null;
+  if (/^gemini-2\.5-pro/.test(bare)) {
+    return { name: 'Gemini 2.5 Pro', min: 128, max: 32768, canDisable: false, efforts: { minimal: 128, low: 1024, medium: 8192, high: 32768 } };
+  }
+  if (/^gemini-2\.5-flash-lite/.test(bare)) {
+    return { name: 'Gemini 2.5 Flash-Lite', min: 512, max: 24576, canDisable: true, efforts: { minimal: 512, low: 1024, medium: 8192, high: 24576 } };
+  }
+  return { name: 'Gemini 2.5 Flash', min: 0, max: 24576, canDisable: true, efforts: { minimal: 0, low: 1024, medium: 8192, high: 24576 } };
+}
+
+// Levels documented for models whose ladder differs from the generic wire
+// vocabulary (a catalog ladder, when declared, still takes precedence).
+function documentedThinkingLevels(model) {
+  const bare = String(model || '').replace(/^models\//i, '').toLowerCase();
+  if (bare === 'gemini-4-argon' || bare === 'gemini-3.8-flash') return ['low', 'medium', 'high'];
+  return null;
+}
+
+function checkBudget(model, spec, budget) {
+  if (!Number.isInteger(budget) || budget < -1) {
+    throw new TypeError('thinkingBudget must be -1 (dynamic), 0, or a positive integer.');
+  }
+  if (!spec || budget === -1) return;
+  if (budget === 0 && !spec.canDisable) {
+    throw new TypeError(`${model} (${spec.name}) cannot disable thinking; thinkingBudget 0 is not allowed.`);
+  }
+  if (budget !== 0 && (budget < spec.min || budget > spec.max)) {
+    throw new TypeError(`${model} (${spec.name}) thinkingBudget must be -1, ${spec.canDisable ? '0, or ' : ''}${spec.min}–${spec.max}; received ${budget}.`);
+  }
+}
+
+// Only translate the public option names. Omitting settings preserves the
+// provider's model default. Gemini 2.5 models use thinkingBudget (a generic
+// effort maps to a budget; an explicit thinkingLevel is rejected locally and
+// budgets are range-checked). Other models use thinkingLevel, checked against
+// the catalog/documented ladder; unknown models pass values within the wire
+// vocabulary and the server decides.
+export function geminiThinkingConfig(model, opts = {}, { includeThoughts, provider = 'gemini' } = {}) {
   const rawBudget = opts.thinkingBudget ?? opts.thinkingBudgetTokens;
   const hasBudget = rawBudget !== undefined && rawBudget !== null && rawBudget !== '';
+  const spec = budgetSpec(model);
+  const explicitLevel = opts.thinkingLevel == null ? '' : String(opts.thinkingLevel).trim().toLowerCase();
   const rawLevel = opts.thinkingLevel ?? (hasBudget ? undefined : opts.effort);
   const level = rawLevel == null ? '' : String(rawLevel).trim().toLowerCase();
   const config = {};
@@ -14,15 +70,16 @@ export function geminiThinkingConfig(model, opts = {}, { includeThoughts } = {})
   if (level && hasBudget) {
     throw new TypeError('Choose thinkingLevel/effort or thinkingBudget, not both.');
   }
-  if (level) {
-    if (!/^gemini-3(?:[.-]|$)/.test(id)) {
-      throw new TypeError(`${model} uses thinkingBudget instead of thinkingLevel/effort.`);
+  if (spec && explicitLevel) {
+    throw new TypeError(`${model} (${spec.name}) does not support thinkingLevel; use thinkingBudget.`);
+  }
+  if (spec && level) {
+    if (!Object.hasOwn(spec.efforts, level)) {
+      throw new TypeError(`${model} supports thinking levels ${Object.keys(spec.efforts).join(', ')}; received ${level}.`);
     }
-    let supported = LEVELS;
-    if (/^gemini-3(?:\.0)?-pro(?:-|$)/.test(id)) supported = ['low', 'high'];
-    else if (/^gemini-3\.1-pro(?:-|$)/.test(id) || /^gemini-3\.[78]-flash(?:-|$)/.test(id)) {
-      supported = ['low', 'medium', 'high'];
-    } else if (/^gemini-3\.1-flash-lite.*image/.test(id)) supported = ['minimal', 'high'];
+    config.thinkingBudget = spec.efforts[level];
+  } else if (level) {
+    const supported = catalogThinkingLevels(model, provider) ?? documentedThinkingLevels(model) ?? LEVELS;
     if (!supported.includes(level)) {
       throw new TypeError(`${model} supports thinking levels ${supported.join(', ')}; received ${level}.`);
     }
@@ -30,18 +87,7 @@ export function geminiThinkingConfig(model, opts = {}, { includeThoughts } = {})
   }
   if (hasBudget) {
     const budget = Number(rawBudget);
-    if (!Number.isInteger(budget) || budget < -1) {
-      throw new TypeError('thinkingBudget must be -1 (dynamic), 0, or a positive integer.');
-    }
-    if (/^gemini-2\.5-pro(?:-|$)/.test(id) && budget !== -1 && (budget < 128 || budget > 32768)) {
-      throw new TypeError(`${model} requires thinkingBudget -1 or 128..32768.`);
-    }
-    if (/^gemini-2\.5-flash(?:-|$)/.test(id) && budget > 24576) {
-      throw new TypeError(`${model} requires thinkingBudget at most 24576.`);
-    }
-    if (/^gemini-2\.5-flash-lite(?:-|$)/.test(id) && budget > 0 && budget < 512) {
-      throw new TypeError(`${model} requires thinkingBudget -1, 0, or 512..24576.`);
-    }
+    checkBudget(model, spec, budget);
     config.thinkingBudget = budget;
   }
   return Object.keys(config).length ? config : undefined;

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

@@ -1,6 +1,11 @@
 import { GoogleGenerativeAI } from '@google/generative-ai';
 import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
-import { canFallbackNonStreaming, emitProviderRetryStage, withRetry } from './retry-classifier.mjs';
+import {
+  canFallbackNonStreaming,
+  emitProviderRetryStage,
+  markProviderRecoveryExhausted,
+  withRetry,
+} from './retry-classifier.mjs';
 import { noteErrorUsage } from './lib/note-error-usage.mjs';
 import { traceNonStreamingFallback } from './lib/transport-fallback-trace.mjs';
 import {
@@ -12,6 +17,18 @@ import {
 } from '../stall-policy.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import { GEMINI_FIRST_BYTE_TIMEOUT_MS, consumeGeminiRestStreamResponse } from './gemini-stream.mjs';
+import {
+  applyGeminiErrorContract,
+  geminiContinuationUnsupportedError,
+  geminiFinishErrorFields,
+  geminiFinishReasonKind,
+} from './gemini-error-contract.mjs';
+import {
+  GEMINI_MIDSTREAM_MAX_ATTEMPTS,
+  geminiEndsWithFunctionResponse,
+  geminiInvalidStreamReason,
+  runGeminiStreamAttempts,
+} from './gemini-retry-policy.mjs';
 import { geminiTextLeakGuardFor, streamGeminiSdkAttempt } from './gemini-sdk-request.mjs';
 import { emitGeminiToolCalls } from './gemini-schema.mjs';
 import { buildGeminiRequest, geminiCachedRestBody } from './gemini-request-body.mjs';
@@ -32,10 +49,13 @@ import {
   GEMINI_GLOBAL_CACHE_DELETE_GRACE_MS,
   _geminiCredentialFingerprint,
   _invalidateGeminiCachesForCredentialFingerprint,
+  geminiExplicitCacheRefused,
+  markGeminiExplicitCacheRefused,
 } from './gemini-cache.mjs';
 import {
   awaitSharedCreate,
   dropRejectedGeminiCache,
+  geminiBareModelId,
   geminiCacheCreateBody,
   geminiCacheEntry,
   geminiCachePrefixIdentity,
@@ -59,7 +79,7 @@ import {
 let _modelRefreshInFlight = null;
 const GEMINI_AVAILABILITY_TIMEOUT_MS = 1_000;
 
-function geminiRestError(res, text, label) {
+export function geminiRestError(res, text, label) {
   let payload = null;
   try {
     payload = text ? JSON.parse(text) : null;
@@ -78,16 +98,11 @@ function geminiRestError(res, text, label) {
     err.error = detail;
     err.data = payload;
     if (detail.status) err.geminiStatus = detail.status;
-    if (Array.isArray(detail.details)) err.details = detail.details;
-    const retryAfter = res.headers?.get?.('retry-after') ?? res.headers?.get?.('retry-after-ms');
-    // RESOURCE_EXHAUSTED without a server retry window is deterministic
-    // quota exhaustion. With Retry-After present, leave it request-local
-    // so withRetry can honor the mandated delay.
-    // A 429 RESOURCE_EXHAUSTED is a request-local rate limit even without
-    // Retry-After (Google/LiteLLM retry). Do not stamp it as a quota code.
-    if (detail.status && (retryAfter == null || retryAfter === '') && res.status !== 429) {
-      err.code = detail.status;
-    }
+    const details = detail.details ?? detail.errorDetails;
+    if (Array.isArray(details)) err.details = details;
+    // Typed contract (code/retryAfterMs/resetAt/quotaScope); the core decides
+    // whether a 429 RESOURCE_EXHAUSTED is request-local or a quota refusal.
+    applyGeminiErrorContract(err, { details, googleStatus: detail.status, message: detail.message });
   }
   return err;
 }
@@ -139,6 +154,9 @@ export class GeminiProvider {
   // input already includes cache. See registry.mjs.
   static inputExcludesCache = false;
   name = 'gemini';
+  // The two-phase ladder (gemini-retry-policy.mjs) is the whole recovery:
+  // a spent ladder surfaces instead of parking on loop recovery cycles.
+  retryPolicy = Object.freeze({ recoveryCycles: false });
   genAI;
   config;
   _fetch;
@@ -263,7 +281,11 @@ export class GeminiProvider {
     if (decision.canReuseState) {
       return state.cacheName;
     }
-    if (!apiKey) return null;
+    // A request forked from a shared prefix (/btw: opts.sharedCachePrefixCount)
+    // only reads the session's live cache. Creating or refreshing one would
+    // store the fork's own suffix (the appended reply and question).
+    if (opts.sharedCachePrefixCount) return decision.canAttachState ? state.cacheName : null;
+    if (!apiKey || geminiExplicitCacheRefused(model)) return null;
     const { canAttachState } = decision;
     if (geminiPrefixBelowMinimum({ model, systemInstruction, geminiTools, contents, opts, currentIter })) {
       return canAttachState ? state.cacheName : null;
@@ -443,6 +465,7 @@ export class GeminiProvider {
       _setGeminiGlobalCache(globalCacheKey, entry);
       return entry;
     } catch (err) {
+      markGeminiExplicitCacheRefused(model, err);
       process.stderr.write(`[gemini] cachedContents.create error: ${err?.message || err}\n`);
       return null;
     }
@@ -571,10 +594,28 @@ export class GeminiProvider {
       cachedContent,
     });
     const parsed = parseGeminiCandidate(response, textLeakGuard);
-    emitGeminiToolCalls(parsed.nativeToolCalls, callbacks.onToolCall);
     const usage = resolveGeminiUsage(response, opts, cachedContent, useModel);
+    // Terminal status first: a failed candidate's calls are never dispatched.
     const incomplete = geminiIncompleteError(response, parsed, useModel, usage);
-    if (incomplete) throw incomplete;
+    if (incomplete) {
+      Object.assign(incomplete, geminiFinishErrorFields(response));
+      if (geminiFinishReasonKind(incomplete.finishReason) === 'continuation') {
+        // Direct Gemini only: surface the typed result with its token.
+        throw geminiContinuationUnsupportedError(incomplete, response);
+      }
+      // A malformed / unexpected tool call that survived the stream ladder
+      // (4 attempts) is spent; the loop must not multiply that budget.
+      if (
+        geminiInvalidStreamReason(response, textLeakGuard, {
+          afterToolResult: geminiEndsWithFunctionResponse(request.contents),
+        })
+      ) {
+        markProviderRecoveryExhausted(incomplete, { owner: 'gemini-stream', attempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS });
+      }
+      throw incomplete;
+    }
+    textLeakGuard?.releaseDeferredToolCalls?.();
+    emitGeminiToolCalls(parsed.nativeToolCalls, callbacks.onToolCall);
     return geminiSendResult(parsed, useModel, opts, usage);
   }
 
@@ -602,7 +643,7 @@ export class GeminiProvider {
   }
 
   async _restGenerateContent(useModel, apiKey, body, fallbackSignal) {
-    const nonStreamUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(useModel)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+    const nonStreamUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(geminiBareModelId(useModel))}:generateContent?key=${encodeURIComponent(apiKey)}`;
     const res = await this._fetch(nonStreamUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -626,10 +667,10 @@ export class GeminiProvider {
   // { retryUncached: true } when the cache itself was rejected and the send
   // must be replayed without it.
   async _streamCachedViaRest(stream, internal) {
-    const { opts, signal, useModel, contents, generationConfig, cachedContent, callbacks } = stream;
+    const { opts, signal, useModel, contents, generationConfig, safetySettings, cachedContent, callbacks } = stream;
     const apiKey = this._getApiKey();
-    const genUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(useModel)}:streamGenerateContent?alt=sse&key=${encodeURIComponent(apiKey)}`;
-    const body = geminiCachedRestBody({ opts, contents, cachedContent, generationConfig });
+    const genUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(geminiBareModelId(useModel))}:streamGenerateContent?alt=sse&key=${encodeURIComponent(apiKey)}`;
+    const body = geminiCachedRestBody({ opts, contents, cachedContent, generationConfig, safetySettings });
     // cachedContent owns tools + toolConfig. The API rejects a
     // generateContent request that repeats either field.
     // Option A (mirror anthropic-oauth): no absolute wall-clock cap on a
@@ -643,10 +684,16 @@ export class GeminiProvider {
     const restPassthrough = createPassthroughSignal(signal);
     const totalSignal = restPassthrough.signal;
     try {
-      return await withRetry(
-        async ({ signal: attemptSignal }) => {
+      const afterToolResult = geminiEndsWithFunctionResponse(contents);
+      return await runGeminiStreamAttempts({
+        signal: totalSignal,
+        sleepFn: this.config?.sleepFn,
+        onRetry: geminiRetryLogger(opts, '[gemini-rest]'),
+        afterToolResult,
+        run: async ({ signal: attemptSignal, connected }) => {
           signalRequesting(opts);
           const res = await this._openRestStream(genUrl, body, attemptSignal);
+          connected();
           const textLeakGuard = geminiTextLeakGuardFor(stream);
           const response = await consumeGeminiRestStreamResponse(res, {
             signal: attemptSignal,
@@ -658,8 +705,7 @@ export class GeminiProvider {
           });
           return { response, textLeakGuard };
         },
-        { signal: totalSignal, onRetry: geminiRetryLogger(opts, '[gemini-rest]') }
-      );
+      });
     } catch (err) {
       if (
         !internal.skipExplicitCache &&
@@ -685,26 +731,31 @@ export class GeminiProvider {
   }
 
   async _streamViaSdk(stream) {
-    const { opts, signal, useModel, systemInstruction, geminiTools, toolConfig, generationConfig, contents } = stream;
+    const { opts, signal, useModel, systemInstruction, geminiTools, toolConfig, generationConfig, safetySettings, contents } =
+      stream;
     const genModel = this._currentGenAI().getGenerativeModel({
       model: useModel,
       systemInstruction,
       tools: geminiTools,
       ...(toolConfig ? { toolConfig } : {}),
       ...(generationConfig ? { generationConfig } : {}),
+      ...(safetySettings ? { safetySettings } : {}),
     });
     // Option A (mirror anthropic-oauth): pure pass-through of the external
     // signal, no absolute streaming total cap. See the REST path.
     const sdkPassthrough = createPassthroughSignal(signal);
     const totalSignal = sdkPassthrough.signal;
     try {
-      return await withRetry(
-        async ({ signal: attemptSignal }) => {
+      return await runGeminiStreamAttempts({
+        signal: totalSignal,
+        sleepFn: this.config?.sleepFn,
+        onRetry: geminiRetryLogger(opts, '[gemini]'),
+        afterToolResult: geminiEndsWithFunctionResponse(contents),
+        run: async ({ signal: attemptSignal, connected }) => {
           signalRequesting(opts);
-          return await streamGeminiSdkAttempt(genModel, stream, attemptSignal);
+          return await streamGeminiSdkAttempt(genModel, stream, attemptSignal, connected);
         },
-        { signal: totalSignal, onRetry: geminiRetryLogger(opts, '[gemini]') }
-      );
+      });
     } catch (err) {
       const recovered = await this._recoverGeminiNonStreaming({
         streamErr: err,

package/src/runtime/agent/orchestrator/providers/grok-client-version.mjs

@@ -3,7 +3,7 @@ import { createNpmVersionSource, maxSemver } from './npm-cli-version.mjs';
 // Grok CLI client version for the cli-chat-proxy version gate (HTTP 426).
 // Effective = env override, else max(floor, learned-from-426, live npm latest
 // of the official @xai-official/grok CLI).
-export const GROK_CLI_VERSION_FLOOR = '1.0.52';
+export const GROK_CLI_VERSION_FLOOR = '1.0.60';
 export const GROK_CLI_NPM_PACKAGE = '@xai-official/grok';
 
 const live = createNpmVersionSource(GROK_CLI_NPM_PACKAGE, { persistKey: 'grok-cli' });