@hank-warren/pi-statusline 0.2.0 → 0.2.2

package/README.md

@@ -25,7 +25,9 @@ When Pi's `~/.pi/agent/auth.json` contains OAuth credentials for Anthropic (Clau
 
 Numbers are colored by remaining headroom: green above 60, yellow 41–60, orange 16–40, red at 15 and below.
 
-Usage is fetched from the providers' own usage endpoints with Pi's stored tokens — read-only; tokens are never refreshed or written. Fetches happen on session start and after each turn, throttled to once per minute, and are strictly best-effort: on any failure the last-known value is kept, and providers without credentials (or before the first successful fetch) are simply omitted, leaving the statusline exactly as before. Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); older fonts render them as replacement boxes.
+Usage is fetched from the providers' own usage endpoints with Pi's stored tokens — read-only; tokens are never refreshed or written. Fetches happen on session start and after each turn, throttled to at most once every five minutes (the Anthropic usage endpoint rate-limits aggressively), and are strictly best-effort: on any failure the last-known value is kept, and providers without credentials (or before the first successful fetch) are simply omitted, leaving the statusline exactly as before. While a provider that *does* have credentials still has no value, the throttle drops to 30 seconds — Pi only refreshes an expired OAuth access token when that provider is first used, so a session starting with a stale Anthropic token would otherwise show no Claude meter for a full interval.
+
+Polling is host-wide, not per-session. Usage percentages describe the account rather than the session, and a busy machine runs dozens of pi processes, so every process shares `~/.pi/agent/statusline-usage.json`: it holds the last good snapshot plus the time the last poll was *started*, written atomically via a temp file and rename. A session adopts the cached values on its first refresh — so the meters are populated before it has issued a single request — and only polls when that shared timestamp is older than the interval. A provider answering `429` is parked for fifteen minutes (tracked per provider, so a rate-limited Anthropic never stops codex from updating) and stops counting as pending, since retrying harder is what earns the rate limit in the first place. Each provider's cache entry is keyed to a fingerprint (a sha256 prefix, never the token itself) of the credentials that fetched it: switching accounts — or rotating a token — discards that provider's cached numbers and backoff and polls immediately, so an exhausted old account's meters never masquerade as the new account's. Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); older fonts render them as replacement boxes.
 
 ## Neon cache-wave celebration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [

package/usage.ts

@@ -1,6 +1,8 @@
-import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { pid } from "node:process";
 
 /** Remaining (not used) integer percents per provider window. */
 export interface UsageSnapshot {
@@ -10,7 +12,24 @@ export interface UsageSnapshot {
 
 const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
-const REFRESH_INTERVAL_MS = 60_000;
+/**
+ * Minimum spacing between usage polls. The Anthropic usage endpoint rate-limits
+ * (429) aggressively, so keep this well above a per-turn cadence.
+ */
+export const USAGE_REFRESH_INTERVAL_MS = 5 * 60_000;
+/**
+ * Shorter spacing used while a credentialed provider still has no value. Pi
+ * refreshes an expired OAuth token only when that provider is first used, so a
+ * session that starts with a stale token would otherwise show nothing for a
+ * full refresh interval.
+ */
+export const USAGE_RETRY_INTERVAL_MS = 30_000;
+/**
+ * How long a provider is left alone after it answers 429. Polls are host-wide
+ * (see the shared cache below), so a rate limit means the provider itself wants
+ * a break rather than that we are racing ourselves.
+ */
+export const USAGE_RATE_LIMIT_BACKOFF_MS = 15 * 60_000;
 const FETCH_TIMEOUT_MS = 10_000;
 const ONE_DAY_SECONDS = 86_400;
 
@@ -89,16 +108,110 @@ export function usageBand(remaining: number): "green" | "yellow" | "orange" | "r
 
 type FetchFn = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
 	ok: boolean;
+	status?: number;
 	json(): Promise<unknown>;
 }>;
 
 export interface UsageTrackerOptions {
 	authPath?: string;
+	cachePath?: string;
 	fetchFn?: FetchFn;
 	onChange?: () => void;
 	now?: () => number;
 }
 
+type ProviderKey = "claude" | "codex";
+
+const PROVIDER_KEYS = ["claude", "codex"] as const;
+
+/** Non-reversible per-provider credential fingerprints; never raw tokens. */
+type ProviderIdentities = Partial<Record<ProviderKey, string>>;
+
+function fingerprint(material: string): string {
+	return createHash("sha256").update(material).digest("hex").slice(0, 16);
+}
+
+/**
+ * Fingerprint the credentials each provider would be polled with. Usage
+ * percentages belong to an account, so a cached value is only trustworthy
+ * while the credentials that produced it are still the ones in auth.json —
+ * after an account switch, yesterday's "1% left" is somebody else's meter.
+ */
+function credentialIdentities(auth: AuthEntries): ProviderIdentities {
+	const identities: ProviderIdentities = {};
+	if (hasClaudeAuth(auth)) identities.claude = fingerprint(String(auth.anthropic?.access));
+	if (hasCodexAuth(auth)) {
+		const entry = auth["openai-codex"];
+		identities.codex = fingerprint(`${entry?.access as string}\n${entry?.accountId as string}`);
+	}
+	return identities;
+}
+
+/**
+ * Host-wide poll state shared by every pi process. Usage percentages are a
+ * property of the account, not of a session, so one poll per interval per host
+ * is both sufficient and necessary: a busy host runs dozens of pi processes, and
+ * per-process polling stampedes the endpoints into rate limiting everyone.
+ */
+interface UsageCache {
+	/** Last time any process started a poll; gates the shared throttle. */
+	attemptedAt: number;
+	/** Absolute times before which a rate-limited provider must not be polled. */
+	backoff: Partial<Record<ProviderKey, number>>;
+	snapshot: UsageSnapshot;
+	/** Credential fingerprints the snapshot was fetched with. */
+	identity: ProviderIdentities;
+}
+
+const EMPTY_CACHE: UsageCache = {
+	attemptedAt: Number.NEGATIVE_INFINITY,
+	backoff: {},
+	snapshot: {},
+	identity: {},
+};
+
+/**
+ * Drop cached values that were fetched with different credentials. A token
+ * rotation looks the same as an account switch here; the cost of treating it
+ * as one is a single immediate re-poll, while trusting a stale identity means
+ * showing another account's numbers as if they were current.
+ */
+function pruneCache(cache: UsageCache, identity: ProviderIdentities): UsageCache {
+	const snapshot = { ...cache.snapshot };
+	const backoff = { ...cache.backoff };
+	let changed = false;
+	for (const key of PROVIDER_KEYS) {
+		if (cache.identity[key] === identity[key]) continue;
+		if (snapshot[key] !== undefined || backoff[key] !== undefined) changed = true;
+		delete snapshot[key];
+		delete backoff[key];
+	}
+	if (!changed) return cache;
+	// The pruned values also claimed the shared throttle slot; the new account's
+	// first poll must not wait out a window started for somebody else.
+	return { attemptedAt: Number.NEGATIVE_INFINITY, backoff, snapshot, identity };
+}
+
+function parseUsageCache(json: unknown): UsageCache | undefined {
+	if (typeof json !== "object" || json === null) return undefined;
+	const body = json as { attemptedAt?: unknown; backoff?: unknown; snapshot?: unknown; identity?: unknown };
+	if (typeof body.attemptedAt !== "number" || !Number.isFinite(body.attemptedAt)) return undefined;
+	const snapshot = typeof body.snapshot === "object" && body.snapshot !== null ? (body.snapshot as UsageSnapshot) : {};
+	const backoff: UsageCache["backoff"] = {};
+	const identity: ProviderIdentities = {};
+	for (const key of PROVIDER_KEYS) {
+		if (typeof body.backoff === "object" && body.backoff !== null) {
+			const value = (body.backoff as Record<string, unknown>)[key];
+			if (typeof value === "number" && Number.isFinite(value)) backoff[key] = value;
+		}
+		if (typeof body.identity === "object" && body.identity !== null) {
+			const value = (body.identity as Record<string, unknown>)[key];
+			if (typeof value === "string") identity[key] = value;
+		}
+	}
+	return { attemptedAt: body.attemptedAt, backoff, snapshot, identity };
+}
+
 interface AuthEntries {
 	anthropic?: { access?: unknown };
 	"openai-codex"?: { access?: unknown; accountId?: unknown };
@@ -126,15 +239,20 @@ function hasCodexAuth(auth: AuthEntries): boolean {
  */
 export class UsageTracker {
 	private readonly authPath: string;
+	private readonly cachePath: string;
 	private readonly fetchFn: FetchFn;
 	private readonly onChange?: () => void;
 	private readonly now: () => number;
 	private current: UsageSnapshot = {};
+	private identities: ProviderIdentities = {};
+	private awaitingProvider = true;
+	private readonly rateLimited = new Set<ProviderKey>();
 	private lastAttempt = Number.NEGATIVE_INFINITY;
 	private inFlight: Promise<void> | undefined;
 
 	constructor(options: UsageTrackerOptions = {}) {
 		this.authPath = options.authPath ?? join(homedir(), ".pi", "agent", "auth.json");
+		this.cachePath = options.cachePath ?? join(homedir(), ".pi", "agent", "statusline-usage.json");
 		this.fetchFn = options.fetchFn ?? ((url, init) => fetch(url, init));
 		this.onChange = options.onChange;
 		this.now = options.now ?? Date.now;
@@ -144,11 +262,17 @@ export class UsageTracker {
 		return this.current;
 	}
 
+	/**
+	 * Interval until the next allowed attempt: the short retry window while a
+	 * credentialed provider is still missing a value, the full interval otherwise.
+	 */
+	private currentInterval(): number {
+		return this.awaitingProvider ? USAGE_RETRY_INTERVAL_MS : USAGE_REFRESH_INTERVAL_MS;
+	}
+
 	/** Throttled refresh; resolves when the current attempt (if any) settles. */
 	refresh(): Promise<void> {
 		if (this.inFlight) return this.inFlight;
-		if (this.now() - this.lastAttempt < REFRESH_INTERVAL_MS) return Promise.resolve();
-		this.lastAttempt = this.now();
 		const attempt = this.performRefresh()
 			.catch(() => {
 				// Usage display is best-effort and must never interrupt the agent.
@@ -160,25 +284,117 @@ export class UsageTracker {
 		return attempt;
 	}
 
+	/**
+	 * One refresh cycle: adopt whatever another process has already published,
+	 * then poll only if the shared throttle allows it.
+	 */
 	private async performRefresh(): Promise<void> {
 		const auth = (await this.readAuth()) ?? {};
-		const [claude, codex] = await Promise.all([this.fetchClaude(auth), this.fetchCodex(auth)]);
+		const identity = credentialIdentities(auth);
+		const cache = pruneCache((await this.readCache()) ?? EMPTY_CACHE, identity);
+		this.pruneCurrent(identity);
+		// Another process's values are as good as ours and cost no request, so a new
+		// session shows real numbers on its very first render.
+		this.publish(this.merge(cache.snapshot, auth), auth, cache);
+
+		const now = this.now();
+		const lastAttempt = Math.max(this.lastAttempt, cache.attemptedAt);
+		if (now - lastAttempt < this.currentInterval()) return;
+		const claudeAllowed = hasClaudeAuth(auth) && now >= (cache.backoff.claude ?? Number.NEGATIVE_INFINITY);
+		const codexAllowed = hasCodexAuth(auth) && now >= (cache.backoff.codex ?? Number.NEGATIVE_INFINITY);
+		if (!claudeAllowed && !codexAllowed) return;
+
+		this.lastAttempt = now;
+		// Claim the slot before fetching so sibling processes skip this window even
+		// if our own request is slow or fails outright. The claim carries the fresh
+		// identity so siblings do not re-prune and stampede the same window.
+		await this.writeCache({ ...cache, attemptedAt: now, identity });
+
+		const [claude, codex] = await Promise.all([
+			claudeAllowed ? this.fetchClaude(auth) : Promise.resolve(undefined),
+			codexAllowed ? this.fetchCodex(auth) : Promise.resolve(undefined),
+		]);
+		const backoff = { ...cache.backoff };
+		for (const key of ["claude", "codex"] as const) {
+			if (this.rateLimited.has(key)) backoff[key] = now + USAGE_RATE_LIMIT_BACKOFF_MS;
+			else if ((key === "claude" ? claude : codex) !== undefined) delete backoff[key];
+		}
+		this.rateLimited.clear();
+
+		const next = this.merge({ claude, codex }, auth);
+		const updated: UsageCache = { attemptedAt: now, backoff, snapshot: next, identity };
+		this.publish(next, auth, updated);
+		await this.writeCache(updated);
+	}
+
+	/**
+	 * Drop in-memory values fetched with previous credentials so merge() cannot
+	 * resurrect another account's numbers, and let the changed identity reopen
+	 * this process's own throttle gate.
+	 */
+	private pruneCurrent(identity: ProviderIdentities): void {
+		const changedKeys = PROVIDER_KEYS.filter((key) => this.identities[key] !== identity[key]);
+		this.identities = identity;
+		if (changedKeys.length === 0) return;
+		this.lastAttempt = Number.NEGATIVE_INFINITY;
+		if (!changedKeys.some((key) => this.current[key] !== undefined)) return;
+		const next = { ...this.current };
+		for (const key of changedKeys) delete next[key];
+		this.current = next;
+		// snapshot() changed even if the upcoming publish() sees no further delta.
+		this.onChange?.();
+	}
+
+	/**
+	 * Layer fresh values over the last-known ones and drop providers without
+	 * credentials: a logged-out provider must disappear immediately, while a
+	 * failed fetch keeps whatever we last saw.
+	 */
+	private merge(incoming: UsageSnapshot, auth: AuthEntries): UsageSnapshot {
 		const next: UsageSnapshot = {};
-		// A logged-out provider (missing/invalid auth entry) is dropped immediately;
-		// a fetch failure with credentials present keeps the last-known value.
 		if (hasClaudeAuth(auth)) {
-			const nextClaude = claude ?? this.current.claude;
-			if (nextClaude) next.claude = nextClaude;
+			const claude = incoming.claude ?? this.current.claude;
+			if (claude) next.claude = claude;
 		}
 		if (hasCodexAuth(auth)) {
-			const nextCodex = codex ?? this.current.codex;
-			if (nextCodex) next.codex = nextCodex;
+			const codex = incoming.codex ?? this.current.codex;
+			if (codex) next.codex = codex;
 		}
+		return next;
+	}
+
+	/** Adopt a snapshot, recompute the retry gate, and repaint only on a change. */
+	private publish(next: UsageSnapshot, auth: AuthEntries, cache: UsageCache): void {
+		const now = this.now();
+		// A provider serving 429s is not "pending": retrying it faster is exactly
+		// what got us rate limited, so it must not hold the short window open.
+		this.awaitingProvider =
+			(hasClaudeAuth(auth) && next.claude === undefined && now >= (cache.backoff.claude ?? 0)) ||
+			(hasCodexAuth(auth) && next.codex === undefined && now >= (cache.backoff.codex ?? 0));
 		if (JSON.stringify(next) === JSON.stringify(this.current)) return;
 		this.current = next;
 		this.onChange?.();
 	}
 
+	private async readCache(): Promise<UsageCache | undefined> {
+		try {
+			return parseUsageCache(JSON.parse(await readFile(this.cachePath, "utf8")));
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Atomic write; a lost race just costs one extra poll, never a corrupt file. */
+	private async writeCache(cache: UsageCache): Promise<void> {
+		const temporary = `${this.cachePath}.${pid}.tmp`;
+		try {
+			await writeFile(temporary, JSON.stringify(cache), { mode: 0o600 });
+			await rename(temporary, this.cachePath);
+		} catch {
+			// The cache is an optimisation; failing to share it must never surface.
+		}
+	}
+
 	private async readAuth(): Promise<AuthEntries | undefined> {
 		try {
 			const parsed: unknown = JSON.parse(await readFile(this.authPath, "utf8"));
@@ -189,11 +405,12 @@ export class UsageTracker {
 		}
 	}
 
-	private async fetchJson(url: string, headers: Record<string, string>): Promise<unknown> {
+	private async fetchJson(url: string, headers: Record<string, string>, provider: ProviderKey): Promise<unknown> {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
 		try {
 			const response = await this.fetchFn(url, { headers, signal: controller.signal });
+			if (response.status === 429) this.rateLimited.add(provider);
 			if (!response.ok) return undefined;
 			return await response.json();
 		} finally {
@@ -205,10 +422,14 @@ export class UsageTracker {
 		if (!hasClaudeAuth(auth)) return undefined;
 		try {
 			return parseClaudeUsage(
-				await this.fetchJson(CLAUDE_USAGE_URL, {
-					Authorization: `Bearer ${auth.anthropic?.access as string}`,
-					"anthropic-beta": "oauth-2025-04-20",
-				}),
+				await this.fetchJson(
+					CLAUDE_USAGE_URL,
+					{
+						Authorization: `Bearer ${auth.anthropic?.access as string}`,
+						"anthropic-beta": "oauth-2025-04-20",
+					},
+					"claude",
+				),
 			);
 		} catch {
 			return undefined;
@@ -222,10 +443,14 @@ export class UsageTracker {
 		const accountId = entry?.accountId as string;
 		try {
 			return parseCodexUsage(
-				await this.fetchJson(CODEX_USAGE_URL, {
-					Authorization: `Bearer ${access}`,
-					"chatgpt-account-id": accountId,
-				}),
+				await this.fetchJson(
+					CODEX_USAGE_URL,
+					{
+						Authorization: `Bearer ${access}`,
+						"chatgpt-account-id": accountId,
+					},
+					"codex",
+				),
 			);
 		} catch {
 			return undefined;