refactor(agents): centralize failover normalization

src/agents/failover-error.ts

@@ -1,4 +1,7 @@
-import type { FailoverReason } from "./pi-embedded-helpers.js";
+import {
+  classifyFailoverReason,
+  type FailoverReason,
+} from "./pi-embedded-helpers.js";
 
 export class FailoverError extends Error {
   readonly reason: FailoverReason;
@@ -51,3 +54,116 @@ export function resolveFailoverStatus(
       return undefined;
   }
 }
+
+function getStatusCode(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const candidate =
+    (err as { status?: unknown; statusCode?: unknown }).status ??
+    (err as { statusCode?: unknown }).statusCode;
+  if (typeof candidate === "number") return candidate;
+  if (typeof candidate === "string" && /^\d+$/.test(candidate)) {
+    return Number(candidate);
+  }
+  return undefined;
+}
+
+function getErrorCode(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const candidate = (err as { code?: unknown }).code;
+  if (typeof candidate !== "string") return undefined;
+  const trimmed = candidate.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function getErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (
+    typeof err === "number" ||
+    typeof err === "boolean" ||
+    typeof err === "bigint"
+  ) {
+    return String(err);
+  }
+  if (typeof err === "symbol") return err.description ?? "";
+  if (err && typeof err === "object") {
+    const message = (err as { message?: unknown }).message;
+    if (typeof message === "string") return message;
+  }
+  return "";
+}
+
+export function resolveFailoverReasonFromError(
+  err: unknown,
+): FailoverReason | null {
+  if (isFailoverError(err)) return err.reason;
+
+  const status = getStatusCode(err);
+  if (status === 402) return "billing";
+  if (status === 429) return "rate_limit";
+  if (status === 401 || status === 403) return "auth";
+  if (status === 408) return "timeout";
+
+  const code = (getErrorCode(err) ?? "").toUpperCase();
+  if (
+    ["ETIMEDOUT", "ESOCKETTIMEDOUT", "ECONNRESET", "ECONNABORTED"].includes(
+      code,
+    )
+  ) {
+    return "timeout";
+  }
+
+  const message = getErrorMessage(err);
+  if (!message) return null;
+  return classifyFailoverReason(message);
+}
+
+export function describeFailoverError(err: unknown): {
+  message: string;
+  reason?: FailoverReason;
+  status?: number;
+  code?: string;
+} {
+  if (isFailoverError(err)) {
+    return {
+      message: err.message,
+      reason: err.reason,
+      status: err.status,
+      code: err.code,
+    };
+  }
+  const message = getErrorMessage(err) || String(err);
+  return {
+    message,
+    reason: resolveFailoverReasonFromError(err) ?? undefined,
+    status: getStatusCode(err),
+    code: getErrorCode(err),
+  };
+}
+
+export function coerceToFailoverError(
+  err: unknown,
+  context?: {
+    provider?: string;
+    model?: string;
+    profileId?: string;
+  },
+): FailoverError | null {
+  if (isFailoverError(err)) return err;
+  const reason = resolveFailoverReasonFromError(err);
+  if (!reason) return null;
+
+  const message = getErrorMessage(err) || String(err);
+  const status = getStatusCode(err) ?? resolveFailoverStatus(reason);
+  const code = getErrorCode(err);
+
+  return new FailoverError(message, {
+    reason,
+    provider: context?.provider,
+    model: context?.model,
+    profileId: context?.profileId,
+    status,
+    code,
+    cause: err instanceof Error ? err : undefined,
+  });
+}