@bastani/atomic 0.8.26-alpha.5 → 0.8.26-alpha.7

package/dist/builtin/workflows/src/shared/workflow-failures.ts

@@ -1,19 +1,41 @@
-import type { WorkflowFailureKind } from "./store-types.js";
+import type {
+  WorkflowFailureCode,
+  WorkflowFailureDisposition,
+  WorkflowFailureKind,
+  WorkflowFailureRecoverability,
+} from "./store-types.js";
 
 export interface WorkflowFailure {
   readonly kind: WorkflowFailureKind;
-  /** Original error text, preserved for diagnostics. */
+  /** Specific additive reason within the existing broad failure kind. */
+  readonly code?: WorkflowFailureCode;
+  /** Redacted diagnostic text safe for snapshots and persistence. */
   readonly message: string;
   /** Sanitized workflow-facing text shown on run/stage snapshots. */
   readonly userMessage: string;
   readonly retryable: boolean;
   readonly resumable: boolean;
+  readonly recoverability: WorkflowFailureRecoverability;
+  readonly disposition: WorkflowFailureDisposition;
+  readonly retryAfterMs?: number;
   readonly cause?: unknown;
 }
 
 export const WORKFLOW_AUTH_FAILURE_MESSAGE =
   "You must be logged in to run workflows. Run /login and try again.";
 
+export const WORKFLOW_MISSING_API_KEY_FAILURE_MESSAGE =
+  "A required model provider API key is missing. Configure the provider credentials and resume the workflow.";
+
+export const WORKFLOW_INVALID_PROVIDER_CREDENTIALS_MESSAGE =
+  "The configured model provider credentials are invalid. Update the provider API key, then start a new workflow run.";
+
+export const WORKFLOW_FORBIDDEN_MODEL_CONFIG_MESSAGE =
+  "The configured model provider or model is not available with the current credentials. Update the model configuration, then start a new workflow run.";
+
+export const WORKFLOW_UNKNOWN_MODEL_MESSAGE =
+  "The configured model is not available. Update the workflow model configuration, then start a new workflow run.";
+
 const WORKFLOW_FAILURE_KINDS: ReadonlySet<WorkflowFailureKind> = new Set([
   "auth",
   "rate_limit",
@@ -26,22 +48,56 @@ export function isWorkflowFailureKind(kind: string): kind is WorkflowFailureKind
   return WORKFLOW_FAILURE_KINDS.has(kind as WorkflowFailureKind);
 }
 
+export function isWorkflowFailureCode(code: string): code is WorkflowFailureCode {
+  switch (code) {
+    case "login_required":
+    case "missing_api_key":
+    case "invalid_api_key":
+    case "forbidden_config":
+    case "unknown_model":
+    case "rate_limited":
+    case "quota_limited":
+    case "provider_unavailable":
+    case "cancelled":
+    case "unknown":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function isWorkflowFailureRecoverability(value: string): value is WorkflowFailureRecoverability {
+  return value === "recoverable" || value === "non_recoverable" || value === "unknown";
+}
+
+export function isWorkflowFailureDisposition(value: string): value is WorkflowFailureDisposition {
+  return value === "active_blocked" || value === "terminal_killed" || value === "terminal_failed";
+}
+
 function makeWorkflowFailure(
   kind: WorkflowFailureKind,
   message: string,
   opts: {
     readonly retryable: boolean;
     readonly resumable: boolean;
+    readonly recoverability: WorkflowFailureRecoverability;
+    readonly disposition: WorkflowFailureDisposition;
     readonly cause: unknown;
+    readonly code?: WorkflowFailureCode;
+    readonly retryAfterMs?: number;
     readonly userMessage?: string;
   },
 ): WorkflowFailure {
   return {
     kind,
+    ...(opts.code !== undefined ? { code: opts.code } : {}),
     message,
-    userMessage: opts.userMessage ?? message,
+    userMessage: opts.userMessage ?? redactSensitiveText(message),
     retryable: opts.retryable,
     resumable: opts.resumable,
+    recoverability: opts.recoverability,
+    disposition: opts.disposition,
+    ...(opts.retryAfterMs !== undefined ? { retryAfterMs: opts.retryAfterMs } : {}),
     cause: opts.cause,
   };
 }
@@ -82,6 +138,35 @@ type StructuredSignal = {
   readonly code?: string | number;
   readonly name?: string;
   readonly stopReason?: string;
+  readonly message?: string;
+  readonly retryAfterMs?: number;
+};
+
+type WorkflowFailureDecision = {
+  readonly kind: WorkflowFailureKind;
+  readonly code: WorkflowFailureCode;
+  readonly retryable: boolean;
+  readonly resumable: boolean;
+  readonly recoverability: WorkflowFailureRecoverability;
+  readonly disposition: WorkflowFailureDisposition;
+  readonly userMessage?: string;
+  readonly retryAfterMs?: number;
+};
+
+type WorkflowFailureClassificationSource =
+  | "top_level"
+  | "diagnostic"
+  | "nested"
+  | "cause"
+  | "aggregate";
+
+type WorkflowFailureEvidence = "strong_signal" | "weak_signal" | "message" | "status";
+
+type WorkflowFailureClassification = {
+  readonly decision: WorkflowFailureDecision;
+  readonly source: WorkflowFailureClassificationSource;
+  readonly evidence: WorkflowFailureEvidence;
+  readonly message?: string;
 };
 
 function integerFrom(value: unknown): number | undefined {
@@ -91,17 +176,61 @@ function integerFrom(value: unknown): number | undefined {
   return Number.isInteger(parsed) ? parsed : undefined;
 }
 
+function numberFrom(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "string" || value.trim().length === 0) return undefined;
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function retryAfterHeaderMs(value: unknown): number | undefined {
+  const numeric = numberFrom(value);
+  if (numeric !== undefined && numeric >= 0) return Math.round(numeric * 1000);
+  if (typeof value !== "string" || value.trim().length === 0) return undefined;
+  const dateMs = Date.parse(value);
+  if (!Number.isFinite(dateMs)) return undefined;
+  return Math.max(0, dateMs - Date.now());
+}
+
+function retryAfterMsFrom(error: unknown): number | undefined {
+  const directMs = numberFrom(field(error, "retryAfterMs"));
+  if (directMs !== undefined && directMs >= 0) return Math.round(directMs);
+
+  const seconds = numberFrom(field(error, "retryAfterSeconds"));
+  if (seconds !== undefined && seconds >= 0) return Math.round(seconds * 1000);
+
+  // Provider SDKs commonly mirror the HTTP Retry-After header as retryAfter,
+  // so the ambiguous bare field follows header semantics (seconds/date). Use
+  // retryAfterMs for explicit millisecond values.
+  const retryAfter = retryAfterHeaderMs(field(error, "retryAfter"));
+  if (retryAfter !== undefined) return retryAfter;
+
+  const retryAfterHeader = retryAfterHeaderMs(field(error, "retry-after"));
+  if (retryAfterHeader !== undefined) return retryAfterHeader;
+
+  const headers = field(error, "headers");
+  const headerRecord = asRecord(headers);
+  const headerValue = headerRecord?.["retry-after"] ?? headerRecord?.["Retry-After"];
+  return retryAfterHeaderMs(headerValue);
+}
+
 function structuredSignal(error: unknown): StructuredSignal {
   const status = integerFrom(field(error, "status"))
     ?? integerFrom(field(error, "statusCode"))
     ?? integerFrom(field(error, "httpStatus"));
   const rawCode = field(error, "code");
   const code = typeof rawCode === "string" || typeof rawCode === "number" ? rawCode : undefined;
+  const name = errorName(error);
+  const stopReason = stringField(error, "stopReason");
+  const message = structuredErrorMessage(error);
+  const retryAfterMs = retryAfterMsFrom(error);
   return {
     ...(status !== undefined ? { status } : {}),
     ...(code !== undefined ? { code } : {}),
-    ...(errorName(error) !== undefined ? { name: errorName(error)! } : {}),
-    ...(stringField(error, "stopReason") !== undefined ? { stopReason: stringField(error, "stopReason")! } : {}),
+    ...(name !== undefined ? { name } : {}),
+    ...(stopReason !== undefined ? { stopReason } : {}),
+    ...(message !== undefined ? { message } : {}),
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
   };
 }
 
@@ -121,121 +250,38 @@ function diagnosticErrors(error: unknown): readonly unknown[] {
   return errors;
 }
 
+function nestedProviderError(error: unknown): unknown {
+  return field(error, "error") ?? field(error, "response") ?? field(error, "body");
+}
+
 function normalizeCode(value: string | number | undefined): string | undefined {
   if (value === undefined) return undefined;
-  return String(value).trim().toLowerCase().replaceAll("-", "_");
+  return String(value).trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
 }
 
-function kindFromStatus(status: number | undefined): WorkflowFailureKind | undefined {
-  switch (status) {
-    case 401:
-    case 403:
-      return "auth";
-    case 429:
-      return "rate_limit";
-    case 500:
-    case 502:
-    case 503:
-    case 504:
-      return "provider";
-    default:
-      return undefined;
-  }
-}
+type StructuredCodeEvidence =
+  | { readonly kind: "semantic_code"; readonly normalized: string }
+  | { readonly kind: "wrapper_http_status"; readonly status: number };
 
-function kindFromCode(code: string | number | undefined): WorkflowFailureKind | undefined {
-  const normalized = normalizeCode(code);
-  switch (normalized) {
-    case undefined:
-      return undefined;
-    case "401":
-    case "403":
-    case "auth":
-    case "auth_required":
-    case "authentication_required":
-    case "unauthorized":
-    case "forbidden":
-    case "invalid_api_key":
-    case "missing_api_key":
-      return "auth";
-    case "429":
-    case "rate_limit":
-    case "rate_limit_exceeded":
-    case "too_many_requests":
-    case "quota_exceeded":
-      return "rate_limit";
-    case "aborterror":
-    case "aborted":
-    case "cancelled":
-    case "canceled":
-      return "cancelled";
-    case "500":
-    case "502":
-    case "503":
-    case "504":
-    case "provider_error":
-    case "service_unavailable":
-    case "temporarily_unavailable":
-    case "overloaded":
-      return "provider";
-    default:
-      return undefined;
+function httpStatusFromCode(value: string | number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "number") {
+    return Number.isInteger(value) && value >= 100 && value <= 599 ? value : undefined;
   }
+  const trimmed = value.trim();
+  if (!/^\d{3}$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  return parsed >= 100 && parsed <= 599 ? parsed : undefined;
 }
 
-function structuredKind(error: unknown, seen = new Set<unknown>()): WorkflowFailureKind | undefined {
-  if (error === undefined || error === null || seen.has(error)) return undefined;
-  if (typeof error === "object") seen.add(error);
-
-  const signal = structuredSignal(error);
-  if (signal.stopReason?.toLowerCase() === "aborted") return "cancelled";
-  const statusKind = kindFromStatus(signal.status);
-  if (statusKind !== undefined) return statusKind;
-  const codeKind = kindFromCode(signal.code) ?? kindFromCode(signal.name);
-  if (codeKind !== undefined) return codeKind;
-
-  for (const diagnosticError of diagnosticErrors(error)) {
-    const diagnosticKind = structuredKind(diagnosticError, seen);
-    if (diagnosticKind !== undefined) return diagnosticKind;
-  }
+function codeEvidenceFrom(value: string | number | undefined): StructuredCodeEvidence | undefined {
+  const status = httpStatusFromCode(value);
+  if (status !== undefined) return { kind: "wrapper_http_status", status };
 
-  return structuredKind(causeOf(error), seen);
-}
-
-function failureForKind(kind: WorkflowFailureKind, message: string, cause: unknown): WorkflowFailure {
-  switch (kind) {
-    case "auth":
-      return makeWorkflowFailure("auth", message, {
-        userMessage: WORKFLOW_AUTH_FAILURE_MESSAGE,
-        retryable: true,
-        resumable: true,
-        cause,
-      });
-    case "rate_limit":
-      return makeWorkflowFailure("rate_limit", message, {
-        retryable: true,
-        resumable: true,
-        cause,
-      });
-    case "cancelled":
-      return makeWorkflowFailure("cancelled", message, {
-        retryable: false,
-        resumable: false,
-        cause,
-      });
-    case "provider":
-      return makeWorkflowFailure("provider", message, {
-        retryable: true,
-        resumable: true,
-        cause,
-      });
-    case "unknown":
-      return makeWorkflowFailure("unknown", message, {
-        retryable: false,
-        resumable: true,
-        cause,
-      });
-  }
+  const normalized = normalizeCode(value);
+  return normalized !== undefined && normalized.length > 0
+    ? { kind: "semantic_code", normalized }
+    : undefined;
 }
 
 type TokenMatch = readonly string[];
@@ -286,24 +332,141 @@ function tokenNearAny(tokens: readonly string[], anchor: string, candidates: Rea
   return false;
 }
 
-const AUTH_PHRASES: readonly TokenMatch[] = [
-  ["no", "api", "key"],
-  ["api", "key", "not", "found"],
-  ["missing", "api", "key"],
-  ["no", "model", "selected"],
-  ["no", "models", "available"],
+const INVALID_API_KEY_CODES = new Set([
+  "401",
+  "invalid_api_key",
+  "incorrect_api_key",
+  "invalid_api_key_error",
+  "invalid_credentials",
+  "bad_credentials",
+  "authentication_error",
+]);
+
+const LOGIN_REQUIRED_CODES = new Set([
+  "auth",
+  "auth_required",
+  "authentication_required",
+  "login_required",
+  "not_logged_in",
+]);
+
+const MISSING_API_KEY_CODES = new Set([
+  "missing_api_key",
+  "api_key_missing",
+  "no_api_key",
+]);
+
+const RATE_LIMIT_CODES = new Set([
+  "429",
+  "rate_limit",
+  "rate_limited",
+  "rate_limit_exceeded",
+  "too_many_requests",
+]);
+
+const QUOTA_LIMIT_CODES = new Set([
+  "quota",
+  "quota_exceeded",
+  "insufficient_quota",
+  "usage_limit",
+  "usage_limit_exceeded",
+]);
+
+const CANCELLED_CODES = new Set([
+  "aborterror",
+  "aborted",
+  "cancelled",
+  "canceled",
+]);
+
+const PROVIDER_UNAVAILABLE_CODES = new Set([
+  "500",
+  "502",
+  "503",
+  "504",
+  "provider_error",
+  "service_unavailable",
+  "temporarily_unavailable",
+  "overloaded",
+  "timeout",
+  "network_error",
+]);
+
+const UNKNOWN_MODEL_CODES = new Set([
+  "unknown_model",
+  "model_not_found",
+  "model_not_available",
+  "unsupported_model",
+]);
+
+const FORBIDDEN_CONFIG_CODES = new Set([
+  "403",
+  "forbidden",
+  "permission_denied",
+  "access_denied",
+  "forbidden_config",
+  "invalid_model_config",
+  "model_access_denied",
+]);
+
+const LOGIN_REQUIRED_PHRASES: readonly TokenMatch[] = [
   ["not", "logged", "in"],
   ["log", "in"],
   ["login", "required"],
   ["authentication", "required"],
+  ["please", "login"],
+  ["please", "log", "in"],
   ["unauthorized"],
 ];
 
+const LOCAL_LOGIN_REQUIRED_PHRASES: readonly TokenMatch[] = [
+  ["not", "logged", "in"],
+  ["login", "required"],
+  ["please", "login"],
+  ["please", "log", "in"],
+  ["log", "in", "to", "continue"],
+];
+
+const PROVIDER_AUTH_FALLBACK_PHRASES: readonly TokenMatch[] = [
+  ["unauthorized"],
+  ["authentication", "required"],
+];
+
+const MISSING_API_KEY_PHRASES: readonly TokenMatch[] = [
+  ["no", "api", "key"],
+  ["api", "key", "not", "found"],
+  ["missing", "api", "key"],
+  ["api", "key", "missing"],
+  ["no", "model", "selected"],
+  ["no", "models", "available"],
+];
+
+const INVALID_API_KEY_PHRASES: readonly TokenMatch[] = [
+  ["incorrect", "api", "key"],
+  ["invalid", "api", "key"],
+  ["api", "key", "invalid"],
+  ["api", "key", "incorrect"],
+  ["invalid", "credentials"],
+  ["invalid", "credential"],
+];
+
+const INVALID_API_KEY_CONTEXT = new Set(["invalid", "incorrect"]);
+
+const HTTP_RATE_LIMIT_PHRASES: readonly TokenMatch[] = [
+  ["429"],
+  ["too", "many", "requests"],
+];
+
 const RATE_LIMIT_PHRASES: readonly TokenMatch[] = [
   ["rate", "limit"],
-  ["429"],
+  ["rate", "limited"],
+];
+
+const QUOTA_LIMIT_PHRASES: readonly TokenMatch[] = [
   ["quota"],
-  ["too", "many", "requests"],
+  ["quota", "exceeded"],
+  ["insufficient", "quota"],
+  ["usage", "limit"],
 ];
 
 const CANCELLED_PHRASES: readonly TokenMatch[] = [
@@ -312,11 +475,30 @@ const CANCELLED_PHRASES: readonly TokenMatch[] = [
   ["canceled"],
 ];
 
-const PROVIDER_PHRASES: readonly TokenMatch[] = [
+const UNKNOWN_MODEL_PHRASES: readonly TokenMatch[] = [
   ["model", "not", "found"],
+  ["unknown", "model"],
+  ["unsupported", "model"],
+  ["model", "does", "not", "exist"],
+  ["model", "not", "available"],
+];
+
+const FORBIDDEN_CONFIG_PHRASES: readonly TokenMatch[] = [
+  ["forbidden", "config"],
+  ["forbidden", "configuration"],
+  ["permission", "denied"],
+  ["access", "denied"],
+  ["not", "allowed", "to", "access", "model"],
+  ["does", "not", "have", "access", "to", "model"],
+];
+
+const PROVIDER_UNAVAILABLE_PHRASES: readonly TokenMatch[] = [
   ["overloaded"],
   ["temporarily", "unavailable"],
   ["service", "unavailable"],
+  ["provider", "unavailable"],
+  ["provider", "error"],
+  ["model", "unavailable"],
   ["503"],
 ];
 
@@ -350,26 +532,470 @@ const PROVIDER_CONTEXT = new Set([
   "service",
 ]);
 
-function fallbackKindFromMessage(message: string, name: string | undefined): WorkflowFailureKind | undefined {
-  const tokens = tokenize(message);
-  if (hasAnyPhrase(tokens, AUTH_PHRASES) || tokenNearAny(tokens, "oauth", AUTH_CONTEXT, 8)) return "auth";
-  if (hasAnyPhrase(tokens, RATE_LIMIT_PHRASES)) return "rate_limit";
-  if (name?.toLowerCase() === "aborterror" || hasAnyPhrase(tokens, CANCELLED_PHRASES)) return "cancelled";
+function redactedSecretReplacement(prefix: string): string {
+  return `${prefix}[redacted]`;
+}
+
+function redactSensitiveText(value: string): string {
+  return value
+    .replace(/(sk-[A-Za-z0-9_-]{8})[A-Za-z0-9_-]+/g, redactedSecretReplacement("$1"))
+    .replace(/\b(authorization\s*:\s*bearer\s+)[^\s,;]+/gi, "$1[redacted]")
+    .replace(/\b(bearer\s+)[A-Za-z0-9._~+/-]{8,}=*/gi, "$1[redacted]")
+    .replace(/((?:api[_-]?key|token|credential|secret)\s*[:=]\s*)[^\s,;]+/gi, "$1[redacted]");
+}
+
+function authDecision(code: WorkflowFailureCode): WorkflowFailureDecision {
+  if (code === "invalid_api_key") {
+    return {
+      kind: "auth",
+      code,
+      retryable: false,
+      resumable: false,
+      recoverability: "non_recoverable",
+      disposition: "terminal_killed",
+      userMessage: WORKFLOW_INVALID_PROVIDER_CREDENTIALS_MESSAGE,
+    };
+  }
+  if (code === "missing_api_key") {
+    return {
+      kind: "auth",
+      code,
+      retryable: true,
+      resumable: true,
+      recoverability: "recoverable",
+      disposition: "active_blocked",
+      userMessage: WORKFLOW_MISSING_API_KEY_FAILURE_MESSAGE,
+    };
+  }
+  return {
+    kind: "auth",
+    code: "login_required",
+    retryable: true,
+    resumable: true,
+    recoverability: "recoverable",
+    disposition: "active_blocked",
+    userMessage: WORKFLOW_AUTH_FAILURE_MESSAGE,
+  };
+}
+
+function rateLimitDecision(
+  code: "rate_limited" | "quota_limited",
+  retryAfterMs?: number,
+): WorkflowFailureDecision {
+  return {
+    kind: "rate_limit",
+    code,
+    retryable: true,
+    resumable: true,
+    recoverability: "recoverable",
+    disposition: "active_blocked",
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+  };
+}
+
+function providerUnavailableDecision(retryAfterMs?: number): WorkflowFailureDecision {
+  return {
+    kind: "provider",
+    code: "provider_unavailable",
+    retryable: true,
+    resumable: true,
+    recoverability: "recoverable",
+    disposition: "active_blocked",
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+  };
+}
+
+function terminalProviderConfigDecision(code: "forbidden_config" | "unknown_model"): WorkflowFailureDecision {
+  return {
+    kind: "provider",
+    code,
+    retryable: false,
+    resumable: false,
+    recoverability: "non_recoverable",
+    disposition: "terminal_killed",
+    userMessage: code === "unknown_model" ? WORKFLOW_UNKNOWN_MODEL_MESSAGE : WORKFLOW_FORBIDDEN_MODEL_CONFIG_MESSAGE,
+  };
+}
+
+function cancelledDecision(): WorkflowFailureDecision {
+  return {
+    kind: "cancelled",
+    code: "cancelled",
+    retryable: false,
+    resumable: false,
+    recoverability: "non_recoverable",
+    disposition: "terminal_killed",
+  };
+}
+
+function unknownDecision(): WorkflowFailureDecision {
+  return {
+    kind: "unknown",
+    code: "unknown",
+    retryable: false,
+    resumable: true,
+    recoverability: "unknown",
+    disposition: "terminal_failed",
+  };
+}
+
+function strongDecisionFromNormalizedCode(normalized: string | undefined, retryAfterMs?: number): WorkflowFailureDecision | undefined {
+  if (normalized === undefined) return undefined;
+  if (CANCELLED_CODES.has(normalized)) return cancelledDecision();
+  if (INVALID_API_KEY_CODES.has(normalized)) return authDecision("invalid_api_key");
+  if (MISSING_API_KEY_CODES.has(normalized)) return authDecision("missing_api_key");
+  if (RATE_LIMIT_CODES.has(normalized)) return rateLimitDecision("rate_limited", retryAfterMs);
+  if (QUOTA_LIMIT_CODES.has(normalized)) return rateLimitDecision("quota_limited", retryAfterMs);
+  if (UNKNOWN_MODEL_CODES.has(normalized)) return terminalProviderConfigDecision("unknown_model");
+  if (FORBIDDEN_CONFIG_CODES.has(normalized)) return terminalProviderConfigDecision("forbidden_config");
+  if (PROVIDER_UNAVAILABLE_CODES.has(normalized)) return providerUnavailableDecision(retryAfterMs);
+  return undefined;
+}
+
+function weakLoginDecisionFromNormalizedCode(normalized: string | undefined): WorkflowFailureDecision | undefined {
+  return normalized !== undefined && LOGIN_REQUIRED_CODES.has(normalized)
+    ? authDecision("login_required")
+    : undefined;
+}
+
+function classificationForDecision(
+  decision: WorkflowFailureDecision,
+  source: WorkflowFailureClassificationSource,
+  message: string | undefined,
+  evidence: WorkflowFailureEvidence = "message",
+): WorkflowFailureClassification {
+  return {
+    decision,
+    source,
+    evidence,
+    ...(message !== undefined ? { message } : {}),
+  };
+}
+
+function hasInvalidApiKeyMessage(tokens: readonly string[]): boolean {
+  return hasAnyPhrase(tokens, INVALID_API_KEY_PHRASES)
+    || (hasPhrase(tokens, ["api", "key"]) && tokenNearAny(tokens, "key", INVALID_API_KEY_CONTEXT, 6));
+}
+
+function decisionFromMessageTokens(tokens: readonly string[], name: string | undefined, retryAfterMs?: number): WorkflowFailureDecision | undefined {
+  if (name?.toLowerCase() === "aborterror" || hasAnyPhrase(tokens, CANCELLED_PHRASES)) return cancelledDecision();
+  if (hasAnyPhrase(tokens, HTTP_RATE_LIMIT_PHRASES)) return rateLimitDecision("rate_limited", retryAfterMs);
+  if (hasAnyPhrase(tokens, QUOTA_LIMIT_PHRASES)) return rateLimitDecision("quota_limited", retryAfterMs);
+  if (hasAnyPhrase(tokens, RATE_LIMIT_PHRASES)) return rateLimitDecision("rate_limited", retryAfterMs);
+  if (hasInvalidApiKeyMessage(tokens)) return authDecision("invalid_api_key");
+  if (hasAnyPhrase(tokens, MISSING_API_KEY_PHRASES)) return authDecision("missing_api_key");
+  if (hasAnyPhrase(tokens, LOGIN_REQUIRED_PHRASES) || tokenNearAny(tokens, "oauth", AUTH_CONTEXT, 8)) return authDecision("login_required");
+  if (hasAnyPhrase(tokens, UNKNOWN_MODEL_PHRASES)) return terminalProviderConfigDecision("unknown_model");
+  if (hasAnyPhrase(tokens, FORBIDDEN_CONFIG_PHRASES)) return terminalProviderConfigDecision("forbidden_config");
   if (
-    hasAnyPhrase(tokens, PROVIDER_PHRASES)
+    hasAnyPhrase(tokens, PROVIDER_UNAVAILABLE_PHRASES)
     || tokenNearAny(tokens, "model", MODEL_PROVIDER_CONTEXT, 8)
     || tokenNearAny(tokens, "provider", PROVIDER_CONTEXT, 8)
-  ) return "provider";
+  ) return providerUnavailableDecision(retryAfterMs);
   return undefined;
 }
 
+function decisionFromStatus(status: number | undefined, retryAfterMs: number | undefined): WorkflowFailureDecision | undefined {
+  switch (status) {
+    case 401:
+      return authDecision("invalid_api_key");
+    case 403:
+      return terminalProviderConfigDecision("forbidden_config");
+    case 429:
+      return rateLimitDecision("rate_limited", retryAfterMs);
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return providerUnavailableDecision(retryAfterMs);
+    default:
+      return undefined;
+  }
+}
+
+const STATUS_MESSAGE_REFINEMENT_CODES: ReadonlySet<WorkflowFailureCode> = new Set([
+  "invalid_api_key",
+  "missing_api_key",
+  "unknown_model",
+  "forbidden_config",
+]);
+
+const BROAD_AUTH_MESSAGE_REFINEMENT_CODES: ReadonlySet<WorkflowFailureCode> = new Set([
+  "invalid_api_key",
+  "missing_api_key",
+]);
+
+const STATUS_RELATED_MESSAGE_REFINEMENT_CODES: ReadonlySet<WorkflowFailureCode> = new Set([
+  "invalid_api_key",
+  "missing_api_key",
+  "unknown_model",
+  "forbidden_config",
+  "rate_limited",
+  "quota_limited",
+  "cancelled",
+]);
+
+function isRecoverableActiveBlocked(classification: WorkflowFailureClassification): boolean {
+  return classification.decision.disposition === "active_blocked"
+    && classification.decision.recoverability === "recoverable";
+}
+
+function canUseRelatedClassificationBeforeStatus(classification: WorkflowFailureClassification): boolean {
+  if (classification.evidence === "weak_signal") return false;
+  if (classification.evidence === "message") {
+    return STATUS_RELATED_MESSAGE_REFINEMENT_CODES.has(classification.decision.code);
+  }
+  return classification.decision.code !== "login_required";
+}
+
+function isClearLocalLoginMessage(message: string, tokens: readonly string[] = tokenize(message)): boolean {
+  if (message.toLowerCase().includes("/login")) return true;
+  return hasAnyPhrase(tokens, LOCAL_LOGIN_REQUIRED_PHRASES);
+}
+
+function hasFallbackApiError401(tokens: readonly string[]): boolean {
+  return hasPhrase(tokens, ["401"]) && hasPhrase(tokens, ["api", "error"]);
+}
+
+function classifyFallbackProviderAuthMessage(message: string, tokens: readonly string[]): WorkflowFailureDecision | undefined {
+  if (isClearLocalLoginMessage(message, tokens)) return undefined;
+  return hasAnyPhrase(tokens, PROVIDER_AUTH_FALLBACK_PHRASES) || hasFallbackApiError401(tokens)
+    ? authDecision("invalid_api_key")
+    : undefined;
+}
+
+function canUseLoginClassificationBeforeWrapper401(
+  classification: WorkflowFailureClassification | undefined,
+): classification is WorkflowFailureClassification {
+  if (classification === undefined || classification.decision.code !== "login_required") return false;
+  return classification.evidence === "weak_signal"
+    || classification.evidence === "strong_signal"
+    || (classification.message !== undefined && isClearLocalLoginMessage(classification.message));
+}
+
+function classificationFromNormalizedCode(
+  normalized: string | undefined,
+  retryAfterMs: number | undefined,
+  source: WorkflowFailureClassificationSource,
+  message: string | undefined,
+): { readonly strong?: WorkflowFailureClassification; readonly weak?: WorkflowFailureClassification } {
+  const strong = strongDecisionFromNormalizedCode(normalized, retryAfterMs);
+  if (strong !== undefined) {
+    return { strong: classificationForDecision(strong, source, message, "strong_signal") };
+  }
+  const weak = weakLoginDecisionFromNormalizedCode(normalized);
+  return weak !== undefined
+    ? { weak: classificationForDecision(weak, source, message, "weak_signal") }
+    : {};
+}
+
+function aggregateErrorItems(error: unknown): readonly unknown[] {
+  const nativeErrors = error instanceof AggregateError ? error.errors as unknown : undefined;
+  const errors = nativeErrors ?? field(error, "errors");
+  return Array.isArray(errors) ? errors : [];
+}
+
+function fallbackAggregateClassification(innerError: unknown): WorkflowFailureClassification {
+  const message = errorMessage(innerError);
+  const fallback = fallbackDecisionFromMessage(message, errorName(innerError));
+  return classificationForDecision(fallback ?? unknownDecision(), "aggregate", message);
+}
+
+function recoverableBlockedClassification(classifications: readonly WorkflowFailureClassification[]): WorkflowFailureClassification {
+  return classifications.find((classification) => classification.decision.retryAfterMs !== undefined)
+    ?? classifications[0]!;
+}
+
+function aggregateClassification(error: unknown, seen: Set<unknown>): WorkflowFailureClassification | undefined {
+  const innerErrors = aggregateErrorItems(error);
+  if (innerErrors.length === 0) return undefined;
+
+  const classifications = innerErrors.map((innerError) => {
+    const branchSeen = new Set(seen);
+    return structuredClassification(innerError, "aggregate", branchSeen) ?? fallbackAggregateClassification(innerError);
+  });
+
+  const terminalKilled = classifications.find(
+    (classification) => classification.decision.disposition === "terminal_killed",
+  );
+  if (terminalKilled !== undefined) return terminalKilled;
+
+  const allRecoverableBlocked = classifications.every(isRecoverableActiveBlocked);
+  if (allRecoverableBlocked) return recoverableBlockedClassification(classifications);
+
+  return classificationForDecision(unknownDecision(), "aggregate", errorMessage(error));
+}
+
+function selectDiagnosticFailureClassification(
+  diagnostics: readonly unknown[],
+  seen: ReadonlySet<unknown>,
+): WorkflowFailureClassification | undefined {
+  const classifications: WorkflowFailureClassification[] = [];
+  for (const diagnosticError of diagnostics) {
+    const diagnosticSeen = new Set(seen);
+    const diagnosticClassification = structuredClassification(diagnosticError, "diagnostic", diagnosticSeen);
+    if (diagnosticClassification !== undefined) classifications.push(diagnosticClassification);
+  }
+  if (classifications.length === 0) return undefined;
+
+  const terminalKilled = classifications.find(
+    (classification) => classification.decision.disposition === "terminal_killed",
+  );
+  if (terminalKilled !== undefined) return terminalKilled;
+
+  const terminalFailed = classifications.find(
+    (classification) => classification.decision.disposition === "terminal_failed",
+  );
+  if (terminalFailed !== undefined) return terminalFailed;
+
+  const allRecoverableBlocked = classifications.every(isRecoverableActiveBlocked);
+  if (allRecoverableBlocked) return recoverableBlockedClassification(classifications);
+
+  return classifications[0]!;
+}
+
+function relatedStructuredClassification(error: unknown, seen: Set<unknown>): WorkflowFailureClassification | undefined {
+  const diagnosticClassification = selectDiagnosticFailureClassification(diagnosticErrors(error), seen);
+  if (diagnosticClassification !== undefined) return diagnosticClassification;
+
+  const nested = nestedProviderError(error);
+  if (nested !== undefined && nested !== error) {
+    const nestedClassification = structuredClassification(nested, "nested", seen);
+    if (nestedClassification !== undefined) return nestedClassification;
+  }
+
+  const causeClassification = structuredClassification(causeOf(error), "cause", seen);
+  if (causeClassification !== undefined) return causeClassification;
+
+  return aggregateClassification(error, seen);
+}
+
+function structuredClassification(
+  error: unknown,
+  source: WorkflowFailureClassificationSource = "top_level",
+  seen = new Set<unknown>(),
+): WorkflowFailureClassification | undefined {
+  if (error === undefined || error === null || seen.has(error)) return undefined;
+  if (typeof error === "object") seen.add(error);
+
+  const signal = structuredSignal(error);
+  const signalMessage = signal.message ?? (typeof error === "string" ? error : undefined);
+  if (signal.stopReason?.toLowerCase() === "aborted") {
+    return classificationForDecision(cancelledDecision(), source, signalMessage, "strong_signal");
+  }
+
+  const retryAfterMs = signal.retryAfterMs;
+  let weakClassification: WorkflowFailureClassification | undefined;
+
+  const codeEvidence = codeEvidenceFrom(signal.code);
+  if (codeEvidence?.kind === "semantic_code") {
+    const codeClassification = classificationFromNormalizedCode(codeEvidence.normalized, retryAfterMs, source, signalMessage);
+    if (codeClassification.strong !== undefined) return codeClassification.strong;
+    weakClassification = codeClassification.weak ?? weakClassification;
+  }
+
+  const nameClassification = classificationFromNormalizedCode(normalizeCode(signal.name), retryAfterMs, source, signalMessage);
+  if (nameClassification.strong !== undefined) return nameClassification.strong;
+  weakClassification = nameClassification.weak ?? weakClassification;
+
+  const messageTokens = signalMessage !== undefined ? tokenize(signalMessage) : undefined;
+  const messageDecision = messageTokens !== undefined
+    ? decisionFromMessageTokens(messageTokens, signal.name, retryAfterMs)
+    : undefined;
+  const providerAuthMessageDecision = signalMessage !== undefined && messageTokens !== undefined
+    ? classifyFallbackProviderAuthMessage(signalMessage, messageTokens)
+    : undefined;
+  if (
+    weakClassification !== undefined &&
+    messageDecision !== undefined &&
+    BROAD_AUTH_MESSAGE_REFINEMENT_CODES.has(messageDecision.code)
+  ) {
+    return classificationForDecision(messageDecision, source, signalMessage);
+  }
+
+  const relatedClassification = relatedStructuredClassification(error, seen);
+  const effectiveStatus = signal.status ?? (codeEvidence?.kind === "wrapper_http_status" ? codeEvidence.status : undefined);
+  const statusDecision = decisionFromStatus(effectiveStatus, retryAfterMs);
+  if (statusDecision !== undefined) {
+    if (relatedClassification !== undefined && canUseRelatedClassificationBeforeStatus(relatedClassification)) {
+      return relatedClassification;
+    }
+    if (
+      signalMessage !== undefined &&
+      (effectiveStatus === 401 || effectiveStatus === 403) &&
+      messageDecision !== undefined &&
+      STATUS_MESSAGE_REFINEMENT_CODES.has(messageDecision.code)
+    ) {
+      return classificationForDecision(messageDecision, source, signalMessage);
+    }
+    if (effectiveStatus === 401) {
+      if (canUseLoginClassificationBeforeWrapper401(relatedClassification)) {
+        return relatedClassification;
+      }
+      if (canUseLoginClassificationBeforeWrapper401(weakClassification)) {
+        return weakClassification;
+      }
+      if (signalMessage !== undefined && isClearLocalLoginMessage(signalMessage)) {
+        return classificationForDecision(authDecision("login_required"), source, signalMessage);
+      }
+    }
+    return classificationForDecision(statusDecision, source, signalMessage, "status");
+  }
+
+  if (source !== "top_level") {
+    if (
+      providerAuthMessageDecision !== undefined &&
+      (messageDecision === undefined || messageDecision.code === "login_required")
+    ) {
+      return classificationForDecision(providerAuthMessageDecision, source, signalMessage);
+    }
+    if (messageDecision !== undefined) {
+      return classificationForDecision(messageDecision, source, signalMessage);
+    }
+  }
+
+  if (relatedClassification !== undefined) return relatedClassification;
+
+  return weakClassification;
+}
+
+function fallbackDecisionFromMessage(message: string, name: string | undefined): WorkflowFailureDecision | undefined {
+  const tokens = tokenize(message);
+  const decision = decisionFromMessageTokens(tokens, name);
+  const providerAuthDecision = classifyFallbackProviderAuthMessage(message, tokens);
+  if (providerAuthDecision !== undefined && (decision === undefined || decision.code === "login_required")) {
+    return providerAuthDecision;
+  }
+  if (decision === undefined && isClearLocalLoginMessage(message, tokens)) {
+    return authDecision("login_required");
+  }
+  return decision;
+}
+
+function failureForDecision(decision: WorkflowFailureDecision, message: string, cause: unknown): WorkflowFailure {
+  const safeMessage = redactSensitiveText(message);
+  return makeWorkflowFailure(decision.kind, safeMessage, {
+    code: decision.code,
+    retryable: decision.retryable,
+    resumable: decision.resumable,
+    recoverability: decision.recoverability,
+    disposition: decision.disposition,
+    cause,
+    ...(decision.userMessage !== undefined ? { userMessage: decision.userMessage } : {}),
+    ...(decision.retryAfterMs !== undefined ? { retryAfterMs: decision.retryAfterMs } : {}),
+  });
+}
+
 export function classifyWorkflowFailure(error: unknown): WorkflowFailure {
   const message = errorMessage(error);
-  const structured = structuredKind(error);
-  if (structured !== undefined) return failureForKind(structured, message, error);
+  const structured = structuredClassification(error);
+  if (structured !== undefined) {
+    const structuredMessage = structured.message ?? message;
+    return failureForDecision(structured.decision, structuredMessage, error);
+  }
 
-  const fallback = fallbackKindFromMessage(message, errorName(error));
-  if (fallback !== undefined) return failureForKind(fallback, message, error);
+  const fallback = fallbackDecisionFromMessage(message, errorName(error));
+  if (fallback !== undefined) return failureForDecision(fallback, message, error);
 
-  return failureForKind("unknown", message, error);
+  return failureForDecision(unknownDecision(), message, error);
 }