@oh-my-pi/pi-ai 16.3.13 → 16.3.15

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [16.3.15] - 2026-07-09
+
+### Breaking Changes
+
+- Renamed `OpenAIResponsesCacheOptions`, `normalizeOpenAIResponsesPromptCacheKey`, and `getOpenAIResponsesPromptCacheKey` to the endpoint-neutral `OpenAICacheOptions`, `normalizeOpenAIPromptCacheKey`, and `getOpenAIPromptCacheKey`.
+
+### Added
+
+- Added automatic prompt-cache affinity header injection for OpenAI-family chat completions
+- Added support for explicit prompt-cache affinity headers in OpenAI-family chat completions
+- Added OpenAI pro reasoning mode support: models carrying the catalog `reasoningMode: "pro"` marker (GPT-5.6 Pro aliases) send `reasoning: { mode: "pro" }` on OpenAI Responses and Codex Responses requests, alongside the configured effort. The Codex request body now honors `requestModelId` so catalog aliases request the base upstream model id.
+
+### Changed
+
+- Updated xAI OAuth to use a dedicated device-code flow instead of redirect/loopback server
+
+### Fixed
+
+- Improved account routing for GPT-5.6 models to better respect paid tier requirements
+- Refined account selection logic to correctly identify plan types from account metadata
+- Fixed OpenAI Codex multi-account routing for GPT-5.6: Sol and Luna requests now prefer Plus-or-higher accounts while Terra remains available to Free/Go accounts; local pro-mode aliases inherit their base model's Codex plan eligibility.
+- Fixed xAI Grok OAuth login to use xAI's device authorization flow: `/login` now opens the verification URL, displays the device code, and polls for approval instead of asking for a pasted redirect or linking to Hermes Agent documentation.
+
+## [16.3.14] - 2026-07-09
+
+### Changed
+
+- Updated Codex reasoning effort mapping to support shifted wire tiers for newer models
+
+### Fixed
+
+- Fixed the Codex Responses request transformer bypassing catalog/compat reasoning effort maps: the clamped user effort is now remapped to the provider wire tier (GPT-5.6's shifted five-tier scale sends `max` for user `xhigh` and `xhigh` for `high`), failing loudly if a map produces a value outside the Codex wire vocabulary.
+
 ## [16.3.13] - 2026-07-09
 
 ### Changed

package/dist/types/providers/openai-codex/request-transformer.d.ts

@@ -1,13 +1,18 @@
-import type { Api, Model } from "../../types.js";
+import type { Model } from "../../types.js";
 /** Reasoning replay scope for the Codex Responses API (`reasoning.context`). */
 export type CodexReasoningContext = "auto" | "current_turn" | "all_turns";
+/** User-facing effort levels accepted by Codex request options. */
+type CodexCallerEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
 export interface ReasoningConfig {
-    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     summary?: "auto" | "concise" | "detailed";
     context?: CodexReasoningContext;
+    /** Pro reasoning serving mode (gpt-5.6+ catalog pro aliases). */
+    mode?: "pro";
 }
 export interface CodexRequestOptions {
-    reasoningEffort?: ReasoningConfig["effort"];
+    /** User-facing effort; the wire-only `max` tier is reached via the model's effort map. */
+    reasoningEffort?: CodexCallerEffort | "none";
     reasoningSummary?: ReasoningConfig["summary"] | null;
     /** Explicit `reasoning.context` override; defaults to `all_turns` when unset. The `all_turns` value is gated to gpt-5.4+ Codex models — older ids reject it, so it is suppressed and `context` omitted. */
     reasoningContext?: CodexReasoningContext;
@@ -49,6 +54,7 @@ export interface RequestBody {
 }
 /** Returns whether a Codex request can use the text-only Responses Lite transport. */
 export declare function shouldUseCodexResponsesLite(body: RequestBody, requested: boolean | undefined): boolean;
-export declare function transformRequestBody(body: RequestBody, model: Model<Api>, options?: CodexRequestOptions, prompt?: {
+export declare function transformRequestBody(body: RequestBody, model: Model<"openai-codex-responses">, options?: CodexRequestOptions, prompt?: {
     developerMessages: string[];
 }): Promise<RequestBody>;
+export {};

package/dist/types/providers/openai-responses-wire.d.ts

@@ -6008,6 +6008,13 @@ export interface Reasoning {
      * - `xhigh` is supported for all models after `gpt-5.1-codex-max`.
      */
     effort?: ReasoningEffort | null;
+    /**
+     * **gpt-5.6 and later models only**
+     *
+     * Reasoning serving mode. `pro` routes the request to the pro reasoning
+     * path (more compute per response); omit for the standard path.
+     */
+    mode?: "pro" | null;
     /**
      * @deprecated **Deprecated:** use `summary` instead.
      *

package/dist/types/providers/openai-shared.d.ts

@@ -1,3 +1,4 @@
+import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import type { OpenAICompat, OpenAIReasoningDisableMode, OpenAIStreamMarkupHealingPattern, OpenRouterRouting, ResolvedOpenAICompat, ResolvedOpenAIResponsesCompat, ResolvedOpenAISharedCompat, VercelGatewayRouting } from "@oh-my-pi/pi-catalog/types";
 import { type Api, type AssistantMessage, type CacheRetention, type Context, type ImageContent, type Message, type MessageAttribution, type Model, type ServiceTier, type StopReason, type StreamOptions, type TextContent, type TextSignatureV1, type ThinkingContent, type Tool, type ToolCall, type ToolResultMessage, type Usage } from "../types.js";
 import { kStreamingLastParseLen, kStreamingPartialJson } from "../utils/block-symbols.js";
@@ -26,7 +27,8 @@ export interface OpenAIRequestSetupModel extends OpenAIModelIdentity {
     premiumMultiplier?: number;
     compat?: Pick<ResolvedOpenAISharedCompat, "promptCacheSessionHeader">;
 }
-export interface OpenAIResponsesCacheOptions {
+/** Cache identity controls shared by OpenAI-family transports. */
+export interface OpenAICacheOptions {
     cacheRetention?: CacheRetention;
     sessionId?: string;
     promptCacheKey?: string;
@@ -85,11 +87,13 @@ export interface OpenAIUsageAccounting {
     orchestration?: Usage["orchestration"];
 }
 export declare function calculateOpenAIUsageAccounting(accounting: OpenAIUsageAccountingInput): OpenAIUsageAccounting;
-export declare function normalizeOpenAIResponsesPromptCacheKey(sessionId: string | undefined): string | undefined;
+/** Normalize a cache identity to the wire limit accepted by OpenAI-family providers. */
+export declare function normalizeOpenAIPromptCacheKey(sessionId: string | undefined): string | undefined;
 export declare function normalizeOpenRouterResponsesSessionId(sessionId: string | undefined): string | undefined;
-export declare function getOpenAIResponsesPromptCacheKey(options: OpenAIResponsesCacheOptions | undefined): string | undefined;
-export declare function getOpenAIResponsesRoutingSessionId(options: Pick<OpenAIResponsesCacheOptions, "cacheRetention" | "sessionId"> | undefined): string | undefined;
-export declare function getOpenRouterResponsesSessionId(options: Pick<OpenAIResponsesCacheOptions, "cacheRetention" | "sessionId"> | undefined): string | undefined;
+/** Resolve a prompt-cache identity, falling back to the provider session unless caching is disabled. */
+export declare function getOpenAIPromptCacheKey(options: OpenAICacheOptions | undefined): string | undefined;
+export declare function getOpenAIResponsesRoutingSessionId(options: Pick<OpenAICacheOptions, "cacheRetention" | "sessionId"> | undefined): string | undefined;
+export declare function getOpenRouterResponsesSessionId(options: Pick<OpenAICacheOptions, "cacheRetention" | "sessionId"> | undefined): string | undefined;
 export declare function parseAzureDeploymentNameMap(value: string | undefined): Map<string, string>;
 export declare function createOpenAIStrictToolsState(): OpenAIStrictToolsState;
 export declare function clearOpenAIStrictToolsState(state: OpenAIStrictToolsState): void;
@@ -275,6 +279,15 @@ export interface OpenAICompatPolicy {
         emptyLengthFinishIsContextError: boolean;
     };
 }
+/**
+ * Map a user-facing effort to the provider wire value: explicit compat
+ * override first, then the model's baked `thinking.effortMap`, else identity.
+ * Shared by the chat-completions/Responses policy resolver and the Codex
+ * request transformer.
+ */
+export declare function mapOpenAIReasoningEffort(model: Pick<Model, "thinking">, compat: {
+    reasoningEffortMap?: Partial<Record<Effort, string>>;
+} | undefined, effort: string): string;
 export declare function resolveOpenAICompatPolicy<TApi extends Api>(model: Model<TApi>, options: ResolveOpenAICompatPolicyOptions): OpenAICompatPolicy;
 export declare function applyChatCompletionsCompatPolicy(params: OpenAICompletionsParams, policy: OpenAICompatPolicy): void;
 export declare function applyChatCompletionsReasoningParams(params: OpenAICompletionsParams, model: Model<"openai-completions">, compat: ResolvedOpenAICompat, options: (ChatCompletionsReasoningOptions & {

package/dist/types/registry/oauth/device-code.d.ts

@@ -0,0 +1,25 @@
+/** Result returned by one OAuth device-code polling attempt. */
+export type OAuthDeviceCodePollResult<T> = {
+    status: "complete";
+    value: T;
+} | {
+    status: "pending";
+} | {
+    status: "slow_down";
+} | {
+    status: "failed";
+    message: string;
+};
+/** Options for polling an RFC 8628-style OAuth device-code flow. */
+export interface OAuthDeviceCodeFlowOptions<T> {
+    /** Poll the provider once and classify the response. */
+    poll(): OAuthDeviceCodePollResult<T> | Promise<OAuthDeviceCodePollResult<T>>;
+    /** Provider-requested polling cadence; defaults to RFC 8628's five seconds. */
+    intervalSeconds?: number;
+    /** Provider-issued expiry window for the device code. */
+    expiresInSeconds?: number;
+    /** Cancels the flow with the legacy "Login cancelled" error. */
+    signal?: AbortSignal;
+}
+/** Poll an OAuth device-code flow until completion, provider failure, timeout, or cancellation. */
+export declare function pollOAuthDeviceCodeFlow<T>(options: OAuthDeviceCodeFlowOptions<T>): Promise<T>;

package/dist/types/registry/oauth/index.d.ts

@@ -1,30 +1,6 @@
 import type { OAuthCredentials, OAuthProvider, OAuthProviderId, OAuthProviderInfo, OAuthProviderInterface } from "./types.js";
+export * from "./device-code.js";
 export type * from "./types.js";
-/** Result returned by one OAuth device-code polling attempt. */
-export type OAuthDeviceCodePollResult<T> = {
-    status: "complete";
-    value: T;
-} | {
-    status: "pending";
-} | {
-    status: "slow_down";
-} | {
-    status: "failed";
-    message: string;
-};
-/** Options for polling an RFC 8628-style OAuth device-code flow. */
-export interface OAuthDeviceCodeFlowOptions<T> {
-    /** Poll the provider once and classify the response. */
-    poll(): OAuthDeviceCodePollResult<T> | Promise<OAuthDeviceCodePollResult<T>>;
-    /** Provider-requested polling cadence; defaults to RFC 8628's five seconds. */
-    intervalSeconds?: number;
-    /** Provider-issued expiry window for the device code. */
-    expiresInSeconds?: number;
-    /** Cancels the flow with the legacy "Login cancelled" error. */
-    signal?: AbortSignal;
-}
-/** Poll an OAuth device-code flow until completion, provider failure, timeout, or cancellation. */
-export declare function pollOAuthDeviceCodeFlow<T>(options: OAuthDeviceCodeFlowOptions<T>): Promise<T>;
 /**
  * Register a custom OAuth provider.
  */

package/dist/types/registry/oauth/xai-oauth.d.ts

@@ -1,14 +1,11 @@
 import type { FetchImpl } from "../../types.js";
-import { OAuthCallbackFlow } from "./callback-server.js";
 import type { OAuthController, OAuthCredentials } from "./types.js";
 /**
- * Validate an xAI OIDC discovery endpoint against scheme + host.
+ * Validate an xAI OIDC endpoint against its scheme and host.
  *
- * Hermes `_xai_validate_oauth_endpoint` L2997-3035. The discovery response is
- * long-lived and cached in {@link OAuthCredentials}; a single MITM during
- * initial login could substitute a malicious `token_endpoint` that would then
- * receive every future refresh_token. Rejecting non-HTTPS or non-`x.ai` /
- * `*.x.ai` hosts pins the cached endpoint to the xAI auth origin.
+ * The discovery response is long-lived and its token endpoint receives every
+ * future refresh token. Rejecting non-HTTPS or non-`x.ai` / `*.x.ai` hosts
+ * pins that endpoint to the xAI auth origin.
  *
  * @throws Error with message `Invalid xAI <field>: <url>` when the URL fails
  *         either scheme or host validation.
@@ -18,29 +15,16 @@ export declare function validateXAIEndpoint(url: string, field: string): string;
  * Check whether a JWT access token is at or past its `exp` claim (with an
  * optional refresh-skew margin).
  *
- * Hermes `_xai_access_token_is_expiring` L2979-2994. Returns `false` for any
- * malformed input — this is a refresh-trigger check, not a validation, so
- * non-JWTs ("no token in cache") must NOT trigger a spurious refresh.
+ * Returns `false` for malformed input because this is a refresh-trigger check,
+ * not token validation.
  */
 export declare function isXAIAccessTokenExpiring(jwt: string, skewSeconds?: number): boolean;
-/**
- * xAI Grok OAuth code flow (Hermes `_xai_oauth_loopback_login` L5315-5469).
- */
-export declare class XAIOAuthFlow extends OAuthCallbackFlow {
-    #private;
-    constructor(ctrl: OAuthController);
-    generateAuthUrl(state: string, redirectUri: string): Promise<{
-        url: string;
-        instructions?: string;
-    }>;
-    exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials>;
-}
+/** Log in to xAI Grok with the RFC 8628 device authorization grant. */
 export declare function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCredentials>;
 /**
  * Refresh an xAI OAuth access token using a stored refresh_token.
  *
- * Hermes `refresh_xai_oauth_pure` L3087-3160. Re-runs OIDC discovery and
- * re-validates the cached `token_endpoint` on the refresh hot path so a
- * cached-but-poisoned endpoint cannot silently leak a refresh_token.
+ * Re-runs OIDC discovery and re-validates the token endpoint before sending
+ * the stored refresh token.
  */
 export declare function refreshXAIOAuthToken(refreshToken: string, fetchOverride?: FetchImpl): Promise<OAuthCredentials>;

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

@@ -268,7 +268,6 @@ declare const ALL: ({
     readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<import("./oauth/index.js").OAuthCredentials>;
     readonly refreshToken: (credentials: import("./oauth/index.js").OAuthCredentials) => Promise<import("./oauth/index.js").OAuthCredentials>;
-    readonly pasteCodeFlow: true;
 } | {
     readonly id: "xiaomi";
     readonly name: "Xiaomi MiMo";

package/dist/types/registry/xai-oauth.d.ts

@@ -4,5 +4,4 @@ export declare const xaiOauthProvider: {
     readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: OAuthLoginCallbacks) => Promise<OAuthCredentials>;
     readonly refreshToken: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
-    readonly pasteCodeFlow: true;
 };

package/dist/types/types.d.ts

@@ -231,9 +231,9 @@ export interface StreamOptions {
      */
     sessionId?: string;
     /**
-     * Optional prompt-cache identity. When set, OpenAI Responses-compatible
-     * providers use this for `prompt_cache_key` while keeping `sessionId` for
-     * provider routing / conversation headers.
+     * Optional prompt-cache identity. OpenAI-family providers use this for
+     * `prompt_cache_key` payloads and cache-affinity headers such as
+     * `x-grok-conv-id`; when omitted, they fall back to `sessionId`.
      */
     promptCacheKey?: string;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.3.13",
+	"version": "16.3.15",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.3.13",
-		"@oh-my-pi/pi-utils": "16.3.13",
-		"@oh-my-pi/pi-wire": "16.3.13",
+		"@oh-my-pi/pi-catalog": "16.3.15",
+		"@oh-my-pi/pi-utils": "16.3.15",
+		"@oh-my-pi/pi-wire": "16.3.15",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-gateway/server.ts

@@ -112,8 +112,8 @@ function deriveSessionId(modelId: string, context: Context): string {
 		parts.push(JSON.stringify({ role: first.role, content: first.content }));
 	}
 	const seed = parts.join("\u0000");
-	// The 36-char UUID flows through unchanged: Codex's
-	// `normalizeOpenAIResponsesPromptCacheKey` accepts ≤64 chars verbatim.
+	// The 36-char UUID flows through unchanged:
+	// `normalizeOpenAIPromptCacheKey` accepts ≤64 chars verbatim.
 	return deterministicUuid(seed);
 }
 

package/src/auth-storage.ts

@@ -761,25 +761,82 @@ function isAbortSignalOption(
 	return typeof value === "object" && value !== null && "aborted" in value && "addEventListener" in value;
 }
 
-function requiresOpenAICodexProModel(provider: string, modelId: string | undefined): boolean {
-	return provider === "openai-codex" && typeof modelId === "string" && modelId.includes("-spark");
+type OpenAICodexPlanRequirement = "none" | "paid" | "pro";
+type OpenAICodexPlanClass = "free" | "paid" | "pro" | "unknown";
+
+const GPT_56_PAID_CODEX_MODEL_PATTERN = /^gpt-5\.6-(?:sol|luna)(?:-pro)?$/;
+const OPENAI_CODEX_PRO_PLAN_TOKENS: Record<string, true> = {
+	pro: true,
+};
+const OPENAI_CODEX_PAID_PLAN_TOKENS: Record<string, true> = {
+	plus: true,
+	business: true,
+	team: true,
+	enterprise: true,
+	edu: true,
+	education: true,
+	teacher: true,
+	teachers: true,
+	health: true,
+	gov: true,
+	government: true,
+};
+const OPENAI_CODEX_FREE_PLAN_TOKENS: Record<string, true> = {
+	free: true,
+	go: true,
+};
+
+/**
+ * Account tier needed for model-aware Codex OAuth routing.
+ *
+ * GPT-5.6 Terra (including its local pro-mode alias) remains available on every
+ * plan. Sol and Luna pro-mode aliases inherit their base models' paid tier;
+ * only Spark currently has a documented Pro-plan preference in Codex.
+ */
+function resolveOpenAICodexPlanRequirement(provider: string, modelId: string | undefined): OpenAICodexPlanRequirement {
+	if (provider !== "openai-codex" || typeof modelId !== "string") return "none";
+	const separator = modelId.lastIndexOf("/");
+	const bareModelId = (separator === -1 ? modelId : modelId.slice(separator + 1)).toLowerCase();
+	if (bareModelId.includes("-spark")) return "pro";
+	if (bareModelId === "gpt-5.6" || GPT_56_PAID_CODEX_MODEL_PATTERN.test(bareModelId)) return "paid";
+	return "none";
 }
 
 function getUsagePlanType(report: UsageReport | null): string | undefined {
 	const metadata = report?.metadata;
-	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
-	const planType = (metadata as { planType?: unknown }).planType;
-	return typeof planType === "string" ? planType.toLowerCase() : undefined;
+	if (!metadata) return undefined;
+	const planType = metadata.planType;
+	if (typeof planType !== "string") return undefined;
+	const normalized = planType
+		.trim()
+		.toLowerCase()
+		.replace(/[\s-]+/g, "_");
+	return normalized.startsWith("chatgpt_") ? normalized.slice("chatgpt_".length) : normalized;
 }
 
-function getOpenAICodexPlanPriority(report: UsageReport | null): number {
+function classifyOpenAICodexPlan(report: UsageReport | null): OpenAICodexPlanClass {
 	const planType = getUsagePlanType(report);
-	if (!planType) return 1;
-	return planType.includes("pro") ? 0 : 2;
+	if (!planType) return "unknown";
+	const tokens = planType.split("_");
+	if (tokens.some(token => OPENAI_CODEX_PRO_PLAN_TOKENS[token] === true)) return "pro";
+	if (tokens.some(token => OPENAI_CODEX_PAID_PLAN_TOKENS[token] === true)) return "paid";
+	if (tokens.some(token => OPENAI_CODEX_FREE_PLAN_TOKENS[token] === true)) return "free";
+	return "unknown";
+}
+
+function getOpenAICodexPlanEligibility(
+	report: UsageReport | null,
+	requirement: OpenAICodexPlanRequirement,
+): boolean | undefined {
+	if (requirement === "none") return true;
+	const planClass = classifyOpenAICodexPlan(report);
+	if (planClass === "unknown") return undefined;
+	return requirement === "paid" ? planClass !== "free" : planClass === "pro";
 }
 
-function hasOpenAICodexProPlan(report: UsageReport | null): boolean {
-	return getUsagePlanType(report)?.includes("pro") === true;
+function getOpenAICodexPlanPriority(report: UsageReport | null, requirement: OpenAICodexPlanRequirement): number {
+	const eligibility = getOpenAICodexPlanEligibility(report, requirement);
+	return eligibility === true ? 0 : eligibility === undefined ? 1 : 2;
 }
 
 function compareUsageRankingMetric(left: number, right: number): number {
@@ -3186,8 +3243,7 @@ export class AuthStorage {
 	#compareRankedOAuthCandidatePriority(
 		left: RankedOAuthCandidate,
 		right: RankedOAuthCandidate,
-		provider: string,
-		modelId: string | undefined,
+		planRequirement: OpenAICodexPlanRequirement,
 	): number {
 		if (left.blocked !== right.blocked) return left.blocked ? 1 : -1;
 		if (left.blocked && right.blocked) {
@@ -3196,7 +3252,7 @@ export class AuthStorage {
 			if (leftBlockedUntil !== rightBlockedUntil) return leftBlockedUntil - rightBlockedUntil;
 			return 0;
 		}
-		if (requiresOpenAICodexProModel(provider, modelId) && left.planPriority !== right.planPriority) {
+		if (planRequirement !== "none" && left.planPriority !== right.planPriority) {
 			return left.planPriority - right.planPriority;
 		}
 		if (left.hasPriorityBoost !== right.hasPriorityBoost) return left.hasPriorityBoost ? -1 : 1;
@@ -3214,20 +3270,18 @@ export class AuthStorage {
 	#compareRankedOAuthCandidates(
 		left: RankedOAuthCandidate,
 		right: RankedOAuthCandidate,
-		provider: string,
-		modelId: string | undefined,
+		planRequirement: OpenAICodexPlanRequirement,
 	): number {
-		const priority = this.#compareRankedOAuthCandidatePriority(left, right, provider, modelId);
+		const priority = this.#compareRankedOAuthCandidatePriority(left, right, planRequirement);
 		return priority !== 0 ? priority : left.orderPos - right.orderPos;
 	}
 
 	#orderRankedOAuthCandidates(
 		candidates: RankedOAuthCandidate[],
 		sessionId: string | undefined,
-		provider: string,
-		modelId: string | undefined,
+		planRequirement: OpenAICodexPlanRequirement,
 	): OAuthCandidate[] {
-		candidates.sort((left, right) => this.#compareRankedOAuthCandidates(left, right, provider, modelId));
+		candidates.sort((left, right) => this.#compareRankedOAuthCandidates(left, right, planRequirement));
 		if (!sessionId) {
 			return candidates.map(candidate => ({
 				selection: candidate.selection,
@@ -3252,7 +3306,7 @@ export class AuthStorage {
 		for (const candidate of unblocked) {
 			if (
 				candidate !== previous &&
-				this.#compareRankedOAuthCandidatePriority(previous, candidate, provider, modelId) !== 0
+				this.#compareRankedOAuthCandidatePriority(previous, candidate, planRequirement) !== 0
 			) {
 				bucketIndex += 1;
 			}
@@ -3297,6 +3351,7 @@ export class AuthStorage {
 		providerKey: string;
 		provider: string;
 		order: number[];
+		planRequirement: OpenAICodexPlanRequirement;
 		credentials: OAuthSelection[];
 		options?: AuthApiKeyOptions;
 		sessionId?: string;
@@ -3378,7 +3433,7 @@ export class AuthStorage {
 				blocked,
 				blockedUntil,
 				hasPriorityBoost: strategy.hasPriorityBoost?.(primary) ?? false,
-				planPriority: getOpenAICodexPlanPriority(usage),
+				planPriority: getOpenAICodexPlanPriority(usage, args.planRequirement),
 				secondaryUsed: this.#normalizeUsageFraction(secondaryTarget),
 				secondaryDrainRate: this.#computeWindowDrainRate(
 					secondaryTarget,
@@ -3390,7 +3445,7 @@ export class AuthStorage {
 				orderPos,
 			});
 		}
-		return this.#orderRankedOAuthCandidates(ranked, args.sessionId, args.provider, args.options?.modelId);
+		return this.#orderRankedOAuthCandidates(ranked, args.sessionId, args.planRequirement);
 	}
 
 	/**
@@ -3418,8 +3473,9 @@ export class AuthStorage {
 		const strategy = this.#rankingStrategyResolver?.(provider);
 		const rankingContext: CredentialRankingContext = { modelId: options?.modelId };
 		const blockScope = strategy?.blockScope?.(rankingContext);
-		const requiresProModel = requiresOpenAICodexProModel(provider, options?.modelId);
-		const checkUsage = strategy !== undefined && (credentials.length > 1 || requiresProModel);
+		const planRequirement = resolveOpenAICodexPlanRequirement(provider, options?.modelId);
+		const hasPlanRequirement = planRequirement !== "none";
+		const checkUsage = strategy !== undefined && (credentials.length > 1 || hasPlanRequirement);
 		const sessionCredential = this.#getSessionCredential(provider, sessionId);
 		const sessionPreferredIndex = sessionCredential?.type === "oauth" ? sessionCredential.index : undefined;
 		const sessionPreferredCredential =
@@ -3438,12 +3494,13 @@ export class AuthStorage {
 			sessionPreferredIndex !== undefined &&
 			sessionPreferredCanRefreshOrUse &&
 			!this.#isCredentialBlocked(provider, providerKey, sessionPreferredIndex, blockScope);
-		const shouldRank = checkUsage && (!sessionPreferredIsAvailable || requiresProModel);
+		const shouldRank = checkUsage && (!sessionPreferredIsAvailable || hasPlanRequirement);
 		const rankingOrder = shouldRank && sessionId ? credentials.map((_credential, index) => index) : order;
 		const candidates = shouldRank
 			? await this.#rankOAuthSelections({
 					providerKey,
 					provider,
+					planRequirement,
 					order: rankingOrder,
 					credentials,
 					options,
@@ -3457,7 +3514,7 @@ export class AuthStorage {
 					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
 					.map(selection => ({ selection, usage: null, usageChecked: false }));
 
-		if (sessionPreferredIndex !== undefined && !requiresProModel) {
+		if (sessionPreferredIndex !== undefined && !hasPlanRequirement) {
 			const sessionPreferredCandidate = candidates.findIndex(
 				candidate =>
 					!this.#isCredentialBlocked(provider, providerKey, candidate.selection.index, blockScope) &&
@@ -3537,10 +3594,12 @@ export class AuthStorage {
 			}),
 		);
 
-		// Skip the Pro-plan filter when no candidate is confirmed Pro, so users with only
-		// non-Pro accounts can still attempt Spark requests (e.g. trial/grandfathered access).
-		const enforceProRequirement =
-			requiresProModel && candidates.some(candidate => hasOpenAICodexProPlan(candidate.usage));
+		// Enforce a tier only when at least one account is confirmed eligible. If
+		// every report is unknown or ineligible, preserve trial/grandfathered access
+		// by allowing the normal candidate fallback to attempt the request.
+		const enforcePlanRequirement =
+			hasPlanRequirement &&
+			candidates.some(candidate => getOpenAICodexPlanEligibility(candidate.usage, planRequirement) === true);
 
 		const fallback = candidates[0];
 
@@ -3556,7 +3615,8 @@ export class AuthStorage {
 					allowBlocked: false,
 					prefetchedUsage: candidate.usage,
 					usagePrechecked: candidate.usageChecked,
-					enforceProRequirement,
+					planRequirement,
+					enforcePlanRequirement,
 					strategy,
 					rankingContext,
 					blockScope,
@@ -3571,7 +3631,8 @@ export class AuthStorage {
 				allowBlocked: true,
 				prefetchedUsage: fallback.usage,
 				usagePrechecked: fallback.usageChecked,
-				enforceProRequirement,
+				planRequirement,
+				enforcePlanRequirement,
 				strategy,
 				rankingContext,
 				blockScope,
@@ -3709,7 +3770,8 @@ export class AuthStorage {
 			allowBlocked: boolean;
 			prefetchedUsage?: UsageReport | null;
 			usagePrechecked?: boolean;
-			enforceProRequirement?: boolean;
+			planRequirement?: OpenAICodexPlanRequirement;
+			enforcePlanRequirement?: boolean;
 			strategy?: CredentialRankingStrategy;
 			rankingContext?: CredentialRankingContext;
 			blockScope?: string;
@@ -3722,7 +3784,8 @@ export class AuthStorage {
 			allowBlocked,
 			prefetchedUsage = null,
 			usagePrechecked = false,
-			enforceProRequirement,
+			planRequirement: providedPlanRequirement,
+			enforcePlanRequirement,
 			strategy,
 			rankingContext,
 			blockScope,
@@ -3741,12 +3804,13 @@ export class AuthStorage {
 		// refresh / persist / CAS-disable addresses the row by this stable id.
 		const credentialId = this.#getStoredCredentials(provider)[selection.index]?.id;
 
-		const requiresProModel = requiresOpenAICodexProModel(provider, options?.modelId);
-		const applyProFilter = enforceProRequirement ?? requiresProModel;
+		const planRequirement = providedPlanRequirement ?? resolveOpenAICodexPlanRequirement(provider, options?.modelId);
+		const hasPlanRequirement = planRequirement !== "none";
+		const applyPlanFilter = enforcePlanRequirement ?? hasPlanRequirement;
 		let usage: UsageReport | null = null;
 		let usageChecked = false;
 
-		if ((checkUsage && !allowBlocked) || requiresProModel) {
+		if ((checkUsage && !allowBlocked) || hasPlanRequirement) {
 			if (usagePrechecked) {
 				usage = prefetchedUsage;
 				usageChecked = true;
@@ -3757,7 +3821,7 @@ export class AuthStorage {
 				});
 				usageChecked = true;
 			}
-			if (applyProFilter && !hasOpenAICodexProPlan(usage)) {
+			if (applyPlanFilter && getOpenAICodexPlanEligibility(usage, planRequirement) !== true) {
 				return undefined;
 			}
 			if (checkUsage && !allowBlocked && usage && strategy && rankingContext) {
@@ -3825,7 +3889,7 @@ export class AuthStorage {
 			} else {
 				this.#replaceCredentialAt(provider, selection.index, updated);
 			}
-			if ((checkUsage && !allowBlocked) || requiresProModel) {
+			if ((checkUsage && !allowBlocked) || hasPlanRequirement) {
 				const sameAccount = selection.credential.accountId === updated.accountId;
 				if (!usageChecked || !sameAccount) {
 					usage = await this.#getUsageReport(provider, updated, {
@@ -3834,7 +3898,7 @@ export class AuthStorage {
 					});
 					usageChecked = true;
 				}
-				if (applyProFilter && !hasOpenAICodexProPlan(usage)) {
+				if (applyPlanFilter && getOpenAICodexPlanEligibility(usage, planRequirement) !== true) {
 					return undefined;
 				}
 				if (checkUsage && !allowBlocked && usage && strategy && rankingContext) {

package/src/providers/azure-openai-responses.ts

@@ -34,7 +34,7 @@ import {
 	applyResponsesReasoningParams,
 	buildResponsesInput,
 	createInitialResponsesAssistantMessage,
-	getOpenAIResponsesPromptCacheKey,
+	getOpenAIPromptCacheKey,
 	isOpenAIResponsesProgressEvent,
 	parseAzureDeploymentNameMap,
 	processResponsesStream,
@@ -348,7 +348,7 @@ function buildParams(
 		model: deploymentName,
 		input: messages,
 		stream: true,
-		prompt_cache_key: getOpenAIResponsesPromptCacheKey(options),
+		prompt_cache_key: getOpenAIPromptCacheKey(options),
 		// Encrypted reasoning replay (applyResponsesReasoningParams) requires
 		// stateless responses, matching the openai provider.
 		store: false,