@hank-warren/pi-statusline 0.2.0 → 0.2.1

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. 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.1",
   "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,7 @@
-import { readFile } from "node:fs/promises";
+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 +11,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 +107,51 @@ 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";
+
+/**
+ * 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;
+}
+
+const EMPTY_CACHE: UsageCache = { attemptedAt: Number.NEGATIVE_INFINITY, backoff: {}, snapshot: {} };
+
+function parseUsageCache(json: unknown): UsageCache | undefined {
+	if (typeof json !== "object" || json === null) return undefined;
+	const body = json as { attemptedAt?: unknown; backoff?: unknown; snapshot?: 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"] = {};
+	if (typeof body.backoff === "object" && body.backoff !== null) {
+		for (const key of ["claude", "codex"] as const) {
+			const value = (body.backoff as Record<string, unknown>)[key];
+			if (typeof value === "number" && Number.isFinite(value)) backoff[key] = value;
+		}
+	}
+	return { attemptedAt: body.attemptedAt, backoff, snapshot };
+}
+
 interface AuthEntries {
 	anthropic?: { access?: unknown };
 	"openai-codex"?: { access?: unknown; accountId?: unknown };
@@ -126,15 +179,19 @@ 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 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 +201,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 +223,96 @@ 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 cache = (await this.readCache()) ?? EMPTY_CACHE;
+		// 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.
+		await this.writeCache({ ...cache, attemptedAt: now });
+
+		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 };
+		this.publish(next, auth, updated);
+		await this.writeCache(updated);
+	}
+
+	/**
+	 * 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 +323,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 +340,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 +361,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;