@oh-my-pi/pi-ai 18.8.1 → 18.8.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [18.8.3] - 2026-10-07
+
+### Added
+
+- Added `OAuthRefreshUnavailableError`, a retryable error that `keys.getWithCredential` and `oauth.access` reject with when every usable OAuth credential failed to refresh transiently; `keys.get` resolves `undefined` instead so availability probes move on to their next candidate ([#14843](https://github.com/can1357/oh-my-pi/pull/14843) by [@H4vC](https://github.com/H4vC))
+
+### Fixed
+
+- Fixed a single transient OAuth token-refresh failure (network blip, timeout, 5xx) ending a running session, including subagents restricted to an account pool, with a non-retryable "No API key for provider" error while the stored credential was still valid; the refresh error now surfaces and the request is retried ([#14843](https://github.com/can1357/oh-my-pi/pull/14843) by [@H4vC](https://github.com/H4vC))
+
 ## [18.8.1] - 2026-10-07
 
 ### Added

package/dist/types/auth/cascade.d.ts

@@ -2,7 +2,7 @@ import { type ApiKeyResolver, type ResolvedApiKey } from "../auth-retry.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi, OAuthRequestIdentity } from "./types.js";
+import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi } from "./types.js";
 /** Runtime (--api-key) and config (models.yml) key overrides plus the config-value resolver. */
 export declare class KeyOverrides {
     #private;
@@ -117,7 +117,13 @@ export declare class KeyCascade implements KeysApi {
      * credential to reach the correct host.
      */
     peek(provider: string): Promise<string | undefined>;
-    /** Resolve a bearer together with the stored row that supplied it. */
+    /**
+     * Resolve a bearer together with the stored row that supplied it, for a request.
+     * Same precedence as {@link KeyCascade.get}, but rejects with
+     * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+     * refresh failed with a retryable error and no other permitted source could serve
+     * the request, so request paths retry instead of reporting a missing key.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Get API key for a provider.
@@ -127,8 +133,11 @@ export declare class KeyCascade implements KeysApi {
      * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
      * can serve or a config key (a models.yml `apiKey`, often for a proxy
      * `baseUrl`) owns the provider, rather than using any other credential.
+     * A transient OAuth refresh failure resolves `undefined`, so availability
+     * probes move on to their next candidate; request paths use
+     * {@link KeyCascade.getWithCredential}, which surfaces it.
      */
-    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void): Promise<string | undefined>;
+    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
     /**
      * Build an {@link ApiKeyResolver} backed by this storage, implementing the
      * central a/b/c auth-retry policy:

package/dist/types/auth/oauth.d.ts

@@ -37,9 +37,11 @@ export declare class OAuthAccounts implements OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer API-key resolution.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available
+     * (none stored, or every one definitively failed to refresh) or
+     * runtime/config overrides have replaced OAuth with an explicit API key.
+     * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+     * retryable) when a retryable refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**

package/dist/types/auth/select.d.ts

@@ -32,6 +32,8 @@ export type TryOAuthOptions = {
     blockScopes?: readonly 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;
+    /** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+    onTransientRefreshFailure?: (error: unknown) => void;
 };
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
 export interface CredentialSelectorDeps {

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

@@ -812,9 +812,20 @@ export interface KeysApi {
      * 4. API key persisted by a successful `/login`
      * 5. Environment variable
      * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+     *
+     * Resolves `undefined` when no permitted credential can serve, including when
+     * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+     * probes move on to their next candidate. Request paths use
+     * {@link KeysApi.getWithCredential}, which surfaces that failure.
      */
     get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-    /** Resolve a bearer together with its durable stored credential row id, when known. */
+    /**
+     * Resolve a bearer together with its durable stored credential row id, when known.
+     * Same precedence as {@link KeysApi.get}, but rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+     * with a retryable error and no other permitted source could serve the request;
+     * the stored credential is kept.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Peek at API key for a provider without refreshing OAuth tokens.
@@ -935,9 +946,11 @@ export interface OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer {@link AuthStorage.keys.get}.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available (none
+     * stored, or every one definitively failed to refresh) or runtime/config
+     * overrides have replaced OAuth with an explicit API key. Rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+     * refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**

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

@@ -10,6 +10,16 @@ export declare class MissingApiKeyError extends Error {
     readonly provider: string | undefined;
     constructor(provider?: string, message?: string);
 }
+/**
+ * Every usable OAuth credential for a provider failed to refresh with a
+ * retryable error (network blip, timeout, 5xx). The stored credentials are
+ * intact, so this is classified transient: retrying the request can succeed,
+ * unlike {@link MissingApiKeyError}. The refresh failure is kept as `cause`.
+ */
+export declare class OAuthRefreshUnavailableError extends Error {
+    readonly provider: string;
+    constructor(provider: string, cause: unknown);
+}
 /** A user-facing login flow required an `onPrompt` callback that was not supplied. */
 export declare class OnPromptRequiredError extends Error {
     constructor(providerLabel: string);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.8.1",
+	"version": "18.8.3",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.8.1",
-		"@oh-my-pi/pi-catalog": "18.8.1",
-		"@oh-my-pi/pi-natives": "18.8.1",
-		"@oh-my-pi/pi-utils": "18.8.1",
-		"@oh-my-pi/pi-wire": "18.8.1"
+		"@oh-my-pi/omptype": "18.8.3",
+		"@oh-my-pi/pi-catalog": "18.8.3",
+		"@oh-my-pi/pi-natives": "18.8.3",
+		"@oh-my-pi/pi-utils": "18.8.3",
+		"@oh-my-pi/pi-wire": "18.8.3"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/cascade.ts

@@ -1,5 +1,5 @@
 import { authPolicyFor } from "@oh-my-pi/pi-catalog/compat/auth";
-import { $env, $envExact } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, logger } from "@oh-my-pi/pi-utils";
 import { type ApiKeyResolver, markAfterSiblingWait, type ResolvedApiKey } from "../auth-retry";
 import { getEnvApiKey, getEnvApiKeyName } from "../env-api-key";
 import * as AIError from "../error";
@@ -7,7 +7,7 @@ import { isUsageLimitOutcome } from "../error/rate-limit";
 import { AUTHENTICATED_SENTINEL } from "../registry/types";
 import type { SessionAffinity } from "./affinity";
 import type { CredentialPool } from "./pool";
-import type { CredentialSelector } from "./select";
+import type { CredentialSelector, OAuthResolutionResult } from "./select";
 import type {
 	AuthApiKeyOptions,
 	AuthCredential,
@@ -308,7 +308,13 @@ export class KeyCascade implements KeysApi {
 		return undefined;
 	}
 
-	/** Resolve a bearer together with the stored row that supplied it. */
+	/**
+	 * Resolve a bearer together with the stored row that supplied it, for a request.
+	 * Same precedence as {@link KeyCascade.get}, but rejects with
+	 * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+	 * refresh failed with a retryable error and no other permitted source could serve
+	 * the request, so request paths retry instead of reporting a missing key.
+	 */
 	async getWithCredential(
 		provider: string,
 		sessionId?: string,
@@ -316,7 +322,7 @@ export class KeyCascade implements KeysApi {
 	): Promise<ResolvedApiKey | undefined> {
 		let credentialId: number | undefined;
 		let oauthIdentity: OAuthRequestIdentity | undefined;
-		const apiKey = await this.get(provider, sessionId, options, (id, identity) => {
+		const apiKey = await this.#resolve(provider, sessionId, options, (id, identity) => {
 			credentialId = id;
 			oauthIdentity = identity;
 		});
@@ -331,8 +337,21 @@ export class KeyCascade implements KeysApi {
 	 * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
 	 * can serve or a config key (a models.yml `apiKey`, often for a proxy
 	 * `baseUrl`) owns the provider, rather than using any other credential.
+	 * A transient OAuth refresh failure resolves `undefined`, so availability
+	 * probes move on to their next candidate; request paths use
+	 * {@link KeyCascade.getWithCredential}, which surfaces it.
 	 */
-	async get(
+	async get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
+		try {
+			return await this.#resolve(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			logger.debug("API key probe skipped transient OAuth refresh failure", { provider, error: error.message });
+			return undefined;
+		}
+	}
+
+	async #resolve(
 		provider: string,
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
@@ -363,7 +382,16 @@ export class KeyCascade implements KeysApi {
 
 		// Precedence: a deliberate OAuth/login credential wins, then an explicit env var,
 		// then a stored static api_key (which may be a stale broker-migrated copy) as a last resort.
-		const oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		// A transient OAuth refresh failure still lets later sources serve the request; it is
+		// rethrown only when none can, so callers retry instead of reporting a missing key.
+		let oauthResolved: OAuthResolutionResult | undefined;
+		let oauthRefreshFailure: AIError.OAuthRefreshUnavailableError | undefined;
+		try {
+			oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			oauthRefreshFailure = error;
+		}
 		if (oauthResolved) {
 			if (onCredentialId && oauthResolved.credentialId !== undefined) {
 				const { orgId, region, inferenceRegion } = oauthResolved.credential;
@@ -372,6 +400,7 @@ export class KeyCascade implements KeysApi {
 			return oauthResolved.apiKey;
 		}
 		if (restricted) {
+			if (oauthRefreshFailure) throw oauthRefreshFailure;
 			throw new AIError.MissingApiKeyError(
 				provider,
 				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool and none of those accounts is available)`,
@@ -420,6 +449,7 @@ export class KeyCascade implements KeysApi {
 			if (apiKey !== undefined && credentialId !== undefined) onCredentialId?.(credentialId);
 			return apiKey;
 		}
+		if (oauthRefreshFailure) throw oauthRefreshFailure;
 		return undefined;
 	}
 

package/src/auth/oauth.ts

@@ -127,9 +127,11 @@ export class OAuthAccounts implements OAuthApi {
 	 * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
 	 * scenarios, prefer API-key resolution.
 	 *
-	 * Returns `undefined` when no OAuth credential is available, the
-	 * credential fails to refresh, or runtime/config overrides have replaced
-	 * OAuth with an explicit API key.
+	 * Returns `undefined` when no usable OAuth credential is available
+	 * (none stored, or every one definitively failed to refresh) or
+	 * runtime/config overrides have replaced OAuth with an explicit API key.
+	 * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+	 * retryable) when a retryable refresh failure left no usable credential.
 	 */
 	async access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined> {
 		// Runtime / config overrides intentionally short-circuit OAuth: when the

package/src/auth/select.ts

@@ -65,6 +65,8 @@ export type TryOAuthOptions = {
 	blockScopes?: readonly 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;
+	/** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+	onTransientRefreshFailure?: (error: unknown) => void;
 };
 
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
@@ -653,6 +655,14 @@ export class CredentialSelector {
 							: { selection, usage: null, usageChecked: false },
 					);
 		const preflightFailures = new Set<OAuthCandidate>();
+		// The last retryable refresh error (network, timeout, 5xx) that removed a candidate.
+		// When no candidate resolves, it is rethrown so callers retry instead of reporting
+		// a missing key. Refresher outcomes after a dead grant (row disabled, CAS lost) are
+		// classified auth failures and keep resolving to undefined.
+		let transientRefreshFailure: unknown;
+		const recordTransientRefreshFailure = (error: unknown): void => {
+			if (AIError.retriable(AIError.classify(error))) transientRefreshFailure = error;
+		};
 
 		const sessionPreferredCandidate = candidates.findIndex(
 			candidate =>
@@ -799,16 +809,21 @@ export class CredentialSelector {
 							// to a sibling account with the wrong prefetched usage/plan.
 							return;
 						}
-					} else if (credentialId !== undefined) {
-						const latestIndex = this.#deps.pool.entries(provider).findIndex(entry => entry.id === credentialId);
-						if (latestIndex !== -1) {
-							this.#deps.blocks.mark(
-								provider,
-								providerKey,
-								latestIndex,
-								Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
-								AUTH_BLOCK_SCOPE,
-							);
+					} else {
+						recordTransientRefreshFailure(error);
+						if (credentialId !== undefined) {
+							const latestIndex = this.#deps.pool
+								.entries(provider)
+								.findIndex(entry => entry.id === credentialId);
+							if (latestIndex !== -1) {
+								this.#deps.blocks.mark(
+									provider,
+									providerKey,
+									latestIndex,
+									Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
+									AUTH_BLOCK_SCOPE,
+								);
+							}
 						}
 					}
 					preflightFailures.add(candidate);
@@ -882,11 +897,15 @@ export class CredentialSelector {
 					rankingContext,
 					blockScope,
 					blockScopes,
+					onTransientRefreshFailure: recordTransientRefreshFailure,
 				});
 				if (resolved) return resolved;
 			}
 		}
 
+		if (transientRefreshFailure !== undefined) {
+			throw new AIError.OAuthRefreshUnavailableError(provider, transientRefreshFailure);
+		}
 		return undefined;
 	}
 
@@ -1117,6 +1136,7 @@ export class CredentialSelector {
 					if (allowFallback) return this.resolveOAuth(provider, sessionId, options);
 				}
 			} else {
+				usageOptions.onTransientRefreshFailure?.(error);
 				// Block temporarily for transient failures (5 minutes)
 				this.#deps.blocks.mark(
 					provider,

package/src/auth/types.ts

@@ -894,9 +894,20 @@ export interface KeysApi {
 	 * 4. API key persisted by a successful `/login`
 	 * 5. Environment variable
 	 * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+	 *
+	 * Resolves `undefined` when no permitted credential can serve, including when
+	 * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+	 * probes move on to their next candidate. Request paths use
+	 * {@link KeysApi.getWithCredential}, which surfaces that failure.
 	 */
 	get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-	/** Resolve a bearer together with its durable stored credential row id, when known. */
+	/**
+	 * Resolve a bearer together with its durable stored credential row id, when known.
+	 * Same precedence as {@link KeysApi.get}, but rejects with
+	 * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+	 * with a retryable error and no other permitted source could serve the request;
+	 * the stored credential is kept.
+	 */
 	getWithCredential(
 		provider: string,
 		sessionId?: string,
@@ -1017,9 +1028,11 @@ export interface OAuthApi {
 	 * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
 	 * scenarios, prefer {@link AuthStorage.keys.get}.
 	 *
-	 * Returns `undefined` when no OAuth credential is available, the
-	 * credential fails to refresh, or runtime/config overrides have replaced
-	 * OAuth with an explicit API key.
+	 * Returns `undefined` when no usable OAuth credential is available (none
+	 * stored, or every one definitively failed to refresh) or runtime/config
+	 * overrides have replaced OAuth with an explicit API key. Rejects with
+	 * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+	 * refresh failure left no usable credential.
 	 */
 	access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
 	/**

package/src/error/auth.ts

@@ -19,6 +19,26 @@ export class MissingApiKeyError extends Error {
 	}
 }
 
+/**
+ * Every usable OAuth credential for a provider failed to refresh with a
+ * retryable error (network blip, timeout, 5xx). The stored credentials are
+ * intact, so this is classified transient: retrying the request can succeed,
+ * unlike {@link MissingApiKeyError}. The refresh failure is kept as `cause`.
+ */
+export class OAuthRefreshUnavailableError extends Error {
+	readonly provider: string;
+
+	constructor(provider: string, cause: unknown) {
+		super(
+			`OAuth token refresh failed for provider ${provider}: ${cause instanceof Error ? cause.message : String(cause)}`,
+			{ cause },
+		);
+		this.name = "OAuthRefreshUnavailableError";
+		this.provider = provider;
+		attach(this, create(Flag.Transient));
+	}
+}
+
 /** A user-facing login flow required an `onPrompt` callback that was not supplied. */
 export class OnPromptRequiredError extends Error {
 	constructor(providerLabel: string) {