Retry attributable xAI capacity protocol mismatches

xAI and Grok sometimes surface capacity or overload as
protocol_mismatch instead of a retryable status. Remap those
attributable phrases to retryable while leaving quota exhaustion,
unknown providers, and OpenCode Go unchanged.

Author: TheGreatAxios

src/agent/retry-policy.test.ts

@@ -34,6 +34,39 @@ describe("createCorbitsRetryPolicy", () => {
     expect(decision).toEqual({ kind: "retry", delayMs: 500 });
   });
 
+  test("bounds attributable xAI capacity retries to three attempts", async () => {
+    const decide = policy({ providerId: "xai/default" });
+    const situation = (attempt: number) => ({
+      attempt,
+      elapsedMs: 0,
+      error: {
+        category: "protocol_mismatch" as const,
+        message: "The model is currently at capacity",
+      },
+    });
+
+    expect(await decide(situation(1))).toEqual({ kind: "retry", delayMs: 500 });
+    expect(await decide(situation(2))).toEqual({
+      kind: "retry",
+      delayMs: 1000,
+    });
+    expect(await decide(situation(3))).toEqual({ kind: "abort" });
+  });
+
+  test("aborts attributable xAI quota exhaustion", async () => {
+    const decision = await policy({ providerId: "xai/default" })({
+      attempt: 1,
+      elapsedMs: 0,
+      error: {
+        category: "quota_exhausted",
+        message: "Service temporarily unavailable: quota exhausted",
+        statusCode: 429,
+        retryAfterMs: 86_400_000,
+      },
+    });
+    expect(decision).toEqual({ kind: "abort" });
+  });
+
   test("aborts an OpenCode Go malformed streamed SSE schema response", async () => {
     const decision = await policy({ providerId: "opencode-go/corbits" })({
       attempt: 1,

src/inference-gateway-error.test.ts

@@ -281,6 +281,78 @@ describe("normalizeInferenceErrorForRetry", () => {
     expect(normalized).toBe(error);
   });
 
+  test("known-xAI message-only capacity protocol error becomes retryable", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "protocol_mismatch",
+      message: "The model is currently at capacity. Please try again later.",
+      providerId: "xai/default",
+      retryAfterMs: 2_500,
+    });
+    expect(normalized.category).toBe("retryable");
+    expect(normalized.retryAfterMs).toBe(2_500);
+  });
+
+  test("known-xAI JSON-bodied high-demand protocol error becomes retryable", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "protocol_mismatch",
+      message: "malformed JSON in SSE data payload",
+      providerId: "xai/default",
+      raw: {
+        error: {
+          message: "The service is unavailable due to high demand",
+        },
+      },
+    });
+    expect(normalized.category).toBe("retryable");
+  });
+
+  test("known-xAI exact temporary-unavailable phrase becomes retryable", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "protocol_mismatch",
+      message: "Service temporarily unavailable",
+      providerId: "xai/default",
+    });
+    expect(normalized.category).toBe("retryable");
+  });
+
+  test("explicit Grok adapter overload protocol error becomes retryable", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "protocol_mismatch",
+      message: "The upstream service is overloaded",
+      providerId: "grok-responses",
+    });
+    expect(normalized.category).toBe("retryable");
+  });
+
+  test("unknown provider capacity protocol_mismatch stays unchanged", () => {
+    const error = {
+      category: "protocol_mismatch" as const,
+      message: "The model is currently at capacity",
+      providerId: "openai",
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("OpenCode Go capacity prose stays protocol_mismatch", () => {
+    const error = {
+      category: "protocol_mismatch" as const,
+      message: "The model is currently at capacity",
+      providerId: "opencode-go/default",
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("known-xAI quota exhaustion stays non-retryable despite capacity prose", () => {
+    const error = {
+      category: "quota_exhausted" as const,
+      message: "Service temporarily unavailable: quota exhausted",
+      statusCode: 429,
+      providerId: "xai/default",
+      retryAfterMs: 86_400_000,
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
   test("known-xAI bare 429 reclassifies as retryable", () => {
     const bare = {
       category: "quota_exhausted" as const,

src/inference-gateway-error.ts

@@ -238,6 +238,55 @@ function textHasXaiQuotaMarkers(...parts: string[]): boolean {
   return XAI_QUOTA_BODY_MARKERS.some((marker) => combined.includes(marker));
 }
 
+/**
+ * xAI / Grok capacity and overload phrases that arrive as protocol_mismatch
+ * (message-only or JSON raw) when the stream is not valid SSE. Exact
+ * "Service temporarily unavailable" is intentional — do not widen to the
+ * gateway "service unavailable" substring, which would rematch quota copy.
+ */
+const XAI_CAPACITY_TEXT_MARKERS = [
+  "currently at capacity",
+  "overloaded",
+  "high demand",
+] as const;
+
+const XAI_CAPACITY_EXACT_MESSAGES = new Set([
+  "service temporarily unavailable",
+]);
+
+function textSuggestsXaiCapacity(...parts: string[]): boolean {
+  const combined = parts.join("\n").toLowerCase();
+  if (XAI_CAPACITY_TEXT_MARKERS.some((marker) => combined.includes(marker))) {
+    return true;
+  }
+  // Exact phrase is message-only; do not substring-match so quota suffixes stay out.
+  return XAI_CAPACITY_EXACT_MESSAGES.has(parts[0]?.trim().toLowerCase() ?? "");
+}
+
+/**
+ * Remap attributable xAI / Grok capacity protocol_mismatch errors to retryable.
+ * Unknown providers and OpenCode Go stay terminal. Never remaps quota_exhausted.
+ */
+export function normalizeXaiCapacityError(
+  error: InferenceErrorWithGoContext,
+): InferenceError {
+  if (error.category !== "protocol_mismatch") return error;
+  if (!isKnownXaiProviderId(error.providerId)) return error;
+  if (!textSuggestsXaiCapacity(error.message ?? "", stringFromRaw(error.raw))) {
+    return error;
+  }
+
+  return {
+    category: "retryable",
+    message: GATEWAY_OVERLOAD_USER_MESSAGE,
+    statusCode: error.statusCode ?? 503,
+    ...(error.raw !== undefined ? { raw: error.raw } : {}),
+    ...(error.retryAfterMs !== undefined
+      ? { retryAfterMs: error.retryAfterMs }
+      : {}),
+  };
+}
+
 /**
  * True when a known-xAI HTTP 429 looks like a short rate limit rather than a
  * usage/quota window. Used by both retry normalization and transcript copy —
@@ -400,8 +449,9 @@ function normalizeCodexUsageLimitError(
  * Reclassify gateway overload errors so the default retry policy treats them as
  * transient instead of aborting on protocol_mismatch. Also normalizes OpenCode
  * Go quota/rate-limit shapes (including HTTP 400 mis-status), known-xAI short
- * 429s, Codex usage limits (nested detail.error with resets_in_seconds), and
- * known-Codex short 429s that are not usage_limit_reached.
+ * 429s, attributable xAI capacity protocol_mismatch, Codex usage limits
+ * (nested detail.error with resets_in_seconds), and known-Codex short 429s that
+ * are not usage_limit_reached.
  */
 export function normalizeInferenceErrorForRetry(
   error: InferenceErrorWithGoContext,
@@ -412,6 +462,9 @@ export function normalizeInferenceErrorForRetry(
   const xaiNormalized = normalizeXaiRateLimitError(error);
   if (xaiNormalized !== error) return xaiNormalized;
 
+  const xaiCapacity = normalizeXaiCapacityError(error);
+  if (xaiCapacity !== error) return xaiCapacity;
+
   const codexNormalized = normalizeCodexUsageLimitError(error);
   if (codexNormalized !== error) return codexNormalized;