mixdog 1.2.1 → 1.2.3

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

@@ -0,0 +1,273 @@
+/**
+ * gemini-error-contract.mjs — Google RPC error details → the provider error
+ * contract shared by Gemini (REST + SDK) and Antigravity:
+ *   status, code (lowercased), retryAfterMs (uncapped), resetAt (epoch ms),
+ *   quotaScope ('minute' | 'day' | undefined).
+ *
+ * Details come from `error.details` (REST body) or `errorDetails` (SDK
+ * GoogleGenerativeAIFetchError). Entries are google.rpc.RetryInfo,
+ * QuotaFailure and ErrorInfo.
+ */
+
+const DURATION_RE = /^(?:\d+(?:\.\d+)?(?:ms|s|m|h))+$/;
+const DURATION_PART_RE = /(\d+(?:\.\d+)?)(ms|s|m|h)/g;
+const DURATION_UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
+const BARE_SECONDS_RE = /^\d+(?:\.\d+)?$/;
+
+// Google error classification: a per-minute quota with no RetryInfo is
+// retried after one quota window.
+export const GEMINI_PER_MINUTE_RETRY_MS = 60_000;
+
+// "Please retry in 34.07s" (Gemini API) / "reset after 2h1m1s" (Cloud Code).
+const MESSAGE_DELAY_RE = /(?:please retry in|reset after)\s+((?:\d+(?:\.\d+)?(?:ms|h|m|s))+)/i;
+const LIMIT_ZERO_RE = /limit:\s*0(?!\d|\.\d)/i;
+const CAPACITY_MESSAGE_RE = /exhausted your capacity|capacity exceeded|model_capacity_exhausted/i;
+// ErrorInfo reasons that name a spent quota with no window of its own.
+const TERMINAL_REASONS = new Set(['quota_exhausted', 'insufficient_g1_credits_balance']);
+const CAPACITY_REASONS = new Set(['model_capacity_exhausted', 'model_capacity_exceeded']);
+
+const GOOGLE_STATUS_HTTP = {
+  INVALID_ARGUMENT: 400,
+  UNAUTHENTICATED: 401,
+  PERMISSION_DENIED: 403,
+  NOT_FOUND: 404,
+  RESOURCE_EXHAUSTED: 429,
+  INTERNAL: 500,
+  UNAVAILABLE: 503,
+  DEADLINE_EXCEEDED: 504,
+};
+
+function detailType(entry) {
+  return typeof entry?.['@type'] === 'string' ? entry['@type'] : '';
+}
+
+function durationMs(value) {
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (BARE_SECONDS_RE.test(text)) return Math.ceil(Number(text) * 1000);
+    if (!DURATION_RE.test(text)) return null;
+    let total = 0;
+    for (const [, amount, unit] of text.matchAll(DURATION_PART_RE)) total += Number(amount) * DURATION_UNIT_MS[unit];
+    return Math.ceil(total);
+  }
+  if (value && typeof value === 'object') {
+    const ms = Number(value.seconds || 0) * 1000 + Number(value.nanos || 0) / 1_000_000;
+    return Number.isFinite(ms) && ms >= 0 ? Math.ceil(ms) : null;
+  }
+  return null;
+}
+
+// A zero wait is no advice: the caller's normal backoff (or the per-minute
+// window) applies instead of an immediate re-issue.
+function adviceMs(value) {
+  const ms = durationMs(value);
+  return ms > 0 ? ms : undefined;
+}
+
+function scopeOf(text) {
+  if (/per[\s_-]?day|daily/i.test(text)) return 'day';
+  if (/per[\s_-]?minute/i.test(text)) return 'minute';
+  return undefined;
+}
+
+/**
+ * `quotaScope` is 'minute' / 'day' from the typed quota ids only (never from
+ * the length of the server's wait); 'plan' marks a spent
+ * quota with no window (ErrorInfo QUOTA_EXHAUSTED, or a QuotaFailure
+ * violation with a zero limit; message prose alone never counts). Capacity
+ * (MODEL_CAPACITY_EXHAUSTED / "exhausted your capacity") is an overload of the
+ * shared pool: code `model_capacity_exhausted`, never a quota scope.
+ * @param {{ details?: unknown, errorDetails?: unknown, googleStatus?: string, message?: string }} input
+ * @returns {{ code?: string, retryAfterMs?: number, resetAt?: number, quotaScope?: 'minute'|'day'|'plan' }}
+ */
+export function geminiErrorContract({ details, errorDetails, googleStatus, message } = {}) {
+  const list = [details, errorDetails].flatMap((entry) => (Array.isArray(entry) ? entry : []));
+  let reason = '';
+  let retryAfterMs;
+  let resetAt;
+  const scopes = new Set();
+  let zeroLimit = false;
+  for (const entry of list) {
+    const type = detailType(entry);
+    if (type.endsWith('.RetryInfo') || entry?.retryDelay !== undefined) {
+      retryAfterMs ??= adviceMs(entry.retryDelay);
+    }
+    if (type.endsWith('.QuotaFailure') || Array.isArray(entry?.violations)) {
+      for (const violation of entry.violations || []) {
+        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 || ''))) {
+          zeroLimit = true;
+        }
+      }
+    }
+    if (type.endsWith('.ErrorInfo') || typeof entry?.reason === 'string') {
+      if (!reason && typeof entry.reason === 'string') reason = entry.reason.trim().toLowerCase();
+      const metadata = entry.metadata && typeof entry.metadata === 'object' ? entry.metadata : {};
+      retryAfterMs ??= adviceMs(metadata.quotaResetDelay);
+      const stamp = Date.parse(String(metadata.quotaResetTimeStamp || ''));
+      if (resetAt === undefined && Number.isFinite(stamp)) resetAt = stamp;
+      const scope = scopeOf(
+        [metadata.quotaId, metadata.quota_limit, metadata.quota_metric, entry.reason].filter(Boolean).join(' ')
+      );
+      if (scope) scopes.add(scope);
+    }
+  }
+  const text = typeof message === 'string' ? message : '';
+  // The message names capacity only when nothing typed said otherwise (a
+  // reason, a quota id or RetryInfo outranks it, as in classifyGoogleError).
+  const capacity =
+    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;
+  if (retryAfterMs === undefined) {
+    const named = MESSAGE_DELAY_RE.exec(text);
+    if (named) retryAfterMs = adviceMs(named[1]);
+  }
+  // Per-minute quota with no RetryInfo: wait one quota window.
+  if (retryAfterMs === undefined && quotaScope === 'minute' && !capacity) retryAfterMs = GEMINI_PER_MINUTE_RETRY_MS;
+  if (resetAt === undefined && retryAfterMs !== undefined) resetAt = Date.now() + retryAfterMs;
+  if (!capacity && !quotaScope && (TERMINAL_REASONS.has(reason) || zeroLimit)) quotaScope = 'plan';
+  const status = typeof googleStatus === 'string' ? googleStatus.trim().toLowerCase() : '';
+  const code = capacity ? 'model_capacity_exhausted' : reason || status;
+  return {
+    ...(code ? { code } : {}),
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    ...(resetAt !== undefined ? { resetAt } : {}),
+    ...(quotaScope ? { quotaScope } : {}),
+  };
+}
+
+/** Copy the contract fields onto `err`; an already-typed `code` is kept. */
+export function applyGeminiErrorContract(err, input) {
+  const { code, ...rest } = geminiErrorContract(input);
+  Object.assign(err, rest);
+  if (code && !(typeof err.code === 'string' && err.code)) err.code = code;
+  return err;
+}
+
+/**
+ * The `{ error: {...} }` envelope a Gemini/Cloud Code stream carries in-band
+ * instead of an HTTP error status. Returns the typed error, or null when the
+ * chunk is an ordinary payload.
+ */
+export function geminiInBandError(chunk, label) {
+  const detail = chunk && typeof chunk === 'object' ? chunk.error : null;
+  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)}`);
+  err.name = 'GeminiInBandError';
+  if (status) {
+    err.status = status;
+    err.httpStatus = status;
+  }
+  if (googleStatus) err.geminiStatus = googleStatus.toUpperCase();
+  err.error = body;
+  const details = body.details ?? body.errorDetails;
+  if (Array.isArray(details)) err.details = details;
+  return applyGeminiErrorContract(err, { details, googleStatus, message: body.message });
+}
+
+/** Throw the typed in-band error when `chunk` is an error envelope. */
+export function assertNoGeminiInBandError(chunk, label) {
+  const err = geminiInBandError(chunk, label);
+  if (err) throw err;
+}
+
+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) {
+  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-family.mjs

@@ -0,0 +1,9 @@
+// True for an id in the Gemini wire family ("gemini-4-argon", "models/gemini-3.1-pro",
+// "gemini-pro-agent"). It names the family only, never a generation: it separates
+// Gemini from the other model families an Antigravity gateway serves (Claude,
+// GPT-OSS), which reject Gemini-only request fields outright.
+const GEMINI_FAMILY = /(?:^|\/)gemini-/i;
+
+export function isGeminiFamilyModel(model) {
+  return GEMINI_FAMILY.test(String(model || ''));
+}

package/src/runtime/agent/orchestrator/providers/gemini-history-signatures.mjs

@@ -1,10 +1,15 @@
+import { isGeminiFamilyModel } from './gemini-family.mjs';
+
 const SYNTHETIC_TOOL_SIGNATURE = 'skip_thought_signature_validator';
 
-// Gemini 3 validates the first functionCall in every step of the current turn.
-// Foreign/interrupted histories may not have a native signature for that call.
-// Preserve real signatures and unsigned siblings of a signed parallel batch.
+// Gemini models that validate thought signatures check the first functionCall
+// in every step of the current turn. Foreign/interrupted histories may not have
+// a native signature for that call. Preserve real signatures and unsigned
+// siblings of a signed parallel batch. The validator-bypass token is a Gemini
+// wire token: it is only fabricated for the Gemini family, because the other
+// families an Antigravity gateway serves reject it.
 export function ensureGeminiToolCallSignatures(contents, model) {
-  if (!/^(?:models\/)?gemini-3(?:[.-]|$)/i.test(String(model || ''))) return contents;
+  if (!isGeminiFamilyModel(model)) return contents;
   let activeTurnStart = 0;
   for (let index = contents.length - 1; index >= 0; index -= 1) {
     const content = contents[index];

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);
+  const generationConfig =
+    thinkingConfig || Object.keys(controls).length
+      ? { ...(thinkingConfig ? { thinkingConfig } : {}), ...controls }
+      : undefined;
   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

@@ -14,6 +14,7 @@ import { createProviderReplay } from './lib/provider-replay.mjs';
 import { collectGeminiGroundingSources, parseGeminiTextPartMetadata, parseToolCalls } from './gemini-schema.mjs';
 import { _resolveGeminiCacheUsage } from './gemini-cache.mjs';
 import { traceGeminiCache } from './gemini-cache-policy.mjs';
+import { geminiPolicyFinishCode } from './gemini-error-contract.mjs';
 
 // Candidate text and tool calls after the text-leak guard: leaked
 // (text-embedded) tool calls are appended to the native ones and empty the
@@ -64,7 +65,8 @@ export function geminiIncompleteError(response, parsed, useModel, usage = null)
   if (!finishReason || normalizedFinishReason === 'STOP') return null;
   return Object.assign(new Error(`Gemini response incomplete: finishReason=${finishReason}`), {
     name: 'ProviderIncompleteError',
-    code: 'PROVIDER_INCOMPLETE',
+    // Safety/recitation are policy refusals the core presents as such.
+    code: geminiPolicyFinishCode(finishReason) || 'PROVIDER_INCOMPLETE',
     providerIncomplete: true,
     finishReason,
     partialContent: parsed.content,

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

@@ -0,0 +1,180 @@
+/**
+ * gemini-retry-policy.mjs — Gemini API retry constants and the two-phase
+ * attempt loop (request backoff and stream retry):
+ *
+ *   connection phase  up to 10 attempts, 5s initial delay doubling to a 30s
+ *                     cap, ±30% jitter (a server-advised wait replaces it);
+ *   stream phase      a failure after the response opened (a stream that ends
+ *                     with no finish reason is one: the transport raises it as
+ *                     a truncated stream), or a response the model left
+ *                     unusable (malformed / unexpected tool call, empty text),
+ *                     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 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
+ *                     (provider-terminal, no quota scope; the wait stays on
+ *                     the error for display).
+ *
+ * Replay stays gated by the stream-outcome contract: a stream that exposed
+ * text or dispatched a tool is never re-issued.
+ */
+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({
+  maxAttempts: 10,
+  // Wait before retry N reads index N (the leading 5s covers index 0 and 1):
+  // 5s, 10s, 20s, then the 30s cap.
+  backoffMs: Object.freeze([5000, 5000, 10_000, 20_000, 30_000]),
+  retryJitterRatio: 0.3,
+  // Server advice gets positive-only jitter and is never below the step.
+  retryAfterJitterRatio: 0.2,
+  adviceAtLeastBackoff: true,
+  retry499: true,
+});
+
+// A server wait longer than this is a lock-out, not a retry.
+export const GEMINI_MAX_RETRYABLE_ADVICE_MS = 300_000;
+
+function hasLongAdvice(err) {
+  const { kind, retryAfterMs } = providerErrorKind(err);
+  return retryAfterMs > GEMINI_MAX_RETRYABLE_ADVICE_MS && !DETERMINISTIC_KINDS.has(kind);
+}
+
+/** True when the request's last turn is a tool result (functionResponse). */
+export function geminiEndsWithFunctionResponse(contents) {
+  const last = Array.isArray(contents) ? contents[contents.length - 1] : null;
+  return Array.isArray(last?.parts) && last.parts.some((part) => part?.functionResponse);
+}
+
+export const GEMINI_MIDSTREAM_MAX_ATTEMPTS = 4;
+export const GEMINI_MIDSTREAM_INITIAL_DELAY_MS = 1000;
+
+const midstreamStepMs = (streamAttempt) => GEMINI_MIDSTREAM_INITIAL_DELAY_MS * 2 ** streamAttempt;
+
+/**
+ * Wait before re-issuing after a stream-phase failure, or null when it must
+ * surface. A server-advised wait on a retryable kind replaces the step.
+ */
+export function geminiMidstreamDelayMs(err, streamAttempt, signal = null) {
+  if (streamAttempt + 1 >= GEMINI_MIDSTREAM_MAX_ATTEMPTS || signal?.aborted) return null;
+  if (readStreamOutcome(err).replaySafe !== true) return null;
+  const { kind } = providerErrorKind(err);
+  if (hasLongAdvice(err)) return null;
+  // A status-only 499 (client closed request) is retried, as on the request
+  // ladder; a typed code on the 499 keeps it final.
+  const closed499 =
+    GEMINI_REQUEST_RETRY.retry499 && kind === 'invalid_request' && statusOf(err) === 499 && !typedCodeKind(err);
+  if (DETERMINISTIC_KINDS.has(kind) && !closed499) return null;
+  // 429 is request-local here: classifyError calls it permanent, but a rate
+  // limit that is not a spent quota is retried like any other stream fault.
+  if (!closed499 && classifyError(err) !== 'transient' && kind !== 'rate_limited') return null;
+  return midstreamRetryDelayMs(err, midstreamStepMs(streamAttempt));
+}
+
+const statusOf = (err) => Number(err?.httpStatus || err?.status || 0);
+
+/**
+ * Invalid stream: the reason a finished response is unusable
+ * ('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];
+  const parts = Array.isArray(candidate?.content?.parts) ? candidate.content.parts : [];
+  if (parts.some((part) => part?.functionCall)) return null;
+  if ((textLeakGuard?.getLeakedToolCalls?.() || []).length > 0) return null;
+  if ((textLeakGuard?.getRelayedText?.() || '').length > 0) 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
+    .filter((part) => part?.thought !== true && typeof part?.text === 'string')
+    .map((part) => part.text)
+    .join('')
+    .replace(/[\u200B-\u200D\uFEFF\u200E\u200F]/g, '')
+    .trim();
+  return text ? null : 'NO_RESPONSE_TEXT';
+}
+
+/**
+ * Run `run` under the Gemini ladder. `run({ signal, connected })` performs one
+ * open + consume and calls `connected()` once the response opened; it resolves
+ * `{ response, textLeakGuard }`.
+ */
+export async function runGeminiStreamAttempts({ run, signal, onRetry, sleepFn, afterToolResult = false }) {
+  for (let streamAttempt = 0; ; streamAttempt++) {
+    let connected = false;
+    let result;
+    try {
+      result = await withRetry(
+        async ({ signal: attemptSignal }) => {
+          try {
+            return await run({
+              signal: attemptSignal,
+              connected: () => {
+                connected = true;
+              },
+            });
+          } catch (err) {
+            // A server wait over the limit ends recovery on either phase.
+            if (hasLongAdvice(err)) {
+              throw markProviderRecoveryExhausted(err, {
+                owner: connected ? 'gemini-stream' : 'gemini-connection',
+                terminal: true,
+              });
+            }
+            // The connection ladder is spent on opening; a stream-phase
+            // failure belongs to the stream ladder below.
+            throw connected ? markProviderRecoveryExhausted(err, { owner: 'gemini-connection' }) : err;
+          }
+        },
+        { ...GEMINI_REQUEST_RETRY, finalOnExhaust: true, signal, sleepFn, onRetry }
+      );
+    } 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 });
+      await sleepWithAbort(waitMs, signal, sleepFn, 'Gemini stream retry wait aborted');
+      continue;
+    }
+    const invalid = geminiInvalidStreamReason(result.response, result.textLeakGuard, { afterToolResult });
+    if (!invalid || signal?.aborted) return result;
+    const unusable = Object.assign(new Error(`Gemini stream unusable: ${invalid}`), {
+      name: 'InvalidStreamError',
+      code: invalid.toLowerCase(),
+    });
+    if (streamAttempt + 1 >= GEMINI_MIDSTREAM_MAX_ATTEMPTS) {
+      // A spent ladder on an empty answer is a failure, not an answer; a
+      // malformed / unexpected tool call keeps its finish-reason error.
+      if (invalid !== 'NO_RESPONSE_TEXT') return result;
+      throw markProviderRecoveryExhausted(unusable, {
+        owner: 'gemini-stream',
+        attempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS,
+        terminal: true,
+      });
+    }
+    const waitMs = midstreamStepMs(streamAttempt);
+    onRetry?.({
+      attempt: streamAttempt + 1,
+      maxAttempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS,
+      lastErr: unusable,
+      delayMs: waitMs,
+    });
+    await sleepWithAbort(waitMs, signal, sleepFn, 'Gemini stream retry wait aborted');
+  }
+}