@adeildo/pi-providers 5.1.0 → 5.3.0

package/src/ui/login.ts

@@ -0,0 +1,278 @@
+// A framed screen for a provider login: what it is doing, the URL or the code to use, and the answer
+// it waits for. The provider drives it through the interaction pi would hand it.
+import { spawn } from "node:child_process";
+
+import type { AuthEvent, AuthPrompt, ProviderAuthInteraction } from "@earendil-works/pi-ai";
+import {
+	copyToClipboard,
+	type ExtensionContext,
+	type KeybindingsManager,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type Focusable,
+	hyperlink,
+	Input,
+	Key,
+	matchesKey,
+	Text,
+	type TUI,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
+
+import { frameBottom, frameInner, frameRow, frameTop } from "./frame.ts";
+
+const MAX_LOG = 5;
+
+/** Pi's own Text wraps the URL and the instructions into the rows the frame draws. */
+function wrap(text: string, width: number): string[] {
+	return new Text(text, 0, 0).render(width);
+}
+
+/** The opener pi uses, so the sign-in page opens on its own and the URL stays for the rest. */
+function openBrowser(target: string): void {
+	const opener: [string, string[]] =
+		process.platform === "darwin"
+			? ["open", [target]]
+			: process.platform === "win32"
+				? ["rundll32", ["url.dll,FileProtocolHandler", target]]
+				: ["xdg-open", [target]];
+	spawn(...opener, { stdio: "ignore", detached: true })
+		.on("error", () => {})
+		.unref();
+}
+
+export interface LoginSession {
+	interaction: ProviderAuthInteraction;
+	/** Ends the screen once the login finished one way or another. */
+	close(): void;
+}
+
+/** Opens the framed login, or undefined when this host cannot draw it. */
+export function loginScreen(
+	ctx: ExtensionContext,
+	label: string,
+	signal: AbortSignal,
+): Promise<LoginSession | undefined> {
+	if (ctx.mode !== "tui" || typeof ctx.ui.custom !== "function") return Promise.resolve(undefined);
+	return new Promise((resolve) => {
+		void ctx.ui.custom<undefined>((tui, theme, keybindings, done) => {
+			const view = new LoginView(tui, theme, label, signal, () => done(undefined), {
+				keybindings,
+			});
+			resolve({ interaction: view.interaction(), close: () => view.finish() });
+			return view;
+		});
+	});
+}
+
+interface Pending {
+	prompt: AuthPrompt;
+	resolve: (value: string) => void;
+	reject: (error: Error) => void;
+}
+
+/** What the screen does outside itself: open the sign-in page and copy the URL out. */
+export interface LoginActions {
+	keybindings?: KeybindingsManager;
+	open?: (url: string) => void;
+	copy?: (text: string) => Promise<void>;
+}
+
+export class LoginView implements Component, Focusable {
+	focused = true;
+	private readonly input = new Input();
+	private readonly log: string[] = [];
+	private link: { url: string; instructions?: string } | undefined;
+	private code: string | undefined;
+	private copyNote: string | undefined;
+	private pending: Pending | undefined;
+	private selected = 0;
+	private closed = false;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly label: string,
+		private readonly signal: AbortSignal,
+		private readonly closeView: () => void,
+		private readonly actions: LoginActions = {},
+	) {
+		this.input.onSubmit = (value) => {
+			// An empty answer would cancel the callback and fail the exchange.
+			if (value !== "") this.settle(value);
+		};
+		this.input.onEscape = () => this.cancel();
+		signal.addEventListener("abort", () => this.finish(), { once: true });
+	}
+
+	interaction(): ProviderAuthInteraction {
+		return {
+			signal: this.signal,
+			prompt: async (prompt) => await this.ask(prompt),
+			notify: (event) => this.show(event),
+		};
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		const pending = this.pending;
+		if (pending === undefined) return;
+		if (pending.prompt.type === "select") {
+			this.move(data, pending.prompt.options.length);
+			return;
+		}
+		if (this.link !== undefined && this.copyLink(data)) return;
+		this.input.handleInput(data);
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const inner = frameInner(width);
+		const rows = this.log.slice(-MAX_LOG).map((line) => this.theme.fg("muted", `· ${line}`));
+		if (this.link !== undefined) {
+			if (this.link.instructions !== undefined)
+				rows.push(...wrap(this.theme.fg("warning", this.link.instructions), inner));
+			rows.push(...wrap(this.theme.fg("accent", hyperlink(this.link.url, this.link.url)), inner));
+			rows.push(this.linkHint());
+		}
+		if (this.code !== undefined) rows.push(this.theme.bold(this.code));
+		rows.push("", ...this.promptRows(inner), "", this.hint());
+		return [
+			frameTop(this.theme, `Entrar · ${this.label}`, width),
+			...rows.map((row) => frameRow(this.theme, row, inner)),
+			frameBottom(this.theme, width),
+		];
+	}
+
+	/** Ends the screen; the login it was drawing ended one way or another. */
+	finish(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.cancel();
+		this.closeView();
+	}
+
+	private ask(prompt: AuthPrompt): Promise<string> {
+		return new Promise((resolve, reject) => {
+			this.pending = { prompt, resolve, reject };
+			this.selected = 0;
+			this.input.setValue("");
+			this.tui.requestRender();
+		});
+	}
+
+	private show(event: AuthEvent): void {
+		if (event.type === "auth_url") {
+			this.link = { url: event.url, instructions: event.instructions };
+			this.copyNote = undefined;
+			(this.actions.open ?? openBrowser)(event.url);
+		} else if (event.type === "device_code") {
+			this.code = event.userCode;
+			this.link = { url: event.verificationUri };
+			this.copyNote = undefined;
+		} else {
+			this.log.push(event.message);
+		}
+		this.tui.requestRender();
+	}
+
+	/** The copy key on a shown URL, which is what a session without a browser needs. */
+	private copyLink(data: string): boolean {
+		const link = this.link;
+		if (link === undefined) return false;
+		if (this.actions.keybindings?.matches(data, "app.message.copy") !== true) return false;
+		void (this.actions.copy ?? copyToClipboard)(link.url).then(
+			() => {
+				this.copyNote = "copied";
+				this.tui.requestRender();
+			},
+			(error: unknown) => {
+				this.copyNote = error instanceof Error ? error.message : "copy failed";
+				this.tui.requestRender();
+			},
+		);
+		return true;
+	}
+
+	private linkHint(): string {
+		const keys = this.actions.keybindings?.getKeys("app.message.copy") ?? [];
+		const copy = this.copyNote ?? (keys.length > 0 ? `${keys.join("/")} to copy` : "copy");
+		const click = process.platform === "darwin" ? "cmd+click" : "ctrl+click";
+		return this.theme.fg("dim", `${click} to open   ${copy}`);
+	}
+
+	private settle(value: string): void {
+		const pending = this.pending;
+		this.pending = undefined;
+		this.tui.requestRender();
+		pending?.resolve(value);
+	}
+
+	private cancel(): void {
+		const pending = this.pending;
+		this.pending = undefined;
+		this.tui.requestRender();
+		pending?.reject(new Error(`${this.label}: login cancelled`));
+	}
+
+	private move(data: string, count: number): void {
+		if (count === 0) return;
+		if (matchesKey(data, Key.up)) this.selected = (this.selected - 1 + count) % count;
+		else if (matchesKey(data, Key.down)) this.selected = (this.selected + 1) % count;
+		else if (matchesKey(data, Key.enter)) {
+			const pending = this.pending;
+			const option =
+				pending?.prompt.type === "select" ? pending.prompt.options[this.selected] : undefined;
+			if (option !== undefined) this.settle(option.id);
+			return;
+		} else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.cancel();
+			return;
+		}
+		this.tui.requestRender();
+	}
+
+	private promptRows(inner: number): string[] {
+		const pending = this.pending;
+		if (pending === undefined) return [this.theme.fg("dim", "waiting…")];
+		const room = Math.max(1, inner - 2);
+		const asked = this.theme.fg("text", truncateToWidth(pending.prompt.message, inner));
+		if (pending.prompt.type === "select") {
+			const options = pending.prompt.options.map((option, index) => {
+				const pointer = index === this.selected ? this.theme.fg("accent", "❯ ") : "  ";
+				const label = index === this.selected ? this.theme.bold(option.label) : option.label;
+				return `${pointer}${truncateToWidth(label, room)}`;
+			});
+			return [asked, ...options];
+		}
+
+		const value = this.input.getValue();
+		const shown =
+			pending.prompt.type === "secret" && value !== "" ? "•".repeat(value.length) : value;
+		const field =
+			shown === ""
+				? this.theme.fg("dim", truncateToWidth(pending.prompt.placeholder ?? "", room))
+				: `${shown}${this.theme.fg("accent", "▎")}`;
+		return [asked, `${this.theme.fg("accent", "❯ ")}${field}`];
+	}
+
+	private hint(): string {
+		const keys: [string, string][] =
+			this.pending?.prompt.type === "select"
+				? [
+						["↑↓", "move"],
+						["enter", "choose"],
+						["esc", "cancel"],
+					]
+				: [
+						["enter", "submit"],
+						["esc", "cancel"],
+					];
+		return keys
+			.map(([key, action]) => `${this.theme.fg("muted", key)} ${this.theme.fg("dim", action)}`)
+			.join("   ");
+	}
+}

package/src/ui/picker.ts

@@ -0,0 +1,161 @@
+// Our dialogs wear the same frame as the rest of the harness. A host that cannot draw a component,
+// like RPC, falls back to pi's own select.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+
+import { frameBottom, frameInner, frameRow, frameTop } from "./frame.ts";
+
+/** One row of a picker: a label, and a second column on the right. */
+export interface PickOption {
+	label: string;
+	description?: string;
+}
+
+const POINTER = "\u276f ";
+const MAX_VISIBLE = 10;
+const GAP = 2;
+const MIN_DESCRIPTION = 12;
+
+/** The options in our frame; undefined when the answer is cancelled. */
+export async function pick(
+	ctx: ExtensionContext,
+	title: string,
+	options: readonly (string | PickOption)[],
+	dialog: { signal?: AbortSignal } = {},
+): Promise<string | undefined> {
+	if (options.length === 0) return undefined;
+	if (ctx.mode !== "tui" || typeof ctx.ui.custom !== "function") {
+		return await ctx.ui.select(title, options.map(plainText), dialog);
+	}
+	return await ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
+		let finished = false;
+		const finish = (value: string | undefined) => {
+			if (finished) return;
+			finished = true;
+			done(value);
+		};
+		dialog.signal?.addEventListener("abort", () => finish(undefined), { once: true });
+		return new FramedSelect(tui, theme, title, options, finish);
+	});
+}
+
+/** A host that only takes lines gets the two columns on one. */
+function plainText(option: string | PickOption): string {
+	if (typeof option === "string") return option;
+	return option.description === undefined ? option.label : `${option.label}  ${option.description}`;
+}
+
+function labelOf(option: string | PickOption): string {
+	return typeof option === "string" ? option : option.label;
+}
+
+function descriptionOf(option: string | PickOption): string | undefined {
+	return typeof option === "string" ? undefined : option.description;
+}
+
+export class FramedSelect implements Component {
+	private selected = 0;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly title: string,
+		private readonly options: readonly (string | PickOption)[],
+		private readonly done: (value: string | undefined) => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.up)) this.move(-1);
+		else if (matchesKey(data, Key.down)) this.move(1);
+		else if (matchesKey(data, Key.home)) this.selected = 0;
+		else if (matchesKey(data, Key.end)) this.selected = this.options.length - 1;
+		else if (matchesKey(data, Key.enter)) this.choose();
+		else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) this.done(undefined);
+		else return;
+		this.tui.requestRender();
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const inner = frameInner(width);
+		const { start, end } = this.window();
+		const position =
+			start > 0 || end < this.options.length
+				? `${this.selected + 1}/${this.options.length}`
+				: undefined;
+		return [
+			frameTop(this.theme, this.title, width),
+			...this.options
+				.slice(start, end)
+				.map((option, index) => this.line(this.row(option, start + index, inner), inner)),
+			this.line("", inner),
+			this.line(this.hint(position), inner),
+			frameBottom(this.theme, width),
+		];
+	}
+
+	/** One line: the pointer, the label, and the description in a column shared by every row. */
+	private row(option: string | PickOption, index: number, inner: number): string {
+		const chosen = index === this.selected;
+		const pointer = chosen ? this.theme.fg("accent", POINTER) : " ".repeat(POINTER.length);
+		const room = Math.max(1, inner - POINTER.length);
+		const description = descriptionOf(option);
+		if (description === undefined) return `${pointer}${truncateToWidth(labelOf(option), room)}`;
+
+		const column = this.column(room);
+		const name = truncateToWidth(
+			chosen ? this.theme.bold(labelOf(option)) : labelOf(option),
+			column,
+		);
+		const gap = " ".repeat(Math.max(GAP, column - visibleWidth(name)));
+		const rest = truncateToWidth(description, Math.max(0, room - column - gap.length));
+		return `${pointer}${name}${gap}${rest}`;
+	}
+
+	/** Wide enough for the longest label, and never more than half of the room. */
+	private column(room: number): number {
+		const widest = Math.max(...this.options.map((option) => visibleWidth(labelOf(option))));
+		return Math.min(widest + GAP, Math.max(MIN_DESCRIPTION, Math.floor(room / 2)));
+	}
+
+	private window(): { start: number; end: number } {
+		const start = Math.max(
+			0,
+			Math.min(this.selected - Math.floor(MAX_VISIBLE / 2), this.options.length - MAX_VISIBLE),
+		);
+		return { start, end: Math.min(start + MAX_VISIBLE, this.options.length) };
+	}
+
+	private move(step: number): void {
+		const count = this.options.length;
+		this.selected = (this.selected + step + count) % count;
+	}
+
+	private choose(): void {
+		const option = this.options[this.selected];
+		if (option !== undefined) this.done(labelOf(option));
+	}
+
+	private hint(position: string | undefined): string {
+		const keys = [
+			`${this.theme.fg("muted", "↑↓")} ${this.theme.fg("dim", "move")}`,
+			`${this.theme.fg("muted", "enter")} ${this.theme.fg("dim", "select")}`,
+			`${this.theme.fg("muted", "esc")} ${this.theme.fg("dim", "cancel")}`,
+		];
+		if (position !== undefined) keys.push(this.theme.fg("dim", position));
+		return keys.join("   ");
+	}
+
+	private line(text: string, inner: number): string {
+		return frameRow(this.theme, text, inner);
+	}
+}

package/src/ui/quota.ts

@@ -0,0 +1,31 @@
+// A plan's windows as every dialog of this package draws them, in fixed columns so rows line up.
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { UsageWindow } from "../usage/types.ts";
+
+const NAME_WIDTH = 4;
+const PERCENT_WIDTH = 4;
+const RESET_WIDTH = 13;
+
+/** The color a window's usage reads in: healthy, getting full, or spent. */
+export function quotaTone(used: number): "success" | "warning" | "error" {
+	if (used >= 90) return "error";
+	if (used >= 70) return "warning";
+	return "success";
+}
+
+/** One window: `5h    62% resets in 2h `. */
+export function quotaWindow(theme: Theme, window: UsageWindow): string {
+	const percent = theme.bold(
+		theme.fg(quotaTone(window.used), `${window.used}%`.padStart(PERCENT_WIDTH)),
+	);
+	const reset = (window.resetsIn === undefined ? "" : `resets in ${window.resetsIn}`).padEnd(
+		RESET_WIDTH,
+	);
+	return `${theme.fg("muted", window.name.padEnd(NAME_WIDTH))} ${percent} ${theme.fg("muted", reset)}`;
+}
+
+/** Every window of a plan, side by side. */
+export function quotaWindows(theme: Theme, windows: readonly UsageWindow[]): string {
+	return windows.map((window) => quotaWindow(theme, window)).join("   ");
+}

package/src/usage/anthropic.ts

@@ -0,0 +1,150 @@
+// Anthropic's plan: the unified headers on every response, the usage endpoint, and the one-token call
+// for when the endpoint refuses. The endpoint is rate limited per token, so it is asked once.
+import { isObject } from "@adeildo/pi-kit";
+
+import type { AccountUsage, QuotaReader, UsageRequest, Window } from "./types.ts";
+
+const PREFIX = "anthropic-ratelimit-unified-";
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const PROBE_URL = "https://api.anthropic.com/v1/messages";
+const PROBE_MODEL = "claude-haiku-4-5";
+const OAUTH_BETA = "oauth-2025-04-20";
+const TIMEOUT_MS = 15_000;
+
+/** How to read Anthropic's plan, with the Claude Code version the caller reports. */
+export function anthropicQuota(version: () => string): QuotaReader {
+	return {
+		read: (request) => fetchUsage(request, version()),
+		probe: (request) => probeUsage(request, version()),
+		headers: fromHeaders,
+	};
+}
+
+export function fromHeaders(headers: Record<string, string>): AccountUsage | undefined {
+	const lower: Record<string, string> = {};
+	for (const [name, value] of Object.entries(headers)) lower[name.toLowerCase()] = value;
+
+	const session = headerWindow(lower, "5h");
+	const week = headerWindow(lower, "7d");
+	if (session === undefined && week === undefined) return undefined;
+	return {
+		...(session === undefined ? {} : { session }),
+		...(week === undefined ? {} : { week }),
+	};
+}
+
+export function fromEndpoint(body: unknown): AccountUsage | undefined {
+	if (!isObject(body)) return undefined;
+
+	const limits = Array.isArray(body.limits) ? body.limits.filter(isObject) : [];
+	const session = limitWindow(limits, "session") ?? bucketWindow(body.five_hour);
+	const week = limitWindow(limits, "weekly_all") ?? bucketWindow(body.seven_day);
+	if (session === undefined && week === undefined) return undefined;
+	return {
+		...(session === undefined ? {} : { session }),
+		...(week === undefined ? {} : { week }),
+	};
+}
+
+/** The endpoint's answer, or undefined when it refuses or the network fails. Never throws. */
+export async function fetchUsage(
+	request: UsageRequest,
+	version: string,
+): Promise<AccountUsage | undefined> {
+	try {
+		const response = await fetch(USAGE_URL, {
+			headers: {
+				Authorization: `Bearer ${request.token}`,
+				"anthropic-beta": OAUTH_BETA,
+				"anthropic-version": "2023-06-01",
+				Accept: "application/json",
+				// The endpoint gives the generous bucket to callers that look like Claude Code.
+				"User-Agent": `claude-cli/${version} (external, cli)`,
+			},
+			signal: usageSignal(request.signal),
+		});
+		if (!response.ok) return undefined;
+		return fromEndpoint(await response.json());
+	} catch {
+		return undefined;
+	}
+}
+
+/** The plan's windows from a one-token call, for when the endpoint refuses. Never throws. */
+export async function probeUsage(
+	request: UsageRequest,
+	version: string,
+): Promise<AccountUsage | undefined> {
+	try {
+		const response = await fetch(PROBE_URL, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${request.token}`,
+				"anthropic-beta": `claude-code-20250219,${OAUTH_BETA}`,
+				"anthropic-version": "2023-06-01",
+				"content-type": "application/json",
+				"x-app": "cli",
+				"User-Agent": `claude-cli/${version}`,
+			},
+			body: JSON.stringify({
+				model: PROBE_MODEL,
+				max_tokens: 1,
+				stream: false,
+				system: [
+					{ type: "text", text: "You are Claude Code, Anthropic's official CLI for Claude." },
+				],
+				messages: [{ role: "user", content: "ok" }],
+			}),
+			signal: usageSignal(request.signal),
+		});
+		// A rejection carries the windows too, so the status does not matter here.
+		return fromHeaders(Object.fromEntries(response.headers));
+	} catch {
+		return undefined;
+	}
+}
+
+/** The request signal, cancelled by the caller or by the timeout. */
+function usageSignal(signal: AbortSignal | undefined): AbortSignal {
+	const timeout = AbortSignal.timeout(TIMEOUT_MS);
+	return signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+}
+
+function headerWindow(headers: Record<string, string>, key: string): Window | undefined {
+	const used = numberOf(headers[`${PREFIX}${key}-utilization`]);
+	if (used === undefined) return undefined;
+	// The headers carry a fraction; a percent is what a person reads.
+	return percentWindow(used * 100, numberOf(headers[`${PREFIX}${key}-reset`]));
+}
+
+function limitWindow(limits: readonly Record<string, unknown>[], kind: string): Window | undefined {
+	const entry = limits.find((candidate) => candidate.kind === kind);
+	if (entry === undefined) return undefined;
+	return percentWindow(numberOf(entry.percent), dateOf(entry.resets_at));
+}
+
+function bucketWindow(value: unknown): Window | undefined {
+	if (!isObject(value)) return undefined;
+	return percentWindow(numberOf(value.utilization), dateOf(value.resets_at));
+}
+
+function percentWindow(used: number | undefined, resetsAt: number | undefined): Window | undefined {
+	if (used === undefined) return undefined;
+	return {
+		used: Math.round(Math.max(0, Math.min(100, used)) * 10) / 10,
+		...(resetsAt === undefined || resetsAt <= 0 ? {} : { resetsAt: Math.round(resetsAt) }),
+	};
+}
+
+function numberOf(value: unknown): number | undefined {
+	if (value === null || value === undefined) return undefined;
+	if (typeof value === "string" && value.trim() === "") return undefined;
+	const parsed = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function dateOf(value: unknown): number | undefined {
+	if (typeof value !== "string") return undefined;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? Math.round(parsed / 1000) : undefined;
+}

package/src/usage/quota.ts

@@ -0,0 +1,76 @@
+// Reads a plan once per account and keeps the answer for the process. The record the caller gives
+// decides the reader of each provider, so another provider is another entry.
+import type { AccountUsage, QuotaReader, UsageRequest } from "./types.ts";
+
+const RETRY_AFTER_FAILURE_MS = 15 * 60 * 1000;
+
+export function quotaKey(providerId: string, accountId: string): string {
+	return `${providerId}/${accountId}`;
+}
+
+export class Quota {
+	private readonly readings = new Map<string, AccountUsage>();
+	private readonly inFlight = new Map<string, Promise<AccountUsage | undefined>>();
+	private readonly failedAt = new Map<string, number>();
+
+	constructor(private readonly readers: Record<string, QuotaReader | undefined>) {}
+
+	/** Whether this provider's plan can be read at all. */
+	reads(providerId: string): boolean {
+		return this.readers[providerId] !== undefined;
+	}
+
+	read(providerId: string, accountId: string): AccountUsage | undefined {
+		return this.readings.get(quotaKey(providerId, accountId));
+	}
+
+	/** The windows a response of this provider carries, when its reader knows them. */
+	fromHeaders(providerId: string, headers: Record<string, string>): AccountUsage | undefined {
+		return this.readers[providerId]?.headers?.(headers);
+	}
+
+	async ensure(
+		providerId: string,
+		accountId: string,
+		token: string | undefined,
+	): Promise<AccountUsage | undefined> {
+		const reader = this.readers[providerId];
+		if (reader === undefined || token === undefined) return undefined;
+		const key = quotaKey(providerId, accountId);
+		const known = this.readings.get(key);
+		if (known !== undefined && !rolled(known, Date.now())) return known;
+		if (Date.now() - (this.failedAt.get(key) ?? 0) < RETRY_AFTER_FAILURE_MS) return known;
+
+		const running = this.inFlight.get(key);
+		if (running !== undefined) return await running;
+		const task = this.fill(key, reader, token);
+		this.inFlight.set(key, task);
+		try {
+			return await task;
+		} finally {
+			this.inFlight.delete(key);
+		}
+	}
+
+	/** The reader first; when it refuses, its fallback still carries the windows. */
+	private async fill(
+		key: string,
+		reader: QuotaReader,
+		token: string,
+	): Promise<AccountUsage | undefined> {
+		const request: UsageRequest = { token };
+		const usage = (await reader.read(request)) ?? (await reader.probe?.(request));
+		if (usage === undefined) this.failedAt.set(key, Date.now());
+		else this.readings.set(key, usage);
+		return usage;
+	}
+}
+
+/** A window that already rolled over makes the reading stale. */
+function rolled(usage: AccountUsage, now: number): boolean {
+	const seconds = Math.floor(now / 1000);
+	return (
+		(usage.session?.resetsAt !== undefined && usage.session.resetsAt <= seconds) ||
+		(usage.week?.resetsAt !== undefined && usage.week.resetsAt <= seconds)
+	);
+}