@oh-my-pi/pi-ai 18.3.4 → 18.4.0

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

@@ -161,6 +161,11 @@ interface UsageCacheEntry {
 	fetchedAt: number;
 }
 
+/** Identity of one credential block row: credential, provider key, and scope. */
+function blockKey(credentialId: number, block: { providerKey: string; blockScope: string }): string {
+	return `${credentialId}\0${block.providerKey}\0${block.blockScope}`;
+}
+
 function usageOverlayKey(
 	provider: Provider,
 	ids: { accountId?: string; email?: string; projectId?: string; orgId?: string },
@@ -278,6 +283,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	#usageCache?: UsageCacheEntry;
 	#usageInflight?: Promise<UsageReport[] | null>;
 	#credentialBlockReconcileAfter: Map<string, number> = new Map();
+	/** Exact deleted rows suppressed until their old deadline, including snapshots racing the DELETE acknowledgement. */
+	#deletedCredentialBlocks: Map<string, CredentialBlockSnapshot> = new Map();
+	/** Local block writes not yet reflected by the broker; see {@link #pendingBlocksFor}. */
+	#pendingCredentialBlocks: Map<string, CredentialBlockSnapshot> = new Map();
 	#usageCacheEpoch = 0;
 	/** Raw broker credentials retained to size aggregate usage requests before account-pool filtering. */
 	#brokerUsageProviderByCredentialId = new Map<number, Provider>();
@@ -379,16 +388,13 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		const previousBlocksByKey = new Map<string, string>();
 		for (const entry of previous) {
 			for (const block of entry.blocks ?? []) {
-				previousBlocksByKey.set(
-					`${entry.id}\0${block.providerKey}\0${block.blockScope}`,
-					`${block.blockedUntilMs}\0${block.updatedAtMs ?? ""}`,
-				);
+				previousBlocksByKey.set(blockKey(entry.id, block), `${block.blockedUntilMs}\0${block.updatedAtMs ?? ""}`);
 			}
 		}
 		const activeKeys = new Set<string>();
 		for (const entry of next) {
 			for (const block of entry.blocks ?? []) {
-				const key = `${entry.id}\0${block.providerKey}\0${block.blockScope}`;
+				const key = blockKey(entry.id, block);
 				activeKeys.add(key);
 				const signature = `${block.blockedUntilMs}\0${block.updatedAtMs ?? ""}`;
 				if (previousBlocksByKey.get(key) === signature) continue;
@@ -675,7 +681,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined {
 		if (this.getCredentialBlock(credentialId, providerKey, blockScope) === undefined) return undefined;
-		return this.#credentialBlockReconcileAfter.get(`${credentialId}\0${providerKey}\0${blockScope}`);
+		return this.#credentialBlockReconcileAfter.get(blockKey(credentialId, { providerKey, blockScope }));
 	}
 
 	listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[] {
@@ -705,11 +711,14 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		this.#noteActivity();
 		this.#upsertSnapshotBlock(block);
 		this.#invalidateUsageCache();
+		const key = blockKey(block.credentialId, block);
 		this.#credentialBlockReconcileAfter.set(
-			`${block.credentialId}\0${block.providerKey}\0${block.blockScope}`,
+			key,
 			Math.min(block.blockedUntilMs, Date.now() + CREDENTIAL_BLOCK_RECONCILE_DELAY_MS),
 		);
 		const body = toCredentialBlockSnapshot(block);
+		const pending = this.#pendingCredentialBlocks.get(key);
+		if (!pending || pending.blockedUntilMs < body.blockedUntilMs) this.#pendingCredentialBlocks.set(key, body);
 		void this.#client
 			.upsertCredentialBlock(block.credentialId, body)
 			.then(() => {
@@ -725,14 +734,39 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			});
 	}
 
-	deleteCredentialBlock(_credentialId: number, _providerKey: string, _blockScope: string): void {
-		// The broker protocol only supports deleting every block for a credential.
-		// Keep scoped blocks until expiry rather than risk deleting unrelated or
-		// newer broker state through that broader operation.
+	deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void {
+		this.#noteActivity();
+		const key = blockKey(credentialId, { providerKey, blockScope });
+		this.#pendingCredentialBlocks.delete(key);
+		const deleted = this.#snapshot.credentials
+			.find(entry => entry.id === credentialId)
+			?.blocks?.find(block => block.providerKey === providerKey && block.blockScope === blockScope);
+		if (deleted) this.#deletedCredentialBlocks.set(key, deleted);
+		this.#deleteSnapshotBlocks(credentialId, { providerKey, blockScope });
+		this.#credentialBlockReconcileAfter.delete(key);
+		this.#invalidateUsageCache();
+		void this.#client
+			.deleteCredentialBlock(credentialId, { providerKey, blockScope })
+			.then(() => {
+				this.#maybeRefreshSnapshot("credential block delete");
+			})
+			.catch(error => {
+				if (this.#deletedCredentialBlocks.get(key) === deleted) this.#deletedCredentialBlocks.delete(key);
+				this.#maybeRefreshSnapshot("credential block delete failed");
+				logger.warn("auth-broker credential block delete propagation failed", {
+					id: credentialId,
+					providerKey,
+					blockScope,
+					error: String(error),
+				});
+			});
 	}
 
 	deleteCredentialBlocks(credentialId: number): void {
 		this.#noteActivity();
+		for (const key of this.#pendingCredentialBlocks.keys()) {
+			if (key.startsWith(`${credentialId}\0`)) this.#pendingCredentialBlocks.delete(key);
+		}
 		this.#deleteSnapshotBlocks(credentialId);
 		for (const key of this.#credentialBlockReconcileAfter.keys()) {
 			if (key.startsWith(`${credentialId}\0`)) this.#credentialBlockReconcileAfter.delete(key);
@@ -753,6 +787,12 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	cleanExpiredCredentialBlocks(nowMs: number): void {
 		this.#pruneExpiredCredentialBlocks(nowMs);
+		for (const [key, block] of this.#deletedCredentialBlocks) {
+			if (block.blockedUntilMs <= nowMs) this.#deletedCredentialBlocks.delete(key);
+		}
+		for (const [key, block] of this.#pendingCredentialBlocks) {
+			if (block.blockedUntilMs <= nowMs) this.#pendingCredentialBlocks.delete(key);
+		}
 		for (const [key, reconcileAfterMs] of this.#credentialBlockReconcileAfter) {
 			if (reconcileAfterMs <= nowMs) this.#credentialBlockReconcileAfter.delete(key);
 		}
@@ -938,9 +978,29 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	#normalizeSnapshotEntryBlocks(entry: SnapshotEntry, nowMs: number): SnapshotEntry {
-		if (!entry.blocks || entry.blocks.length === 0) return entry;
-		const blocks = entry.blocks
-			.filter(block => block.blockedUntilMs > nowMs)
+		const pending = this.#pendingBlocksFor(entry, nowMs);
+		if ((!entry.blocks || entry.blocks.length === 0) && pending.length === 0) return entry;
+		// A pending row replaces a shorter reported row for the same scope.
+		const merged = [
+			...(entry.blocks ?? []).filter(
+				block =>
+					!pending.some(
+						candidate => candidate.providerKey === block.providerKey && candidate.blockScope === block.blockScope,
+					),
+			),
+			...pending,
+		];
+		const blocks = merged
+			.filter(block => {
+				if (block.blockedUntilMs <= nowMs) return false;
+				const deleted = this.#deletedCredentialBlocks.get(blockKey(entry.id, block));
+				// Suppress only the exact row we deleted. A fresh block in this
+				// scope, including one with the same deadline but a newer update,
+				// remains authoritative while the DELETE propagates.
+				return (
+					!deleted || deleted.blockedUntilMs !== block.blockedUntilMs || deleted.updatedAtMs !== block.updatedAtMs
+				);
+			})
 			.map(block => ({
 				providerKey: block.providerKey,
 				blockScope: block.blockScope,
@@ -954,7 +1014,32 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		return next;
 	}
 
+	/**
+	 * Locally written blocks the incoming entry does not yet carry. The broker
+	 * write is asynchronous: a snapshot racing it, or a failed write, must not
+	 * erase a block this process still depends on. A pending row retires once the
+	 * broker reports it (or a longer deadline) or when it expires.
+	 */
+	#pendingBlocksFor(entry: SnapshotEntry, nowMs: number): CredentialBlockSnapshot[] {
+		if (this.#pendingCredentialBlocks.size === 0) return [];
+		const pending: CredentialBlockSnapshot[] = [];
+		const prefix = `${entry.id}\0`;
+		for (const [key, block] of this.#pendingCredentialBlocks) {
+			if (!key.startsWith(prefix)) continue;
+			const reported = entry.blocks?.find(
+				candidate => candidate.providerKey === block.providerKey && candidate.blockScope === block.blockScope,
+			);
+			if (block.blockedUntilMs <= nowMs || (reported && reported.blockedUntilMs >= block.blockedUntilMs)) {
+				this.#pendingCredentialBlocks.delete(key);
+				continue;
+			}
+			pending.push(block);
+		}
+		return pending;
+	}
+
 	#upsertSnapshotBlock(block: StoredCredentialBlock): void {
+		this.#deletedCredentialBlocks.delete(blockKey(block.credentialId, block));
 		const index = this.#snapshot.credentials.findIndex(entry => entry.id === block.credentialId);
 		if (index === -1) return;
 		const entry = this.#snapshot.credentials[index]!;
@@ -978,13 +1063,20 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		this.#snapshot = { ...this.#snapshot, credentials };
 	}
 
-	#deleteSnapshotBlocks(credentialId: number): void {
+	#deleteSnapshotBlocks(credentialId: number, target?: { providerKey: string; blockScope: string }): void {
 		const index = this.#snapshot.credentials.findIndex(entry => entry.id === credentialId);
 		if (index === -1) return;
 		const entry = this.#snapshot.credentials[index]!;
 		if (!entry.blocks || entry.blocks.length === 0) return;
+		const blocks = target
+			? entry.blocks.filter(
+					block => block.providerKey !== target.providerKey || block.blockScope !== target.blockScope,
+				)
+			: [];
+		if (blocks.length === entry.blocks.length) return;
 		const next: SnapshotEntry = { ...entry };
-		delete next.blocks;
+		if (blocks.length > 0) next.blocks = blocks;
+		else delete next.blocks;
 		const credentials = [...this.#snapshot.credentials];
 		credentials[index] = next;
 		this.#snapshot = { ...this.#snapshot, credentials };
@@ -1050,14 +1142,22 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	async invalidateUsageCache(signal?: AbortSignal): Promise<void> {
 		this.#noteActivity();
 		this.#invalidateUsageCache();
-		await this.#client.notifyUsageStale(signal).catch(err => {
+		try {
+			await this.#client.notifyUsageStale(signal);
+		} catch (err) {
 			logger.warn("auth-broker notification of stale usage failed", { error: String(err) });
-		});
+		} finally {
+			// A concurrent read may have reached the broker before it processed the
+			// notification. That response cannot seed the post-notification cache.
+			this.#invalidateUsageCache();
+		}
 	}
 
 	#invalidateUsageCache(): void {
-		this.#usageCache = undefined;
-		this.#usageInflight = undefined;
+		// Snapshot/block updates invalidate quota evidence, not a failed broker
+		// connection's cooldown. Keep the flight too: its completion will queue
+		// one current-generation successor instead of overlapping broker calls.
+		if (this.#usageCache?.reports !== null) this.#usageCache = undefined;
 		this.#usageCacheEpoch += 1;
 	}
 
@@ -1102,9 +1202,8 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	/**
 	 * Store-level hook consumed by `AuthStorage.usage.reports()` — proxies
-	 * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't
-	 * rate-limited by Anthropic's per-IP `/usage` cap the way a heavy
-	 * residential laptop is, so all credentials surface every cycle.
+	 * to the broker's `/v1/usage` endpoint. Shared per-credential caches and
+	 * cooldowns keep separate clients from multiplying provider probes.
 	 */
 	async fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null> {
 		this.#noteActivity();
@@ -1119,8 +1218,8 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	 * same response (coalesced + cached), then overlays any client-observed
 	 * header hints for the matching credential.
 	 *
-	 * The broker already aggregates with its own 30s TTL on the server side; our
-	 * 15s client TTL is below that so we usually re-use the broker's cache too.
+	 * The broker caches each credential independently; the short client TTL
+	 * also folds sequential consumers into one broker round-trip.
 	 */
 	async getUsageReport(
 		provider: Provider,
@@ -1280,7 +1379,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		const inflight = this.#client
 			.fetchUsage({ maxAccountsPerProvider: this.#maxBrokerUsageAccounts() })
 			.then(body => {
-				if (epoch !== this.#usageCacheEpoch) return this.#loadUsageReports();
+				if (epoch !== this.#usageCacheEpoch) {
+					if (this.#usageInflight === inflight) this.#usageInflight = undefined;
+					return this.#loadUsageReports();
+				}
 				this.#usageCache = { reports: body.reports, fetchedAt: Date.now() };
 				return body.reports;
 			})
@@ -1289,7 +1391,6 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 				// Documented 15s TTL fallback: cache the null so sequential callers
 				// don't re-hit the broker while it's still down. See
 				// docs/auth-broker-gateway.md § "Client-side single-flight".
-				if (epoch !== this.#usageCacheEpoch) return this.#loadUsageReports();
 				this.#usageCache = { reports: null, fetchedAt: Date.now() };
 				return null;
 			})

package/src/auth-broker/server.ts

@@ -43,6 +43,7 @@ import {
 } from "./types";
 import {
 	clientUsageReportRequestSchema,
+	credentialBlockDeleteRequestSchema,
 	credentialBlockRequestSchema,
 	credentialDisableRequestSchema,
 	credentialUploadRequestSchema,
@@ -832,6 +833,25 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 						return json(status, { error: message });
 					}
 				}
+				const blockDeleteMatch = req.method === "DELETE" ? pathname.match(BLOCK_ROUTE) : null;
+				if (blockDeleteMatch) {
+					const id = Number.parseInt(blockDeleteMatch[1], 10);
+					const parsed = await parseBody(req, credentialBlockDeleteRequestSchema);
+					if (!parsed.ok) return parsed.response;
+					if (!opts.storage.credentials.snapshot().credentials.some(entry => entry.id === id)) {
+						return json(404, { error: `No credential with id=${id}` });
+					}
+					try {
+						opts.storage.blocks.delete(id, parsed.data.providerKey, parsed.data.blockScope);
+						const response: CredentialBlocksDeleteResponse = { ok: true };
+						logger.info("auth-broker credential block deleted", { id, peer, ...parsed.data });
+						return json(200, response);
+					} catch (error) {
+						const message = error instanceof Error ? error.message : String(error);
+						logger.warn("auth-broker credential block delete failed", { id, peer, error: message });
+						return json(500, { error: message });
+					}
+				}
 				const blocksDeleteMatch = req.method === "DELETE" ? pathname.match(BLOCKS_ROUTE) : null;
 				if (blocksDeleteMatch) {
 					const id = Number.parseInt(blocksDeleteMatch[1], 10);

package/src/auth-broker/types.ts

@@ -96,12 +96,15 @@ export interface DisabledCredentialsResponse {
 /** POST /v1/credential/:id/block request body. */
 export type CredentialBlockRequest = CredentialBlockSnapshot;
 
+/** DELETE /v1/credential/:id/block request body; empty scope targets only the global row. */
+export type CredentialBlockDeleteRequest = Pick<CredentialBlockSnapshot, "providerKey" | "blockScope">;
+
 /** POST /v1/credential/:id/block response body. */
 export interface CredentialBlockResponse {
 	ok: boolean;
 }
 
-/** DELETE /v1/credential/:id/blocks response body. */
+/** DELETE /v1/credential/:id/block or /blocks response body. */
 export interface CredentialBlocksDeleteResponse {
 	ok: boolean;
 }

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

@@ -27,6 +27,7 @@ import type {
 	ClientUsageReportRequest,
 	ClientUsageReportResponse,
 	ClientUsageSummaryResponse,
+	CredentialBlockDeleteRequest,
 	CredentialBlockRequest,
 	CredentialBlockResponse,
 	CredentialBlockSnapshot,
@@ -393,6 +394,12 @@ export const disabledCredentialsResponseSchema: FluentType<DisabledCredentialsRe
 
 export const credentialBlockRequestSchema: FluentType<CredentialBlockRequest> = credentialBlockSnapshotSchema;
 
+export const credentialBlockDeleteRequestSchema: FluentType<CredentialBlockDeleteRequest> = type({
+	"+": "reject",
+	providerKey: type("string").atLeastLength(1),
+	blockScope: "string",
+});
+
 export const credentialBlockResponseSchema: FluentType<CredentialBlockResponse> = type({
 	"+": "reject",
 	ok: "boolean",

package/src/auth-retry.ts

@@ -18,10 +18,10 @@ import { isConcurrencyCapExclusion, isUsageLimitOutcome } from "./error/rate-lim
  * - `error !== undefined && lastChance` → **step (c): switch account**
  *   (invalidate/usage-limit the current credential and rotate to a sibling).
  *
- * Current drivers preserve that bounded a/b/c sequence for ordinary 401/auth
- * failures. Account-scoped policy denials, 403s, and usage-limit failures skip
- * refresh and may repeat step (c) until the resolver returns `undefined`,
- * cycles, or hits {@link AUTH_RETRY_MAX_ATTEMPTS}.
+ * Current drivers give an ordinary 401/auth failure one step (b) before
+ * repeating step (c) through distinct siblings. Account-scoped policy denials,
+ * 403s, and usage-limit failures skip refresh. Rotation stops when the resolver
+ * returns `undefined`, cycles, or hits {@link AUTH_RETRY_MAX_ATTEMPTS}.
  */
 export interface ApiKeyResolveContext {
 	/** True when the resolver should rotate to a sibling credential. */
@@ -42,6 +42,12 @@ export interface ResolvedApiKey {
 	apiKey: string;
 	/** Durable row id of the credential that supplied this bearer, when known. */
 	credentialId?: number;
+	/**
+	 * Resolved after `LimitsApi.rotate` slept out a sibling's short block
+	 * (`afterSiblingWait`): the driver accepts this bearer even if the request
+	 * already sent it before that block.
+	 */
+	afterSiblingWait?: boolean;
 }
 
 export type ApiKeyResolution = string | ResolvedApiKey | undefined;
@@ -53,6 +59,19 @@ export function resolvedApiKeyBearer(resolved: ApiKeyResolution): string | undef
 	return (typeof resolved === "string" ? resolved : resolved?.apiKey) || undefined;
 }
 
+/**
+ * Mark a post-rotation resolution as following a sibling-unblock wait so the
+ * retry driver may resend a bearer it already tried. Used by the rotating
+ * resolvers (`KeyCascade.resolver`, coding-agent `createApiKeyResolver`).
+ */
+export function markAfterSiblingWait(resolved: ApiKeyResolution): ApiKeyResolution {
+	const apiKey = resolvedApiKeyBearer(resolved);
+	if (apiKey === undefined) return resolved;
+	return typeof resolved === "string"
+		? { apiKey, afterSiblingWait: true }
+		: { ...resolved, apiKey, afterSiblingWait: true };
+}
+
 /** A static bearer string, or a {@link ApiKeyResolver} that mints/rotates one. */
 export type ApiKey = string | ApiKeyResolver;
 
@@ -105,9 +124,8 @@ export function seedApiKeyResolver(seed: ApiKeyResolution, resolver: ApiKeyResol
 export { isAuthRetryableError };
 
 /**
- * Legacy bounded a/b/c retry sequence retained for public compatibility:
- * `false` → refresh-same, `true` → rotate/switch. Current drivers consume it
- * once for ordinary 401/auth failures; usage/account-limit failures may repeat
+ * Legacy a/b/c retry sequence retained for public compatibility:
+ * `false` → refresh-same, `true` → rotate/switch. Current drivers may repeat
  * sibling rotation until a termination guard fires.
  */
 export const AUTH_RETRY_STEPS: readonly boolean[] = [false, true];
@@ -155,8 +173,6 @@ export interface AuthRetryKeyState {
 	lastKey: string;
 	/** Whether the current credential already consumed its 401 refresh-same retry. */
 	refreshedCurrent: boolean;
-	/** Whether the legacy non-usage auth path already switched to one sibling. */
-	legacyAuthSwitchUsed: boolean;
 	/** Whether this operation already replayed once after an explicit token-refresh request. */
 	tokenRefreshReplayUsed?: boolean;
 	/** Total outbound attempts accepted for this logical operation, including the initial request. */
@@ -168,14 +184,20 @@ export function createAuthRetryKeyState(initialKey: string): AuthRetryKeyState {
 		attemptedKeys: new Set([initialKey]),
 		lastKey: initialKey,
 		refreshedCurrent: false,
-		legacyAuthSwitchUsed: false,
 		tokenRefreshReplayUsed: false,
 		attempts: 1,
 	};
 }
 
-function acceptRetryKey(state: AuthRetryKeyState, key: string, refreshedCurrent: boolean): string | undefined {
-	if (state.attemptedKeys.has(key) || state.attempts >= AUTH_RETRY_MAX_ATTEMPTS) return undefined;
+function acceptRetryKey(
+	state: AuthRetryKeyState,
+	key: string,
+	refreshedCurrent: boolean,
+	afterSiblingWait = false,
+): string | undefined {
+	if ((!afterSiblingWait && state.attemptedKeys.has(key)) || state.attempts >= AUTH_RETRY_MAX_ATTEMPTS) {
+		return undefined;
+	}
 	state.attemptedKeys.add(key);
 	state.attempts += 1;
 	state.lastKey = key;
@@ -202,7 +224,6 @@ export async function resolveNextAuthRetryKey(
 	}
 	const directRotation = isDirectCredentialRotationError(error);
 	if (!directRotation) {
-		if (state.legacyAuthSwitchUsed) return undefined;
 		if (!state.refreshedCurrent) {
 			const refreshed = await resolveRetryKey(resolver, false, error, signal, state.lastKey, onResolved);
 			state.refreshedCurrent = true;
@@ -215,11 +236,13 @@ export async function resolveNextAuthRetryKey(
 	}
 
 	if (signal?.aborted) return undefined;
-	const rotated = await resolveRetryKey(resolver, true, error, signal, state.lastKey, onResolved);
+	let afterSiblingWait = false;
+	const rotated = await resolveRetryKey(resolver, true, error, signal, state.lastKey, resolved => {
+		afterSiblingWait = typeof resolved === "object" && resolved.afterSiblingWait === true;
+		onResolved?.(resolved);
+	});
 	if (signal?.aborted || rotated === undefined) return undefined;
-	const accepted = acceptRetryKey(state, rotated, !directRotation);
-	if (accepted !== undefined && !directRotation) state.legacyAuthSwitchUsed = true;
-	return accepted;
+	return acceptRetryKey(state, rotated, !directRotation, afterSiblingWait);
 }
 
 function oauthCredentialIdentity(access: OAuthAccess): string {
@@ -248,9 +271,9 @@ async function runOAuthAttempt<T>(
  *   applicable policy is exhausted, the resolver declines or cycles, or the
  *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. An explicit typed
  *   token-refresh request gets exactly one refresh-current replay and never
- *   enters sibling rotation. Ordinary 401/auth failures retain one
- *   refresh-same plus one sibling switch; 403/usage-limit failures rotate
- *   directly through distinct siblings.
+ *   enters sibling rotation. Ordinary 401/auth failures get one refresh-same,
+ *   then rotate through distinct siblings; 403/usage-limit failures skip the
+ *   refresh and rotate directly.
  *
  * Used by non-streaming consumers (image generation, web search, completion
  * helpers). The streaming driver in `stream.ts` implements the same policy with
@@ -331,7 +354,7 @@ export interface WithOAuthAccessOptions {
  * - initial → `getOAuthAccess` (or `opts.seed`).
  * - typed token-refresh request → one forced refresh-current replay, then stop.
  * - 401/auth failure → one `getOAuthAccess` with `forceRefresh: true` for the
- *   current account, then sibling rotation.
+ *   current account, then sibling rotation through distinct credentials.
  * - 403/usage-limit failure → `rotateSessionCredential` directly, without a
  *   force-refresh detour.
  *
@@ -363,7 +386,6 @@ export async function withOAuthAccess<T>(
 	const attemptedBearers = new Set([lastAccess.accessToken]);
 	const attemptedCredentialIdentities = new Set([oauthCredentialIdentity(lastAccess)]);
 	let attemptCount = 1;
-	let legacyAuthSwitchUsed = false;
 	let refreshedCurrent = false;
 	let tokenRefreshReplayUsed = false;
 	let attemptResult = await runOAuthAttempt(lastAccess, attempt, isAuthError);
@@ -398,7 +420,6 @@ export async function withOAuthAccess<T>(
 
 		const directRotation = isDirectCredentialRotationError(lastError);
 		if (!directRotation) {
-			if (legacyAuthSwitchUsed) break;
 			if (!refreshedCurrent) {
 				refreshedCurrent = true;
 				try {
@@ -424,14 +445,16 @@ export async function withOAuthAccess<T>(
 		}
 
 		if (signal?.aborted || attemptCount >= AUTH_RETRY_MAX_ATTEMPTS) break;
+		let afterSiblingWait = false;
 		try {
-			const rotated = await storage.limits.rotate(provider, sessionId, {
+			const rotation = await storage.limits.rotate(provider, sessionId, {
 				error: lastError,
 				signal,
 				apiKey: lastAccess.accessToken,
 				credentialId: lastAccess.credentialId,
 			});
-			if (!rotated) break;
+			if (!rotation.switched) break;
+			afterSiblingWait = rotation.afterSiblingWait === true;
 			next = await storage.oauth.access(provider, sessionId, { signal });
 		} catch {
 			next = undefined;
@@ -439,8 +462,8 @@ export async function withOAuthAccess<T>(
 		if (signal?.aborted || !next) break;
 		const credentialIdentity = oauthCredentialIdentity(next);
 		if (
-			attemptedCredentialIdentities.has(credentialIdentity) ||
-			attemptedBearers.has(next.accessToken) ||
+			(!afterSiblingWait &&
+				(attemptedCredentialIdentities.has(credentialIdentity) || attemptedBearers.has(next.accessToken))) ||
 			attemptCount >= AUTH_RETRY_MAX_ATTEMPTS
 		) {
 			break;
@@ -450,7 +473,6 @@ export async function withOAuthAccess<T>(
 		attemptCount += 1;
 		lastAccess = next;
 		refreshedCurrent = !directRotation;
-		if (!directRotation) legacyAuthSwitchUsed = true;
 		attemptResult = await runOAuthAttempt(next, attempt, isAuthError);
 		if (attemptResult.ok) return attemptResult.result;
 		lastError = attemptResult.error;

package/src/images/openai-hosted.ts

@@ -20,11 +20,15 @@ const IMAGE_SYSTEM_INSTRUCTION =
 interface HostedOutput {
 	type: "image_generation_call" | "message";
 	result?: string;
+	size?: string;
+	quality?: string;
 	content?: Array<{ type?: string; text?: string; refusal?: string }>;
 }
 
 interface HostedResponse {
 	output?: HostedOutput[];
+	/** Resolved tool configuration echoed by the backend, including the image model that actually ran. */
+	tools?: Array<{ type?: string; model?: string }>;
 	usage?: { input_tokens?: number; output_tokens?: number };
 	error?: { message?: string };
 }
@@ -83,7 +87,12 @@ function collectResponse(response: HostedResponse): ImageGenerationResult {
 	for (const output of response.output ?? []) {
 		if (output.type === "image_generation_call" && output.result) {
 			const bytes = Buffer.from(output.result, "base64");
-			images.push({ data: output.result, mimeType: parseImageMetadata(bytes)?.mimeType ?? "image/webp" });
+			images.push({
+				data: output.result,
+				mimeType: parseImageMetadata(bytes)?.mimeType ?? "image/webp",
+				...(output.size ? { size: output.size } : {}),
+				...(output.quality ? { quality: output.quality } : {}),
+			});
 		}
 		if (output.type === "message") {
 			for (const part of output.content ?? []) {
@@ -93,7 +102,13 @@ function collectResponse(response: HostedResponse): ImageGenerationResult {
 		}
 	}
 	const text = texts.join("\n").trim();
-	return { images, ...(text ? { text } : {}), usage: usageFromWire(response.usage) };
+	const model = response.tools?.find(tool => tool.type === "image_generation")?.model;
+	return {
+		images,
+		...(text ? { text } : {}),
+		usage: usageFromWire(response.usage),
+		...(model ? { model } : {}),
+	};
 }
 
 async function parseSse(response: Response, signal?: AbortSignal): Promise<ImageGenerationResult> {
@@ -116,7 +131,7 @@ async function parseSse(response: Response, signal?: AbortSignal): Promise<Image
 			completed = event.response;
 		}
 	}
-	return collectResponse(completed?.output?.length ? completed : { output: fallbackOutput, usage: completed?.usage });
+	return collectResponse(completed?.output?.length ? completed : { ...completed, output: fallbackOutput });
 }
 
 export async function generateHostedImage(

package/src/images/types.ts

@@ -17,12 +17,21 @@ export interface ImageGenerationRequest {
 export interface GeneratedImage {
 	data: string;
 	mimeType: string;
+	/** Output dimensions (`WIDTHxHEIGHT`) the provider reports for this image, which may differ from the request. */
+	size?: string;
+	/** Rendering quality the provider reports for this image. */
+	quality?: string;
 }
 
 export interface ImageGenerationResult {
 	images: GeneratedImage[];
 	text?: string;
 	usage: Usage;
+	/**
+	 * Image model the provider reports having run. Hosted backends may substitute their own model for the
+	 * selected catalog entry (the ChatGPT/Codex backend does), so callers should prefer this over the catalog id.
+	 */
+	model?: string;
 }
 
 export interface ImageGenerationOptions {

package/src/index.ts

@@ -39,6 +39,7 @@ export type * from "./providers/openai-completions";
 export type * from "./providers/openai-responses";
 export type * from "./providers/synthetic";
 export * from "./registry";
+export { resolveCacheRetention } from "./utils";
 export * from "./stream";
 export * from "./types";
 export * from "./usage";

package/src/judgment/types.ts

@@ -117,15 +117,19 @@ export class JudgmentParseError extends Error {
 
 /**
  * Usage from a backend that reports token counts and, optionally, one billed
- * USD amount. Judgment pricing is input-only, so the amount lands on `input`.
+ * USD amount. Missing or non-finite amounts contribute zero to session totals.
+ * Judgment pricing is input-only, so the amount lands on `input`.
  */
-export function tokenUsage(input: number, output: number, cost = 0): Usage {
+export function tokenUsage(input: number | undefined, output: number | undefined, cost = 0): Usage {
+	const inputTokens = typeof input === "number" && Number.isFinite(input) ? input : 0;
+	const outputTokens = typeof output === "number" && Number.isFinite(output) ? output : 0;
+	const billedCost = Number.isFinite(cost) ? cost : 0;
 	return {
-		input,
-		output,
+		input: inputTokens,
+		output: outputTokens,
 		cacheRead: 0,
 		cacheWrite: 0,
-		totalTokens: input + output,
-		cost: { input: cost, output: 0, cacheRead: 0, cacheWrite: 0, total: cost },
+		totalTokens: inputTokens + outputTokens,
+		cost: { input: billedCost, output: 0, cacheRead: 0, cacheWrite: 0, total: billedCost },
 	};
 }