fix(subagent): surface scrubbed xAI worker diagnostics

Worker mailbox errors used a summary that dropped the provider
reason, and xAI fatal 400s never lifted nested error.message over
HTTP statusText. Keep raw on the captured inference.error, lift
nested 400 copy for xAI the same way Codex does, and put the
scrubbed full line on wait_agents so the next Grok 400 names why.

Author: TheGreatAxios

src/inference-error-message.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { normalizeInferenceErrorForTerminal } from "./inference-gateway-error.js";
 import {
   CREDENTIAL_FAILURE_USER_MESSAGE,
+  createResolvedProviderFailureError,
   inferenceErrorMessage,
   terminalProviderFailureMessage,
 } from "./inference-error-message.js";
@@ -229,6 +230,18 @@ describe("terminalProviderFailureMessage", () => {
     expect(message).toContain('reconnect profile "default-2"');
   });
 
+  test("xAI worker failure line lifts nested 400 diagnostic over Bad Request", () => {
+    const error = createResolvedProviderFailureError("xai/default-2", {
+      category: "fatal",
+      message: "Bad Request",
+      statusCode: 400,
+      raw: { error: { message: "Invalid request: recursive JSON schema" } },
+    });
+    expect(error.message).toContain("Invalid request: recursive JSON schema");
+    expect(error.message).toContain("xai/default-2");
+    expect(error.message).not.toContain("Bad Request");
+  });
+
   test("terminal Codex credential failure keeps branded wording plus the explicit command", () => {
     const normalized = normalizeInferenceErrorForTerminal(
       {

src/inference-error-message.ts

@@ -20,6 +20,7 @@ import {
   isGatewayOverloadInferenceError,
   isKnownOAuthProviderId,
   isXaiShortRateLimitInferenceError,
+  normalizeInferenceErrorForTerminal,
   parseCodexUsageLimitFromError,
   RATE_LIMIT_USER_MESSAGE,
   type InferenceErrorLike,
@@ -253,18 +254,6 @@ function terminalProviderFailureGuidance(
     : 'Try again or switch models with "/model".';
 }
 
-function terminalProviderFailureSummary(
-  providerId: string,
-  error: InferenceErrorLike,
-  displayLabel?: string,
-): string {
-  const label = terminalProviderFailureLabel(providerId, displayLabel);
-  const category = terminalProviderFailureCategory(error);
-  const guidance = terminalProviderFailureGuidance(error, category, providerId);
-  const tail = guidance.length > 0 ? ` ${guidance}` : "";
-  return `${label} Provider failed (${category}).${tail}`;
-}
-
 export type ResolvedProviderFailureError = Error & {
   readonly name: "ResolvedProviderFailureError";
   readonly providerId: string;
@@ -277,16 +266,20 @@ export function createResolvedProviderFailureError(
   providerError: InferenceErrorLike,
   displayLabel?: string,
 ): ResolvedProviderFailureError {
+  const normalized = normalizeInferenceErrorForTerminal(
+    providerError,
+    providerId,
+  );
   return Object.assign(
     new Error(
-      terminalProviderFailureSummary(providerId, providerError, displayLabel),
+      terminalProviderFailureMessage(providerId, normalized, displayLabel),
     ),
     {
       name: "ResolvedProviderFailureError" as const,
       providerId,
-      category: terminalProviderFailureCategory(providerError),
-      ...(providerError.statusCode !== undefined
-        ? { statusCode: providerError.statusCode }
+      category: terminalProviderFailureCategory(normalized),
+      ...(normalized.statusCode !== undefined
+        ? { statusCode: normalized.statusCode }
         : {}),
     },
   );

src/inference-gateway-error.test.ts

@@ -627,6 +627,34 @@ describe("normalizeInferenceErrorForRetry", () => {
     expect(normalizeInferenceErrorForRetry(error)).toBe(error);
   });
 
+  test("lifts an xAI fatal 400 nested diagnostic over Bad Request", () => {
+    const raw = {
+      error: { message: "Invalid request: recursive JSON schema" },
+    };
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Bad Request",
+      statusCode: 400,
+      providerId: "xai/default-2",
+      raw,
+    });
+    expect(normalized.category).toBe("fatal");
+    expect(normalized.message).toBe("Invalid request: recursive JSON schema");
+    expect(normalized.statusCode).toBe(400);
+    expect(normalized.raw).toBe(raw);
+  });
+
+  test("lifts a grok-responses fatal 400 nested diagnostic", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Bad Request",
+      statusCode: 400,
+      providerId: "grok-responses",
+      raw: { error: { message: "tools.0.parameters is invalid" } },
+    });
+    expect(normalized.message).toBe("tools.0.parameters is invalid");
+  });
+
   test("does not lift a Codex-shaped fatal 400 without a providerId", () => {
     const error = {
       category: "fatal" as const,

src/inference-gateway-error.ts

@@ -638,17 +638,24 @@ function normalizeCodexCredential404Error(
 }
 
 /**
- * Codex 400s arrive as fatal with HTTP statusText ("Bad Request") while the
- * real diagnostic sits on nested `detail.error`. Lift the nested copy so the
- * transcript is actionable; keep category fatal — this is not overflow,
- * rate-limit, or quota.
+ * Fatal 400s arrive with HTTP statusText ("Bad Request") while the real
+ * diagnostic sits on nested `detail.error` / `error.message`. Lift the nested
+ * copy so the transcript is actionable; keep category fatal — this is not
+ * overflow, rate-limit, or quota. Codex and xAI/Grok both do this; other
+ * providers keep statusText until their body shape is characterized.
  */
-function normalizeCodexFatal400Message(
+function normalizeFatal400NestedMessage(
   error: InferenceErrorWithGoContext,
 ): InferenceError {
-  if (!isKnownCodexProviderId(error.providerId)) return error;
   if (error.category !== "fatal") return error;
   if (error.statusCode !== 400) return error;
+  const providerId = error.providerId;
+  if (
+    !isKnownCodexProviderId(providerId) &&
+    !isKnownXaiProviderId(providerId)
+  ) {
+    return error;
+  }
 
   const current = error.message ?? "";
   if (current.length > 0 && current.toLowerCase() !== "bad request") {
@@ -815,9 +822,9 @@ function normalizeOAuthUpgradeRequiredError(
  * 429s, attributable xAI capacity protocol_mismatch, Codex usage limits
  * (nested detail.error with resets_in_seconds), known-Codex short 429s that
  * are not usage_limit_reached, known-Codex 404s carrying an
- * auth-rejection signal (expired/revoked credential), known-Codex fatal
- * 400s whose message is empty or "Bad Request" (nested diagnostic on raw), and
- * known-OAuth fatal 426s (unauthenticated-provider upgrade rejection).
+ * auth-rejection signal (expired/revoked credential), known-Codex and known-xAI
+ * fatal 400s whose message is empty or "Bad Request" (nested diagnostic on raw),
+ * and known-OAuth fatal 426s (unauthenticated-provider upgrade rejection).
  */
 export function normalizeInferenceErrorForRetry(
   error: InferenceErrorWithGoContext,
@@ -840,8 +847,8 @@ export function normalizeInferenceErrorForRetry(
   const codexCredential = normalizeCodexCredential404Error(error);
   if (codexCredential !== error) return codexCredential;
 
-  const codexFatal400 = normalizeCodexFatal400Message(error);
-  if (codexFatal400 !== error) return codexFatal400;
+  const fatal400 = normalizeFatal400NestedMessage(error);
+  if (fatal400 !== error) return fatal400;
 
   const oauthUpgrade = normalizeOAuthUpgradeRequiredError(error);
   if (oauthUpgrade !== error) return oauthUpgrade;

src/subagent/run-resolved-provider-failure.test.ts

@@ -32,8 +32,9 @@ import {
 const OPAQUE_SECRET = "opaque credential with spaces?!";
 const RAW_DIAGNOSTIC = `\u001b[31mPOST https://provider.invalid returned\n credential ${OPAQUE_SECRET} in response body\u001b[0m`;
 const NORMALIZED_DIAGNOSTIC = `POST https://provider.invalid returned credential ${OPAQUE_SECRET} in response body`;
-const SAFE_MESSAGE =
-  'test-provider Provider failed (fatal). Try again or switch models with "/model".';
+const SCRUBBED_DIAGNOSTIC =
+  "POST https://provider.invalid returned credential [redacted: configured credential] in response body";
+const SAFE_MESSAGE = `test-provider Provider failed (fatal): ${SCRUBBED_DIAGNOSTIC}. Try again or switch models with "/model".`;
 const provider = {
   providerName: "test-provider",
   baseURL: "http://localhost",
@@ -282,6 +283,35 @@ describe("resolved sub-agent provider failures", () => {
     expect(JSON.stringify(observed)).not.toContain(RAW_DIAGNOSTIC);
   });
 
+  test("xAI 400 mailbox line lifts the nested diagnostic from raw", async () => {
+    const caught = await withResolvedProviderRun(
+      async (run, cwd) => {
+        try {
+          await run({
+            ...runParams(cwd),
+            provider: { ...provider, providerName: "xai/default-2" },
+          });
+        } catch (error) {
+          return error;
+        }
+        throw new Error("expected runSubAgent to reject");
+      },
+      {
+        category: "fatal",
+        message: "Bad Request",
+        statusCode: 400,
+        raw: { error: { message: "Invalid request: recursive JSON schema" } },
+      },
+    );
+    expect(isResolvedProviderFailureError(caught)).toBe(true);
+    expect((caught as ResolvedProviderFailureError).message).toContain(
+      "Invalid request: recursive JSON schema",
+    );
+    expect((caught as ResolvedProviderFailureError).message).not.toContain(
+      "Bad Request",
+    );
+  });
+
   test("split spawn_agent and wait_agents return only the safe message", async () => {
     await withResolvedProviderRun(async (run, cwd) => {
       const { sessions, agentId, waitResult } = await spawnAndWait(
@@ -326,8 +356,7 @@ describe("resolved sub-agent provider failures", () => {
           cwd,
           "rejected provider failure",
         );
-        const safeFailure =
-          "test-provider Provider failed (retryable). Try again.";
+        const safeFailure = `test-provider Provider failed (retryable): ${SCRUBBED_DIAGNOSTIC}. Try again.`;
 
         const serialized = JSON.stringify(waitResult);
         expect(serialized).toContain(safeFailure);
@@ -351,15 +380,14 @@ describe("resolved sub-agent provider failures", () => {
         message: RAW_DIAGNOSTIC,
         statusCode: 500,
       },
-      expected: "test-provider Provider failed (retryable). Try again.",
+      expected: `test-provider Provider failed (retryable): ${SCRUBBED_DIAGNOSTIC}. Try again.`,
     },
     {
       error: { category: "protocol_mismatch", message: RAW_DIAGNOSTIC },
-      expected:
-        'test-provider Provider failed (protocol_mismatch). Switch models with "/model".',
+      expected: `test-provider Provider failed (protocol_mismatch): ${SCRUBBED_DIAGNOSTIC}. Switch models with "/model".`,
     },
   ] satisfies { error: InferenceErrorLike; expected: string }[])(
-    "preserves $error.category guidance without exposing its diagnostic",
+    "preserves $error.category guidance and the scrubbed diagnostic",
     async ({ error, expected }) => {
       const caught = await withResolvedProviderRun(async (run, cwd) => {
         try {
@@ -434,7 +462,7 @@ describe("resolved sub-agent provider failures", () => {
     expect(resolved.category).toBe("retryable");
     expect(resolved.statusCode).toBe(503);
     expect(resolved.message).toBe(
-      "test-provider Provider failed (retryable). Try again.",
+      `test-provider Provider failed (retryable): still failing. Try again.`,
     );
   });
 

src/subagent/run.ts

@@ -1466,6 +1466,10 @@ async function runSubAgentInner(
           ...(error.retryAfterMs !== undefined
             ? { retryAfterMs: error.retryAfterMs }
             : {}),
+          ...("raw" in error && error.raw !== undefined
+            ? { raw: error.raw }
+            : {}),
+          providerId: params.provider.providerName,
         };
       }
       if (onTurnBoundary(event)) {