@oh-my-pi/pi-ai 16.1.17 → 16.1.18

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [16.1.18] - 2026-06-25
+
+### Added
+
+- Added `listOAuthAccounts` for retrieving a read-only list of stored OAuth account identities
+- Added `getOAuthAccessAt` to resolve an OAuth token exclusively for a specific account position
+
+### Changed
+
+- Refactored OAuth token persistence and disable logic to use stable credential IDs instead of positional indices to prevent race conditions during concurrent updates
+- Updated OAuth failure classification to treat 403 status codes, rate limits, and network errors as transient, preventing unnecessary credential invalidation
+
+### Fixed
+
+- Fixed Codex Responses Lite staying enabled for image prompts, which caused GPT/Codex image turns to be rejected as `Invalid value: 'input_image'`; image-bearing Codex requests now fall back to the full Responses transport. ([#3421](https://github.com/can1357/oh-my-pi/issues/3421))
+- Fixed the auth-broker background refresher disabling OAuth credentials unconditionally (`disableCredentialById`) on a definitive refresh failure, so a credential another process or a fresh login rotated mid-refresh could be torn down even though the stored row already held a valid token. The definitive-failure teardown now happens inside `AuthStorage.refreshCredentialById` via the same compare-and-set the in-stream and usage-probe paths use — it disables only when the persisted row still matches the credential the refresh actually attempted, and reloads on a CAS loss; the refresher now only logs.
+- Fixed OAuth refresh persisting the rotated token by a positional index captured before the refresh `await`. A concurrent disable could reorder or shrink a provider's credential array while the refresh was in flight, landing the new token on the wrong row (or silently dropping it) and leaving accounts with a stale refresh token that failed — and was then disabled — on the next cycle. Refresh persistence, selection-index resync, and CAS-disable now address the row by id across `forceRefreshCredentialById`, candidate preflight, and in-stream selection (`#replaceCredentialById` / `#disableCredentialByIdIfMatches`).
+- Fixed `isDefinitiveOAuthFailure` treating a bare HTTP 403 (and generic `unauthorized` / access-token-expired wording) as a definitive credential failure, which permanently disabled healthy OAuth accounts on WAF, egress rate-limit, permission, and account-verification responses. Bare 403, rate limits (429), gateway/5xx, and more network errors (`ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, …) are now classified transient; only explicit dead-grant errors (`invalid_grant`, `invalid_token`, `unauthorized_client`, revoked, `refresh token … expired`) or a bare 401 tear the credential down.
+
 ## [16.1.17] - 2026-06-24
 
 ### Added

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

@@ -467,6 +467,19 @@ export type OAuthAccessResolution = ({
 } & OAuthAccess) | ({
     ok: false;
 } & OAuthAccessFailure);
+/**
+ * Read-only identity of one stored OAuth account, in stable storage order.
+ * Returned by {@link AuthStorage.listOAuthAccounts}; `position` (0-based) is the
+ * selector accepted by {@link AuthStorage.getOAuthAccessAt}.
+ */
+export interface OAuthAccountSummary {
+    position: number;
+    credentialId: number;
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+    enterpriseUrl?: string;
+}
 export interface InvalidateCredentialMatchingOptions {
     signal?: AbortSignal;
     sessionId?: string;
@@ -703,6 +716,14 @@ export declare class AuthStorage {
         sessionId?: string;
         baseUrl?: string;
     }): boolean;
+    /**
+     * The {@link UsageProvider} registered for `provider`, or undefined when the
+     * provider has no usage endpoint at all. Lets callers tell "a credential we
+     * could have fetched usage for but didn't" apart from "a provider with no
+     * usage concept" (web-search keys, local/keyless servers, inference
+     * providers without a usage API) — the latter never warrants a usage row.
+     */
+    usageProviderFor(provider: Provider): UsageProvider | undefined;
     fetchUsageReports(options?: {
         baseUrlResolver?: (provider: Provider) => string | undefined;
         /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
@@ -782,6 +803,13 @@ export declare class AuthStorage {
      * OAuth with an explicit API key.
      */
     getOAuthAccess(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
+    /**
+     * Read-only list of stored OAuth accounts for `provider` in stable storage
+     * order, WITHOUT refreshing any token. The array position (0-based) is the
+     * selector accepted by {@link AuthStorage.getOAuthAccessAt}; a "pick the Nth
+     * account" UI should render `position + 1`.
+     */
+    listOAuthAccounts(provider: string): OAuthAccountSummary[];
     /**
      * Resolve every stored OAuth credential for `provider` independently.
      *
@@ -791,6 +819,18 @@ export declare class AuthStorage {
      * exercise each stored account exactly once.
      */
     getOAuthAccesses(provider: string, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution[]>;
+    /**
+     * Resolve a single stored OAuth credential by its account position (0-based,
+     * matching {@link AuthStorage.listOAuthAccounts}). Refreshes ONLY that
+     * credential ({@link #resolveStoredOAuthAccess} runs with `allowFallback:
+     * false`), so — unlike {@link AuthStorage.getOAuthAccesses} — a definitive
+     * failure of the targeted account surfaces as a failed resolution rather than
+     * silently rotating or rate-tripping a sibling.
+     *
+     * Returns `undefined` when `position` is out of range or runtime/config
+     * overrides have replaced OAuth with an explicit API key.
+     */
+    getOAuthAccessAt(provider: string, position: number, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution | undefined>;
     /**
      * List saved rate-limit resets for every stored OAuth account of `provider`
      * (Codex), fetched LIVE from the dedicated `rate-limit-reset-credits` route.

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

@@ -47,6 +47,8 @@ export interface RequestBody {
     service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
     [key: string]: unknown;
 }
+/** 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?: {
     developerMessages: string[];
 }): Promise<RequestBody>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.1.17",
+	"version": "16.1.18",
 	"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.1.17",
-		"@oh-my-pi/pi-utils": "16.1.17",
-		"@oh-my-pi/pi-wire": "16.1.17",
+		"@oh-my-pi/pi-catalog": "16.1.18",
+		"@oh-my-pi/pi-utils": "16.1.18",
+		"@oh-my-pi/pi-wire": "16.1.18",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-broker/refresher.ts

@@ -5,9 +5,10 @@
  * any whose `expires - Date.now() < refreshSkewMs`. Refresh single-flight
  * lives in {@link AuthStorage} so manual and background refreshes share the
  * same upstream attempt.
- * Definitively-failed credentials (invalid_grant / 401 not from network blip)
- * are disabled via {@link AuthStorage.disableCredentialById} so the next
- * snapshot pull surfaces a clean delete on the client.
+ * Definitively-failed credentials (invalid_grant / bare 401, not a network
+ * blip) are torn down inside {@link AuthStorage.refreshCredentialById} via a
+ * compare-and-set disable — only when no peer/login rotated the row first — so
+ * the next snapshot pull surfaces a clean delete on the client.
  */
 import { logger } from "@oh-my-pi/pi-utils";
 import { type AuthStorage, isDefinitiveOAuthFailure } from "../auth-storage";
@@ -104,11 +105,10 @@ export class AuthBrokerRefresher {
 		} catch (error) {
 			const errorMsg = String(error);
 			if (isDefinitiveOAuthFailure(errorMsg)) {
-				logger.warn("auth-broker refresh failed definitively; disabling credential", {
-					id,
-					error: errorMsg,
-				});
-				this.#storage.disableCredentialById(id, `auth-broker refresh failed: ${errorMsg}`);
+				// AuthStorage.refreshCredentialById already CAS-disabled the row
+				// (unless a peer/login rotated it first, in which case the live
+				// credential is intentionally kept). Nothing to do here but record it.
+				logger.warn("auth-broker refresh failed definitively", { id, error: errorMsg });
 			} else {
 				logger.debug("auth-broker refresh failed (transient)", { id, error: errorMsg });
 			}

package/src/auth-storage.ts

@@ -568,9 +568,17 @@ const MAX_PENDING_DISABLED_EVENTS = 32;
  * while streaming requests correctly tear the row down.
  */
 const OAUTH_DEFINITIVE_FAILURE_REGEX =
-	/invalid_grant|invalid_token|revoked|unauthorized|expired.*refresh|refresh.*expired/i;
-const OAUTH_TRANSIENT_FAILURE_REGEX = /timeout|network|fetch failed|ECONNREFUSED/i;
-const OAUTH_HTTP_AUTH_REGEX = /\b(401|403)\b/;
+	/invalid_grant|invalid_token|unauthorized_client|\brevoked\b|refresh[\s_]?token.*expired/i;
+// Transient: network blips, rate limits, gateway/5xx, and infra denials
+// (WAF / egress 403, permission / account-verification) — block-and-retry,
+// never tear the credential down for these.
+const OAUTH_TRANSIENT_FAILURE_REGEX =
+	/timeout|network|fetch failed|ECONN(?:REFUSED|RESET)|ETIMEDOUT|EAI_AGAIN|socket hang up|\b(?:408|425|429|5\d{2})\b|rate.?limit|too many requests|temporar|unavailable|forbidden|permission_denied|cloudflare|captcha/i;
+// A bare 401 from an OAuth token endpoint means the stored grant/client is
+// dead. 403 is deliberately excluded: it is overwhelmingly WAF / egress
+// rate-limit / permission / account-verification — none of which mean the
+// refresh token itself is invalid.
+const OAUTH_HTTP_AUTH_REGEX = /\b401\b/;
 
 export function isDefinitiveOAuthFailure(errorMsg: string): boolean {
 	if (OAUTH_DEFINITIVE_FAILURE_REGEX.test(errorMsg)) return true;
@@ -673,6 +681,20 @@ export interface OAuthAccountIdentity {
 }
 
 export type OAuthAccessResolution = ({ ok: true } & OAuthAccess) | ({ ok: false } & OAuthAccessFailure);
+
+/**
+ * Read-only identity of one stored OAuth account, in stable storage order.
+ * Returned by {@link AuthStorage.listOAuthAccounts}; `position` (0-based) is the
+ * selector accepted by {@link AuthStorage.getOAuthAccessAt}.
+ */
+export interface OAuthAccountSummary {
+	position: number;
+	credentialId: number;
+	accountId?: string;
+	email?: string;
+	projectId?: string;
+	enterpriseUrl?: string;
+}
 export interface InvalidateCredentialMatchingOptions {
 	signal?: AbortSignal;
 	sessionId?: string;
@@ -887,6 +909,7 @@ class AuthStorageUsageCache implements UsageCache {
 
 type StoredCredential = { id: number; credential: AuthCredential };
 type OAuthSelection = { credential: OAuthCredential; index: number };
+type StoredOAuthSelection = { credentialId: number; credential: OAuthCredential; index: number };
 
 type OAuthCandidate = {
 	selection: OAuthSelection;
@@ -1519,6 +1542,42 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Persist a refreshed credential addressed by id, not a positional index.
+	 * A concurrent disable can reorder/shrink the provider's row array while an
+	 * async refresh is in flight, so a pre-await index is unsafe; resolving the
+	 * row by id at write time lands the rotated token on the correct row. Returns
+	 * the row's current index, or -1 when it was disabled/removed mid-refresh.
+	 */
+	#replaceCredentialById(provider: string, id: number, credential: AuthCredential): number {
+		const entries = this.#getStoredCredentials(provider);
+		const index = entries.findIndex(entry => entry.id === id);
+		if (index === -1) return -1;
+		this.#store.updateAuthCredential(id, credential);
+		const updated = [...entries];
+		updated[index] = { id, credential };
+		this.#setStoredCredentials(provider, updated);
+		return index;
+	}
+
+	/**
+	 * CAS-disable the row with `id`, but only if its persisted credential still
+	 * matches `expected` — i.e. no peer/login rotated it while we refreshed.
+	 * Addresses the row by id (re-resolved here, then matched on `data` in the
+	 * store) so a concurrent reorder can't tear down the wrong credential.
+	 */
+	#disableCredentialByIdIfMatches(
+		provider: string,
+		id: number,
+		expected: AuthCredential,
+		disabledCause: string,
+	): boolean {
+		const entries = this.#getStoredCredentials(provider);
+		const index = entries.findIndex(entry => entry.id === id);
+		if (index === -1) return false;
+		return this.#tryDisableCredentialAtIfMatches(provider, index, expected, disabledCause);
+	}
+
 	#emitCredentialDisabled(event: CredentialDisabledEvent): void {
 		if (this.#credentialDisabledListeners.size === 0) {
 			// No subscribers — buffer for later replay. Cap the backlog so a process that runs
@@ -2601,6 +2660,17 @@ export class AuthStorage {
 		);
 	}
 
+	/**
+	 * The {@link UsageProvider} registered for `provider`, or undefined when the
+	 * provider has no usage endpoint at all. Lets callers tell "a credential we
+	 * could have fetched usage for but didn't" apart from "a provider with no
+	 * usage concept" (web-search keys, local/keyless servers, inference
+	 * providers without a usage API) — the latter never warrants a usage row.
+	 */
+	usageProviderFor(provider: Provider): UsageProvider | undefined {
+		return this.#usageProviderResolver?.(provider);
+	}
+
 	async fetchUsageReports(options?: {
 		baseUrlResolver?: (provider: Provider) => string | undefined;
 		/** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
@@ -3278,7 +3348,12 @@ export class AuthStorage {
 						type: "oauth",
 					};
 					candidate.selection.credential = updated;
-					this.#replaceCredentialAt(provider, candidate.selection.index, updated);
+					if (credentialId !== undefined) {
+						const idx = this.#replaceCredentialById(provider, credentialId, updated);
+						if (idx !== -1) candidate.selection.index = idx;
+					} else {
+						this.#replaceCredentialAt(provider, candidate.selection.index, updated);
+					}
 				} catch (error) {
 					// Recovery for definitive failures (incl. peer rotation) lives in
 					// #tryOAuthCredential; log instead of swallowing silently — a bare
@@ -3460,6 +3535,8 @@ export class AuthStorage {
 			strategy?: CredentialRankingStrategy;
 			rankingContext?: CredentialRankingContext;
 			blockScope?: string;
+			/** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
+			allowFallback?: boolean;
 		},
 	): Promise<OAuthResolutionResult | undefined> {
 		const {
@@ -3471,6 +3548,7 @@ export class AuthStorage {
 			strategy,
 			rankingContext,
 			blockScope,
+			allowFallback = true,
 		} = usageOptions;
 		if (!allowBlocked && this.#isCredentialBlocked(providerKey, selection.index, blockScope)) {
 			return undefined;
@@ -3479,6 +3557,11 @@ export class AuthStorage {
 		if (!(await this.#prepareOAuthCredentialForRequest(provider, selection, options))) {
 			return undefined;
 		}
+		// Capture the row id once, immediately after #prepareOAuthCredentialForRequest
+		// resynced selection.index from the store. A concurrent disable during the
+		// usage/refresh awaits below can shift positional indices, so every later
+		// 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;
@@ -3521,7 +3604,7 @@ export class AuthStorage {
 				const refreshedCredentials = await this.#refreshOAuthCredential(
 					provider,
 					selection.credential,
-					this.#getStoredCredentials(provider)[selection.index]?.id,
+					credentialId,
 					options?.signal,
 				);
 				const apiKey = customProvider.getApiKey
@@ -3537,7 +3620,7 @@ export class AuthStorage {
 				const refreshedCredentials = await this.#refreshOAuthCredential(
 					provider,
 					selection.credential,
-					this.#getStoredCredentials(provider)[selection.index]?.id,
+					credentialId,
 					options?.signal,
 				);
 				const oauthCreds: Record<string, OAuthCredentials> = {
@@ -3557,7 +3640,12 @@ export class AuthStorage {
 				enterpriseUrl: result.newCredentials.enterpriseUrl ?? selection.credential.enterpriseUrl,
 				apiEndpoint: result.newCredentials.apiEndpoint ?? selection.credential.apiEndpoint,
 			};
-			this.#replaceCredentialAt(provider, selection.index, updated);
+			if (credentialId !== undefined) {
+				const idx = this.#replaceCredentialById(provider, credentialId, updated);
+				if (idx !== -1) selection.index = idx;
+			} else {
+				this.#replaceCredentialAt(provider, selection.index, updated);
+			}
 			if ((checkUsage && !allowBlocked) || requiresProModel) {
 				const sameAccount = selection.credential.accountId === updated.accountId;
 				if (!usageChecked || !sameAccount) {
@@ -3607,7 +3695,6 @@ export class AuthStorage {
 				// refresh token has changed, the peer rotation succeeded and we should pick
 				// up the new credential instead of soft-deleting the row that the peer just
 				// updated.
-				const credentialId = this.#getStoredCredentials(provider)[selection.index]?.id;
 				if (credentialId !== undefined) {
 					const latestRow = this.#store.listAuthCredentials(provider).find(row => row.id === credentialId);
 					const latestCredential = latestRow?.credential;
@@ -3618,29 +3705,37 @@ export class AuthStorage {
 							credentialId,
 						});
 						await this.reload();
-						return this.#resolveOAuthSelection(provider, sessionId, options);
+						if (allowFallback) return this.#resolveOAuthSelection(provider, sessionId, options);
 					}
 				}
 				// Permanently disable invalid credentials with an explicit cause for inspection/debugging.
 				// Use a CAS-style disable conditioned on the row still containing the stale credential
 				// we tried to refresh, so a peer rotation that lands between the pre-check above and
 				// this disable doesn't soft-delete the freshly-rotated row.
-				const disabled = this.#tryDisableCredentialAtIfMatches(
-					provider,
-					selection.index,
-					selection.credential,
-					`oauth refresh failed: ${errorMsg}`,
-				);
+				const disabled =
+					credentialId !== undefined
+						? this.#disableCredentialByIdIfMatches(
+								provider,
+								credentialId,
+								selection.credential,
+								`oauth refresh failed: ${errorMsg}`,
+							)
+						: this.#tryDisableCredentialAtIfMatches(
+								provider,
+								selection.index,
+								selection.credential,
+								`oauth refresh failed: ${errorMsg}`,
+							);
 				if (!disabled) {
 					logger.debug("OAuth refresh disable lost CAS; reloading after peer rotation", {
 						provider,
 						index: selection.index,
 					});
 					await this.reload();
-					return this.#resolveOAuthSelection(provider, sessionId, options);
+					if (allowFallback) return this.#resolveOAuthSelection(provider, sessionId, options);
 				}
 				if (this.#getCredentialsForProvider(provider).some(credential => credential.type === "oauth")) {
-					return this.#resolveOAuthSelection(provider, sessionId, options);
+					if (allowFallback) return this.#resolveOAuthSelection(provider, sessionId, options);
 				}
 			} else {
 				// Block temporarily for transient failures (5 minutes)
@@ -3784,6 +3879,83 @@ export class AuthStorage {
 		};
 	}
 
+	/** Stored OAuth credentials for `provider` in stable order, paired with their full-list index and row id. */
+	#getStoredOAuthSelections(provider: string): StoredOAuthSelection[] {
+		return this.#getStoredCredentials(provider)
+			.map((entry, index) => ({ credentialId: entry.id, credential: entry.credential, index }))
+			.filter((entry): entry is StoredOAuthSelection => entry.credential.type === "oauth");
+	}
+
+	/** Refresh one stored OAuth selection and shape it as an {@link OAuthAccessResolution}. */
+	async #resolveStoredOAuthAccess(
+		provider: string,
+		selection: StoredOAuthSelection,
+		providerKey: string,
+		options: AuthApiKeyOptions | undefined,
+	): Promise<OAuthAccessResolution> {
+		try {
+			const resolved = await this.#tryOAuthCredential(
+				provider,
+				{ credential: selection.credential, index: selection.index },
+				providerKey,
+				undefined,
+				options,
+				{ checkUsage: false, allowBlocked: true, allowFallback: false },
+			);
+			if (!resolved) {
+				return {
+					ok: false,
+					credentialId: selection.credentialId,
+					accountId: selection.credential.accountId,
+					email: selection.credential.email,
+					projectId: selection.credential.projectId,
+					enterpriseUrl: selection.credential.enterpriseUrl,
+					error: "OAuth access unavailable",
+				};
+			}
+			const { credential } = resolved;
+			return {
+				ok: true,
+				credentialId: selection.credentialId,
+				accessToken: credential.access,
+				accountId: credential.accountId,
+				email: credential.email,
+				projectId: credential.projectId,
+				enterpriseUrl: credential.enterpriseUrl,
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				credentialId: selection.credentialId,
+				accountId: selection.credential.accountId,
+				email: selection.credential.email,
+				projectId: selection.credential.projectId,
+				enterpriseUrl: selection.credential.enterpriseUrl,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}
+
+	/**
+	 * Read-only list of stored OAuth accounts for `provider` in stable storage
+	 * order, WITHOUT refreshing any token. The array position (0-based) is the
+	 * selector accepted by {@link AuthStorage.getOAuthAccessAt}; a "pick the Nth
+	 * account" UI should render `position + 1`.
+	 */
+	listOAuthAccounts(provider: string): OAuthAccountSummary[] {
+		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) {
+			return [];
+		}
+		return this.#getStoredOAuthSelections(provider).map((selection, position) => ({
+			position,
+			credentialId: selection.credentialId,
+			accountId: selection.credential.accountId,
+			email: selection.credential.email,
+			projectId: selection.credential.projectId,
+			enterpriseUrl: selection.credential.enterpriseUrl,
+		}));
+	}
+
 	/**
 	 * Resolve every stored OAuth credential for `provider` independently.
 	 *
@@ -3797,62 +3969,38 @@ export class AuthStorage {
 			return [];
 		}
 		const providerKey = this.#getProviderTypeKey(provider, "oauth");
-		const selections = this.#getStoredCredentials(provider)
-			.map((entry, index) => ({ credentialId: entry.id, credential: entry.credential, index }))
-			.filter(
-				(entry): entry is { credentialId: number; credential: OAuthCredential; index: number } =>
-					entry.credential.type === "oauth",
-			);
 		return Promise.all(
-			selections.map(async (selection): Promise<OAuthAccessResolution> => {
-				try {
-					const resolved = await this.#tryOAuthCredential(
-						provider,
-						{ credential: selection.credential, index: selection.index },
-						providerKey,
-						undefined,
-						options,
-						{
-							checkUsage: false,
-							allowBlocked: true,
-						},
-					);
-					if (!resolved) {
-						return {
-							ok: false,
-							credentialId: selection.credentialId,
-							accountId: selection.credential.accountId,
-							email: selection.credential.email,
-							projectId: selection.credential.projectId,
-							enterpriseUrl: selection.credential.enterpriseUrl,
-							error: "OAuth access unavailable",
-						};
-					}
-					const { credential } = resolved;
-					return {
-						ok: true,
-						credentialId: selection.credentialId,
-						accessToken: credential.access,
-						accountId: credential.accountId,
-						email: credential.email,
-						projectId: credential.projectId,
-						enterpriseUrl: credential.enterpriseUrl,
-					};
-				} catch (error) {
-					return {
-						ok: false,
-						credentialId: selection.credentialId,
-						accountId: selection.credential.accountId,
-						email: selection.credential.email,
-						projectId: selection.credential.projectId,
-						enterpriseUrl: selection.credential.enterpriseUrl,
-						error: error instanceof Error ? error.message : String(error),
-					};
-				}
-			}),
+			this.#getStoredOAuthSelections(provider).map(selection =>
+				this.#resolveStoredOAuthAccess(provider, selection, providerKey, options),
+			),
 		);
 	}
 
+	/**
+	 * Resolve a single stored OAuth credential by its account position (0-based,
+	 * matching {@link AuthStorage.listOAuthAccounts}). Refreshes ONLY that
+	 * credential ({@link #resolveStoredOAuthAccess} runs with `allowFallback:
+	 * false`), so — unlike {@link AuthStorage.getOAuthAccesses} — a definitive
+	 * failure of the targeted account surfaces as a failed resolution rather than
+	 * silently rotating or rate-tripping a sibling.
+	 *
+	 * Returns `undefined` when `position` is out of range or runtime/config
+	 * overrides have replaced OAuth with an explicit API key.
+	 */
+	async getOAuthAccessAt(
+		provider: string,
+		position: number,
+		options?: AuthApiKeyOptions,
+	): Promise<OAuthAccessResolution | undefined> {
+		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) {
+			return undefined;
+		}
+		const selection = this.#getStoredOAuthSelections(provider)[position];
+		if (!selection) return undefined;
+		const providerKey = this.#getProviderTypeKey(provider, "oauth");
+		return this.#resolveStoredOAuthAccess(provider, selection, providerKey, options);
+	}
+
 	/**
 	 * List saved rate-limit resets for every stored OAuth account of `provider`
 	 * (Codex), fetched LIVE from the dedicated `rate-limit-reset-credits` route.
@@ -4229,22 +4377,55 @@ export class AuthStorage {
 			if (target.credential.type !== "oauth") {
 				throw new Error(`Credential ${id} is not OAuth (provider=${provider}, type=${target.credential.type})`);
 			}
+			// The exact credential we are about to refresh — captured before the
+			// await so a definitive failure can CAS-disable the row against the
+			// value we actually attempted (NOT the expires:0 clone below).
+			const attempted = target.credential;
 			// Pass a clone with expires=0 so the cached not-yet-expired short-circuit
 			// in #refreshOAuthCredential doesn't suppress the requested refresh.
-			const stale: OAuthCredential = { ...target.credential, expires: 0 };
-			const refreshed = await this.#refreshOAuthCredential(provider as Provider, stale, id, signal);
+			const stale: OAuthCredential = { ...attempted, expires: 0 };
+			let refreshed: OAuthCredentials;
+			try {
+				refreshed = await this.#refreshOAuthCredential(provider as Provider, stale, id, signal);
+			} catch (error) {
+				// A definitively-dead grant tears the row down here, where the
+				// attempted credential is known. CAS on the persisted credential so a
+				// peer/login rotation in flight leaves the freshly-rotated row intact.
+				if (isDefinitiveOAuthFailure(String(error))) {
+					// CAS-loss (false) means a peer/login rotated the row mid-refresh, so
+					// our #data copy is stale — reload so the next caller serves the
+					// freshly-rotated credential rather than the dead token we attempted.
+					if (
+						!this.#disableCredentialByIdIfMatches(
+							provider,
+							id,
+							attempted,
+							`oauth refresh failed: ${String(error)}`,
+						)
+					) {
+						await this.reload();
+					}
+				}
+				throw error;
+			}
 			const updated: OAuthCredential = {
 				type: "oauth",
 				access: refreshed.access,
 				refresh: refreshed.refresh,
 				expires: refreshed.expires,
-				accountId: refreshed.accountId ?? target.credential.accountId,
-				email: refreshed.email ?? target.credential.email,
-				projectId: refreshed.projectId ?? target.credential.projectId,
-				enterpriseUrl: refreshed.enterpriseUrl ?? target.credential.enterpriseUrl,
-				apiEndpoint: refreshed.apiEndpoint ?? target.credential.apiEndpoint,
+				accountId: refreshed.accountId ?? attempted.accountId,
+				email: refreshed.email ?? attempted.email,
+				projectId: refreshed.projectId ?? attempted.projectId,
+				enterpriseUrl: refreshed.enterpriseUrl ?? attempted.enterpriseUrl,
+				apiEndpoint: refreshed.apiEndpoint ?? attempted.apiEndpoint,
 			};
-			this.#replaceCredentialAt(provider, index, updated);
+			// Persist by id: the array may have been reordered/shrunk while the
+			// refresh was in flight, so the pre-await positional index is unsafe. A
+			// -1 means the row was disabled/removed mid-refresh — surface that as a
+			// miss rather than implying a live row the snapshot won't contain.
+			if (this.#replaceCredentialById(provider, id, updated) === -1) {
+				throw new Error(`No credential with id=${id}`);
+			}
 			return {
 				id,
 				provider,

package/src/providers/openai-codex/request-transformer.ts

@@ -59,6 +59,26 @@ export interface RequestBody {
 	[key: string]: unknown;
 }
 
+function containsInputImage(value: unknown): boolean {
+	if (!value || typeof value !== "object") return false;
+	if ((value as { type?: unknown }).type === "input_image") return true;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			if (containsInputImage(item)) return true;
+		}
+		return false;
+	}
+	for (const item of Object.values(value)) {
+		if (containsInputImage(item)) return true;
+	}
+	return false;
+}
+
+/** Returns whether a Codex request can use the text-only Responses Lite transport. */
+export function shouldUseCodexResponsesLite(body: RequestBody, requested: boolean | undefined): boolean {
+	return requested === true && !containsInputImage(body.input);
+}
+
 function getReasoningConfig(model: Model<Api>, options: CodexRequestOptions): ReasoningConfig {
 	const config: ReasoningConfig = {
 		effort:
@@ -211,7 +231,8 @@ export async function transformRequestBody(
 		body.input = [...developerMessages, ...body.input];
 	}
 
-	if (options.responsesLite) {
+	const responsesLite = shouldUseCodexResponsesLite(body, options.responsesLite);
+	if (responsesLite) {
 		if (Array.isArray(body.input)) {
 			stripImageDetails(body.input);
 		}
@@ -231,7 +252,7 @@ export async function transformRequestBody(
 		// Responses Lite keeps reasoning replay server-side; codex-rs requests
 		// `all_turns` there and otherwise omits context so the server default
 		// (currently `current_turn`) applies.
-		const reasoningContext = options.reasoningContext ?? (options.responsesLite ? "all_turns" : undefined);
+		const reasoningContext = options.reasoningContext ?? (responsesLite ? "all_turns" : undefined);
 		if (reasoningContext !== undefined) {
 			body.reasoning.context = reasoningContext;
 		}

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

@@ -61,6 +61,7 @@ import {
 	type CodexRequestOptions,
 	type InputItem,
 	type RequestBody,
+	shouldUseCodexResponsesLite,
 	transformRequestBody,
 } from "./openai-codex/request-transformer";
 import { CodexApiError } from "./openai-codex/response-handler";
@@ -697,7 +698,7 @@ async function buildCodexRequestContext(
 	};
 
 	const providerSessionState = getCodexProviderSessionState(options?.providerSessionState);
-	const responsesLite = options?.responsesLite === true;
+	const responsesLite = shouldUseCodexResponsesLite(transformedBody, options?.responsesLite);
 	const sessionKey = getCodexWebSocketSessionKey(transportSessionId, model, accountId, baseUrl, responsesLite);
 	const publicSessionKey = transportSessionId ? `${baseUrl}:${model.id}:${transportSessionId}` : undefined;
 	if (sessionKey && publicSessionKey) {