fix(agents): dispatch auth failures by type

RomneyDa · RomneyDa · commit 35eb8d9e0f56 · 2026-06-01T11:40:01.000-07:00
diff --git a/src/agents/auth-profiles/oauth-manager.ts b/src/agents/auth-profiles/oauth-manager.ts
@@ -11,6 +11,7 @@ import {
   log,
 } from "./constants.js";
 import { shouldMirrorRefreshedOAuthCredential } from "./oauth-identity.js";
+import { OAuthRefreshFailureError } from "./oauth-refresh-failure.js";
 import {
   buildRefreshContentionError,
   isGlobalRefreshLockTimeoutError,
@@ -61,9 +62,8 @@ export type ResolvedOAuthAccess = {
   credential: OAuthCredential;
 };
 
-export class OAuthManagerRefreshError extends Error {
+export class OAuthManagerRefreshError extends OAuthRefreshFailureError {
   readonly profileId: string;
-  readonly provider: string;
   readonly code?: string;
   readonly lockPath?: string;
   readonly #refreshedStore: AuthProfileStore;
@@ -91,13 +91,14 @@ export class OAuthManagerRefreshError extends Error {
       storedCredential?.type === "oauth" ? storedCredential : undefined,
     );
     const causeMessage = formatRedactedOAuthRefreshError(params.cause, secrets);
-    super(`OAuth token refresh failed for ${params.credential.provider}: ${causeMessage}`, {
+    super({
+      provider: params.credential.provider,
+      message: `OAuth token refresh failed for ${params.credential.provider}: ${causeMessage}`,
       cause: createRedactedOAuthRefreshCause(delegatedCause, secrets),
     });
     this.name = "OAuthManagerRefreshError";
     this.#credential = params.credential;
     this.profileId = params.profileId;
-    this.provider = params.credential.provider;
     this.#refreshedStore = params.refreshedStore;
     if (structuredCause) {
       this.code = typeof structuredCause.code === "string" ? structuredCause.code : undefined;
diff --git a/src/agents/auth-profiles/oauth-refresh-failure.test.ts b/src/agents/auth-profiles/oauth-refresh-failure.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it } from "vitest";
 import {
   buildOAuthRefreshFailureLoginCommand,
   classifyOAuthRefreshFailure,
+  classifyOAuthRefreshFailureError,
+  OAuthRefreshFailureError,
 } from "./oauth-refresh-failure.js";
 
 describe("oauth refresh failure hints", () => {
@@ -16,4 +18,18 @@ describe("oauth refresh failure hints", () => {
       "openclaw models auth login --provider openai",
     );
   });
+
+  it("classifies typed refresh failures without parsing the display message", () => {
+    expect(
+      classifyOAuthRefreshFailureError(
+        new OAuthRefreshFailureError({
+          provider: "openai",
+          message: "invalid_grant",
+        }),
+      ),
+    ).toEqual({
+      provider: "openai",
+      reason: "invalid_grant",
+    });
+  });
 });
diff --git a/src/agents/auth-profiles/oauth-refresh-failure.ts b/src/agents/auth-profiles/oauth-refresh-failure.ts
@@ -9,6 +9,23 @@ export type OAuthRefreshFailureReason =
   | "invalid_refresh_token"
   | "revoked";
 
+export type OAuthRefreshFailure = {
+  provider: string | null;
+  reason: OAuthRefreshFailureReason | null;
+};
+
+export class OAuthRefreshFailureError extends Error {
+  readonly provider: string;
+  readonly reason: OAuthRefreshFailureReason | null;
+
+  constructor(params: { provider: string; message: string; cause?: unknown }) {
+    super(params.message, { cause: params.cause });
+    this.name = "OAuthRefreshFailureError";
+    this.provider = params.provider;
+    this.reason = classifyOAuthRefreshFailureReason(params.message);
+  }
+}
+
 const OAUTH_REFRESH_FAILURE_PROVIDER_RE = /OAuth token refresh failed for ([^:]+):/i;
 const SAFE_PROVIDER_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
 
@@ -54,10 +71,7 @@ export function classifyOAuthRefreshFailureReason(
   return null;
 }
 
-export function classifyOAuthRefreshFailure(message: string): {
-  provider: string | null;
-  reason: OAuthRefreshFailureReason | null;
-} | null {
+export function classifyOAuthRefreshFailure(message: string): OAuthRefreshFailure | null {
   if (!isOAuthRefreshFailureMessage(message)) {
     return null;
   }
@@ -67,6 +81,16 @@ export function classifyOAuthRefreshFailure(message: string): {
   };
 }
 
+export function classifyOAuthRefreshFailureError(err: unknown): OAuthRefreshFailure | null {
+  if (!(err instanceof OAuthRefreshFailureError)) {
+    return null;
+  }
+  return {
+    provider: sanitizeOAuthRefreshFailureProvider(err.provider),
+    reason: err.reason,
+  };
+}
+
 export function buildOAuthRefreshFailureLoginCommand(provider: string | null | undefined): string {
   const sanitizedProvider = sanitizeOAuthRefreshFailureProvider(provider);
   return sanitizedProvider
diff --git a/src/agents/auth-profiles/oauth.ts b/src/agents/auth-profiles/oauth.ts
@@ -25,6 +25,7 @@ import {
   readManagedExternalCliCredential,
 } from "./external-cli-sync.js";
 import { createOAuthManager, OAuthManagerRefreshError } from "./oauth-manager.js";
+import { OAuthRefreshFailureError } from "./oauth-refresh-failure.js";
 import { assertNoOAuthSecretRefPolicyViolations } from "./policy.js";
 import { clearLastGoodProfileWithLock } from "./profiles.js";
 import { suggestOAuthProfileIdForLegacyDefault } from "./repair.js";
@@ -495,11 +496,13 @@ export async function resolveApiKeyForProfile(
       provider: cred.provider,
       profileId,
     });
-    throw new Error(
-      `OAuth token refresh failed for ${cred.provider}: ${message}. ` +
+    throw new OAuthRefreshFailureError({
+      provider: cred.provider,
+      message:
+        `OAuth token refresh failed for ${cred.provider}: ${message}. ` +
         "Please try again or re-authenticate." +
         (hint ? `\n\n${hint}` : ""),
-      { cause: error },
-    );
+      cause: error,
+    });
   }
 }
diff --git a/src/agents/embedded-agent-runner/compact.ts b/src/agents/embedded-agent-runner/compact.ts
@@ -85,8 +85,8 @@ import { resolveHeartbeatPromptForSystemPrompt } from "../heartbeat-system-promp
 import {
   applyAuthHeaderOverride,
   applyLocalNoAuthHeaderOverride,
-  formatMissingAuthError,
   getApiKeyForModel,
+  MissingProviderAuthError,
   resolveModelAuthMode,
 } from "../model-auth.js";
 import { isFallbackSummaryError, runWithModelFallback } from "../model-fallback.js";
@@ -613,7 +613,7 @@ async function compactEmbeddedAgentSessionDirectOnce(
 
     if (!apiKeyInfo.apiKey) {
       if (apiKeyInfo.mode !== "aws-sdk") {
-        throw new Error(formatMissingAuthError(apiKeyInfo, runtimeModel.provider));
+        throw new MissingProviderAuthError(runtimeModel.provider, apiKeyInfo);
       }
     } else {
       const preparedAuth = await prepareProviderRuntimeAuth({
diff --git a/src/agents/embedded-agent-runner/run/auth-controller.ts b/src/agents/embedded-agent-runner/run/auth-controller.ts
@@ -16,8 +16,8 @@ import {
 import { FailoverError, resolveFailoverStatus } from "../../failover-error.js";
 import { shouldAllowCooldownProbeForReason } from "../../failover-policy.js";
 import {
-  formatMissingAuthError,
   getApiKeyForModel,
+  MissingProviderAuthError,
   type ResolvedProviderAuth,
 } from "../../model-auth.js";
 import {
@@ -350,6 +350,7 @@ export function createEmbeddedRunAuthController(params: {
         provider,
         model: modelId,
         status: resolveFailoverStatus(reason),
+        authProfileFailure: { allInCooldown: failoverParams.allInCooldown },
         cause: failoverParams.error,
       });
     }
@@ -378,7 +379,7 @@ export function createEmbeddedRunAuthController(params: {
     if (!apiKeyInfo.apiKey) {
       if (apiKeyInfo.mode !== "aws-sdk") {
         const runtimeModel = params.getRuntimeModel();
-        throw new Error(formatMissingAuthError(apiKeyInfo, runtimeModel.provider));
+        throw new MissingProviderAuthError(runtimeModel.provider, apiKeyInfo);
       }
       // AWS SDK auth via IMDS / instance role / ECS task role: no explicit API
       // key is available but the SDK default credential chain can resolve
diff --git a/src/agents/failover-error.ts b/src/agents/failover-error.ts
@@ -23,6 +23,7 @@ export class FailoverError extends Error {
   readonly status?: number;
   readonly code?: string;
   readonly rawError?: string;
+  readonly authProfileFailure?: { allInCooldown: boolean };
   // Originating request attribution propagated through wrapper errors so
   // structured log ingestion (e.g. api_health_log) can attribute exhausted
   // failover failures back to a session/lane and the last attempted provider.
@@ -41,6 +42,7 @@ export class FailoverError extends Error {
       status?: number;
       code?: string;
       rawError?: string;
+      authProfileFailure?: { allInCooldown: boolean };
       sessionId?: string;
       lane?: string;
       cause?: unknown;
@@ -56,6 +58,7 @@ export class FailoverError extends Error {
     this.status = params.status;
     this.code = params.code;
     this.rawError = params.rawError;
+    this.authProfileFailure = params.authProfileFailure;
     this.sessionId = params.sessionId;
     this.lane = params.lane;
     this.suspend = params.suspend;
diff --git a/src/agents/model-auth-runtime-shared.ts b/src/agents/model-auth-runtime-shared.ts
@@ -26,13 +26,29 @@ export class ProviderAuthError extends Error {
   }
 }
 
+export class MissingProviderAuthError extends ProviderAuthError {
+  readonly mode: ResolvedProviderAuth["mode"];
+  readonly source: string;
+
+  constructor(provider: string, auth: ResolvedProviderAuth) {
+    super("missing-api-key", provider, formatMissingAuthError(auth, provider));
+    this.name = "MissingProviderAuthError";
+    this.mode = auth.mode;
+    this.source = auth.source;
+  }
+}
+
 export function isProviderAuthError(
   err: unknown,
   code?: ProviderAuthErrorCode,
 ): err is ProviderAuthError {
   return err instanceof ProviderAuthError && (!code || err.code === code);
 }
 
+export function isMissingProviderAuthError(err: unknown): err is MissingProviderAuthError {
+  return err instanceof MissingProviderAuthError;
+}
+
 export function resolveAwsSdkEnvVarName(env: NodeJS.ProcessEnv = process.env): string | undefined {
   if (env[AWS_BEARER_ENV]?.trim()) {
     return AWS_BEARER_ENV;
@@ -55,5 +71,5 @@ export function requireApiKey(auth: ResolvedProviderAuth, provider: string): str
   if (key) {
     return key;
   }
-  throw new ProviderAuthError("missing-api-key", provider, formatMissingAuthError(auth, provider));
+  throw new MissingProviderAuthError(provider, auth);
 }
diff --git a/src/agents/model-auth.test.ts b/src/agents/model-auth.test.ts
@@ -425,6 +425,28 @@ describe("requireApiKey", () => {
       'No API key resolved for provider "openai" (auth mode: api-key, checked: env: OPENAI_API_KEY).',
     );
   });
+
+  it("throws typed missing auth errors with source metadata", () => {
+    let thrown: unknown;
+    try {
+      requireApiKey(
+        {
+          source: "env: OPENAI_API_KEY",
+          mode: "api-key",
+        },
+        "openai",
+      );
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toMatchObject({
+      name: "MissingProviderAuthError",
+      code: "missing-api-key",
+      provider: "openai",
+      mode: "api-key",
+      source: "env: OPENAI_API_KEY",
+    });
+  });
 });
 
 describe("resolveUsableCustomProviderApiKey", () => {
diff --git a/src/agents/model-auth.ts b/src/agents/model-auth.ts
@@ -58,7 +58,9 @@ export {
 } from "./auth-profiles.js";
 export {
   formatMissingAuthError,
+  isMissingProviderAuthError,
   isProviderAuthError,
+  MissingProviderAuthError,
   ProviderAuthError,
   requireApiKey,
   resolveAwsSdkEnvVarName,
diff --git a/src/auto-reply/reply/agent-runner-execution.test.ts b/src/auto-reply/reply/agent-runner-execution.test.ts
@@ -1,5 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { OAuthRefreshFailureError } from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import { FailoverError } from "../../agents/failover-error.js";
 import { LiveSessionModelSwitchError } from "../../agents/live-model-switch-error.js";
+import { MissingProviderAuthError } from "../../agents/model-auth.js";
 import type { SessionEntry } from "../../config/sessions.js";
 import type { ModelDefinitionConfig } from "../../config/types.models.js";
 import { CommandLaneClearedError, GatewayDrainingError } from "../../process/command-queue.js";
@@ -5596,6 +5599,25 @@ describe("runAgentTurnWithFallback", () => {
     }
   });
 
+  it("surfaces gateway reauth guidance from typed OAuth refresh failures", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({
+        provider: "openai",
+        message: "invalid_grant",
+      }),
+    );
+
+    const runAgentTurnWithFallback = await getRunAgentTurnWithFallback();
+    const result = await runAgentTurnWithFallback(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Model login expired on the gateway for openai. Re-auth with `openclaw models auth login --provider openai`, then try again.",
+      );
+    }
+  });
+
   it("surfaces direct provider auth guidance for missing API keys", async () => {
     state.runEmbeddedAgentMock.mockRejectedValueOnce(
       new Error(
@@ -5635,6 +5657,47 @@ describe("runAgentTurnWithFallback", () => {
     }
   });
 
+  it("surfaces typed missing API-key auth guidance without parsing the message", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new MissingProviderAuthError("openai", {
+        mode: "api-key",
+        source: "env: OPENAI_API_KEY",
+      }),
+    );
+
+    const runAgentTurnWithFallback = await getRunAgentTurnWithFallback();
+    const result = await runAgentTurnWithFallback(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        '⚠️ Missing API key for provider "openai". Run `openclaw doctor --fix` to repair stale OpenAI model/session routes, restart the gateway if doctor asks, then try again. If doctor has nothing to repair or the error persists, re-auth with `openclaw models auth login --provider openai` or run `openclaw configure`.',
+      );
+    }
+  });
+
+  it("formats auth-profile failover copy from typed FailoverError metadata", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("Auth profile failover exhausted for provider openai", {
+        reason: "auth",
+        provider: "openai",
+        authProfileFailure: { allInCooldown: true },
+        cause: new Error("invalid_grant"),
+      }),
+    );
+
+    const runAgentTurnWithFallback = await getRunAgentTurnWithFallback();
+    const result = await runAgentTurnWithFallback(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("Couldn't sign in to openai.");
+      expect(result.payload.text).toContain("openclaw configure");
+      expect(result.payload.text).toContain("(invalid_grant)");
+      expect(result.payload.text).not.toContain("Auth profile failover exhausted");
+    }
+  });
+
   it("points stale openai missing-key failures at doctor repair with re-auth fallback", async () => {
     state.runEmbeddedAgentMock.mockRejectedValueOnce(
       new Error('No API key found for provider "openai".'),
diff --git a/src/auto-reply/reply/agent-runner-execution.ts b/src/auto-reply/reply/agent-runner-execution.ts
diff --git a/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts b/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
