@oh-my-pi/pi-ai 17.2.11 → 17.2.12

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [17.2.12] - 2026-08-08
+
+### Fixed
+
+- Fixed account-scoped Codex cyber-policy denials bypassing sibling credential rotation; replay-safe requests now try every configured account before surfacing the error.
+
 ## [17.2.11] - 2026-08-07
 
 ### Breaking Changes

package/dist/types/auth-retry.d.ts

@@ -14,9 +14,9 @@ import { isAuthRetryableError } from "./error/auth-classify.js";
  *   (invalidate/usage-limit the current credential and rotate to a sibling).
  *
  * Current drivers preserve that bounded a/b/c sequence for ordinary 401/auth
- * failures. 403/usage-limit failures skip refresh and may repeat step (c)
- * until the resolver returns `undefined`, cycles, or hits
- * {@link AUTH_RETRY_MAX_ATTEMPTS}.
+ * failures. Account-scoped policy denials, 403s, and usage-limit failures skip
+ * refresh and may repeat step (c) until the resolver returns `undefined`,
+ * cycles, or hits {@link AUTH_RETRY_MAX_ATTEMPTS}.
  */
 export interface ApiKeyResolveContext {
     /** True when the resolver should rotate to a sibling credential. */

package/dist/types/auth-storage.d.ts

@@ -1143,6 +1143,8 @@ export declare class AuthStorage {
      * - usage-limit / account-rate-limit error → {@link AuthStorage.markUsageLimitReached}
      *   (temporary block via its own backoff — default plus server usage-report
      *   reset; sticky left intact so the next resolve re-ranks around the block).
+     * - account-scoped policy denial → temporarily block that account without
+     *   marking its credential suspect, then rotate through eligible siblings.
      * - otherwise (hard 401 / auth failure) → mark the credential suspect (or
      *   reload when no broker hook is wired) and block it, then drop matching
      *   sticky state.

package/dist/types/error/auth-classify.d.ts

@@ -10,11 +10,11 @@ export declare function isInvalidatedOAuthTokenError(error: unknown): boolean;
 /**
  * Whether an upstream failure should rotate to a sibling credential: a hard
  * `401`, a `403` (token valid but access denied — plan, model policy, or org
- * restriction a sibling account may not share), a body-classified usage limit
- * (Codex `usage_limit_reached`, Anthropic account rate-limit, Google
+ * restriction a sibling account may not share), an account-scoped policy
+ * denial such as Codex `cyber_policy`, a body-classified usage limit (Codex
+ * `usage_limit_reached`, Anthropic account rate-limit, Google
  * `resource_exhausted`, OpenAI `insufficient_quota`, …), or a bare `429`
- * whose payload did not preserve a richer quota code.
- * Transient 429s (`Too many requests`, per-minute caps) stay in the
- * upstream-backoff lane.
+ * whose payload did not preserve a richer quota code. Transient 429s
+ * (`Too many requests`, per-minute caps) stay in the upstream-backoff lane.
  */
 export declare function isAuthRetryableError(error: unknown): boolean;

package/dist/types/error/flags.d.ts

@@ -9,6 +9,8 @@ export declare const Flag: {
     readonly MalformedFunctionCall: 2097152;
     readonly ProviderFinishError: 4194304;
     readonly ContentBlocked: 32768;
+    /** Account-scoped provider policy denial that may succeed with another credential. */
+    readonly AccountPolicy: 16384;
     readonly ContextOverflow: 8388608;
     readonly AuthFailed: 16777216;
     readonly SilentAbort: 33554432;
@@ -53,6 +55,8 @@ export declare function classify(error: unknown, api?: Api): number;
  * regexes at call sites.
  */
 export declare function isUsageLimit(error: unknown, api?: Api): boolean;
+/** Whether an upstream rejection is an account-scoped policy denial worth retrying with a sibling credential. */
+export declare function isAccountPolicyError(error: unknown, api?: Api): boolean;
 /**
  * Strict-tool rejection: grammar too large, schema too complex, or structured
  * outputs unsupported by the model/endpoint.

package/dist/types/registry/api-key-login.d.ts

@@ -27,16 +27,18 @@ type ModelsEndpointValidation = {
 export type ApiKeyLoginConfig = {
     /** Display name used in error messages, e.g. "Cerebras", "NanoGPT". */
     providerLabel: string;
-    /** URL opened in browser for the user to grab their key. */
-    authUrl: string;
-    /** Instructions shown with the onAuth callback. */
-    instructions: string;
+    /** URL opened in browser for the user to grab their key, or omitted to skip onAuth. */
+    authUrl?: string;
+    /** Instructions shown with the onAuth callback, or omitted to skip onAuth. */
+    instructions?: string;
     /** Prompt message shown when asking for the key paste. */
     promptMessage: string;
     /** Placeholder string for the prompt (e.g. "sk-...", "csk-..."). */
     placeholder: string;
     /** Validation strategy, or `null` to skip validation. */
     validation: ChatCompletionsValidation | AnthropicMessagesValidation | ModelsEndpointValidation | null;
+    /** Value returned for an empty key; also allows an empty prompt response. */
+    emptyKeyFallback?: string;
 };
 export declare function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthController) => Promise<string>;
 export {};

package/dist/types/registry/cloudflare-ai-gateway.d.ts

@@ -1,11 +1,11 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * Login to Cloudflare AI Gateway.
  *
  * Opens browser to Cloudflare AI Gateway authentication docs and prompts for a gateway token/API key.
  * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
  */
-export declare function loginCloudflareAiGateway(options: OAuthController): Promise<string>;
+export declare const loginCloudflareAiGateway: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const cloudflareAiGatewayProvider: {
     readonly id: "cloudflare-ai-gateway";
     readonly name: "Cloudflare AI Gateway";

package/dist/types/registry/kagi.d.ts

@@ -1,11 +1,11 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * Login to Kagi.
  *
  * Opens browser to API settings and prompts user to paste their API key.
  * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
  */
-export declare function loginKagi(options: OAuthController): Promise<string>;
+export declare const loginKagi: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const kagiProvider: {
     readonly id: "kagi";
     readonly name: "Kagi";

package/dist/types/registry/litellm.d.ts

@@ -1,11 +1,11 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * Login to LiteLLM.
  *
  * Opens browser to LiteLLM setup docs, prompts user to paste their API key.
  * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
  */
-export declare function loginLiteLLM(options: OAuthController): Promise<string>;
+export declare const loginLiteLLM: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const litellmProvider: {
     readonly id: "litellm";
     readonly name: "LiteLLM";

package/dist/types/registry/llama-cpp.d.ts

@@ -1,5 +1,5 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
-export declare function loginLlamaCpp(options: OAuthController): Promise<string>;
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
+export declare const loginLlamaCpp: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const llamaCppProvider: {
     readonly id: "llama.cpp";
     readonly name: "llama.cpp (Local OpenAI-compatible)";

package/dist/types/registry/lm-studio.d.ts

@@ -1,6 +1,6 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
 export declare const DEFAULT_LOCAL_TOKEN = "lm-studio-local";
-export declare function loginLmStudio(options: OAuthController): Promise<string>;
+export declare const loginLmStudio: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const lmStudioProvider: {
     readonly id: "lm-studio";
     readonly name: "LM Studio (Local OpenAI-compatible)";

package/dist/types/registry/parallel.d.ts

@@ -1,11 +1,11 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * Login to Parallel.
  *
  * Opens browser to the API keys page, prompts the user to paste their API key,
  * and returns the API key directly.
  */
-export declare function loginParallel(options: OAuthController): Promise<string>;
+export declare const loginParallel: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const parallelProvider: {
     readonly id: "parallel";
     readonly name: "Parallel";

package/dist/types/registry/tavily.d.ts

@@ -5,7 +5,7 @@ import type { OAuthLoginCallbacks } from "./oauth/types.js";
  * Opens browser to API keys page and prompts user to paste their API key.
  * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
  */
-export declare function loginTavily(options: OAuthLoginCallbacks): Promise<string>;
+export declare const loginTavily: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const tavilyProvider: {
     readonly id: "tavily";
     readonly name: "Tavily";

package/dist/types/registry/vercel-ai-gateway.d.ts

@@ -1,5 +1,5 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
-export declare function loginVercelAiGateway(options: OAuthController): Promise<string>;
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
+export declare const loginVercelAiGateway: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const vercelAiGatewayProvider: {
     readonly id: "vercel-ai-gateway";
     readonly name: "Vercel AI Gateway";

package/dist/types/registry/vllm.d.ts

@@ -1,5 +1,5 @@
-import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types.js";
-export declare function loginVllm(options: OAuthController): Promise<string>;
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
+export declare const loginVllm: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const vllmProvider: {
     readonly id: "vllm";
     readonly name: "vLLM (Local OpenAI-compatible)";

package/dist/types/usage/openai-codex-reset.d.ts

@@ -1,23 +1,3 @@
-/**
- * OpenAI Codex "saved rate limit reset" redemption client.
- *
- * OpenAI lets paid Codex accounts bank a usage-window reset and spend it on
- * demand (announced 2026-06-11). The count is surfaced on `/wham/usage` as
- * `rate_limit_reset_credits.available_count` (see `./openai-codex.ts`), but the
- * actual credit objects and the redeem action live on two dedicated routes:
- *
- *   GET  /wham/rate-limit-reset-credits           → list redeemable credits
- *   POST /wham/rate-limit-reset-credits/consume   → spend one credit
- *        body: { credit_id, redeem_request_id, account_id? }
- *
- * `redeem_request_id` is a client-generated idempotency key (UUID). The consume
- * response carries a `code`: `"reset"` on success, otherwise a business reason
- * (`already_redeemed`, `no_credit`, `nothing_to_reset`).
- *
- * These are thin, dependency-light functions so both the interactive session
- * (the `/usage reset` command + auto-redeem) and any out-of-band tooling can
- * share one wire contract.
- */
 import type { FetchImpl } from "../types.js";
 /** A single redeemable (or already-spent) saved reset. */
 export interface CodexResetCredit {

package/dist/types/usage/shared.d.ts

@@ -1 +1,13 @@
-export declare const toNumber: (value: unknown) => number | undefined;
+import type { UsageStatus } from "../usage.js";
+/** Milliseconds in one hour. */
+export declare const HOUR_MS: number;
+/** Milliseconds in one day. */
+export declare const DAY_MS: number;
+/** Milliseconds in one seven-day week. */
+export declare const WEEK_MS: number;
+/** Parses a finite positive epoch timestamp, tolerating seconds or milliseconds. */
+export declare function parsePositiveTimestamp(value: unknown): number | undefined;
+/** Parses an ISO timestamp into epoch milliseconds. */
+export declare function parseIsoTimestamp(value: unknown): number | undefined;
+/** Maps a used fraction to the standard quota status thresholds. */
+export declare function usageStatus(usedFraction: number | undefined): UsageStatus;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.2.11",
+	"version": "17.2.12",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,10 +38,10 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/omptype": "17.2.11",
-		"@oh-my-pi/pi-catalog": "17.2.11",
-		"@oh-my-pi/pi-utils": "17.2.11",
-		"@oh-my-pi/pi-wire": "17.2.11"
+		"@oh-my-pi/omptype": "17.2.12",
+		"@oh-my-pi/pi-catalog": "17.2.12",
+		"@oh-my-pi/pi-utils": "17.2.12",
+		"@oh-my-pi/pi-wire": "17.2.12"
 	},
 	"devDependencies": {
 		"@bufbuild/protoc-gen-es": "^2.12.1",

package/src/auth-retry.ts

@@ -2,7 +2,7 @@ import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
 import type { OAuthAccess } from "./auth-storage";
 import * as AIError from "./error";
 import { isAuthRetryableError, isInvalidatedOAuthTokenError } from "./error/auth-classify";
-import { isUsageLimit } from "./error/flags";
+import { isAccountPolicyError, isUsageLimit } from "./error/flags";
 import { isConcurrencyCapExclusion, isUsageLimitOutcome } from "./error/rate-limit";
 
 /**
@@ -19,9 +19,9 @@ import { isConcurrencyCapExclusion, isUsageLimitOutcome } from "./error/rate-lim
  *   (invalidate/usage-limit the current credential and rotate to a sibling).
  *
  * Current drivers preserve that bounded a/b/c sequence for ordinary 401/auth
- * failures. 403/usage-limit failures skip refresh and may repeat step (c)
- * until the resolver returns `undefined`, cycles, or hits
- * {@link AUTH_RETRY_MAX_ATTEMPTS}.
+ * failures. Account-scoped policy denials, 403s, and usage-limit failures skip
+ * refresh and may repeat step (c) until the resolver returns `undefined`,
+ * cycles, or hits {@link AUTH_RETRY_MAX_ATTEMPTS}.
  */
 export interface ApiKeyResolveContext {
 	/** True when the resolver should rotate to a sibling credential. */
@@ -91,6 +91,7 @@ export const AUTH_RETRY_STEPS: readonly boolean[] = [false, true];
 export const AUTH_RETRY_MAX_ATTEMPTS = 64;
 
 function isDirectCredentialRotationError(error: unknown): boolean {
+	if (isAccountPolicyError(error)) return true;
 	if (isUsageLimit(error) || isInvalidatedOAuthTokenError(error)) return true;
 	const status = AIError.status(error);
 	const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;

package/src/auth-storage.ts

@@ -1211,6 +1211,14 @@ type OAuthCandidate = UsageCandidate<OAuthCredential>;
 type ApiKeyCandidate = UsageCandidate<ApiKeyCredential>;
 type UsageRankingResult<T extends AuthCredential> = UsageCandidate<T> & { blockedUntil: number | undefined };
 
+type CredentialBlockRouting = {
+	providerKey: string;
+	strategy: CredentialRankingStrategy | undefined;
+	rankingContext: CredentialRankingContext;
+	blockScope: string | undefined;
+	siblingBlockScopes: readonly string[];
+};
+
 type UsageRankedCandidate<T extends AuthCredential> = UsageCandidate<T> & {
 	blocked: boolean;
 	blockedUntil?: number;
@@ -4271,6 +4279,58 @@ export class AuthStorage {
 		return sessionCredential ? { ...sessionCredential, explicit: false } : undefined;
 	}
 
+	#credentialBlockRouting(
+		provider: string,
+		credentialType: AuthCredential["type"],
+		modelId: string | undefined,
+	): CredentialBlockRouting {
+		const providerKey = this.#getProviderTypeKey(provider, credentialType);
+		const strategy = this.#rankingStrategyResolver?.(provider);
+		const rankingContext: CredentialRankingContext = { modelId };
+		const blockScope = strategy?.blockScope?.(rankingContext);
+		return {
+			providerKey,
+			strategy,
+			rankingContext,
+			blockScope,
+			siblingBlockScopes: strategy?.blockScopes?.(rankingContext) ?? (blockScope ? [blockScope] : []),
+		};
+	}
+
+	#blockCredentialForRotation(
+		provider: string,
+		credentialType: AuthCredential["type"],
+		targetIndex: number,
+		blockedUntil: number,
+		routing: CredentialBlockRouting,
+	): UsageLimitMarkResult {
+		if (targetIndex >= 0) {
+			this.#markCredentialBlocked(provider, routing.providerKey, targetIndex, blockedUntil, routing.blockScope);
+		}
+
+		const remainingCredentials = this.#getCredentialsForProvider(provider)
+			.map((credential, index) => ({ credential, index }))
+			.filter(
+				(entry): entry is { credential: AuthCredential; index: number } =>
+					entry.credential.type === credentialType && entry.index !== targetIndex,
+			);
+
+		let retryAtMs: number | undefined;
+		for (const candidate of remainingCredentials) {
+			// Sibling availability must use the same scope set selection reads, or
+			// this reports a sibling as free that selection will then refuse.
+			const candidateBlockedUntil = this.#getCredentialBlockedUntil(
+				provider,
+				routing.providerKey,
+				candidate.index,
+				routing.siblingBlockScopes,
+			);
+			if (candidateBlockedUntil === undefined) return { switched: true };
+			if (retryAtMs === undefined || candidateBlockedUntil < retryAtMs) retryAtMs = candidateBlockedUntil;
+		}
+		return { switched: false, retryAtMs };
+	}
+
 	/**
 	 * Marks the current session's credential as temporarily blocked due to usage limits.
 	 * Uses usage reports to determine accurate reset time when available.
@@ -4313,21 +4373,17 @@ export class AuthStorage {
 		const credentialType = sessionCredential.type;
 		const targetCredentialId = target.id;
 
-		const providerKey = this.#getProviderTypeKey(provider, credentialType);
-		const strategy = this.#rankingStrategyResolver?.(provider);
-		const rankingContext: CredentialRankingContext = { modelId: options?.modelId };
-		const blockScope = strategy?.blockScope?.(rankingContext);
-		const siblingBlockScopes = strategy?.blockScopes?.(rankingContext) ?? (blockScope ? [blockScope] : []);
+		const routing = this.#credentialBlockRouting(provider, credentialType, options?.modelId);
 		const now = Date.now();
 		let blockedUntil = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
 
-		if (credentialType === "oauth" && target.credential.type === "oauth" && strategy) {
+		if (credentialType === "oauth" && target.credential.type === "oauth" && routing.strategy) {
 			const report = await raceUsageWithSignal(
 				this.#getUsageReport(provider, target.credential, options),
 				options?.signal,
 			);
 			if (report) {
-				const scopedLimits = this.#getScopedUsageLimits(strategy, report, rankingContext);
+				const scopedLimits = this.#getScopedUsageLimits(routing.strategy, report, routing.rankingContext);
 				if (this.#isUsageLimitReached(scopedLimits)) {
 					const resetAtMs = this.#getUsageResetAtMs(scopedLimits, Date.now());
 					if (resetAtMs && resetAtMs > blockedUntil) {
@@ -4343,32 +4399,7 @@ export class AuthStorage {
 		const targetIndex = this.#getStoredCredentials(provider).findIndex(
 			entry => entry.id === targetCredentialId && entry.credential.type === credentialType,
 		);
-		if (targetIndex >= 0) {
-			this.#markCredentialBlocked(provider, providerKey, targetIndex, blockedUntil, blockScope);
-		}
-
-		const remainingCredentials = this.#getCredentialsForProvider(provider)
-			.map((credential, index) => ({ credential, index }))
-			.filter(
-				(entry): entry is { credential: AuthCredential; index: number } =>
-					entry.credential.type === credentialType && entry.index !== targetIndex,
-			);
-
-		let retryAtMs: number | undefined;
-		for (const candidate of remainingCredentials) {
-			// Sibling availability must use the same scope set selection reads, or
-			// this reports a sibling as free that selection will then refuse, most
-			// visibly when the sibling still carries a legacy shared block.
-			const candidateBlockedUntil = this.#getCredentialBlockedUntil(
-				provider,
-				providerKey,
-				candidate.index,
-				siblingBlockScopes,
-			);
-			if (candidateBlockedUntil === undefined) return { switched: true };
-			if (retryAtMs === undefined || candidateBlockedUntil < retryAtMs) retryAtMs = candidateBlockedUntil;
-		}
-		return { switched: false, retryAtMs };
+		return this.#blockCredentialForRotation(provider, credentialType, targetIndex, blockedUntil, routing);
 	}
 
 	#resolveWindowResetAt(window: UsageLimit["window"]): number | undefined {
@@ -6078,6 +6109,8 @@ export class AuthStorage {
 	 * - usage-limit / account-rate-limit error → {@link AuthStorage.markUsageLimitReached}
 	 *   (temporary block via its own backoff — default plus server usage-report
 	 *   reset; sticky left intact so the next resolve re-ranks around the block).
+	 * - account-scoped policy denial → temporarily block that account without
+	 *   marking its credential suspect, then rotate through eligible siblings.
 	 * - otherwise (hard 401 / auth failure) → mark the credential suspect (or
 	 *   reload when no broker hook is wired) and block it, then drop matching
 	 *   sticky state.
@@ -6114,6 +6147,17 @@ export class AuthStorage {
 		});
 		if (!sessionCredential) return false;
 
+		if (AIError.isAccountPolicyError(error)) {
+			const routing = this.#credentialBlockRouting(provider, sessionCredential.type, options?.modelId);
+			return this.#blockCredentialForRotation(
+				provider,
+				sessionCredential.type,
+				sessionCredential.index,
+				Date.now() + AuthStorage.#defaultBackoffMs,
+				routing,
+			).switched;
+		}
+
 		const providerKey = this.#getProviderTypeKey(provider, sessionCredential.type);
 		// Snapshot sibling availability before mutating so a soft-deleting
 		// suspect hook can't reindex the answer out from under us.

package/src/error/auth-classify.ts

@@ -1,5 +1,5 @@
 import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
-import { isOAuthExpiry, isUsageLimit } from "./flags";
+import { isAccountPolicyError, isOAuthExpiry, isUsageLimit } from "./flags";
 import { isConcurrencyCapExclusion, isUsageLimitOutcome } from "./rate-limit";
 
 /**
@@ -27,15 +27,16 @@ export function isInvalidatedOAuthTokenError(error: unknown): boolean {
 /**
  * Whether an upstream failure should rotate to a sibling credential: a hard
  * `401`, a `403` (token valid but access denied — plan, model policy, or org
- * restriction a sibling account may not share), a body-classified usage limit
- * (Codex `usage_limit_reached`, Anthropic account rate-limit, Google
+ * restriction a sibling account may not share), an account-scoped policy
+ * denial such as Codex `cyber_policy`, a body-classified usage limit (Codex
+ * `usage_limit_reached`, Anthropic account rate-limit, Google
  * `resource_exhausted`, OpenAI `insufficient_quota`, …), or a bare `429`
- * whose payload did not preserve a richer quota code.
- * Transient 429s (`Too many requests`, per-minute caps) stay in the
- * upstream-backoff lane.
+ * whose payload did not preserve a richer quota code. Transient 429s
+ * (`Too many requests`, per-minute caps) stay in the upstream-backoff lane.
  */
 export function isAuthRetryableError(error: unknown): boolean {
 	if (isUsageLimit(error)) return true;
+	if (isAccountPolicyError(error)) return true;
 	if (isInvalidatedOAuthTokenError(error)) return true;
 	const httpStatus = extractHttpStatusFromError(error);
 	const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;

package/src/error/flags.ts

@@ -25,6 +25,8 @@ export const Flag = {
 	MalformedFunctionCall: 0x0020_0000,
 	ProviderFinishError: 0x0040_0000,
 	ContentBlocked: 0x0000_8000,
+	/** Account-scoped provider policy denial that may succeed with another credential. */
+	AccountPolicy: 0x0000_4000,
 	ContextOverflow: 0x0080_0000,
 	AuthFailed: 0x0100_0000,
 	SilentAbort: 0x0200_0000,
@@ -49,6 +51,7 @@ const KIND_MASK =
 	Flag.MalformedFunctionCall |
 	Flag.ProviderFinishError |
 	Flag.ContentBlocked |
+	Flag.AccountPolicy |
 	Flag.ContextOverflow |
 	Flag.AuthFailed |
 	Flag.SilentAbort |
@@ -102,6 +105,7 @@ const AUTH_FAILURE_PATTERN =
 const MALFORMED_FUNCTION_CALL_PATTERN = /\bmalformed.?function.?call\b/i;
 const PROVIDER_FINISH_ERROR_PATTERN = /\bProvider (?:returned error finish_reason|finish_reason:\s*error)\b/i;
 const CONTENT_FILTER_PATTERN = /\b(?:incomplete:\s*)?content_filter\b/i;
+const ACCOUNT_POLICY_PATTERN = /\bcyber_policy\b|trusted access for cyber/i;
 const STALE_RESPONSE_ITEM_PATTERNS = [/\bItem with id ['"][^'"]+['"] not found\.?/i, /previous[ _]?response/i] as const;
 const STALE_RESPONSE_ITEM_DETAIL_PATTERN = /not[ _]?found|invalid|expired|stale|zero[ _-]?data[ _-]?retention/i;
 /**
@@ -194,6 +198,7 @@ const ERROR_KIND_LABELS: readonly [Flag, string][] = [
 	[Flag.MalformedFunctionCall, "malformed-function-call"],
 	[Flag.ProviderFinishError, "provider-finish-error"],
 	[Flag.ContentBlocked, "content-blocked"],
+	[Flag.AccountPolicy, "account-policy"],
 	[Flag.ContextOverflow, "context-overflow"],
 	[Flag.AuthFailed, "auth-failed"],
 	[Flag.SilentAbort, "silent-abort"],
@@ -336,6 +341,7 @@ function classifyText(errorMessage: string | undefined, errorStatus: number | un
 		if (isMalformedFunctionCallText(errorMessage)) kinds |= Flag.MalformedFunctionCall;
 		if (isProviderFinishErrorText(errorMessage)) kinds |= Flag.ProviderFinishError;
 		if (isContentBlockedText(errorMessage)) kinds |= Flag.ContentBlocked;
+		if (ACCOUNT_POLICY_PATTERN.test(errorMessage)) kinds |= Flag.AccountPolicy | Flag.ContentBlocked;
 		if (isAuthFailureText(errorMessage)) kinds |= Flag.AuthFailed;
 
 		const statusClean = errorStatus ? errorStatus : (status({ message: errorMessage }) ?? undefined);
@@ -398,6 +404,9 @@ export function classify(error: unknown, api?: Api): number {
 			if ("errorId" in link && typeof (link as { errorId: unknown }).errorId === "number") {
 				kinds |= (link as { errorId: number }).errorId & KIND_MASK;
 			}
+			if ("code" in link && typeof link.code === "string" && ACCOUNT_POLICY_PATTERN.test(link.code)) {
+				kinds |= Flag.AccountPolicy | Flag.ContentBlocked;
+			}
 		}
 
 		if (link instanceof AwsCredentialsError) {
@@ -475,6 +484,11 @@ export function isUsageLimit(error: unknown, api?: Api): boolean {
 	return is(classify(error, api), Flag.UsageLimit);
 }
 
+/** Whether an upstream rejection is an account-scoped policy denial worth retrying with a sibling credential. */
+export function isAccountPolicyError(error: unknown, api?: Api): boolean {
+	return is(classify(error, api), Flag.AccountPolicy);
+}
+
 /**
  * Strict-tool rejection: grammar too large, schema too complex, or structured
  * outputs unsupported by the model/endpoint.

package/src/registry/api-key-login.ts

@@ -38,16 +38,18 @@ type ModelsEndpointValidation = {
 export type ApiKeyLoginConfig = {
 	/** Display name used in error messages, e.g. "Cerebras", "NanoGPT". */
 	providerLabel: string;
-	/** URL opened in browser for the user to grab their key. */
-	authUrl: string;
-	/** Instructions shown with the onAuth callback. */
-	instructions: string;
+	/** URL opened in browser for the user to grab their key, or omitted to skip onAuth. */
+	authUrl?: string;
+	/** Instructions shown with the onAuth callback, or omitted to skip onAuth. */
+	instructions?: string;
 	/** Prompt message shown when asking for the key paste. */
 	promptMessage: string;
 	/** Placeholder string for the prompt (e.g. "sk-...", "csk-..."). */
 	placeholder: string;
 	/** Validation strategy, or `null` to skip validation. */
 	validation: ChatCompletionsValidation | AnthropicMessagesValidation | ModelsEndpointValidation | null;
+	/** Value returned for an empty key; also allows an empty prompt response. */
+	emptyKeyFallback?: string;
 };
 
 export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthController) => Promise<string> {
@@ -56,15 +58,24 @@ export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthCon
 			throw new AIError.OnPromptRequiredError(config.providerLabel);
 		}
 
-		options.onAuth?.({
-			url: config.authUrl,
-			instructions: config.instructions,
-		});
+		if (config.authUrl && config.instructions) {
+			options.onAuth?.({
+				url: config.authUrl,
+				instructions: config.instructions,
+			});
+		}
 
-		const apiKey = await options.onPrompt({
-			message: config.promptMessage,
-			placeholder: config.placeholder,
-		});
+		const apiKey =
+			config.emptyKeyFallback === undefined
+				? await options.onPrompt({
+						message: config.promptMessage,
+						placeholder: config.placeholder,
+					})
+				: await options.onPrompt({
+						message: config.promptMessage,
+						placeholder: config.placeholder,
+						allowEmpty: true,
+					});
 
 		if (options.signal?.aborted) {
 			throw new AIError.LoginCancelledError();
@@ -72,6 +83,9 @@ export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthCon
 
 		const trimmed = apiKey.trim();
 		if (!trimmed) {
+			if (config.emptyKeyFallback !== undefined) {
+				return config.emptyKeyFallback;
+			}
 			throw new AIError.ApiKeyRequiredError();
 		}