Merge pull request #1138 from corbitsdev/cl-8627-classify-expired-codex-credentials-as-credential-failures

fix(inference): treat Codex 404s as expired credentials

Author: TheGreatAxios

src/inference-error-message.test.ts

@@ -160,6 +160,50 @@ describe("terminalProviderFailureMessage", () => {
     );
   });
 
+  test("terminal Codex credential 404 names the profile with a re-login hint", () => {
+    const normalized = normalizeInferenceErrorForTerminal(
+      {
+        category: "fatal",
+        message: "Not Found",
+        statusCode: 404,
+        raw: {
+          error: {
+            code: "invalid_token",
+            message: "Not authorized: the access token has been revoked",
+          },
+        },
+      },
+      "codex/work",
+    );
+    const message = terminalProviderFailureMessage("codex/work", normalized);
+    expect(message).toContain('Codex profile "work"');
+    expect(message).toContain("Not Found");
+    expect(message).not.toContain("/model");
+    // One re-login hint, not a stutter: the branded diagnostic dedups via
+    // the shared carriesCodexReLoginHint predicate.
+    expect(message.toLowerCase().match(/log in again/g)).toHaveLength(1);
+  });
+
+  test("terminal bare Codex 404 without an auth signal keeps switch-models guidance", () => {
+    const normalized = normalizeInferenceErrorForTerminal(
+      { category: "fatal", message: "Not Found", statusCode: 404 },
+      "codex/work",
+    );
+    const message = terminalProviderFailureMessage("codex/work", normalized);
+    expect(message).toContain('"/model"');
+    expect(message.toLowerCase()).not.toMatch(/log in again/);
+  });
+
+  test("terminal genuine unknown-model 404 keeps switch-models guidance", () => {
+    const message = terminalProviderFailureMessage("codex/work", {
+      category: "fatal",
+      message: "The model 'gpt-99' does not exist",
+      statusCode: 404,
+      providerId: "codex/work",
+    });
+    expect(message).toContain('"/model"');
+  });
+
   test.each([
     {
       name: "Bearer header",

src/inference-error-message.ts

@@ -14,6 +14,7 @@ import {
 import { stripTerminalControlSequences } from "./util/control-char-strip.js";
 import { scrubSecretShapedContent } from "./plugins/tool-result-secret-scrub.js";
 import {
+  carriesCodexReLoginHint,
   gatewayOverloadUserMessage,
   isCodexShortRateLimitInferenceError,
   isGatewayOverloadInferenceError,
@@ -146,14 +147,22 @@ export function terminalProviderFailureMessage(
     ? diagnostic
     : `${diagnostic}.`;
   const guidance = terminalProviderFailureGuidance(error, category);
-  return `${label} Provider failed (${category}): ${diagnosticSentence} ${guidance}`;
+  const tail = guidance.length > 0 ? ` ${guidance}` : "";
+  return `${label} Provider failed (${category}): ${diagnosticSentence}${tail}`;
 }
 
 function terminalProviderFailureGuidance(
   error: InferenceErrorLike,
   category: string,
 ): string {
-  if (category === "credential_failure") return CREDENTIAL_FAILURE_USER_MESSAGE;
+  if (category === "credential_failure") {
+    // Normalized credential failures already carry the re-login hint in the
+    // diagnostic (e.g. Codex profile copy); repeating it reads as a stutter.
+    // Shared with the classifier via carriesCodexReLoginHint — one predicate.
+    return carriesCodexReLoginHint(error.message ?? "")
+      ? ""
+      : CREDENTIAL_FAILURE_USER_MESSAGE;
+  }
   if (category === "context_overflow") return "Try /clear to start fresh.";
   // A 429 that survived the harness's paced retries is a wait-it-out rate
   // limit, not a generic flake: say so instead of the bare "Try again."
@@ -180,7 +189,9 @@ function terminalProviderFailureSummary(
 ): string {
   const label = terminalProviderFailureLabel(providerId, displayLabel);
   const category = terminalProviderFailureCategory(error);
-  return `${label} Provider failed (${category}). ${terminalProviderFailureGuidance(error, category)}`;
+  const guidance = terminalProviderFailureGuidance(error, category);
+  const tail = guidance.length > 0 ? ` ${guidance}` : "";
+  return `${label} Provider failed (${category}).${tail}`;
 }
 
 export type ResolvedProviderFailureError = Error & {

src/inference-gateway-error.test.ts

@@ -1,9 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import {
+  carriesCodexReLoginHint,
+  codexCredential404ReclassifiedStats,
   GATEWAY_OVERLOAD_USER_MESSAGE,
   isGatewayOverloadInferenceError,
   looksLikeHtmlGatewayBody,
   normalizeInferenceErrorForRetry,
+  resetCodexCredential404StatsForTests,
   XAI_CAPACITY_USER_MESSAGE,
 } from "./inference-gateway-error.js";
 
@@ -279,6 +282,178 @@ describe("normalizeInferenceErrorForRetry", () => {
     expect(normalized).toBe(error);
   });
 
+  /**
+   * Wire shape for a revoked Codex credential: the harness classifies the
+   * HTTP 404 as fatal with the statusText message while the JSON body rides
+   * on raw. The body carries the auth-rejection signal; the status line
+   * alone ("Not Found") must never reclassify.
+   */
+  const REVOKED_CREDENTIAL_404_RAW = {
+    error: {
+      code: "invalid_token",
+      message: "Not authorized: the access token has been revoked",
+      type: "invalid_request_error",
+    },
+  };
+
+  test("Codex 404 with a revoked-credential body reclassifies as credential_failure", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: REVOKED_CREDENTIAL_404_RAW,
+    });
+    expect(normalized.category).toBe("credential_failure");
+    expect(normalized.message).toContain('Codex profile "work"');
+    expect(carriesCodexReLoginHint(normalized.message)).toBe(true);
+    // Original diagnostic rides along so the failure stays debuggable, and
+    // the wire body stays on raw for logs.
+    expect(normalized.message).toContain("Not Found");
+    expect(normalized.raw).toEqual(REVOKED_CREDENTIAL_404_RAW);
+  });
+
+  test.each([
+    { name: "not authorized", body: "Not authorized" },
+    { name: "unauthorized", body: "401 Unauthorized" },
+    { name: "invalid token", body: "Invalid token" },
+    { name: "expired", body: "The access token expired" },
+    { name: "revoked", body: "Token has been revoked" },
+  ])("Codex 404 with $name signal reclassifies", ({ body }) => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: { error: { message: body } },
+    });
+    expect(normalized.category).toBe("credential_failure");
+    expect(carriesCodexReLoginHint(normalized.message)).toBe(true);
+  });
+
+  test("Codex 404 with an auth signal in the message reclassifies", () => {
+    const normalized = normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Invalid token: expired",
+      statusCode: 404,
+      providerId: "codex/work",
+    });
+    expect(normalized.category).toBe("credential_failure");
+    expect(normalized.message).toContain("Invalid token: expired");
+  });
+
+  test("Codex bare 404 without an auth signal stays fatal", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("Codex routing 404 without an auth signal stays fatal", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: { error: { code: "not_found", message: "No such endpoint" } },
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("Codex 404 naming a dotted unknown model stays fatal", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "The model 'gpt-3.5-turbo' does not exist",
+      statusCode: 404,
+      providerId: "codex/work",
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("Codex 404 naming an unknown model keeps fatal switch-models guidance", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "The model 'gpt-99' does not exist",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: {
+        error: {
+          code: "model_not_found",
+          message: "The model 'gpt-99' does not exist",
+          type: "invalid_request_error",
+        },
+      },
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("Codex model-deprecation 404 containing 'expired' stays fatal", () => {
+    // Keeper: a retired model names itself with the credential marker word,
+    // but logging in again cannot resurrect it — the fatal switch-models
+    // path must win over the expired-credential reclassification.
+    const error = {
+      category: "fatal" as const,
+      message:
+        "The model 'gpt-4o' has expired. Migrate to 'gpt-5' to continue.",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: {
+        error: {
+          code: "model_expired",
+          message: "The model 'gpt-4o' has expired (2025-02-01).",
+          type: "invalid_request_error",
+        },
+      },
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("non-Codex 404 keeps fatal switch-models guidance", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "custom-provider",
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("non-Codex 404 with an auth signal keeps provider scoping", () => {
+    const error = {
+      category: "fatal" as const,
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "custom-provider",
+      raw: { error: { message: "Token has been revoked" } },
+    };
+    expect(normalizeInferenceErrorForRetry(error)).toBe(error);
+  });
+
+  test("reclassified Codex 404s bump the counter with a body sample", () => {
+    resetCodexCredential404StatsForTests();
+    expect(codexCredential404ReclassifiedStats().count).toBe(0);
+    normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+      raw: REVOKED_CREDENTIAL_404_RAW,
+    });
+    // A fatal 404 without an auth signal must not bump the counter.
+    normalizeInferenceErrorForRetry({
+      category: "fatal",
+      message: "Not Found",
+      statusCode: 404,
+      providerId: "codex/work",
+    });
+    const stats = codexCredential404ReclassifiedStats();
+    expect(stats.count).toBe(1);
+    expect(stats.lastSample).toContain("revoked");
+  });
+
   test("known-xAI message-only capacity protocol error becomes retryable", () => {
     const normalized = normalizeInferenceErrorForRetry({
       category: "protocol_mismatch",