mixdog 1.2.1 → 1.2.3

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

@@ -1,6 +1,11 @@
 import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
 import { sanitizeToolPairs } from '../session/context-utils.mjs';
 import { AnthropicFallbackTriggeredError } from './retry-classifier.mjs';
+import {
+  announceAnthropicModelFallback,
+  createAnthropicOverloadTracker,
+  isTerminalOverloadModel,
+} from './anthropic-overload-fallback.mjs';
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { createPassthroughSignal } from '../stall-policy.mjs';
 import { createAbortController } from '../../../shared/abort-controller.mjs';
@@ -78,6 +83,11 @@ export class AnthropicProvider {
       maxRetries: 0,
     });
   }
+  // The model id capability lookups (output cap, thinking/effort shape) read;
+  // a gateway engine maps its routing slug to the Claude id it stands for.
+  _capabilityModel(model) {
+    return model;
+  }
   reloadApiKey() {
     try {
       const newKey = reloadProviderApiKey(this.name, this.config);
@@ -144,6 +154,7 @@ export class AnthropicProvider {
       fastModeLatched: this.fastModeBetaHeaderLatched,
       // Custom providers carry per-model reasoning settings on their own rows.
       modelInfo: isCustomProviderName(this.name) ? this.getCachedModelInfo?.(useModel) || null : null,
+      capabilityModel: this._capabilityModel(useModel),
     });
     this.fastModeBetaHeaderLatched = fastModeLatched;
 
@@ -166,6 +177,13 @@ export class AnthropicProvider {
       } catch {}
     };
 
+    // Request-loop 529s and SSE overload events share one counter; at the
+    // limit the configured fallback model takes over the whole send.
+    const overload = createAnthropicOverloadTracker({
+      model: useModel,
+      fallbackModel: opts._fallbackTriggered ? undefined : opts.fallbackModel,
+      terminalAtLimit: !isCustomProviderName(this.name) && isTerminalOverloadModel(useModel),
+    });
     // The SDK calls and their initial-response retry policy
     // (anthropic-api-transport.mjs).
     const transport = createAnthropicApiTransport({
@@ -176,6 +194,7 @@ export class AnthropicProvider {
       params,
       requestHeaders,
       totalSignal,
+      overload,
     });
     // Usage accounting + caller-visible projection, shared by the streaming
     // success path and the non-streaming fallback (anthropic-turn-result.mjs).
@@ -213,8 +232,10 @@ export class AnthropicProvider {
       recovery,
       onStageChange,
       retry529: opts.retry529 !== false,
+      overload,
     });
 
+    let streamingFallbackTried = false;
     try {
       for (let attemptIndex = 0; attemptIndex <= ANTHROPIC_MAX_MIDSTREAM_RETRIES; attemptIndex++) {
         const streamController = createAbortController();
@@ -274,13 +295,13 @@ export class AnthropicProvider {
 
           return buildTurnResult(parseResult);
         } catch (err) {
-          if (err instanceof AnthropicFallbackTriggeredError) {
-            process.stderr.write(`[${this.name}] ${err.message}\n`);
-            return this._doSend(messages, err.fallbackModel, tools, {
-              ...opts,
-              fallbackModel: undefined,
-              _fallbackTriggered: true,
-            });
+          // The fallback trigger is handled around the whole send below.
+          if (err instanceof AnthropicFallbackTriggeredError) throw err;
+          // Gateways that 404 the streaming endpoint but serve non-streaming:
+          // one non-streaming replay (nothing was streamed yet).
+          if (err?.initialResponseError === true && Number(err.status) === 404 && !streamingFallbackTried) {
+            streamingFallbackTried = true;
+            return await recovery.issueNonStreamingFallback(streamController, err);
           }
           // Ordered recovery ladder: canonical outcome stamp, acknowledged
           // non-streaming replay for exposed output, bounded streaming
@@ -300,6 +321,18 @@ export class AnthropicProvider {
         }
       }
       throw midstream.exhaustedError();
+    } catch (err) {
+      // The fallback trigger can surface from the request loop, a mid-stream
+      // overload, or the non-streaming recovery: handle it around the whole
+      // operation, not just the first request.
+      if (!(err instanceof AnthropicFallbackTriggeredError)) throw err;
+      process.stderr.write(`[${this.name}] ${err.message}\n`);
+      announceAnthropicModelFallback(onStageChange, useModel, err.fallbackModel);
+      return await this._doSend(messages, err.fallbackModel, tools, {
+        ...opts,
+        fallbackModel: undefined,
+        _fallbackTriggered: true,
+      });
     } finally {
       totalTimeout.cleanup();
     }

package/src/runtime/agent/orchestrator/providers/antigravity-oauth-catalog.mjs

@@ -11,6 +11,9 @@
  * comes from `retrieveUserQuotaSummary`, not the per-model catalog counters.
  */
 import { makeModelCache } from './model-cache.mjs';
+import { isGeminiFamilyModel } from './gemini-family.mjs';
+import { isAntigravityClaude } from './antigravity-request.mjs';
+import { getModelMetadataSync } from '../../../shared/llm/model-catalog.mjs';
 import {
   ANTIGRAVITY_MODELS,
   PROJECT_ENDPOINT,
@@ -27,8 +30,9 @@ const TIER_EFFORTS = { 'extra low': 'minimal', minimal: 'minimal', low: 'low', m
 const EFFORT_ORDER = ['minimal', 'low', 'medium', 'high'];
 // IDE-internal completion/chat models are listed without a display name.
 const INTERNAL_ID = /^(?:chat|tab)_/;
-// Bare Gemini 3 ids take the ordinary thinkingLevel field instead of a tier id.
-const BARE_GEMINI3_LEVELS = Object.freeze(['low', 'medium', 'high']);
+// The thinkingLevel values the gateway accepts on a single wire id; `minimal`
+// is an error there, so it is never offered even when a catalog lists it.
+const GATEWAY_THINKING_LEVELS = Object.freeze(['low', 'medium', 'high']);
 
 let _mirror = null;
 export const antigravityModelCache = makeModelCache({
@@ -116,6 +120,23 @@ function chatEntries(rawModels) {
   return out;
 }
 
+// A Gemini wire id without tier siblings takes the ordinary thinkingLevel field.
+// The ladder comes from the catalogs' row for the same Gemini id (models.dev /
+// LiteLLM) narrows what the gateway accepts; when no catalog declares a ladder
+// the gateway-accepted levels are offered and the server judges the value.
+// Only a model the gateway does not flag as thinking-capable has no levels.
+function bareThinkingLevels(wire, supportsReasoning) {
+  if (!supportsReasoning) return [];
+  // Claude behind the gateway takes the same thinkingLevel enum; no catalog
+  // describes these wire ids, so the gateway-accepted levels are offered.
+  if (isAntigravityClaude(wire)) return [...GATEWAY_THINKING_LEVELS];
+  if (!isGeminiFamilyModel(wire)) return [];
+  const effort = getModelMetadataSync(wire, 'gemini')?.reasoningOptions?.find((option) => option?.type === 'effort');
+  if (!Array.isArray(effort?.values) || !effort.values.length) return [...GATEWAY_THINKING_LEVELS];
+  const declared = new Set(effort.values.map((value) => String(value).toLowerCase()));
+  return GATEWAY_THINKING_LEVELS.filter((level) => declared.has(level));
+}
+
 /** Collapse the gateway's per-tier wire ids into picker records. */
 export function normalizeAntigravityCatalog(rawModels) {
   const families = new Map();
@@ -142,13 +163,13 @@ export function normalizeAntigravityCatalog(rawModels) {
       ? Object.fromEntries(efforts.map((effort) => [effort, pickWire(family.wires.get(effort), family.base)]))
       : pickWire(family.wires.get(efforts[0] ?? ''), family.base);
     const id = tiered ? key : wire;
-    const bareGemini3 = !tiered && /^gemini-3(?:\.\d+)?-(?:flash|pro)$/.test(wire);
     const display =
       tiered || !efforts.length ? family.base : `${family.base} (${efforts[0][0].toUpperCase()}${efforts[0].slice(1)})`;
     const kind = familyKind(family.base);
-    let reasoningLevels = [];
-    if (tiered) reasoningLevels = efforts;
-    else if (bareGemini3) reasoningLevels = [...BARE_GEMINI3_LEVELS];
+    // A lone labelled tier already names its effort in the wire id.
+    let reasoningLevels = efforts;
+    if (!efforts.length) reasoningLevels = bareThinkingLevels(wire, family.supportsReasoning);
+    else if (!tiered) reasoningLevels = [];
     models.push({
       id,
       name: display,
@@ -174,9 +195,9 @@ function antigravityCatalogModels() {
 
 /**
  * Turn a picker model + effort into the wire id the gateway accepts. Tiered
- * families consume the effort (the id encodes it); a bare Gemini 3 id keeps it
- * for thinkingLevel; every other record drops it because the model has no
- * effort surface. Unknown ids pass through unchanged.
+ * families consume the effort (the id encodes it); a bare id whose record
+ * lists levels keeps it for thinkingLevel; every other record drops it
+ * because the gateway does not flag the model as thinking-capable. Unknown ids pass through unchanged.
  */
 export function resolveAntigravityWireModel(model, effort, models = antigravityCatalogModels()) {
   const id = String(model || '');

package/src/runtime/agent/orchestrator/providers/antigravity-oauth.mjs

@@ -20,6 +20,7 @@ import { preconnect } from '../../../shared/llm/http-agent.mjs';
 import { createAntigravityStreamCollector } from './antigravity-stream.mjs';
 import { createAntigravityRequest } from './antigravity-transport.mjs';
 import { finalizeAntigravityTurn } from './antigravity-response.mjs';
+import { ANTIGRAVITY_ACCOUNT_COOLDOWN_POLICY } from './antigravity-retry-policy.mjs';
 import {
   CONTENT_ENDPOINT,
   ANTIGRAVITY_MODELS,
@@ -69,6 +70,11 @@ export class AntigravityOAuthProvider {
   // usageMetadata.promptTokenCount is the total, cached tokens included.
   static inputExcludesCache = false;
   name = 'antigravity-oauth';
+  // Roster cooldowns the shared account pool applies when the server names no delay.
+  accountCooldownPolicy = ANTIGRAVITY_ACCOUNT_COOLDOWN_POLICY;
+  // The capacity / quick-retry ladder is the whole recovery: a spent ladder
+  // surfaces instead of parking on loop recovery cycles.
+  retryPolicy = Object.freeze({ recoveryCycles: false });
 
   constructor(config = {}) {
     this.config = config || {};
@@ -162,6 +168,7 @@ export class AntigravityOAuthProvider {
       opts,
       signal: passthrough.signal,
       collector,
+      sleepFn: this.config.sleepFn,
     });
     try {
       try {

package/src/runtime/agent/orchestrator/providers/antigravity-request.mjs

@@ -2,14 +2,25 @@ import { randomUUID, createHash } from 'node:crypto';
 import { createProviderReplay, providerReplayItems } from './lib/provider-replay.mjs';
 import { toGeminiContents, toGeminiRequestTools, toGeminiToolConfig } from './gemini-schema.mjs';
 import { geminiThinkingConfig } from './gemini-thinking.mjs';
+import { isGeminiFamilyModel } from './gemini-family.mjs';
 
 const THOUGHT_SIGNATURE_SENTINEL = 'skip_thought_signature_validator';
 const CLAUDE_MAX_OUTPUT_TOKENS = 64000;
 
+// Claude models behind the gateway speak a different thinking/replay dialect
+// (token budgets, anthropic-beta header, their own signatures). The roster
+// carries no protocol marker, and a wrong guess is rejected upstream, so the
+// vendor prefix of the wire id decides.
 export function isAntigravityClaude(model) {
   return /^claude-/i.test(String(model || ''));
 }
 
+// Claude declarations are validated for the gateway's Anthropic bridge in
+// toGeminiTools (claudeBridge: true); a tool with an invalid schema is left
+// out of the request and reported through `onToolExcluded` / console.warn.
+const claudeRequestTools = (tools, nativeTools, onToolExcluded) =>
+  toGeminiRequestTools(tools, nativeTools, { claudeBridge: true, onToolExcluded });
+
 // Default function-calling mode when the caller sets no toolChoice. VALIDATED
 // (schema-constrained function calls) is what the Antigravity client sends;
 // MIXDOG_ANTIGRAVITY_FC_MODE=AUTO|ANY|VALIDATED overrides it for A/B runs.
@@ -30,14 +41,52 @@ function replayFamilyMatches(message, model) {
   return isAntigravityClaude(recorded) === isAntigravityClaude(model);
 }
 
+// The stream records empty text parts around Claude tool calls; Cloud Code's
+// Claude bridge rejects them on replay ("text.text: Field required").
+const isEmptyPlainTextPart = (part) =>
+  part?.text === '' && part.thought !== true && typeof part.thoughtSignature !== 'string';
+
+// Streamed Claude thinking arrives as many thought deltas with the signature
+// on the closing (often empty) delta; the bridge turns every part into its own
+// thinking block and rejects the unsigned ones ("thinking.signature: Field
+// required"). Rejoin each run into one block that ends at its signature.
+function coalesceClaudeThoughts(parts) {
+  const out = [];
+  let open = null;
+  for (const part of parts) {
+    if (part?.thought !== true) {
+      if (open) out.push(open);
+      open = null;
+      out.push(part);
+      continue;
+    }
+    open = open
+      ? { ...open, ...part, text: `${open.text}${typeof part.text === 'string' ? part.text : ''}` }
+      : { ...part, text: typeof part.text === 'string' ? part.text : '' };
+    if (typeof part.thoughtSignature === 'string') {
+      out.push(open);
+      open = null;
+    }
+  }
+  if (open) out.push(open);
+  return out;
+}
+
 function signatureSafeMessages(messages, model) {
-  return messages.map((message) => {
-    if (message?.role !== 'assistant') return message;
+  const claude = isAntigravityClaude(model);
+  return messages.flatMap((message) => {
+    if (message?.role !== 'assistant') return [message];
     const ownParts = replayFamilyMatches(message, model) ? providerReplayItems(message, 'antigravity') : undefined;
     // Repair tool signatures only after the complete history establishes
     // the active turn, not while normalizing an isolated older message.
-    const parts = ownParts || toGeminiContents([message], model, { repairToolSignatures: false })[0]?.parts;
-    if (!parts?.length) return message;
+    const sourceParts = ownParts || toGeminiContents([message], model, { repairToolSignatures: false })[0]?.parts;
+    const parts =
+      claude && sourceParts
+        ? coalesceClaudeThoughts(sourceParts.filter((part) => !isEmptyPlainTextPart(part)))
+        : sourceParts;
+    // A turn that held only empty parts is omitted, not sent as parts:[].
+    if (sourceParts?.length && !parts.length) return [];
+    if (!parts?.length) return [message];
     for (const part of parts) {
       if (!part || typeof part !== 'object') continue;
       if (part.thought === true || typeof part.thoughtSignature === 'string') {
@@ -47,7 +96,7 @@ function signatureSafeMessages(messages, model) {
         if (!ownParts || !part.thoughtSignature) part.thoughtSignature = THOUGHT_SIGNATURE_SENTINEL;
       }
     }
-    return { ...message, providerReplay: createProviderReplay('antigravity', parts) };
+    return [{ ...message, providerReplay: createProviderReplay('antigravity', parts) }];
   });
 }
 
@@ -59,33 +108,44 @@ function sessionId(contents) {
   return `-${digest.readBigUInt64BE(0) % 9223372036854775807n}`;
 }
 
+// The gateway validates Claude's level against Google's ThinkingLevel enum,
+// whose highest value is `high`; anything it does not name is left out.
+const CLAUDE_GATEWAY_LEVELS = new Set(['low', 'medium', 'high']);
+function claudeGatewayLevel(value) {
+  const level = String(value ?? '').toLowerCase();
+  if (level === 'xhigh' || level === 'max' || level === 'ultra') return 'high';
+  return CLAUDE_GATEWAY_LEVELS.has(level) ? level : null;
+}
+
+// An explicit token budget is sent as-is; otherwise the chosen effort rides
+// on thinkingLevel with the wire id unchanged.
 function claudeThinkingConfig(opts) {
   const budget = opts.thinkingBudget ?? opts.thinkingBudgetTokens;
-  if (opts.thinkingLevel != null || (budget == null && opts.effort != null)) {
-    throw new TypeError(
-      'Antigravity Claude uses thinkingBudget; effort levels cannot be converted to a token budget automatically.'
-    );
-  }
   const thinkingConfig = { includeThoughts: true };
-  if (budget != null) {
-    const value = Number(budget);
-    if (!Number.isInteger(value) || value < 1024 || value >= CLAUDE_MAX_OUTPUT_TOKENS) {
-      throw new TypeError('Antigravity Claude thinkingBudget must be an integer from 1024 to 63999.');
-    }
-    thinkingConfig.thinkingBudget = value;
+  if (budget == null) {
+    const level = claudeGatewayLevel(opts.thinkingLevel ?? opts.effort);
+    if (level) thinkingConfig.thinkingLevel = level;
+    return thinkingConfig;
+  }
+  const value = Number(budget);
+  if (!Number.isInteger(value) || value < 1024 || value >= CLAUDE_MAX_OUTPUT_TOKENS) {
+    throw new TypeError('Antigravity Claude thinkingBudget must be an integer from 1024 to 63999.');
   }
+  thinkingConfig.thinkingBudget = value;
   return thinkingConfig;
 }
 
 // Tiered wire ids (gemini-3.8-flash-high) already encode the thinking
 // level; the provider resolves them from the catalog and clears the
 // effort, so only bare ids reach this field.
-// Thought summaries on by default for every Gemini family, matching the
+// Thought summaries on by default for every Gemini-family model, matching the
 // API-key provider. The gateway also serves GPT-OSS, which rejects the
-// thinking fields outright, so the flag stays Gemini-only.
+// thinking fields outright and which the roster's thinking flag does not
+// separate from Gemini, so the flag stays Gemini-only.
 function antigravityGeminiThinkingConfig(model, opts) {
   return geminiThinkingConfig(model, opts, {
-    includeThoughts: /^gemini-/i.test(model) ? true : undefined,
+    provider: 'antigravity-oauth',
+    includeThoughts: isGeminiFamilyModel(model) ? true : undefined,
   });
 }
 
@@ -105,9 +165,16 @@ export function buildAntigravityRequest(messages, model, tools, opts = {}, proje
   };
   const request = { contents };
   if (systemText) request.systemInstruction = { role: 'user', parts: [{ text: systemText }] };
-  const requestTools = toGeminiRequestTools(tools, opts.nativeTools);
+  const requestTools = claude
+    ? claudeRequestTools(tools, opts.nativeTools, opts.onToolExcluded)
+    : toGeminiRequestTools(tools, opts.nativeTools, {
+        onToolExcluded: opts.onToolExcluded,
+        // Other families (GPT-OSS) keep the plain conversion.
+        validate: isGeminiFamilyModel(model),
+      });
   if (requestTools.length) request.tools = requestTools;
-  if (tools?.length) {
+  // Tool config only accompanies function declarations that were kept.
+  if (requestTools.some((entry) => entry.functionDeclarations?.length)) {
     request.toolConfig = toGeminiToolConfig(opts.toolChoice) || {
       functionCallingConfig: { mode: antigravityFunctionCallingMode() },
     };

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

@@ -8,12 +8,20 @@
  */
 import { traceAgentUsage } from '../agent-trace.mjs';
 import { createProviderReplay } from './lib/provider-replay.mjs';
-import { parseToolCalls, collectGeminiGroundingSources, parseGeminiTextPartMetadata } from './gemini-schema.mjs';
+import {
+  parseToolCalls,
+  emitGeminiToolCalls,
+  collectGeminiGroundingSources,
+  parseGeminiTextPartMetadata,
+} from './gemini-schema.mjs';
+import { geminiFinishErrorFields, geminiPolicyFinishCode } from './gemini-error-contract.mjs';
 
 // Pure usageMetadata normalization shared by the success path and a failed
 // stream's partialUsage.
 export function normalizeAntigravityUsage(um) {
-  const inputTokens = um.promptTokenCount || um.prompt_token_count || 0;
+  const inputTokens =
+    (um.promptTokenCount || um.prompt_token_count || 0) +
+    (um.toolUsePromptTokenCount || um.tool_use_prompt_token_count || 0);
   const cachedTokens = um.cachedContentTokenCount || um.cached_content_token_count || 0;
   const outputTokens =
     (um.candidatesTokenCount || um.candidates_token_count || 0) +
@@ -27,7 +35,7 @@ export function normalizeAntigravityUsage(um) {
  * @param {ReturnType<import('./antigravity-stream.mjs').createAntigravityStreamCollector>} deps.collector
  * @param {string} deps.useModel  wire model id
  * @param {object} deps.opts  send options (session/iteration/providerState)
- * @param {Function|null} deps.onToolCall  set when calls were streamed live
+ * @param {Function|null} deps.onToolCall  receives the turn's calls after a clean finish
  */
 export function finalizeAntigravityTurn({ response, collector, useModel, opts, onToolCall }) {
   const textLeakGuard = collector.leakGuard;
@@ -45,10 +53,8 @@ export function finalizeAntigravityTurn({ response, collector, useModel, opts, o
   // Thought signatures are only valid for the model family that minted
   // them; the request builder consults this when the route changes.
   if (providerReplay) providerReplay.requestContext = { model: useModel };
-  let nativeToolCalls;
-  if (!onToolCall) nativeToolCalls = parseToolCalls(responseParts);
-  else if (collector.streamedNativeToolCalls.length) nativeToolCalls = collector.streamedNativeToolCalls;
-  if (!onToolCall && textLeakGuard?.enabled) nativeToolCalls = textLeakGuard.filterNativeToolCalls(nativeToolCalls);
+  let nativeToolCalls = parseToolCalls(responseParts);
+  if (textLeakGuard?.enabled) nativeToolCalls = textLeakGuard.filterNativeToolCalls(nativeToolCalls);
   let toolCalls = nativeToolCalls;
   if (leakedToolCalls.length) {
     toolCalls = toolCalls?.length ? [...toolCalls, ...leakedToolCalls] : leakedToolCalls;
@@ -79,10 +85,20 @@ export function finalizeAntigravityTurn({ response, collector, useModel, opts, o
     });
   }
 
-  if (finishReason && normalizedFinish !== 'STOP') {
+  // A MAX_TOKENS cut that still delivered whole native functionCall parts is
+  // a tool-use turn: the calls arrived intact, only trailing output was cut.
+  // Every other non-STOP finish fails the turn, and so does a cut whose text
+  // also leaked a call (that call may be as truncated as the text around it).
+  const completeNativeCalls =
+    normalizedFinish === 'MAX_TOKENS' &&
+    String(candidate?.finishReason || '').replace(/^FINISH_REASON_/, '') === 'MAX_TOKENS' &&
+    !leakedToolCalls.length &&
+    !!nativeToolCalls?.length &&
+    nativeToolCalls.every((call) => typeof call?.name === 'string' && call.name !== '');
+  if (finishReason && normalizedFinish !== 'STOP' && !completeNativeCalls) {
     throw Object.assign(new Error(`Antigravity response incomplete: finishReason=${finishReason}`), {
       name: 'ProviderIncompleteError',
-      code: 'PROVIDER_INCOMPLETE',
+      code: geminiPolicyFinishCode(finishReason) || 'PROVIDER_INCOMPLETE',
       providerIncomplete: true,
       finishReason,
       partialContent: content,
@@ -92,10 +108,14 @@ export function finalizeAntigravityTurn({ response, collector, useModel, opts, o
       model: useModel,
       rawUsage: response.usageMetadata || null,
       ...(usage ? { partialUsage: usage, partialModel: useModel } : {}),
-      ...(collector.emittedToolCount ? { emittedToolCall: true, unsafeToRetry: true } : {}),
+      ...geminiFinishErrorFields(response),
     });
   }
 
+  // Terminal status first: a failed turn never runs its tool calls.
+  textLeakGuard?.releaseDeferredToolCalls();
+  emitGeminiToolCalls(nativeToolCalls, onToolCall);
+
   return {
     content,
     model: useModel,

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

@@ -0,0 +1,106 @@
+/**
+ * antigravity-retry-policy.mjs — Antigravity retry constants and the verdict
+ * for a 429:
+ *
+ *   capacity (429/503/529, MODEL_CAPACITY_EXHAUSTED, "server busy"): retried on
+ *     the SAME account and host with 1s → 2s → 4s (8s cap) ±10% jitter, three
+ *     retries, waiting at least the server's RetryInfo delay; advice that
+ *     would push total waiting past 60s surfaces the error (with resetAt).
+ *   Endpoint: the reference falls back to its next endpoint after a failure;
+ *     generation here deliberately stays on the single daily host and never
+ *     walks an endpoint list (a spent ladder surfaces to the account layer).
+ *   RPM / unknown 429: ONE quick retry after 1s (or the server's advice, up to
+ *     60s), then the failure surfaces so the account layer can lock and
+ *     rotate; advice beyond 60s surfaces at once.
+ *   QUOTA_EXHAUSTED (and any day/plan window): never retried here.
+ *
+ * Replay stays gated by the stream-outcome contract: an attempt that exposed
+ * text or dispatched a tool is never re-issued.
+ */
+import { readStreamOutcome } from './lib/stream-outcome.mjs';
+import { DETERMINISTIC_KINDS, providerErrorKind } from './provider-error-kind.mjs';
+
+export const ANTIGRAVITY_CAPACITY_RETRIES = 3;
+export const ANTIGRAVITY_CAPACITY_BASE_MS = 1000;
+export const ANTIGRAVITY_CAPACITY_MAX_MS = 8000;
+export const ANTIGRAVITY_CAPACITY_JITTER_RATIO = 0.1;
+// Total time capacity retries may spend waiting on server-advised delays.
+export const ANTIGRAVITY_CAPACITY_BUDGET_MS = 60_000;
+export const ANTIGRAVITY_QUICK_RETRY_MS = 1000;
+export const ANTIGRAVITY_QUICK_RETRY_MAX_ADVICE_MS = 60_000;
+
+// withRetry options for everything that is not a 429: transient transport and
+// 5xx failures use the capacity schedule (the reference has no other same-host
+// retry; the leading duplicate is the sleep-before-attempt index).
+export const ANTIGRAVITY_RETRY = Object.freeze({
+  maxAttempts: ANTIGRAVITY_CAPACITY_RETRIES + 1,
+  backoffMs: Object.freeze([1000, 1000, 2000, 4000]),
+  retryJitterRatio: ANTIGRAVITY_CAPACITY_JITTER_RATIO,
+  // 429s are handled by antigravity429WaitMs, not the generic loop.
+  retry429: false,
+});
+
+/** Capacity wait for retry number `retryIndex` (0-based): 1s, 2s, 4s, 8s cap, ±10%. */
+export function antigravityCapacityDelayMs(retryIndex) {
+  const base = Math.min(ANTIGRAVITY_CAPACITY_BASE_MS * 2 ** retryIndex, ANTIGRAVITY_CAPACITY_MAX_MS);
+  return Math.round(base * (1 - ANTIGRAVITY_CAPACITY_JITTER_RATIO + Math.random() * 2 * ANTIGRAVITY_CAPACITY_JITTER_RATIO));
+}
+
+export function isAntigravityCapacityError(err) {
+  return err?.code === 'model_capacity_exhausted' || providerErrorKind(err).kind === 'overloaded';
+}
+
+/**
+ * Wait before re-issuing a 429, or null when it must surface. `state` is the
+ * send's `{ capacityRetries, quickRetried }` record.
+ */
+export function antigravity429WaitMs(err, state) {
+  const status = Number(err?.status || err?.httpStatus || 0);
+  const capacity = isAntigravityCapacityError(err);
+  if (status !== 429 && !(capacity && (status === 503 || status === 529))) return null;
+  if (readStreamOutcome(err).replaySafe !== true) return null;
+  const { kind, retryAfterMs } = providerErrorKind(err);
+  if (DETERMINISTIC_KINDS.has(kind) || err.code === 'quota_exhausted' || err.quotaScope === 'day' || err.quotaScope === 'plan') {
+    return null;
+  }
+  // Capacity waits at least the advised RetryInfo delay (the local schedule
+  // is the floor). Total advised waiting stays within the retry budget; an
+  // advice that does not fit surfaces with its reset time rather than
+  // retrying early.
+  if (capacity) {
+    if (state.capacityRetries >= ANTIGRAVITY_CAPACITY_RETRIES) return null;
+    const spent = state.capacityWaitedMs ?? 0;
+    if (retryAfterMs != null && spent + retryAfterMs > ANTIGRAVITY_CAPACITY_BUDGET_MS) {
+      err.resetAt ??= Date.now() + retryAfterMs;
+      return null;
+    }
+    const wait = Math.max(antigravityCapacityDelayMs(state.capacityRetries++), retryAfterMs ?? 0);
+    state.capacityWaitedMs = spent + wait;
+    return wait;
+  }
+  // An RPM hit gets one quick retry; advice up to a minute is honored in
+  // full, a longer wait surfaces so the account pool can rotate.
+  if (state.quickRetried || retryAfterMs > ANTIGRAVITY_QUICK_RETRY_MAX_ADVICE_MS) return null;
+  state.quickRetried = true;
+  return retryAfterMs ?? ANTIGRAVITY_QUICK_RETRY_MS;
+}
+
+// Account-pool roster cooldowns, read
+// generically by the shared pool from the provider's `accountCooldownPolicy`
+// when the server named no delay: a plain rate limit rotates the account for
+// 30s; a spent quota escalates 60s → 5m → 30m → 2h per consecutive refusal of
+// that account (a served answer resets it); anything else 60s; never under 2s.
+// Capacity and server errors never block an account in the shared pool.
+export const ANTIGRAVITY_ACCOUNT_COOLDOWN_POLICY = Object.freeze({
+  floorMs: 2_000,
+  rateLimitedMs: 30_000,
+  quotaStepsMs: Object.freeze([60_000, 5 * 60_000, 30 * 60_000, 2 * 60 * 60_000]),
+  unknownMs: 60_000,
+  rotateOnRateLimit: true,
+  // A roster that is only cooling down waits up to five minutes for its
+  // earliest cooldown instead of failing the send.
+  waitForCooldownMs: 300_000,
+  // An account that needs verification cools for ten minutes while the
+  // roster serves from the next account.
+  blockedMs: 600_000,
+});