@oh-my-pi/pi-ai 16.4.5 → 16.4.6

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [16.4.6] - 2026-07-12
+
+### Added
+
+- Added asynchronous `invalidateUsageCache` method to clear cached usage reports
+- Added support for cross-service usage cache invalidation between AuthStorage and AuthBroker
+
+### Fixed
+
+- Fixed OAuth credential resolution returning "No API key found" when every plan-eligible OpenAI Codex account was rate-limit blocked and the only unblocked account failed the model's plan gate: resolution now runs a last-resort ladder that first yields a plan-fitting account regardless of usage blocks (so callers get real usage-limit retry semantics), then tries every account with the plan filter dropped before reporting no credential
+
 ## [16.4.5] - 2026-07-11
 
 ### Fixed

package/dist/types/auth-broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage.js";
-import type { CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types.js";
+import type { CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse, UsageStaleResponse } from "./types.js";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -60,6 +60,7 @@ export declare class AuthBrokerClient {
         signal?: AbortSignal;
     }): AsyncGenerator<SnapshotStreamEvent>;
     fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
+    notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
     refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;

package/dist/types/auth-broker/remote-store.d.ts

@@ -80,6 +80,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     getCache(key: string): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
+    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
     /**
      * Store-level hook consumed by `AuthStorage` — routes refresh through the
      * broker so the actual refresh token never leaves the broker host. Returns

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

@@ -56,6 +56,10 @@ export interface CredentialBlockResponse {
 export interface CredentialBlocksDeleteResponse {
     ok: boolean;
 }
+/** POST /v1/usage/stale response body. */
+export interface UsageStaleResponse {
+    ok: boolean;
+}
 /**
  * POST /v1/credential request body. The OAuth `refresh` must be the *real*
  * refresh token (not the sentinel) — the broker is the canonical writer.

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -425,6 +425,9 @@ export declare const credentialBlockResponseSchema: import("arktype/internal/var
 export declare const credentialBlocksDeleteResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     ok: boolean;
 }, {}>;
+export declare const usageStaleResponseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    ok: boolean;
+}, {}>;
 export declare const credentialUploadRequestSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     provider: string;
     credential: {

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

@@ -233,6 +233,8 @@ export interface CredentialRefreshLeaseFence {
 }
 export interface AuthCredentialStore {
     close(): void;
+    /** Optional hook to notify the underlying store that usage report cache is stale. */
+    invalidateUsageCache?(signal?: AbortSignal): Promise<void>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     updateAuthCredential(id: number, credential: AuthCredential): void;
     deleteAuthCredential(id: number, disabledCause: string): void;
@@ -930,6 +932,13 @@ export declare class AuthStorage {
         baseUrlResolver?: (provider: string) => string | undefined;
         signal?: AbortSignal;
     }): Promise<ResetCreditRedeemOutcome>;
+    /**
+     * Force-invalidate cached usage reports so the next fetch retrieves fresh
+     * values from upstream providers. If `provider` is specified, only that
+     * provider's credentials are invalidated; otherwise, all credentials in the
+     * store are invalidated.
+     */
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
     invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
     /**

package/package.json

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

package/src/auth-broker/client.ts

@@ -21,6 +21,7 @@ import type {
 	SnapshotResponse,
 	SnapshotStreamEvent,
 	UsageResponse,
+	UsageStaleResponse,
 } from "./types";
 import {
 	credentialBlockResponseSchema,
@@ -32,6 +33,7 @@ import {
 	snapshotResponseSchema,
 	snapshotStreamEventSchema,
 	usageResponseSchema,
+	usageStaleResponseSchema,
 } from "./wire-schemas";
 
 export interface AuthBrokerClientOptions {
@@ -242,6 +244,13 @@ export class AuthBrokerClient {
 		return this.#request<UsageResponse>("GET", "/v1/usage", { schema: usageResponseSchema, signal });
 	}
 
+	notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse> {
+		return this.#request<UsageStaleResponse>("POST", "/v1/usage/stale", {
+			schema: usageStaleResponseSchema,
+			signal,
+		});
+	}
+
 	async refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse> {
 		return this.#request<CredentialRefreshResponse>("POST", `/v1/credential/${id}/refresh`, {
 			schema: credentialRefreshResponseSchema,

package/src/auth-broker/remote-store.ts

@@ -794,6 +794,13 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
+	async invalidateUsageCache(signal?: AbortSignal): Promise<void> {
+		this.#invalidateUsageCache();
+		await this.#client.notifyUsageStale(signal).catch(err => {
+			logger.warn("auth-broker notification of stale usage failed", { error: String(err) });
+		});
+	}
+
 	#invalidateUsageCache(): void {
 		this.#usageCache = undefined;
 		this.#usageInflight = undefined;

package/src/auth-broker/server.ts

@@ -608,6 +608,17 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 						return json(502, { error: message });
 					}
 				}
+				if (req.method === "POST" && pathname === "/v1/usage/stale") {
+					try {
+						opts.storage.invalidateUsageCache?.();
+						logger.info("auth-broker usage cache invalidated", { peer });
+						return json(200, { ok: true });
+					} catch (error) {
+						const message = error instanceof Error ? error.message : String(error);
+						logger.warn("auth-broker usage cache invalidation failed", { peer, error: message });
+						return json(500, { error: message });
+					}
+				}
 				const refreshMatch = req.method === "POST" ? pathname.match(REFRESH_ROUTE) : null;
 				if (refreshMatch) {
 					const id = Number.parseInt(refreshMatch[1], 10);

package/src/auth-broker/types.ts

@@ -75,6 +75,11 @@ export interface CredentialBlocksDeleteResponse {
 	ok: boolean;
 }
 
+/** POST /v1/usage/stale response body. */
+export interface UsageStaleResponse {
+	ok: boolean;
+}
+
 /**
  * POST /v1/credential request body. The OAuth `refresh` must be the *real*
  * refresh token (not the sentinel) — the broker is the canonical writer.

package/src/auth-broker/wire-schemas.ts

@@ -258,6 +258,11 @@ export const credentialBlocksDeleteResponseSchema = type({
 	ok: "boolean",
 });
 
+export const usageStaleResponseSchema = type({
+	"+": "reject",
+	ok: "boolean",
+});
+
 // ─── Upload ────────────────────────────────────────────────────────────────
 
 export const credentialUploadRequestSchema = type({

package/src/auth-storage.ts

@@ -315,6 +315,8 @@ export interface CredentialRefreshLeaseFence {
 
 export interface AuthCredentialStore {
 	close(): void;
+	/** Optional hook to notify the underlying store that usage report cache is stale. */
+	invalidateUsageCache?(signal?: AbortSignal): Promise<void>;
 	listAuthCredentials(provider?: string): StoredAuthCredential[];
 	updateAuthCredential(id: number, credential: AuthCredential): void;
 	deleteAuthCredential(id: number, disabledCause: string): void;
@@ -3739,8 +3741,17 @@ export class AuthStorage {
 
 	/**
 	 * Resolves an OAuth credential, trying credentials in priority order.
-	 * Skips blocked credentials and checks usage limits for providers with usage data.
-	 * Falls back to earliest-unblocking credential if all are blocked.
+	 *
+	 * Resolution ladder — a request in hand always beats "no API key":
+	 * 1. strict: unblocked credentials only, usage limits respected, plan
+	 *    filter enforced (when any account is confirmed eligible);
+	 * 2. plan-fitting last resort: same plan filter, but blocked/exhausted
+	 *    accounts are allowed (blocked candidates rank earliest-unblocking
+	 *    first) so the caller gets real usage-limit semantics from the wire
+	 *    instead of a missing key;
+	 * 3. unfiltered last resort: the plan filter matched nothing usable —
+	 *    skip it and try every account once; the server is the final arbiter
+	 *    of model access.
 	 *
 	 * Returns both the API key bytes for outbound requests AND the refreshed
 	 * {@link OAuthCredential} so callers needing identity metadata (account id,
@@ -3890,42 +3901,34 @@ export class AuthStorage {
 			hasPlanRequirement &&
 			candidates.some(candidate => getOpenAICodexPlanEligibility(candidate.usage, planRequirement) === true);
 
-		const fallback = candidates[0];
+		const passes: Array<{ allowBlocked: boolean; enforcePlanRequirement: boolean }> = [
+			{ allowBlocked: false, enforcePlanRequirement },
+			{ allowBlocked: true, enforcePlanRequirement },
+		];
+		if (enforcePlanRequirement) passes.push({ allowBlocked: true, enforcePlanRequirement: false });
 
-		for (const candidate of candidates) {
-			const resolved = await this.#tryOAuthCredential(
-				provider,
-				candidate.selection,
-				providerKey,
-				sessionId,
-				options,
-				{
-					checkUsage,
-					allowBlocked: false,
-					prefetchedUsage: candidate.usage,
-					usagePrechecked: candidate.usageChecked,
-					planRequirement,
-					enforcePlanRequirement,
-					strategy,
-					rankingContext,
-					blockScope,
-				},
-			);
-			if (resolved) return resolved;
-		}
-
-		if (fallback && this.#isCredentialBlocked(provider, providerKey, fallback.selection.index, blockScope)) {
-			return this.#tryOAuthCredential(provider, fallback.selection, providerKey, sessionId, options, {
-				checkUsage,
-				allowBlocked: true,
-				prefetchedUsage: fallback.usage,
-				usagePrechecked: fallback.usageChecked,
-				planRequirement,
-				enforcePlanRequirement,
-				strategy,
-				rankingContext,
-				blockScope,
-			});
+		for (const pass of passes) {
+			for (const candidate of candidates) {
+				const resolved = await this.#tryOAuthCredential(
+					provider,
+					candidate.selection,
+					providerKey,
+					sessionId,
+					options,
+					{
+						checkUsage,
+						allowBlocked: pass.allowBlocked,
+						prefetchedUsage: candidate.usage,
+						usagePrechecked: candidate.usageChecked,
+						planRequirement,
+						enforcePlanRequirement: pass.enforcePlanRequirement,
+						strategy,
+						rankingContext,
+						blockScope,
+					},
+				);
+				if (resolved) return resolved;
+			}
 		}
 
 		return undefined;
@@ -4666,6 +4669,11 @@ export class AuthStorage {
 		});
 		if (result.ok) {
 			this.#invalidateUsageReportCache(provider, baseUrl);
+			if (this.#store.invalidateUsageCache) {
+				await this.#store.invalidateUsageCache(options.signal).catch(err => {
+					logger.debug("Failed to notify store of stale usage", { err });
+				});
+			}
 			// The window this credential was blocked on (by markUsageLimitReached)
 			// is now reset, so lift its temporary block — otherwise selection
 			// keeps skipping/under-ranking the freshly-reset account.
@@ -4691,6 +4699,40 @@ export class AuthStorage {
 		}
 	}
 
+	/**
+	 * Force-invalidate cached usage reports so the next fetch retrieves fresh
+	 * values from upstream providers. If `provider` is specified, only that
+	 * provider's credentials are invalidated; otherwise, all credentials in the
+	 * store are invalidated.
+	 */
+	async invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void> {
+		if (provider) {
+			this.#invalidateUsageReportCache(provider);
+		} else {
+			this.#usageCacheEpoch += 1;
+			const expired = Date.now() - 1;
+			try {
+				const credentials = this.#store.listAuthCredentials();
+				for (const entry of credentials) {
+					if (entry.credential.type !== "oauth") continue;
+					const cacheKey = this.#buildUsageReportCacheKey(
+						this.#buildUsageRequestForOauth(entry.provider, entry.credential),
+					);
+					const existing = this.#usageCache.getStale<UsageReport | null>(cacheKey);
+					this.#usageCache.set(cacheKey, { value: existing?.value ?? null, expiresAt: expired });
+				}
+			} catch (err) {
+				logger.debug("Failed to list auth credentials for complete usage cache invalidation", { err });
+			}
+		}
+
+		if (this.#store.invalidateUsageCache) {
+			await this.#store.invalidateUsageCache(signal).catch(err => {
+				logger.debug("Failed to notify store of stale usage", { err });
+			});
+		}
+	}
+
 	#invalidateUsageReportCacheForProviderKey(providerKey: string): void {
 		const oauthSuffix = ":oauth";
 		if (!providerKey.endsWith(oauthSuffix)) return;