@oh-my-pi/pi-ai 18.0.5 → 18.0.6

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [18.0.6] - 2026-08-26
+
+### Added
+
+- Added the `backgroundIdleMs` option to customize how long background auth-broker activity remains active before automatically parking.
+
+### Fixed
+
+- Fixed auth-broker background activity keeping processes alive unnecessarily, so unused broker-backed auth storage now parks automatically and no longer prevents CLI exit.
+
 ## [18.0.5] - 2026-08-25
 
 ### Breaking Changes

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

@@ -35,6 +35,14 @@ export interface RemoteAuthCredentialStoreOptions {
     accountPool?: AuthBrokerAccountPool;
     /** Flush cadence for batched observed-usage reports. Default 10s. */
     observedUsageFlushMs?: number;
+    /**
+     * Idle window after the last foreground store use before background
+     * snapshot sync (SSE stream / long-poll) disconnects and parks. A parked
+     * store holds no timers or sockets, so an unclosed store never keeps the
+     * process alive longer than one idle window. Sync resumes transparently on
+     * the next use. Default 20s.
+     */
+    backgroundIdleMs?: number;
 }
 export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     #private;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.0.5",
+	"version": "18.0.6",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,10 +37,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.0.5",
-		"@oh-my-pi/pi-catalog": "18.0.5",
-		"@oh-my-pi/pi-utils": "18.0.5",
-		"@oh-my-pi/pi-wire": "18.0.5"
+		"@oh-my-pi/omptype": "18.0.6",
+		"@oh-my-pi/pi-catalog": "18.0.6",
+		"@oh-my-pi/pi-utils": "18.0.6",
+		"@oh-my-pi/pi-wire": "18.0.6"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

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

@@ -8,7 +8,6 @@
  * runs isn't required.
  */
 import * as os from "node:os";
-import { scheduler } from "node:timers/promises";
 import { getInstallId, logger } from "@oh-my-pi/pi-utils";
 import {
 	type AuthCredential,
@@ -64,6 +63,8 @@ const MAX_WAIT_MS = 5_000;
 const BACKGROUND_WAIT_MS = 30_000;
 const BACKGROUND_BACKOFF_INITIAL_MS = 500;
 const BACKGROUND_BACKOFF_MAX_MS = 30_000;
+/** Idle window after the last foreground store use before background sync parks. */
+const BACKGROUND_IDLE_MS = 20_000;
 
 function compareCredentialBlockSnapshots(a: CredentialBlockSnapshot, b: CredentialBlockSnapshot): number {
 	const provider = a.providerKey.localeCompare(b.providerKey);
@@ -236,6 +237,14 @@ export interface RemoteAuthCredentialStoreOptions {
 	accountPool?: AuthBrokerAccountPool;
 	/** Flush cadence for batched observed-usage reports. Default 10s. */
 	observedUsageFlushMs?: number;
+	/**
+	 * Idle window after the last foreground store use before background
+	 * snapshot sync (SSE stream / long-poll) disconnects and parks. A parked
+	 * store holds no timers or sockets, so an unclosed store never keeps the
+	 * process alive longer than one idle window. Sync resumes transparently on
+	 * the next use. Default 20s.
+	 */
+	backgroundIdleMs?: number;
 }
 
 export class RemoteAuthCredentialStore implements AuthCredentialStore {
@@ -248,6 +257,11 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	#generation = 0;
 	#usageOverlays: Map<string, UsageReport> = new Map();
 	#backgroundAbort = new AbortController();
+	readonly #backgroundIdleMs: number;
+	/** Last foreground store use; background sync parks `#backgroundIdleMs` after this. */
+	#lastActivityMs = Date.now();
+	/** Present while the background loop is parked; resolved by `#noteActivity` or `close()`. */
+	#activityWakeup: PromiseWithResolvers<void> | null = null;
 	#cache: Map<string, CacheEntry> = new Map();
 	#usageCache?: UsageCacheEntry;
 	#usageInflight?: Promise<UsageReport[] | null>;
@@ -281,6 +295,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		this.#client = opts.client;
 		this.#streamSnapshots = opts.streamSnapshots ?? true;
 		this.#observedUsageFlushMs = opts.observedUsageFlushMs ?? 10_000;
+		this.#backgroundIdleMs = opts.backgroundIdleMs ?? BACKGROUND_IDLE_MS;
 		this.#accountPool = opts.accountPool
 			? new Map([...opts.accountPool].map(([provider, identities]) => [provider, new Set(identities)]))
 			: undefined;
@@ -294,6 +309,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	get snapshot(): SnapshotResponse {
+		this.#noteActivity();
 		return this.#snapshot;
 	}
 
@@ -346,49 +362,132 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
+	/**
+	 * Background snapshot sync. Invariant: this loop never keeps the process
+	 * alive on its own. While the store is in active foreground use it holds a
+	 * live broker request (SSE stream or long-poll); once the store has been
+	 * idle for `#backgroundIdleMs` an unref'd watchdog aborts that request and
+	 * the loop parks on a bare promise — zero timers or sockets — until the
+	 * next foreground call. Backoff sleeps use unref'd timers for the same
+	 * reason. A leaked (never-closed) store therefore stops pinning the event
+	 * loop at most one idle window after its last use.
+	 */
 	async #runBackground(): Promise<void> {
 		let backoffMs = BACKGROUND_BACKOFF_INITIAL_MS;
 		while (!this.#closed && !this.#backgroundAbort.signal.aborted) {
-			if (this.#streamSnapshots && !this.#streamingUnsupported) {
+			if (this.#idleRemainingMs() <= 0) {
+				this.#activityWakeup ??= Promise.withResolvers<void>();
+				await this.#activityWakeup.promise;
+				continue;
+			}
+			const watchdog = this.#startIdleWatchdog();
+			try {
+				if (this.#streamSnapshots && !this.#streamingUnsupported) {
+					try {
+						await this.#consumeSnapshotStream(watchdog.signal);
+						backoffMs = BACKGROUND_BACKOFF_INITIAL_MS;
+					} catch (error) {
+						if (this.#closed || this.#backgroundAbort.signal.aborted) break;
+						if (watchdog.idled()) continue;
+						if (error instanceof AuthBrokerStreamUnsupportedError) {
+							this.#streamingUnsupported = true;
+							logger.debug("auth-broker snapshot stream unsupported; falling back to long-poll");
+							continue;
+						}
+						logger.debug("auth-broker snapshot stream failed; backing off", { error: String(error) });
+						await this.#backoffWait(backoffMs);
+						backoffMs = Math.min(BACKGROUND_BACKOFF_MAX_MS, backoffMs * 2);
+					}
+					continue;
+				}
 				try {
-					await this.#consumeSnapshotStream();
+					const result = await this.#client.fetchSnapshot({
+						ifGenerationGt: this.#generation,
+						waitMs: BACKGROUND_WAIT_MS,
+						signal: watchdog.signal,
+					});
+					if (result.status === 200) this.#applySnapshot(result.snapshot, result.generation);
 					backoffMs = BACKGROUND_BACKOFF_INITIAL_MS;
-					continue;
 				} catch (error) {
 					if (this.#closed || this.#backgroundAbort.signal.aborted) break;
-					if (error instanceof AuthBrokerStreamUnsupportedError) {
-						this.#streamingUnsupported = true;
-						logger.debug("auth-broker snapshot stream unsupported; falling back to long-poll");
-						continue;
-					}
-					logger.debug("auth-broker snapshot stream failed; backing off", { error: String(error) });
-					await scheduler.wait(backoffMs, { signal: this.#backgroundAbort.signal }).catch(() => {});
+					if (watchdog.idled()) continue;
+					logger.debug("auth-broker background snapshot sync failed", { error: String(error) });
+					await this.#backoffWait(backoffMs);
 					backoffMs = Math.min(BACKGROUND_BACKOFF_MAX_MS, backoffMs * 2);
-					continue;
 				}
+			} finally {
+				watchdog.stop();
 			}
-			try {
-				const result = await this.#client.fetchSnapshot({
-					ifGenerationGt: this.#generation,
-					waitMs: BACKGROUND_WAIT_MS,
-					signal: this.#backgroundAbort.signal,
-				});
-				if (result.status === 200) this.#applySnapshot(result.snapshot, result.generation);
-				backoffMs = BACKGROUND_BACKOFF_INITIAL_MS;
-			} catch (error) {
-				if (this.#closed || this.#backgroundAbort.signal.aborted) break;
-				logger.debug("auth-broker background snapshot sync failed", { error: String(error) });
-				await scheduler.wait(backoffMs, { signal: this.#backgroundAbort.signal }).catch(() => {});
-				backoffMs = Math.min(BACKGROUND_BACKOFF_MAX_MS, backoffMs * 2);
+		}
+	}
+
+	/** Record a foreground store use; wakes the parked background sync. */
+	#noteActivity(): void {
+		this.#lastActivityMs = Date.now();
+		if (this.#activityWakeup) {
+			this.#activityWakeup.resolve();
+			this.#activityWakeup = null;
+		}
+	}
+
+	#idleRemainingMs(): number {
+		return this.#lastActivityMs + this.#backgroundIdleMs - Date.now();
+	}
+
+	/**
+	 * Abort signal for one background iteration that trips once the store has
+	 * been idle for `#backgroundIdleMs`. The timer is unref'd: it can only fire
+	 * while something else keeps the event loop alive — typically our own
+	 * in-flight broker request, which is exactly what it exists to end.
+	 */
+	#startIdleWatchdog(): { signal: AbortSignal; idled: () => boolean; stop: () => void } {
+		const controller = new AbortController();
+		let idled = false;
+		let timer: Timer | undefined;
+		const arm = (): void => {
+			const remainingMs = this.#idleRemainingMs();
+			if (remainingMs > 0) {
+				timer = setTimeout(arm, remainingMs);
+				timer.unref?.();
+				return;
 			}
+			idled = true;
+			controller.abort(new AIError.AbortError("auth-broker background sync idle"));
+		};
+		arm();
+		return {
+			signal: AbortSignal.any([this.#backgroundAbort.signal, controller.signal]),
+			idled: () => idled,
+			stop: () => clearTimeout(timer),
+		};
+	}
+
+	/**
+	 * Backoff sleep on an unref'd timer so retry waits never pin the process;
+	 * in an otherwise-exiting process the timer simply never fires and the
+	 * suspended loop holds no handles. Wakes early on `close()`.
+	 */
+	async #backoffWait(ms: number): Promise<void> {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		const timer = setTimeout(resolve, ms);
+		timer.unref?.();
+		const onAbort = (): void => {
+			clearTimeout(timer);
+			resolve();
+		};
+		this.#backgroundAbort.signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			await promise;
+		} finally {
+			this.#backgroundAbort.signal.removeEventListener("abort", onAbort);
 		}
 	}
 
-	async #consumeSnapshotStream(): Promise<void> {
-		const iterator = this.#client.openSnapshotStream({ signal: this.#backgroundAbort.signal });
+	async #consumeSnapshotStream(signal: AbortSignal): Promise<void> {
+		const iterator = this.#client.openSnapshotStream({ signal });
 		try {
 			for await (const event of iterator) {
-				if (this.#closed || this.#backgroundAbort.signal.aborted) break;
+				if (this.#closed || signal.aborted) break;
 				this.#streamingActive = true;
 				this.#applyStreamEvent(event);
 			}
@@ -469,12 +568,14 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	/** Re-hydrate the in-memory snapshot from the broker. */
 	async refreshSnapshot(): Promise<SnapshotResponse> {
+		this.#noteActivity();
 		const result = await this.#client.fetchSnapshot();
 		if (result.status === 200) this.#applySnapshot(result.snapshot, result.generation);
 		return this.#snapshot;
 	}
 
 	listAuthCredentials(provider?: string): StoredAuthCredential[] {
+		this.#noteActivity();
 		const out: StoredAuthCredential[] = [];
 		for (const entry of this.#snapshot.credentials) {
 			if (provider !== undefined && entry.provider !== provider) continue;
@@ -490,10 +591,12 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	/** Broker-backed disabled tombstones; empty against brokers predating the endpoint. */
 	listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]> {
+		this.#noteActivity();
 		return this.#client.listDisabledCredentials(provider, signal);
 	}
 
 	getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined {
+		this.#noteActivity();
 		const nowMs = Date.now();
 		this.cleanExpiredCredentialBlocks(nowMs);
 		const entry = this.#snapshot.credentials.find(candidate => candidate.id === credentialId);
@@ -511,6 +614,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[] {
+		this.#noteActivity();
 		const nowMs = Date.now();
 		this.cleanExpiredCredentialBlocks(nowMs);
 		const ids = new Set(credentialIds);
@@ -533,6 +637,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	upsertCredentialBlock(block: StoredCredentialBlock): void {
+		this.#noteActivity();
 		this.#upsertSnapshotBlock(block);
 		this.#invalidateUsageCache();
 		this.#credentialBlockReconcileAfter.set(
@@ -562,6 +667,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	deleteCredentialBlocks(credentialId: number): void {
+		this.#noteActivity();
 		this.#deleteSnapshotBlocks(credentialId);
 		for (const key of this.#credentialBlockReconcileAfter.keys()) {
 			if (key.startsWith(`${credentialId}\0`)) this.#credentialBlockReconcileAfter.delete(key);
@@ -593,6 +699,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	 * authoritative row, so we just mirror it.
 	 */
 	updateAuthCredential(id: number, credential: AuthCredential): void {
+		this.#noteActivity();
 		for (const entry of this.#snapshot.credentials) {
 			if (entry.id !== id) continue;
 			entry.credential = credential as typeof entry.credential;
@@ -601,6 +708,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	deleteAuthCredential(id: number, disabledCause: string): void {
+		this.#noteActivity();
 		this.#removeCredentialById(id);
 		// Fire-and-forget: tell the broker to persist the disable.
 		this.#client.disableCredential(id, disabledCause).catch(error => {
@@ -609,6 +717,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	async deleteAuthCredentialRemote(id: number, disabledCause: string): Promise<boolean> {
+		this.#noteActivity();
 		const found = this.#snapshot.credentials.some(entry => entry.id === id);
 		if (!found) return false;
 		await this.#client.disableCredential(id, disabledCause);
@@ -618,6 +727,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	tryDisableAuthCredentialIfMatches(id: number, _expectedData: string, disabledCause: string): boolean {
+		this.#noteActivity();
 		const found = this.#snapshot.credentials.find(entry => entry.id === id);
 		if (!found) return false;
 		this.deleteAuthCredential(id, disabledCause);
@@ -625,6 +735,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	async waitForFreshSnapshot(maxWaitMs: number, opts: { signal?: AbortSignal } = {}): Promise<boolean> {
+		this.#noteActivity();
 		const previousGeneration = this.#generation;
 		const result = await this.#client.fetchSnapshot({
 			ifGenerationGt: this.#generation,
@@ -636,6 +747,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	async prepareForRequest(credentialId: number, opts: { signal?: AbortSignal } = {}): Promise<boolean> {
+		this.#noteActivity();
 		const entry = this.#snapshot.credentials.find(candidate => candidate.id === credentialId);
 		if (entry?.credential.type !== "oauth" || entry.rotatesInMs === null) return false;
 		const remainingMs = this.#snapshotReceivedAt + entry.rotatesInMs - Date.now();
@@ -644,6 +756,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	async markCredentialSuspect(credentialId: number, opts: { signal?: AbortSignal } = {}): Promise<void> {
+		this.#noteActivity();
 		const { entry } = await this.#client.refreshCredential(credentialId, opts.signal);
 		if (entry.credential.type !== "oauth") {
 			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
@@ -682,6 +795,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	 * any concurrent peer (refresh, generation bump) stays in sync.
 	 */
 	async upsertAuthCredentialRemote(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]> {
+		this.#noteActivity();
 		const { entries } = await this.#client.uploadCredential(provider, credential);
 		this.#applyProviderEntries(provider, entries);
 		this.#maybeRefreshSnapshot("upload");
@@ -866,6 +980,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	getCache(key: string): string | null {
+		this.#noteActivity();
 		const entry = this.#cache.get(key);
 		if (!entry) return null;
 		if (entry.expiresAtSec * 1000 <= Date.now()) {
@@ -876,6 +991,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	setCache(key: string, value: string, expiresAtSec: number): void {
+		this.#noteActivity();
 		this.#cache.set(key, { value, expiresAtSec });
 	}
 
@@ -894,6 +1010,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	async invalidateUsageCache(signal?: AbortSignal): Promise<void> {
+		this.#noteActivity();
 		this.#invalidateUsageCache();
 		await this.#client.notifyUsageStale(signal).catch(err => {
 			logger.warn("auth-broker notification of stale usage failed", { error: String(err) });
@@ -918,6 +1035,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		_credential: OAuthCredential,
 		signal?: AbortSignal,
 	): Promise<OAuthCredentials> {
+		this.#noteActivity();
 		const { entry } = await this.#client.refreshCredential(credentialId, signal);
 		if (entry.credential.type !== "oauth") {
 			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
@@ -951,6 +1069,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	 * residential laptop is, so all credentials surface every cycle.
 	 */
 	async fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null> {
+		this.#noteActivity();
 		const reports = await this.#raceWithSignal(this.#loadUsageReports(), signal);
 		if (!reports) return null;
 		return this.#filterUsageReports(this.#applyUsageOverlays(reports));
@@ -970,6 +1089,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		credential: OAuthCredential,
 		signal?: AbortSignal,
 	): Promise<UsageReport | null> {
+		this.#noteActivity();
 		const reports = await this.#raceWithSignal(this.#loadUsageReports(), signal);
 		const visibleReports = reports ? this.#filterUsageReports(reports) : null;
 		const matched = visibleReports ? matchUsageReport(visibleReports, provider, credential) : null;
@@ -1014,6 +1134,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean {
+		this.#noteActivity();
 		const key = usageOverlayKey(provider, credential);
 		if (!key) return false;
 		const activeOverlay = this.#getActiveUsageOverlay(provider, credential);
@@ -1202,6 +1323,8 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		if (this.#closed) return;
 		this.#closed = true;
 		this.#backgroundAbort.abort();
+		this.#activityWakeup?.resolve();
+		this.#activityWakeup = null;
 		if (this.#observedUsageTimer !== undefined) {
 			clearTimeout(this.#observedUsageTimer);
 			this.#observedUsageTimer = undefined;