@oh-my-pi/pi-ai 13.3.13 → 13.3.14

package/CHANGELOG.md

@@ -2,12 +2,68 @@
 
 ## [Unreleased]
 
+## [13.3.14] - 2026-02-28
+
+### Added
+
+- Exported schema utilities from new `./utils/schema` module, consolidating JSON Schema handling across providers
+- Added `CredentialRankingStrategy` interface for providers to implement usage-based credential selection
+- Added `claudeRankingStrategy` for Anthropic OAuth credentials to enable smart multi-account selection based on usage windows
+- Added `codexRankingStrategy` for OpenAI Codex OAuth credentials with priority boost for fresh 5-hour window starts
+- Added `adaptSchemaForStrict()` helper for unified OpenAI strict schema enforcement across providers
+- Added schema equality and merging utilities: `areJsonValuesEqual()`, `mergeCompatibleEnumSchemas()`, `mergePropertySchemas()`
+- Added Cloud Code Assist schema normalization: `copySchemaWithout()`, `stripResidualCombiners()`, `prepareSchemaForCCA()`
+- Added `sanitizeSchemaForGoogle()` and `sanitizeSchemaForCCA()` for provider-specific schema sanitization
+- Added `StringEnum()` helper for creating string enum schemas compatible with Google and other providers
+- Added `enforceStrictSchema()` and `sanitizeSchemaForStrictMode()` for OpenAI strict mode schema validation
+- Added package exports for `./utils/schema` and `./utils/schema/*` subpaths
+- Added `validateSchemaCompatibility()` to statically audit a JSON Schema against provider-specific rules (`openai-strict`, `google`, `cloud-code-assist-claude`) and return structured violations
+- Added `validateStrictSchemaEnforcement()` to verify the strict-fail-open contract: enforced schemas pass strict validation, failed schemas return the original object identity
+- Added `COMBINATOR_KEYS` (`anyOf`, `allOf`, `oneOf`) and `CCA_UNSUPPORTED_SCHEMA_FIELDS` as exported constants in `fields.ts` to eliminate duplication across modules
+- Added `tryEnforceStrictSchema` result cache (`WeakMap`) to avoid redundant sanitize + enforce work for the same schema object
+- Added comprehensive schema normalization test suite (`schema-normalization.test.ts`) covering strict mode, Google, and Cloud Code Assist normalization paths
+- Added schema compatibility validation test suite (`schema-compatibility.test.ts`) covering all three provider targets
+
+### Changed
+
+- Moved schema utilities from `./utils/typebox-helpers` to new `./utils/schema` module with expanded functionality
+- Refactored OpenAI provider tool conversion to use unified `adaptSchemaForStrict()` helper across codex, completions, and responses
+- Updated `AuthStorage` to support generic credential ranking via `CredentialRankingStrategy` instead of Codex-only logic
+- Moved Google schema sanitization functions from `google-shared.ts` to `./utils/schema` module
+- Changed export path: `./utils/typebox-helpers` → `./utils/schema` in main index
+- `sanitizeSchemaForGoogle()` / `sanitizeSchemaForCCA()` now accept a parameterized `unsupportedFields` set internally, enabling code reuse between the two sanitizers
+- `copySchemaWithout()` rewritten using object-rest destructuring for clarity
+
+### Fixed
+
+- Fixed cycle detection: `WeakSet` guards added to all recursive schema traversals (`sanitizeSchemaForStrictMode`, `enforceStrictSchema`, `normalizeSchemaForCCA`, `normalizeNullablePropertiesForCloudCodeAssist`, `stripResidualCombiners`, `sanitizeSchemaImpl`, `hasResidualCloudCodeAssistIncompatibilities`) — circular schemas no longer cause infinite loops or stack overflows
+- Fixed `hasResidualCloudCodeAssistIncompatibilities`: cycle detection now returns `false` (not `true`) for already-visited nodes, eliminating false positives that forced the CCA fallback schema on valid recursive inputs
+- Fixed `stripResidualCombiners` to iterate to a fixpoint rather than making a single pass, ensuring chained combiner reductions (where one reduction enables another) are fully resolved
+- Fixed `mergeObjectCombinerVariants` required-field computation: the flattened object now takes the intersection of all variants' `required` arrays (unioned with own-level required properties that exist in the merged schema), preventing required fields from being silently dropped or over-included
+- Fixed `mergeCompatibleEnumSchemas` to use deep structural equality (`areJsonValuesEqual`) instead of `Object.is` when deduplicating object-valued enum members
+- Fixed `sanitizeSchemaForGoogle` const-to-enum deduplication to use deep equality instead of reference equality
+- Fixed `sanitizeSchemaForGoogle` type inference for `anyOf`/`oneOf`-flattened const enums: type is now derived from all variants (must agree), falling back to inference from enum values; mixed null/non-null infers the non-null type and sets `nullable`
+- Fixed `sanitizeSchemaForGoogle` recursion to spread options when descending (previously only `insideProperties`, `normalizeTypeArrayToNullable`, `stripNullableKeyword` were forwarded; new fields `unsupportedFields` and `seen` were silently dropped)
+- Fixed `sanitizeSchemaForGoogle` array-valued `type` filtering to exclude non-string entries before processing
+- Removed incorrect `additionalProperties: false` stripping from `sanitizeSchemaForGoogle` (the field is valid in Google schemas when `false`)
+- Fixed `sanitizeSchemaForStrictMode` to strip the `nullable` keyword and expand it into `anyOf: [schema, {type: "null"}]` in the output, matching what OpenAI strict mode actually expects
+- Fixed `sanitizeSchemaForStrictMode` to infer `type: "array"` when `items` is present but `type` is absent
+- Fixed `sanitizeSchemaForStrictMode` to infer a scalar `type` from uniform `enum` values when `type` is not explicitly set
+- Fixed `sanitizeSchemaForStrictMode` const-to-enum merge to use deep equality, preventing duplicate enum entries when `const` and `enum` both exist with the same value
+- Fixed `enforceStrictSchema` to drop `additionalProperties` unconditionally (previously only object-valued `additionalProperties` was recursed into; non-object values were passed through, violating strict schema requirements)
+- Fixed `enforceStrictSchema` to recurse into `$defs` and `definitions` blocks so referenced sub-schemas are also made strict-compliant
+- Fixed `enforceStrictSchema` to handle tuple-style `items` arrays (previously only single-schema `items` objects were recursed)
+- Fixed `enforceStrictSchema` double-wrapping: optional properties already expressed as `anyOf: [..., {type: "null"}]` are not wrapped again
+- Fixed `enforceStrictSchema` `Array.isArray` type-narrowing for `type` field to filter non-string entries before checking for `"object"`
+
 ## [13.3.8] - 2026-02-28
+
 ### Fixed
 
 - Fixed response body reuse error when handling 429 rate limit responses with retry logic
 
 ## [13.3.7] - 2026-02-27
+
 ### Added
 
 - Added `tryEnforceStrictSchema` function that gracefully downgrades to non-strict mode when schema enforcement fails, enabling better compatibility with malformed or circular schemas
@@ -25,6 +81,7 @@
 - Fixed `enforceStrictSchema` to correctly process nested object schemas within `anyOf`, `allOf`, and `oneOf` combinators
 
 ## [13.3.1] - 2026-02-26
+
 ### Added
 
 - Added `topP`, `topK`, `minP`, `presencePenalty`, and `repetitionPenalty` options to `StreamOptions` for fine-grained control over model sampling behavior
@@ -32,8 +89,11 @@
 ## [13.3.0] - 2026-02-26
 
 ### Changed
+
 - Allowed OAuth provider logins to supply a manual authorization code handler with a default prompt when none is provided
+
 ## [13.2.0] - 2026-02-23
+
 ### Added
 
 - Added support for GitHub Copilot provider in strict mode for both openai-completions and openai-responses tool schemas
@@ -43,6 +103,7 @@
 - Fixed tool descriptions being rejected when undefined by providing empty string fallback across all providers
 
 ## [12.19.1] - 2026-02-22
+
 ### Added
 
 - Exported `isProviderRetryableError` function for detecting rate-limit and transient stream errors
@@ -53,6 +114,7 @@
 - Expanded retry detection to include JSON parse errors (unterminated strings, unexpected end of input) in addition to rate-limit errors
 
 ## [12.19.0] - 2026-02-22
+
 ### Added
 
 - Added GitLab Duo provider with support for Claude, GPT-5, and other models via GitLab AI Gateway
@@ -78,6 +140,7 @@
 - Removed `CliAuthStorage` class in favor of new `AuthCredentialStore` with enhanced functionality
 
 ## [12.17.2] - 2026-02-21
+
 ### Added
 
 - Exported `getAntigravityUserAgent()` function for constructing Antigravity User-Agent headers
@@ -88,6 +151,7 @@
 - Unified User-Agent header generation across Antigravity API calls to use centralized `getAntigravityUserAgent()` function
 
 ## [12.17.1] - 2026-02-21
+
 ### Added
 
 - Added new export paths for provider models via `./provider-models` and `./provider-models/*`
@@ -102,10 +166,13 @@
 - Reorganized package.json field ordering for improved readability
 
 ## [12.17.0] - 2026-02-21
+
 ### Fixed
+
 - Cursor provider: bind `execHandlers` when passing handler methods to the exec protocol so handlers receive correct `this` context (fixes "undefined is not an object (evaluating 'this.options')" when using exec tools such as web search with Cursor)
 
 ## [12.16.0] - 2026-02-21
+
 ### Added
 
 - Exported `readModelCache` and `writeModelCache` functions for direct SQLite-backed model cache access
@@ -123,6 +190,7 @@
 - Updated tool call tracking to use status map (Resolved/Aborted) instead of separate sets for better handling of duplicate and aborted tool results
 
 ## [12.15.0] - 2026-02-20
+
 ### Fixed
 
 - Improved error messages for OAuth token refresh failures by including detailed error information from the provider
@@ -134,6 +202,7 @@
 - Changed 429 retry strategy for OpenAI Codex and Google Gemini CLI to use a 5-minute time budget when the server provides a retry delay, instead of a fixed attempt cap
 
 ## [12.14.0] - 2026-02-19
+
 ### Added
 
 - Added `gemini-3.1-pro` model to opencode provider with text and image input support
@@ -161,6 +230,7 @@
 - Added NanoGPT provider support with API-key login, dynamic model discovery from `https://nano-gpt.com/api/v1/models`, and text-model filtering for catalog/runtime discovery ([#111](https://github.com/can1357/oh-my-pi/issues/111))
 
 ## [12.12.3] - 2026-02-19
+
 ### Fixed
 
 - Fixed retry logic to recognize 'unable to connect' errors as transient failures
@@ -173,6 +243,7 @@
 - Fixed Codex websocket append fallback by resetting stale turn-state/model-etag session metadata when request shape diverges from appendable history.
 
 ## [12.11.1] - 2026-02-19
+
 ### Added
 
 - Added support for Claude 4.6 Opus and Sonnet models via Cursor API
@@ -224,6 +295,7 @@
 - Updated README documentation to list all newly supported providers and their authentication requirements
 
 ## [12.10.1] - 2026-02-18
+
 - Added Synthetic provider
 - Added API-key login helpers for Synthetic and Cerebras providers
 
@@ -279,6 +351,7 @@
 - Updated Qwen model context window and max token limits for improved accuracy
 
 ## [12.7.0] - 2026-02-16
+
 ### Added
 
 - Added DeepSeek-V3.2 model support via Amazon Bedrock
@@ -391,6 +464,7 @@
 - Added deprecation filter in model generation script to prevent re-adding deprecated Anthropic models ([#33](https://github.com/can1357/oh-my-pi/issues/33))
 
 ## [11.14.1] - 2026-02-12
+
 ### Added
 
 - Added prompt-caching-scope-2026-01-05 beta feature support
@@ -410,6 +484,7 @@
 - Removed fine-grained-tool-streaming-2025-05-14 beta feature
 
 ## [11.13.1] - 2026-02-12
+
 ### Added
 
 - Added Perplexity (Pro/Max) OAuth login support via native macOS app extraction or email OTP authentication
@@ -417,6 +492,7 @@
 - Added Socket.IO v4 client implementation for authenticated WebSocket communication with Perplexity API
 
 ## [11.12.0] - 2026-02-11
+
 ### Changed
 
 - Increased maximum retry attempts for Codex requests from 2 to 5 to improve reliability on transient failures
@@ -444,6 +520,7 @@
 - Updated `@anthropic-ai/sdk` dependency from ^0.72.1 to ^0.74.0
 
 ## [11.10.0] - 2026-02-10
+
 ### Added
 
 - Added support for Kimi K2, K2 Turbo Preview, and K2.5 models with reasoning capabilities
@@ -454,6 +531,7 @@
 - Fixed Claude Sonnet 4 context window to 200K across multiple providers (was incorrectly set to 1M)
 
 ## [11.8.0] - 2026-02-10
+
 ### Added
 
 - Added `auto` model alias for OpenRouter with automatic model routing
@@ -532,11 +610,13 @@
 - Fixed Bedrock `supportsPromptCaching` to also check model cost fields
 
 ## [11.5.1] - 2026-02-07
+
 ### Fixed
 
 - Fixed schema normalization to handle array-valued `type` fields by converting them to a single type with nullable flag for Google provider compatibility
 
 ## [11.3.0] - 2026-02-06
+
 ### Added
 
 - Added `cacheRetention` option to control prompt cache retention preference ('none', 'short', 'long') across providers
@@ -562,6 +642,7 @@
 - Fixed handling of conversations ending with assistant messages on Anthropic-routed models that reject assistant prefill requests
 
 ## [11.2.3] - 2026-02-05
+
 ### Added
 
 - Added Claude Opus 4.6 model support across multiple providers (Anthropic, Amazon Bedrock, GitHub Copilot, OpenRouter, OpenCode, Vercel AI Gateway)
@@ -1342,4 +1423,4 @@ _Dedicated to Peter's shoulder ([@steipete](https://twitter.com/steipete))_
 
 ## [0.9.4] - 2025-11-26
 
-Initial release with multi-provider LLM support.
+Initial release with multi-provider LLM support.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "13.3.13",
+	"version": "13.3.14",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,7 +41,7 @@
 		"@aws-sdk/client-bedrock-runtime": "^3.998",
 		"@bufbuild/protobuf": "^2.11",
 		"@google/genai": "^1.43",
-		"@oh-my-pi/pi-utils": "13.3.13",
+		"@oh-my-pi/pi-utils": "13.3.14",
 		"@sinclair/typebox": "^0.34",
 		"@smithy/node-http-handler": "^4.4",
 		"ajv": "^8.18",
@@ -117,6 +117,14 @@
 		"./utils/oauth/*": {
 			"types": "./src/utils/oauth/*.ts",
 			"import": "./src/utils/oauth/*.ts"
+		},
+		"./utils/schema": {
+			"types": "./src/utils/schema/index.ts",
+			"import": "./src/utils/schema/index.ts"
+		},
+		"./utils/schema/*": {
+			"types": "./src/utils/schema/*.ts",
+			"import": "./src/utils/schema/*.ts"
 		}
 	}
 }

package/src/auth-storage.ts

@@ -15,6 +15,7 @@ import { googleGeminiCliUsageProvider } from "./providers/google-gemini-cli-usag
 import { getEnvApiKey } from "./stream";
 import type { Provider } from "./types";
 import type {
+	CredentialRankingStrategy,
 	UsageCache,
 	UsageCacheEntry,
 	UsageCredential,
@@ -23,11 +24,11 @@ import type {
 	UsageProvider,
 	UsageReport,
 } from "./usage";
-import { claudeUsageProvider } from "./usage/claude";
+import { claudeRankingStrategy, claudeUsageProvider } from "./usage/claude";
 import { githubCopilotUsageProvider } from "./usage/github-copilot";
 import { antigravityUsageProvider } from "./usage/google-antigravity";
 import { kimiUsageProvider } from "./usage/kimi";
-import { openaiCodexUsageProvider } from "./usage/openai-codex";
+import { codexRankingStrategy, openaiCodexUsageProvider } from "./usage/openai-codex";
 import { zaiUsageProvider } from "./usage/zai";
 import { getOAuthApiKey, getOAuthProvider } from "./utils/oauth";
 // Re-export login functions so consumers of AuthStorage.login() have access
@@ -114,6 +115,7 @@ export interface StoredAuthCredential {
 
 export type AuthStorageOptions = {
 	usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
+	rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
 	usageCache?: UsageCache;
 	usageFetch?: typeof fetch;
 	usageNow?: () => number;
@@ -163,6 +165,15 @@ function resolveDefaultUsageProvider(provider: Provider): UsageProvider | undefi
 	return DEFAULT_USAGE_PROVIDER_MAP.get(provider);
 }
 
+const DEFAULT_RANKING_STRATEGIES = new Map<Provider, CredentialRankingStrategy>([
+	["openai-codex", codexRankingStrategy],
+	["anthropic", claudeRankingStrategy],
+]);
+
+function resolveDefaultRankingStrategy(provider: Provider): CredentialRankingStrategy | undefined {
+	return DEFAULT_RANKING_STRATEGIES.get(provider);
+}
+
 function parseUsageCacheEntry(raw: string): UsageCacheEntry | undefined {
 	try {
 		const parsed = JSON.parse(raw) as { value?: UsageReport | null; expiresAt?: unknown };
@@ -228,6 +239,7 @@ export class AuthStorage {
 	/** Maps provider:type -> credentialIndex -> blockedUntilMs for temporary backoff. */
 	#credentialBackoff: Map<string, Map<number, number>> = new Map();
 	#usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
+	#rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
 	#usageCache?: UsageCache;
 	#usageFetch: typeof fetch;
 	#usageNow: () => number;
@@ -240,6 +252,7 @@ export class AuthStorage {
 		this.#store = store;
 		this.#configValueResolver = options.configValueResolver ?? defaultConfigValueResolver;
 		this.#usageProviderResolver = options.usageProviderResolver ?? resolveDefaultUsageProvider;
+		this.#rankingStrategyResolver = options.rankingStrategyResolver ?? resolveDefaultRankingStrategy;
 		this.#usageCache = options.usageCache ?? new AuthStorageUsageCache(this.#store);
 		this.#usageFetch = options.usageFetch ?? fetch;
 		this.#usageNow = options.usageNow ?? Date.now;
@@ -499,20 +512,25 @@ export class AuthStorage {
 		return order;
 	}
 
-	/** Checks if a credential is temporarily blocked due to usage limits. */
-	#isCredentialBlocked(providerKey: string, credentialIndex: number): boolean {
+	/** Returns block expiry timestamp for a credential, cleaning up expired entries. */
+	#getCredentialBlockedUntil(providerKey: string, credentialIndex: number): number | undefined {
 		const backoffMap = this.#credentialBackoff.get(providerKey);
-		if (!backoffMap) return false;
+		if (!backoffMap) return undefined;
 		const blockedUntil = backoffMap.get(credentialIndex);
-		if (!blockedUntil) return false;
+		if (!blockedUntil) return undefined;
 		if (blockedUntil <= Date.now()) {
 			backoffMap.delete(credentialIndex);
 			if (backoffMap.size === 0) {
 				this.#credentialBackoff.delete(providerKey);
 			}
-			return false;
+			return undefined;
 		}
-		return true;
+		return blockedUntil;
+	}
+
+	/** Checks if a credential is temporarily blocked due to usage limits. */
+	#isCredentialBlocked(providerKey: string, credentialIndex: number): boolean {
+		return this.#getCredentialBlockedUntil(providerKey, credentialIndex) !== undefined;
 	}
 
 	/** Marks a credential as blocked until the specified time. */
@@ -1273,7 +1291,7 @@ export class AuthStorage {
 		const now = this.#usageNow();
 		let blockedUntil = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
 
-		if (provider === "openai-codex" && sessionCredential.type === "oauth") {
+		if (sessionCredential.type === "oauth" && this.#rankingStrategyResolver?.(provider)) {
 			const credential = this.#getCredentialsForProvider(provider)[sessionCredential.index];
 			if (credential?.type === "oauth") {
 				const report = await this.#getUsageReport(provider, credential, options);
@@ -1298,6 +1316,148 @@ export class AuthStorage {
 		return remainingCredentials.some(candidate => !this.#isCredentialBlocked(providerKey, candidate.index));
 	}
 
+	#resolveWindowResetInMs(window: UsageLimit["window"], nowMs: number): number | undefined {
+		if (!window) return undefined;
+		if (typeof window.resetInMs === "number" && Number.isFinite(window.resetInMs)) {
+			return window.resetInMs;
+		}
+		if (typeof window.resetsAt === "number" && Number.isFinite(window.resetsAt)) {
+			return window.resetsAt - nowMs;
+		}
+		return undefined;
+	}
+
+	#normalizeUsageFraction(limit: UsageLimit | undefined): number {
+		const usedFraction = limit?.amount.usedFraction;
+		if (typeof usedFraction !== "number" || !Number.isFinite(usedFraction)) {
+			return 0.5;
+		}
+		return Math.min(Math.max(usedFraction, 0), 1);
+	}
+
+	/** Computes `usedFraction / elapsedHours` — consumption rate per hour within the current window. Lower drain rate = less pressure = preferred. */
+	#computeWindowDrainRate(limit: UsageLimit | undefined, nowMs: number, fallbackDurationMs: number): number {
+		const usedFraction = this.#normalizeUsageFraction(limit);
+		const durationMs = limit?.window?.durationMs ?? fallbackDurationMs;
+		if (!Number.isFinite(durationMs) || durationMs <= 0) {
+			return usedFraction;
+		}
+		const resetInMs = this.#resolveWindowResetInMs(limit?.window, nowMs);
+		if (!Number.isFinite(resetInMs)) {
+			return usedFraction;
+		}
+		const clampedResetInMs = Math.min(Math.max(resetInMs as number, 0), durationMs);
+		const elapsedMs = durationMs - clampedResetInMs;
+		if (elapsedMs <= 0) {
+			return usedFraction;
+		}
+		const elapsedHours = elapsedMs / (60 * 60 * 1000);
+		if (!Number.isFinite(elapsedHours) || elapsedHours <= 0) {
+			return usedFraction;
+		}
+		return usedFraction / elapsedHours;
+	}
+
+	async #rankOAuthSelections(args: {
+		providerKey: string;
+		provider: string;
+		order: number[];
+		credentials: Array<{ credential: OAuthCredential; index: number }>;
+		options?: { baseUrl?: string };
+		strategy: CredentialRankingStrategy;
+	}): Promise<
+		Array<{
+			selection: { credential: OAuthCredential; index: number };
+			usage: UsageReport | null;
+			usageChecked: boolean;
+		}>
+	> {
+		const nowMs = this.#usageNow();
+		const { strategy } = args;
+		const ranked: Array<{
+			selection: { credential: OAuthCredential; index: number };
+			usage: UsageReport | null;
+			usageChecked: boolean;
+			blocked: boolean;
+			blockedUntil?: number;
+			hasPriorityBoost: boolean;
+			secondaryUsed: number;
+			secondaryDrainRate: number;
+			primaryUsed: number;
+			primaryDrainRate: number;
+			orderPos: number;
+		}> = [];
+		// Pre-fetch usage reports in parallel for non-blocked credentials
+		const usageResults = await Promise.all(
+			args.order.map(async idx => {
+				const selection = args.credentials[idx];
+				if (!selection) return null;
+				const blockedUntil = this.#getCredentialBlockedUntil(args.providerKey, selection.index);
+				if (blockedUntil !== undefined) return { selection, usage: null, usageChecked: false, blockedUntil };
+				const usage = await this.#getUsageReport(args.provider, selection.credential, args.options);
+				return { selection, usage, usageChecked: true, blockedUntil: undefined as number | undefined };
+			}),
+		);
+
+		for (let orderPos = 0; orderPos < usageResults.length; orderPos += 1) {
+			const result = usageResults[orderPos];
+			if (!result) continue;
+			const { selection, usage, usageChecked } = result;
+			let { blockedUntil } = result;
+			let blocked = blockedUntil !== undefined;
+			if (!blocked && usage && this.#isUsageLimitReached(usage)) {
+				const resetAtMs = this.#getUsageResetAtMs(usage, nowMs);
+				blockedUntil = resetAtMs ?? nowMs + AuthStorage.#defaultBackoffMs;
+				this.#markCredentialBlocked(args.providerKey, selection.index, blockedUntil);
+				blocked = true;
+			}
+			const windows = usage ? strategy.findWindowLimits(usage) : undefined;
+			const primary = windows?.primary;
+			const secondary = windows?.secondary;
+			const secondaryTarget = secondary ?? primary;
+			ranked.push({
+				selection,
+				usage,
+				usageChecked,
+				blocked,
+				blockedUntil,
+				hasPriorityBoost: strategy.hasPriorityBoost?.(primary) ?? false,
+				secondaryUsed: this.#normalizeUsageFraction(secondaryTarget),
+				secondaryDrainRate: this.#computeWindowDrainRate(
+					secondaryTarget,
+					nowMs,
+					strategy.windowDefaults.secondaryMs,
+				),
+				primaryUsed: this.#normalizeUsageFraction(primary),
+				primaryDrainRate: this.#computeWindowDrainRate(primary, nowMs, strategy.windowDefaults.primaryMs),
+				orderPos,
+			});
+		}
+		ranked.sort((left, right) => {
+			if (left.blocked !== right.blocked) return left.blocked ? 1 : -1;
+			if (left.blocked && right.blocked) {
+				const leftBlockedUntil = left.blockedUntil ?? Number.POSITIVE_INFINITY;
+				const rightBlockedUntil = right.blockedUntil ?? Number.POSITIVE_INFINITY;
+				if (leftBlockedUntil !== rightBlockedUntil) return leftBlockedUntil - rightBlockedUntil;
+				return left.orderPos - right.orderPos;
+			}
+			if (left.hasPriorityBoost !== right.hasPriorityBoost) {
+				return left.hasPriorityBoost ? -1 : 1;
+			}
+			if (left.secondaryDrainRate !== right.secondaryDrainRate)
+				return left.secondaryDrainRate - right.secondaryDrainRate;
+			if (left.secondaryUsed !== right.secondaryUsed) return left.secondaryUsed - right.secondaryUsed;
+			if (left.primaryDrainRate !== right.primaryDrainRate) return left.primaryDrainRate - right.primaryDrainRate;
+			if (left.primaryUsed !== right.primaryUsed) return left.primaryUsed - right.primaryUsed;
+			return left.orderPos - right.orderPos;
+		});
+		return ranked.map(candidate => ({
+			selection: candidate.selection,
+			usage: candidate.usage,
+			usageChecked: candidate.usageChecked,
+		}));
+	}
+
 	/**
 	 * Resolves an OAuth API key, trying credentials in priority order.
 	 * Skips blocked credentials and checks usage limits for providers with usage data.
@@ -1316,25 +1476,33 @@ export class AuthStorage {
 
 		const providerKey = this.#getProviderTypeKey(provider, "oauth");
 		const order = this.#getCredentialOrder(providerKey, sessionId, credentials.length);
-		const fallback = credentials[order[0]];
-		const checkUsage = provider === "openai-codex" && credentials.length > 1;
-
-		for (const idx of order) {
-			const selection = credentials[idx];
-			const apiKey = await this.#tryOAuthCredential(
-				provider,
-				selection,
-				providerKey,
-				sessionId,
-				options,
+		const strategy = this.#rankingStrategyResolver?.(provider);
+		const checkUsage = strategy !== undefined && credentials.length > 1;
+		const candidates = checkUsage
+			? await this.#rankOAuthSelections({ providerKey, provider, order, credentials, options, strategy })
+			: order
+					.map(idx => credentials[idx])
+					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
+					.map(selection => ({ selection, usage: null, usageChecked: false }));
+		const fallback = candidates[0];
+
+		for (const candidate of candidates) {
+			const apiKey = await this.#tryOAuthCredential(provider, candidate.selection, providerKey, sessionId, options, {
 				checkUsage,
-				false,
-			);
+				allowBlocked: false,
+				prefetchedUsage: candidate.usage,
+				usagePrechecked: candidate.usageChecked,
+			});
 			if (apiKey) return apiKey;
 		}
 
-		if (fallback && this.#isCredentialBlocked(providerKey, fallback.index)) {
-			return this.#tryOAuthCredential(provider, fallback, providerKey, sessionId, options, checkUsage, true);
+		if (fallback && this.#isCredentialBlocked(providerKey, fallback.selection.index)) {
+			return this.#tryOAuthCredential(provider, fallback.selection, providerKey, sessionId, options, {
+				checkUsage,
+				allowBlocked: true,
+				prefetchedUsage: fallback.usage,
+				usagePrechecked: fallback.usageChecked,
+			});
 		}
 
 		return undefined;
@@ -1342,14 +1510,19 @@ export class AuthStorage {
 
 	/** Attempts to use a single OAuth credential, checking usage and refreshing token. */
 	async #tryOAuthCredential(
-		provider: string,
+		provider: Provider,
 		selection: { credential: OAuthCredential; index: number },
 		providerKey: string,
 		sessionId: string | undefined,
 		options: { baseUrl?: string } | undefined,
-		checkUsage: boolean,
-		allowBlocked: boolean,
+		usageOptions: {
+			checkUsage: boolean;
+			allowBlocked: boolean;
+			prefetchedUsage?: UsageReport | null;
+			usagePrechecked?: boolean;
+		},
 	): Promise<string | undefined> {
+		const { checkUsage, allowBlocked, prefetchedUsage = null, usagePrechecked = false } = usageOptions;
 		if (!allowBlocked && this.#isCredentialBlocked(providerKey, selection.index)) {
 			return undefined;
 		}
@@ -1358,8 +1531,13 @@ export class AuthStorage {
 		let usageChecked = false;
 
 		if (checkUsage && !allowBlocked) {
-			usage = await this.#getUsageReport(provider, selection.credential, options);
-			usageChecked = true;
+			if (usagePrechecked) {
+				usage = prefetchedUsage;
+				usageChecked = true;
+			} else {
+				usage = await this.#getUsageReport(provider, selection.credential, options);
+				usageChecked = true;
+			}
 			if (usage && this.#isUsageLimitReached(usage)) {
 				const resetAtMs = this.#getUsageResetAtMs(usage, this.#usageNow());
 				this.#markCredentialBlocked(

package/src/index.ts

@@ -35,5 +35,5 @@ export * from "./utils/event-stream";
 export * from "./utils/oauth";
 export * from "./utils/overflow";
 export * from "./utils/retry";
-export * from "./utils/typebox-helpers";
+export * from "./utils/schema";
 export * from "./utils/validation";