@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/domains/quota/codex-provider.ts

@@ -0,0 +1,237 @@
+/**
+ * Quota adapter for the OpenAI Codex subscription.
+ *
+ * Codex CLI stores its own OAuth record in `auth.json`, honoring
+ * `CODEX_HOME` when set the same way the `codex` command does. This
+ * adapter reads that file and never writes it, then reads current usage
+ * from the ChatGPT backend's usage endpoint.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { formatPlan, type QuotaProvider, type UsageCredits, type UsageSnapshot, type UsageWindow } from "./types.js";
+
+export const CODEX_QUOTA_PROVIDER_ID = "codex";
+export const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+
+const DISPLAY_NAME = "Codex";
+const REQUEST_TIMEOUT_MS = 15_000;
+const WINDOW_ORDER: Record<string, number> = { session: 0, weekly: 1 };
+const WEEKLY_THRESHOLD_SECONDS = 86_400;
+
+/** The subset of Codex's stored OAuth record this adapter needs. */
+export interface CodexCredentials {
+	accessToken: string;
+	accountId: string | null;
+}
+
+export interface CodexQuotaOptions {
+	/** Override the credential file location; defaults to `$CODEX_HOME/auth.json` or `~/.codex/auth.json`. */
+	credentialsPath?: string;
+	/** Replace credential reading entirely, which is how tests supply a token. */
+	readCredentials?: () => Promise<CodexCredentials | null>;
+	fetch?: typeof globalThis.fetch;
+	timeoutMs?: number;
+	now?: () => Date;
+}
+
+/** Codex's default credential file path. */
+function defaultCodexCredentialsPath(): string {
+	const codexHome = process.env.CODEX_HOME;
+	return codexHome ? join(codexHome, "auth.json") : join(homedir(), ".codex", "auth.json");
+}
+
+/** Extract the access token and account id from a parsed credential document. */
+function parseCodexCredentials(raw: unknown): CodexCredentials | null {
+	if (!isRecord(raw)) return null;
+	const tokens = raw.tokens;
+	if (!isRecord(tokens)) return null;
+	const accessToken = tokens.access_token;
+	if (typeof accessToken !== "string" || accessToken.length === 0) return null;
+	const accountId = tokens.account_id;
+	return {
+		accessToken,
+		accountId: typeof accountId === "string" ? accountId : null,
+	};
+}
+
+async function readCredentialsFile(path: string): Promise<CodexCredentials | null> {
+	let text: string;
+	try {
+		text = await readFile(path, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		return parseCodexCredentials(JSON.parse(text));
+	} catch {
+		return null;
+	}
+}
+
+/** Build the read-only `codex` quota adapter. */
+export function createCodexQuotaProvider(options: CodexQuotaOptions = {}): QuotaProvider {
+	const credentialsPath = options.credentialsPath ?? defaultCodexCredentialsPath();
+	const readCredentials = options.readCredentials ?? (() => readCredentialsFile(credentialsPath));
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+	const now = options.now ?? (() => new Date());
+
+	const snapshot = (
+		status: UsageSnapshot["status"],
+		message: string | null,
+		extra: Partial<UsageSnapshot> = {},
+	): UsageSnapshot => ({
+		providerId: CODEX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+		status,
+		windows: [],
+		message,
+		fetchedAt: now().toISOString(),
+		...extra,
+	});
+
+	return {
+		id: CODEX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+
+		async detect(): Promise<boolean> {
+			return (await readCredentials()) !== null;
+		},
+
+		async fetch(): Promise<UsageSnapshot> {
+			const credentials = await readCredentials();
+			if (credentials === null) {
+				return snapshot("no_credentials", "No Codex credentials found");
+			}
+
+			const headers: Record<string, string> = {
+				Authorization: `Bearer ${credentials.accessToken}`,
+				"User-Agent": "codex-cli",
+			};
+			if (credentials.accountId !== null) {
+				headers["ChatGPT-Account-Id"] = credentials.accountId;
+			}
+
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			let response: Response;
+			try {
+				response = await doFetch(CODEX_USAGE_URL, {
+					method: "GET",
+					headers,
+					signal: controller.signal,
+				});
+			} catch (error) {
+				return snapshot("error", describeError(error, timeoutMs));
+			} finally {
+				clearTimeout(timer);
+			}
+
+			if (response.status === 401 || response.status === 403) {
+				await discardBody(response);
+				return snapshot("expired", "Sign in with Codex again");
+			}
+			if (response.status !== 200) {
+				await discardBody(response);
+				return snapshot("error", `HTTP ${response.status}`);
+			}
+
+			let body: unknown;
+			try {
+				body = await response.json();
+			} catch {
+				return snapshot("error", "Unexpected usage response");
+			}
+			if (!isRecord(body)) {
+				return snapshot("error", "Unexpected usage response");
+			}
+
+			const planType = typeof body.plan_type === "string" ? body.plan_type : null;
+			return snapshot("ok", null, {
+				windows: usageWindows(body.rate_limit),
+				credits: usageCredits(body.credits),
+				plan: formatPlan(planType),
+			});
+		},
+	};
+}
+
+/** Windows from the `rate_limit.primary_window` and `.secondary_window` slots. */
+function usageWindows(raw: unknown): UsageWindow[] {
+	if (!isRecord(raw)) return [];
+	const windows: UsageWindow[] = [];
+	const primary = buildWindow(raw.primary_window, "session");
+	if (primary !== null) windows.push(primary);
+	const secondary = buildWindow(raw.secondary_window, "weekly");
+	if (secondary !== null) windows.push(secondary);
+	return windows.sort((left, right) => {
+		const order = (WINDOW_ORDER[left.key] ?? 2) - (WINDOW_ORDER[right.key] ?? 2);
+		return order !== 0 ? order : left.label.localeCompare(right.label);
+	});
+}
+
+/** One `rate_limit` window slot, with the key defaulting when `limit_window_seconds` is absent. */
+function buildWindow(raw: unknown, defaultKey: "session" | "weekly"): UsageWindow | null {
+	if (!isRecord(raw)) return null;
+	const usedPct = asNumber(raw.used_percent);
+	if (usedPct === null) return null;
+	const key = windowKey(raw.limit_window_seconds, defaultKey);
+	const label = key === "weekly" ? "Weekly" : "5h";
+	const short = key === "weekly" ? "wk" : "5h";
+	return { key, label, short, usedPct, resetsAt: epochSecondsToIso(raw.reset_at) };
+}
+
+function windowKey(limitWindowSeconds: unknown, defaultKey: "session" | "weekly"): "session" | "weekly" {
+	const seconds = asNumber(limitWindowSeconds);
+	if (seconds === null) return defaultKey;
+	return seconds >= WEEKLY_THRESHOLD_SECONDS ? "weekly" : "session";
+}
+
+/** Credit balance from the `credits` block, present only for credit-billed plans. */
+function usageCredits(raw: unknown): UsageCredits | null {
+	if (!isRecord(raw)) return null;
+	if (raw.unlimited === true) return { display: "Unlimited", usedPct: null };
+	if (raw.has_credits === true && typeof raw.balance === "string" && raw.balance.length > 0) {
+		return { display: raw.balance, usedPct: null };
+	}
+	return null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | null {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const parsed = Number.parseFloat(value.trim());
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+
+/** Convert a UNIX epoch seconds value into an ISO 8601 instant. */
+function epochSecondsToIso(value: unknown): string | null {
+	const seconds = asNumber(value);
+	if (seconds === null) return null;
+	const date = new Date(seconds * 1000);
+	return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function describeError(error: unknown, timeoutMs: number): string {
+	if (error instanceof Error) {
+		return error.name === "AbortError" ? `timeout after ${timeoutMs}ms` : error.message;
+	}
+	return String(error);
+}
+
+async function discardBody(response: Response): Promise<void> {
+	try {
+		await response.body?.cancel();
+	} catch {
+		return;
+	}
+}

package/src/domains/quota/presentation.ts

@@ -0,0 +1,240 @@
+/**
+ * Pure presentation helpers for quota snapshots.
+ *
+ * These produce plain strings and severity words. No terminal, no theme,
+ * no component imports, so the interactive layer decides colour and the
+ * domain stays testable without a TTY.
+ *
+ * Two facts from live accounts shape everything here. A provider may report
+ * no session window at all (Codex reports weekly only), so no surface may
+ * assume a fixed row shape. And two credentials can sit on one account
+ * (anthropic-max and claude-code), so a combined view must fold them rather
+ * than present one budget twice.
+ */
+
+import type { UsageSnapshot, UsageWindow } from "./types.js";
+
+/** How close a window is to its limit, in the absence of a provider word. */
+export type QuotaSeverity = "normal" | "caution" | "warning" | "critical";
+
+const SEVERITY_WORDS = new Set<QuotaSeverity>(["normal", "caution", "warning", "critical"]);
+
+/**
+ * Thresholds for a window the provider did not classify.
+ *
+ * Anthropic sends its own `severity` and that is preferred; these bounds
+ * exist for Codex and Antigravity, which send none.
+ */
+export function severityForPct(usedPct: number): QuotaSeverity {
+	if (usedPct >= 95) return "critical";
+	if (usedPct >= 80) return "warning";
+	if (usedPct >= 60) return "caution";
+	return "normal";
+}
+
+/** A provider's own severity word when it sent a recognized one, else the threshold. */
+export function windowSeverity(window: UsageWindow): QuotaSeverity {
+	const reported = window.severity?.toLowerCase();
+	if (reported !== undefined && SEVERITY_WORDS.has(reported as QuotaSeverity)) {
+		return reported as QuotaSeverity;
+	}
+	return severityForPct(window.usedPct);
+}
+
+/** The snapshot's worst severity, which is what a single indicator should show. */
+export function snapshotSeverity(snapshot: UsageSnapshot): QuotaSeverity {
+	const rank: QuotaSeverity[] = ["normal", "caution", "warning", "critical"];
+	let worst: QuotaSeverity = "normal";
+	for (const window of snapshot.windows) {
+		const severity = windowSeverity(window);
+		if (rank.indexOf(severity) > rank.indexOf(worst)) worst = severity;
+	}
+	return worst;
+}
+
+/** Whole percent, so a footer never jitters on a fractional change. */
+export function formatPct(usedPct: number): string {
+	return `${Math.round(usedPct)}%`;
+}
+
+/** The window a compact indicator should show: the one closest to biting. */
+export function primaryWindow(snapshot: UsageSnapshot): UsageWindow | null {
+	let best: UsageWindow | null = null;
+	for (const window of snapshot.windows) {
+		const rank = { normal: 0, caution: 1, warning: 2, critical: 3 };
+		if (
+			best === null ||
+			rank[windowSeverity(window)] > rank[windowSeverity(best)] ||
+			(rank[windowSeverity(window)] === rank[windowSeverity(best)] && window.usedPct > best.usedPct)
+		)
+			best = window;
+	}
+	return best;
+}
+
+/** The named window when the provider reports one, for surfaces that want a fixed column. */
+export function windowByKey(snapshot: UsageSnapshot, key: string): UsageWindow | null {
+	return snapshot.windows.find((window) => window.key === key) ?? null;
+}
+
+/**
+ * Fold credentials that report the same account.
+ *
+ * anthropic-max and claude-code are separate credentials on one Anthropic
+ * subscription, so showing both doubles the apparent budget. When their
+ * windows agree, the one carrying a plan label survives.
+ */
+export function foldDuplicateAccounts(snapshots: ReadonlyArray<UsageSnapshot>): UsageSnapshot[] {
+	const kept: UsageSnapshot[] = [];
+	for (const snapshot of snapshots) {
+		const twin = kept.findIndex((existing) => sameAccount(existing, snapshot));
+		if (twin < 0) {
+			kept.push(snapshot);
+			continue;
+		}
+		const existing = kept[twin];
+		if (existing !== undefined && existing.plan == null && snapshot.plan != null) kept[twin] = snapshot;
+	}
+	return kept;
+}
+
+function sameAccount(left: UsageSnapshot, right: UsageSnapshot): boolean {
+	if (left.status !== "ok" || right.status !== "ok") return false;
+	const anthropic = new Set(["anthropic-max", "claude-code"]);
+	if (left.providerId === right.providerId || !anthropic.has(left.providerId) || !anthropic.has(right.providerId))
+		return false;
+	if (left.windows.length === 0 || left.windows.length !== right.windows.length) return false;
+	return left.windows.every((window, index) => {
+		const other = right.windows[index];
+		return (
+			other !== undefined &&
+			other.key === window.key &&
+			other.scope === window.scope &&
+			(other.resetsAt === window.resetsAt ||
+				(other.resetsAt !== null &&
+					window.resetsAt !== null &&
+					Math.abs(Date.parse(other.resetsAt) - Date.parse(window.resetsAt)) < 1000)) &&
+			Math.abs(other.usedPct - window.usedPct) < 0.5
+		);
+	});
+}
+
+/**
+ * Lines for the welcome header: one per connected subscription, naming the
+ * plan and whatever windows that provider actually reports.
+ */
+export function welcomeQuotaLines(snapshots: ReadonlyArray<UsageSnapshot>): string[] {
+	const lines: string[] = [];
+	for (const snapshot of foldDuplicateAccounts(snapshots)) {
+		if (snapshot.status === "no_credentials") continue;
+		const head = snapshot.plan ? `${snapshot.displayName} · ${snapshot.plan}` : snapshot.displayName;
+		if (snapshot.status !== "ok") {
+			lines.push(`${head} · ${snapshot.message ?? snapshot.status}`);
+			continue;
+		}
+		const parts = snapshot.windows.map((window) => `${window.label} ${formatPct(window.usedPct)} used`);
+		if (snapshot.credits) parts.push(snapshot.credits.display);
+		lines.push(parts.length > 0 ? `${head} · ${parts.join(" · ")}` : `${head} · connected`);
+	}
+	return lines;
+}
+
+/**
+ * One compact footer segment across providers.
+ *
+ * Weekly is the shared column because every provider observed so far
+ * reports one. A session window is appended only where it exists, which
+ * is what the decision log meant by 5h for Claude models.
+ */
+export function footerQuotaSegment(snapshots: ReadonlyArray<UsageSnapshot>): string | null {
+	const parts: string[] = [];
+	for (const snapshot of foldDuplicateAccounts(snapshots)) {
+		if (snapshot.status !== "ok") continue;
+		const weekly = windowByKey(snapshot, "weekly");
+		const session = windowByKey(snapshot, "session");
+		const shown: string[] = [];
+		if (session) shown.push(`5h ${formatPct(session.usedPct)} used`);
+		if (weekly) shown.push(`wk ${formatPct(weekly.usedPct)} used`);
+		const binding = primaryWindow(snapshot);
+		if (shown.length > 0 && binding?.scope && binding !== session && binding !== weekly) {
+			shown.push(
+				`${binding.scope}${binding.label === binding.scope ? "" : ` ${binding.label}`} ${formatPct(binding.usedPct)} used`,
+			);
+		}
+		if (shown.length === 0) {
+			const fallback = primaryWindow(snapshot);
+			if (fallback) shown.push(`${fallback.short ?? fallback.label} ${formatPct(fallback.usedPct)} used`);
+		}
+		if (shown.length > 0) parts.push(`${shortName(snapshot.displayName)} ${shown.join("/")}`);
+	}
+	return parts.length > 0 ? parts.join(" · ") : null;
+}
+
+function shortName(displayName: string): string {
+	const first = displayName.split(" ")[0] ?? displayName;
+	return first;
+}
+
+/**
+ * One line for the welcome banner and any other single-line surface.
+ *
+ * Paid accounts first, then the free local row, so the contrast between a
+ * consumed subscription window and free local inference is visible in one
+ * glance.
+ */
+export function quotaSummaryLine(snapshots: ReadonlyArray<UsageSnapshot>): string | null {
+	const paid = footerQuotaSegment(snapshots);
+	const local = snapshots.find((snapshot) => snapshot.providerId === "local");
+	const localPart = local?.credits ? `Local ${local.credits.display}` : null;
+	const parts = [paid, localPart].filter((part): part is string => part !== null);
+	return parts.length > 0 ? parts.join(" · ") : null;
+}
+
+/** Rows for the expanded dashboard's Status page, one provider per row. */
+export function statusPageQuotaRows(snapshots: ReadonlyArray<UsageSnapshot>): Array<{
+	label: string;
+	detail: string;
+	severity: QuotaSeverity;
+}> {
+	return foldDuplicateAccounts(snapshots).map((snapshot) => {
+		const label = snapshot.plan ? `${snapshot.displayName} (${snapshot.plan})` : snapshot.displayName;
+		if (snapshot.status !== "ok") {
+			return { label, detail: snapshot.message ?? snapshot.status, severity: "normal" as QuotaSeverity };
+		}
+		const windows = snapshot.windows.map(
+			(window) => `${window.label} ${formatPct(window.usedPct)} used${resetSuffix(window)}`,
+		);
+		if (snapshot.credits) windows.push(`credits ${snapshot.credits.display}`);
+		return {
+			label,
+			detail: windows.length > 0 ? windows.join(" · ") : "connected",
+			severity: snapshotSeverity(snapshot),
+		};
+	});
+}
+
+function resetSuffix(window: UsageWindow): string {
+	return window.resetsAt === null ? "" : ` (resets ${window.resetsAt.slice(0, 16).replace("T", " ")}Z)`;
+}
+
+/**
+ * The local-inference row.
+ *
+ * A local model consumes no subscription window and no credit, so it is
+ * reported as free rather than omitted. Showing it beside the paid rows is
+ * the point: work routed locally is work that did not spend a quota.
+ * The saved-quota figure is deliberately absent here, because proving it
+ * needs per-target token attribution this slice does not collect.
+ */
+export function localQuotaSnapshot(options: { runtimeLabel?: string; fetchedAt?: string | null } = {}): UsageSnapshot {
+	return {
+		providerId: "local",
+		displayName: options.runtimeLabel ?? "Local AI",
+		status: "ok",
+		windows: [],
+		credits: { display: "$0.00", usedPct: null },
+		plan: "Local",
+		message: "no subscription window consumed",
+		fetchedAt: options.fetchedAt ?? null,
+	};
+}

package/src/domains/quota/registry.ts

@@ -0,0 +1,23 @@
+/**
+ * Registry of quota adapters.
+ *
+ * Order is display order. Every adapter is read-only and reports a missing
+ * credential as a snapshot status, so listing one costs nothing when the
+ * operator does not use that product.
+ */
+
+import { createAnthropicMaxQuotaProvider } from "./anthropic-max-provider.js";
+import { createAntigravityQuotaProvider } from "./antigravity-provider.js";
+import { createClaudeCodeQuotaProvider } from "./claude-code-provider.js";
+import { createCodexQuotaProvider } from "./codex-provider.js";
+import type { QuotaProvider } from "./types.js";
+
+export function buildQuotaProviders(): QuotaProvider[] {
+	return [
+		createAnthropicMaxQuotaProvider(),
+		createClaudeCodeQuotaProvider(),
+		createCodexQuotaProvider(),
+		createAntigravityQuotaProvider(),
+		// The copilot adapter attaches here once its credential shape is confirmed.
+	];
+}

package/src/domains/quota/service.ts

@@ -0,0 +1,93 @@
+/**
+ * Session-facing quota reader.
+ *
+ * Refresh stays lazy, as the decision log requires: no background timer.
+ * A surface asks for snapshots, and the service either serves cached ones
+ * or spends one read per provider. Every provider is read concurrently
+ * because they are independent accounts, and a slow one must not hold up
+ * the others.
+ *
+ * Nothing here throws. A provider that fails contributes a snapshot whose
+ * status says so, which is what the surfaces render.
+ */
+
+import { createQuotaCache, DEFAULT_QUOTA_CACHE_TTL_MS, type QuotaCache } from "./cache.js";
+import { localQuotaSnapshot } from "./presentation.js";
+import { buildQuotaProviders } from "./registry.js";
+import type { QuotaProvider, UsageSnapshot } from "./types.js";
+
+export interface QuotaServiceOptions {
+	providers?: QuotaProvider[];
+	cache?: QuotaCache;
+	ttlMs?: number;
+	/** Include the free local-inference row; surfaces that list paid accounts only can opt out. */
+	includeLocal?: boolean;
+	localRuntimeLabel?: string;
+}
+
+export interface QuotaService {
+	/** Cached snapshots without spending a read, for a first paint. */
+	peek(): UsageSnapshot[];
+	/** Snapshots, refreshing any provider whose cached value has expired. */
+	read(): Promise<UsageSnapshot[]>;
+	/** Providers holding usable credentials, without spending a usage read. */
+	detected(): Promise<QuotaProvider[]>;
+}
+
+export function createQuotaService(options: QuotaServiceOptions = {}): QuotaService {
+	const providers = options.providers ?? buildQuotaProviders();
+	const cache = options.cache ?? createQuotaCache({ ttlMs: options.ttlMs ?? DEFAULT_QUOTA_CACHE_TTL_MS });
+	const includeLocal = options.includeLocal ?? true;
+
+	const withLocal = (snapshots: UsageSnapshot[]): UsageSnapshot[] => {
+		if (!includeLocal) return snapshots;
+		const local = options.localRuntimeLabel
+			? localQuotaSnapshot({ runtimeLabel: options.localRuntimeLabel })
+			: localQuotaSnapshot();
+		return [...snapshots, local];
+	};
+
+	return {
+		peek(): UsageSnapshot[] {
+			const cached: UsageSnapshot[] = [];
+			for (const provider of providers) {
+				const snapshot = cache.readLastGood(provider.id);
+				if (snapshot !== null) cached.push(snapshot);
+			}
+			return withLocal(cached);
+		},
+
+		async read(): Promise<UsageSnapshot[]> {
+			const settled = await Promise.all(
+				providers.map(async (provider) => {
+					try {
+						return await cache.resolve(provider);
+					} catch (error) {
+						return {
+							providerId: provider.id,
+							displayName: provider.displayName,
+							status: "error" as const,
+							windows: [],
+							message: error instanceof Error ? error.message : String(error),
+							fetchedAt: null,
+						};
+					}
+				}),
+			);
+			return withLocal(settled.filter((snapshot) => snapshot.status !== "no_credentials"));
+		},
+
+		async detected(): Promise<QuotaProvider[]> {
+			const flags = await Promise.all(
+				providers.map(async (provider) => {
+					try {
+						return await provider.detect();
+					} catch {
+						return false;
+					}
+				}),
+			);
+			return providers.filter((_, index) => flags[index] === true);
+		},
+	};
+}

package/src/domains/quota/summary-feed.ts

@@ -0,0 +1,86 @@
+/**
+ * A synchronous quota line for render paths, refreshed off the frame.
+ *
+ * The welcome banner and the footer are called on every frame and may not
+ * await anything or touch the network. This feed answers instantly from the
+ * last reading, and when that reading is missing or stale it starts one in
+ * the background and calls `onUpdate` when a newer line is ready, which is
+ * how a frame gets requested. That keeps the decision log's lazy refresh
+ * rule: a read happens because a surface was looked at, never on a timer.
+ */
+
+import { quotaSummaryLine } from "./presentation.js";
+import { createQuotaService, type QuotaService } from "./service.js";
+import type { UsageSnapshot } from "./types.js";
+
+export const QUOTA_SUMMARY_TTL_MS = 5 * 60_000;
+
+export interface QuotaSummaryFeedOptions {
+	service?: QuotaService;
+	/** Called after a background read changed any snapshot detail. */
+	onUpdate?: () => void;
+	ttlMs?: number;
+	now?: () => number;
+}
+
+export interface QuotaSummaryFeed {
+	/** The current line, or null until the first reading lands. Never blocks. */
+	peek(): string | null;
+	peekSnapshots(): ReadonlyArray<UsageSnapshot>;
+	/** Stop background reads from requesting frames after teardown. */
+	dispose(): void;
+}
+
+export function createQuotaSummaryFeed(options: QuotaSummaryFeedOptions = {}): QuotaSummaryFeed {
+	const service = options.service ?? createQuotaService();
+	const ttlMs = options.ttlMs ?? QUOTA_SUMMARY_TTL_MS;
+	const now = options.now ?? Date.now;
+
+	let line: string | null = null;
+	let snapshots: ReadonlyArray<UsageSnapshot> = [];
+	let readAt: number | null = null;
+	let inFlight = false;
+	let disposed = false;
+
+	const refresh = (): void => {
+		if (inFlight || disposed) return;
+		inFlight = true;
+		void Promise.resolve()
+			.then(() => (disposed ? snapshots : service.read()))
+			.then((nextSnapshots) => {
+				if (disposed) return;
+				const next = quotaSummaryLine(nextSnapshots);
+				const changed = JSON.stringify(nextSnapshots) !== JSON.stringify(snapshots);
+				snapshots = nextSnapshots;
+				readAt = now();
+				if (changed) {
+					line = next;
+					options.onUpdate?.();
+				}
+			})
+			.catch(() => {
+				// A failed read leaves the previous line standing. Provider failures
+				// already arrive as snapshot statuses, so reaching here means
+				// something outside the adapters broke, and the banner should not
+				// start flickering because of it.
+				readAt = now();
+			})
+			.finally(() => {
+				inFlight = false;
+			});
+	};
+
+	return {
+		peek(): string | null {
+			if (!disposed && (readAt === null || now() - readAt >= ttlMs)) refresh();
+			return line;
+		},
+		peekSnapshots(): ReadonlyArray<UsageSnapshot> {
+			if (!disposed && (readAt === null || now() - readAt >= ttlMs)) refresh();
+			return snapshots;
+		},
+		dispose(): void {
+			disposed = true;
+		},
+	};
+}