@aaroncarry/pi-usage 0.1.0

package/src/providers/index.ts

@@ -0,0 +1,11 @@
+import type { ProviderAdapter } from "../types.ts";
+import { anthropicAdapter } from "./anthropic.ts";
+import { codexAdapter } from "./codex.ts";
+import { deepseekAdapter } from "./deepseek.ts";
+import { githubCopilotAdapter } from "./github-copilot.ts";
+import { openrouterAdapter } from "./openrouter.ts";
+import { zaiAdapter } from "./zai.ts";
+
+export function getBuiltinAdapters(): ProviderAdapter[] {
+	return [codexAdapter, anthropicAdapter, githubCopilotAdapter, openrouterAdapter, zaiAdapter, deepseekAdapter];
+}

package/src/providers/openrouter.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenRouter adapter: prepaid credits via the public credits endpoint. Works
+ * with both API keys and OAuth access tokens (plain Bearer either way).
+ */
+
+import { toNumber } from "../parse.ts";
+import type { AccountBalance, ProviderAdapter, ProviderFetchArgs } from "../types.ts";
+
+const ENDPOINT = "https://openrouter.ai/api/v1/credits";
+
+interface OpenrouterCreditsResponse {
+	data?: {
+		total_credits?: unknown;
+		total_usage?: unknown;
+	} | null;
+}
+
+export const openrouterAdapter: ProviderAdapter = {
+	id: "openrouter",
+	label: "OpenRouter",
+	async fetch({ token, signal, fetchImpl }: ProviderFetchArgs): Promise<AccountBalance> {
+		const response = await fetchImpl(ENDPOINT, {
+			headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+			signal,
+		});
+		if (!response.ok) {
+			throw new Error(`OpenRouter credits API returned HTTP ${response.status}`);
+		}
+		const body: unknown = await response.json();
+		if (typeof body !== "object" || body === null) {
+			throw new Error("OpenRouter credits API returned an unexpected response");
+		}
+		const parsed = body as OpenrouterCreditsResponse;
+		const totalCredits = toNumber(parsed.data?.total_credits);
+		const totalUsage = toNumber(parsed.data?.total_usage);
+		if (totalCredits === undefined || totalUsage === undefined) {
+			throw new Error("OpenRouter credits API returned no credit totals");
+		}
+		return {
+			providerId: "openrouter",
+			label: "OpenRouter",
+			balance: {
+				amount: totalCredits - totalUsage,
+				currency: "USD",
+				note: `used $${totalUsage.toFixed(2)} of $${totalCredits.toFixed(2)}`,
+			},
+			windows: [],
+			notes: [],
+			fetchedAt: Date.now(),
+		};
+	},
+};

package/src/providers/zai.ts

@@ -0,0 +1,200 @@
+/**
+ * z.ai / GLM adapter.
+ *
+ * Two disjoint surfaces, both borrowed from CodexBar's zai.js plugin:
+ * 1. Coding plan quota windows (`/api/monitor/usage/quota/limit`), available
+ *    only to coding-plan keys.
+ * 2. BigModel CN pay-as-you-go balance (console endpoint). Empirically this
+ *    also accepts z.ai global keys, so it is attempted as a best-effort
+ *    fallback regardless of region; a failure never breaks quota display.
+ */
+
+import type { AccountBalance, MoneyBalance, ProviderAdapter, ProviderFetchArgs, UsageWindow } from "../types.ts";
+
+const QUOTA_PATH = "/api/monitor/usage/quota/limit";
+const CN_BALANCE_URL = "https://www.bigmodel.cn/api/biz/account/query-customer-account-report";
+const BASES = { global: "https://api.z.ai", cn: "https://open.bigmodel.cn" } as const;
+
+/** unit → minutes multiplier (1=day, 3=hour, 5=minute, 6=week). */
+const UNIT_MINUTES: Record<number, number> = { 1: 1_440, 3: 60, 5: 1, 6: 10_080 };
+
+interface ZaiLimit {
+	type?: unknown;
+	unit?: unknown;
+	number?: unknown;
+	percentage?: unknown;
+	usage?: unknown;
+	remaining?: unknown;
+	nextResetTime?: unknown;
+}
+
+interface ZaiQuotaResponse {
+	success?: unknown;
+	msg?: unknown;
+	data?: { planName?: unknown; plan?: unknown; limits?: unknown } | null;
+}
+
+interface BigmodelBalanceResponse {
+	success?: unknown;
+	data?: {
+		availableBalance?: unknown;
+		balance?: unknown;
+		rechargeAmount?: unknown;
+		giveAmount?: unknown;
+		totalSpendAmount?: unknown;
+	} | null;
+}
+
+interface ParsedLimit {
+	type: "TIME_LIMIT" | "TOKENS_LIMIT" | "CREDIT_LIMIT";
+	percent: number;
+	windowMinutes?: number;
+	resetsAt?: number;
+	detail?: string;
+}
+
+function optionalInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) ? value : undefined;
+}
+
+/** z.ai mixes seconds and milliseconds epochs; disambiguate by magnitude. */
+function normalizeEpoch(value: number): number {
+	return value < 1e12 ? value * 1000 : value;
+}
+
+function parseLimit(raw: unknown): ParsedLimit | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const limit = raw as ZaiLimit;
+	if (typeof limit.percentage !== "number") return undefined;
+	if (limit.type !== "TIME_LIMIT" && limit.type !== "TOKENS_LIMIT" && limit.type !== "CREDIT_LIMIT") return undefined;
+	const unit = optionalInt(limit.unit);
+	const number = optionalInt(limit.number);
+	const multiplier = unit !== undefined ? UNIT_MINUTES[unit] : undefined;
+	const windowMinutes =
+		multiplier !== undefined && number !== undefined && number > 0 ? number * multiplier : undefined;
+	const reset = optionalInt(limit.nextResetTime);
+	const usage = optionalInt(limit.usage);
+	const remaining = optionalInt(limit.remaining);
+	const detail = usage !== undefined && remaining !== undefined ? `${remaining} of ${usage} left` : undefined;
+	return {
+		type: limit.type,
+		percent: limit.percentage,
+		windowMinutes,
+		resetsAt: reset !== undefined ? normalizeEpoch(reset) : undefined,
+		detail,
+	};
+}
+
+function windowTitle(windowMinutes: number | undefined): string {
+	if (windowMinutes === 300) return "5h";
+	if (windowMinutes === 10_080) return "weekly";
+	if (windowMinutes === 43_200) return "monthly";
+	if (windowMinutes !== undefined && windowMinutes % 60 === 0) return `${windowMinutes / 60}h`;
+	if (windowMinutes !== undefined) return `${windowMinutes}m`;
+	return "window";
+}
+
+function windowsFromLimits(limits: ParsedLimit[]): UsageWindow[] {
+	const windows: UsageWindow[] = [];
+	const creditLimits = limits
+		.filter((limit) => limit.type !== "TIME_LIMIT")
+		.sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER));
+	const timeLimit = limits.filter((limit) => limit.type === "TIME_LIMIT").at(-1);
+	const sessionLimit = creditLimits.length >= 2 ? creditLimits[0] : undefined;
+	const tokenLimit = creditLimits.at(-1);
+	for (const entry of [sessionLimit, tokenLimit, timeLimit]) {
+		if (!entry) continue;
+		windows.push({
+			label: entry.type === "TIME_LIMIT" ? "MCP" : windowTitle(entry.windowMinutes),
+			usedPercent: entry.percent,
+			resetsAt: entry.resetsAt,
+			detail: entry.detail,
+		});
+	}
+	return windows;
+}
+
+/** Server messages arrive in Chinese; map the known one to English. */
+const QUOTA_FAILURE_TRANSLATIONS: Record<string, string> = {
+	"当前用户不存在coding plan": "no coding plan on this account",
+};
+
+async function fetchQuota(
+	url: string,
+	token: string,
+	fetchImpl: ProviderFetchArgs["fetchImpl"],
+	signal: AbortSignal | undefined,
+): Promise<{ windows: UsageWindow[]; plan?: string; failure?: string }> {
+	const response = await fetchImpl(url, {
+		headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+		signal,
+	});
+	if (!response.ok) return { windows: [], failure: `HTTP ${response.status}` };
+	const body: unknown = await response.json();
+	if (typeof body !== "object" || body === null) return { windows: [], failure: "invalid response" };
+	const quota = body as ZaiQuotaResponse;
+	if (quota.success !== true) {
+		const message = typeof quota.msg === "string" ? quota.msg : "invalid response";
+		return { windows: [], failure: QUOTA_FAILURE_TRANSLATIONS[message] ?? message };
+	}
+	if (!Array.isArray(quota.data?.limits)) return { windows: [], failure: "no limits in response" };
+	const limits = quota.data.limits.map(parseLimit).filter((limit): limit is ParsedLimit => limit !== undefined);
+	const windows = windowsFromLimits(limits);
+	const planCandidate = [quota.data?.planName, quota.data?.plan].find((value) => typeof value === "string" && value.trim() !== "");
+	const plan = typeof planCandidate === "string" ? planCandidate.trim() : undefined;
+	return { windows, plan };
+}
+
+async function fetchCnBalance(
+	token: string,
+	fetchImpl: ProviderFetchArgs["fetchImpl"],
+	signal: AbortSignal | undefined,
+): Promise<MoneyBalance | undefined> {
+	const response = await fetchImpl(CN_BALANCE_URL, {
+		headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+		signal,
+	});
+	if (!response.ok) return undefined;
+	const body: unknown = await response.json();
+	if (typeof body !== "object" || body === null) return undefined;
+	const parsed = body as BigmodelBalanceResponse;
+	if (parsed.success !== true) return undefined;
+	const data = parsed.data ?? {};
+	const available = typeof data.availableBalance === "number" ? data.availableBalance : typeof data.balance === "number" ? data.balance : undefined;
+	if (available === undefined || !Number.isFinite(available)) return undefined;
+	const notes: string[] = [];
+	if (typeof data.rechargeAmount === "number") notes.push(`recharged ¥${data.rechargeAmount.toFixed(2)}`);
+	if (typeof data.totalSpendAmount === "number") notes.push(`spent ¥${data.totalSpendAmount.toFixed(2)}`);
+	return { amount: available, currency: "CNY", note: notes.join(" · ") || undefined };
+}
+
+export const zaiAdapter: ProviderAdapter = {
+	id: "zai",
+	label: "GLM",
+	async fetch({ token, signal, fetchImpl, options }: ProviderFetchArgs): Promise<AccountBalance> {
+		const region = options.region === "global" ? "global" : options.region === "cn" ? "cn" : "auto";
+		const bases = region === "auto" ? [BASES.global, BASES.cn] : [BASES[region]];
+		let quotaFailure: string | undefined;
+		let windows: UsageWindow[] = [];
+		let plan: string | undefined;
+		for (const base of bases) {
+			try {
+				const result = await fetchQuota(`${base}${QUOTA_PATH}`, token, fetchImpl, signal);
+				if (result.windows.length > 0) {
+					windows = result.windows;
+					plan = result.plan;
+					break;
+				}
+				quotaFailure ??= result.failure;
+			} catch (error) {
+				quotaFailure ??= error instanceof Error ? error.message : String(error);
+			}
+		}
+		// Best-effort CN balance; a failure here must never break quota display.
+		const balance = await fetchCnBalance(token, fetchImpl, signal).catch(() => undefined);
+		if (windows.length === 0 && !balance) {
+			throw new Error(quotaFailure ? `z.ai: ${quotaFailure}` : "z.ai returned no usage data");
+		}
+		return { providerId: "zai", label: "GLM", plan, windows, balance, notes: [], fetchedAt: Date.now() };
+	},
+};

package/src/service.ts

@@ -0,0 +1,275 @@
+/**
+ * BalanceService: resolves credentials, runs provider adapters, caches
+ * snapshots with a TTL, dedupes concurrent fetches, and runs the background
+ * refresh timer for one session.
+ */
+
+import { intervalMs, type BalanceConfig, type ProviderConfig, loadBalanceConfig } from "./config.ts";
+import {
+	readStoredCredential,
+	readStoredCredentialIds,
+	resolveProviderToken,
+} from "./credentials.ts";
+import { getBuiltinAdapters } from "./providers/index.ts";
+import { createAutoDetectAdapter } from "./providers/auto-detect.ts";
+import { createCustomAdapter } from "./providers/custom.ts";
+import type { AccountBalance, CredentialResolver, FetchLike, ProviderAdapter, ResolvedCredential } from "./types.ts";
+
+export interface BalanceServiceOptions {
+	agentDir: string;
+	config?: BalanceConfig;
+	fetchImpl?: FetchLike;
+	/** Extra/override adapters, mainly for tests. */
+	adapters?: ProviderAdapter[];
+}
+
+function toErrorMessage(error: unknown): string {
+	if (!(error instanceof Error)) return String(error);
+	let message = error.message || error.name;
+	let cause: unknown = error.cause;
+	for (let depth = 0; depth < 3 && cause !== undefined && cause !== null; depth++) {
+		const causeText = describeCause(cause);
+		if (!causeText || message.includes(causeText)) break;
+		message = `${message} (${causeText})`;
+		cause = cause instanceof Error ? cause.cause : undefined;
+	}
+	return message;
+}
+
+function describeCause(cause: unknown): string {
+	if (cause instanceof Error) {
+		if (cause.message) return cause.message;
+		const code = (cause as Error & { code?: unknown }).code;
+		if (typeof code === "string") return code;
+		const errors = (cause as Error & { errors?: unknown }).errors;
+		if (Array.isArray(errors)) {
+			const nested = errors.map(describeCause).filter(Boolean).join(", ");
+			if (nested) return nested;
+		}
+		return cause.name;
+	}
+	return typeof cause === "string" ? cause : "";
+}
+
+export class BalanceService {
+	readonly config: BalanceConfig;
+	private readonly agentDir: string;
+	private readonly fetchImpl: FetchLike;
+	private readonly adapters: Map<string, ProviderAdapter>;
+	private readonly autoAdapters = new Map<string, ProviderAdapter>();
+	private credentialResolver: CredentialResolver | undefined;
+	private readonly balances = new Map<string, AccountBalance>();
+	private readonly lastFetched = new Map<string, number>();
+	private readonly inflight = new Map<string, Promise<AccountBalance>>();
+	private readonly listeners = new Set<() => void>();
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(options: BalanceServiceOptions) {
+		this.agentDir = options.agentDir;
+		this.config = options.config ?? loadBalanceConfig(options.agentDir);
+		this.fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
+		this.adapters = new Map(getBuiltinAdapters().map((adapter) => [adapter.id, adapter]));
+		for (const adapter of options.adapters ?? []) {
+			this.adapters.set(adapter.id, adapter);
+		}
+	}
+
+	/** Wire the live credential resolver (pi's modelRegistry-backed lookup). */
+	setCredentialResolver(resolver: CredentialResolver | undefined): void {
+		this.credentialResolver = resolver;
+	}
+
+	/** Subscribe to cache changes (any fetch finishing). Returns unsubscribe. */
+	onChange(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	/**
+	 * Provider ids that should be displayed: built-in adapters with a stored
+	 * credential, every remaining auth.json credential when auto-detection is
+	 * on, and explicitly configured custom adapters.
+	 */
+	listConfiguredProviderIds(): string[] {
+		const ids: string[] = [];
+		const configured = this.config.providers ?? {};
+		const autoDetect = this.config.autoDetect !== false;
+		for (const id of this.adapters.keys()) {
+			if (configured[id]?.enabled === false) continue;
+			if (readStoredCredential(this.agentDir, id)) ids.push(id);
+		}
+		if (autoDetect) {
+			for (const id of readStoredCredentialIds(this.agentDir)) {
+				if (this.adapters.has(id) || ids.includes(id)) continue;
+				if (configured[id]?.enabled === false) continue;
+				ids.push(id);
+			}
+		}
+		for (const [id, entry] of Object.entries(configured)) {
+			if (entry.enabled === false) continue;
+			if (this.adapters.has(id) || ids.includes(id) || !entry.custom?.url) continue;
+			ids.push(id);
+		}
+		return ids;
+	}
+
+	get(providerId: string): AccountBalance | undefined {
+		return this.balances.get(providerId);
+	}
+
+	/** Best display name before the first fetch lands: config label → adapter label → id. */
+	labelFor(providerId: string): string {
+		return this.config.providers?.[providerId]?.label ?? this.adapterFor(providerId)?.label ?? providerId;
+	}
+
+	/** Cached snapshots for all configured providers (missing ones omitted). */
+	getAll(): AccountBalance[] {
+		return this.listConfiguredProviderIds()
+			.map((id) => this.balances.get(id))
+			.filter((balance): balance is AccountBalance => balance !== undefined);
+	}
+
+	/** Fetch (or return cached) balance for one provider. Never rejects. */
+	async refresh(providerId: string, options?: { force?: boolean; signal?: AbortSignal }): Promise<AccountBalance> {
+		const cached = this.balances.get(providerId);
+		const last = this.lastFetched.get(providerId);
+		// Failed snapshots never satisfy the TTL: transient network errors must
+		// be retried on the next refresh instead of being served for 5 minutes.
+		if (!options?.force && cached && !cached.error && last !== undefined && Date.now() - last < intervalMs(this.config)) {
+			return cached;
+		}
+		const pending = this.inflight.get(providerId);
+		if (pending) return pending;
+		const task = this.fetchBalance(providerId, options?.signal).finally(() => {
+			this.inflight.delete(providerId);
+		});
+		this.inflight.set(providerId, task);
+		return task;
+	}
+
+	/** Refresh every configured provider in parallel. Never rejects. */
+	async refreshAll(options?: { force?: boolean; signal?: AbortSignal }): Promise<AccountBalance[]> {
+		return Promise.all(this.listConfiguredProviderIds().map((id) => this.refresh(id, options)));
+	}
+
+	/** Start the background refresh timer and kick off an initial fetch. */
+	start(): void {
+		if (this.timer) return;
+		void this.refreshAll();
+		this.timer = setInterval(() => {
+			void this.refreshAll();
+		}, intervalMs(this.config));
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+
+	private adapterFor(providerId: string): ProviderAdapter | undefined {
+		const known = this.adapters.get(providerId);
+		if (known) return known;
+		const entry = this.config.providers?.[providerId];
+		if (entry?.custom?.url) {
+			return createCustomAdapter(providerId, entry.custom, entry.label ?? providerId);
+		}
+		if (this.config.autoDetect !== false) {
+			let adapter = this.autoAdapters.get(providerId);
+			if (!adapter) {
+				adapter = createAutoDetectAdapter(providerId);
+				this.autoAdapters.set(providerId, adapter);
+			}
+			return adapter;
+		}
+		return undefined;
+	}
+
+	private async fetchBalance(providerId: string, signal?: AbortSignal): Promise<AccountBalance> {
+		const adapter = this.adapterFor(providerId);
+		let balance: AccountBalance;
+		if (!adapter) {
+			balance = {
+				providerId,
+				label: providerId,
+				windows: [],
+				notes: [],
+				error: `Unknown provider "${providerId}"`,
+				fetchedAt: Date.now(),
+			};
+		} else {
+			balance = await this.runAdapter(providerId, adapter, signal);
+		}
+		const labelOverride = this.config.providers?.[providerId]?.label;
+		if (labelOverride) balance = { ...balance, label: labelOverride };
+		this.balances.set(providerId, balance);
+		this.lastFetched.set(providerId, Date.now());
+		this.notifyListeners();
+		return balance;
+	}
+
+	private async runAdapter(
+		providerId: string,
+		adapter: ProviderAdapter,
+		signal?: AbortSignal,
+	): Promise<AccountBalance> {
+		try {
+			const resolved = await this.resolveRunCredential(providerId);
+			const options: ProviderConfig = this.config.providers?.[providerId] ?? {};
+			return await adapter.fetch({
+				token: resolved.token,
+				baseUrl: resolved.baseUrl,
+				signal,
+				fetchImpl: this.fetchImpl,
+				options,
+			});
+		} catch (error) {
+			return {
+				providerId,
+				label: adapter.label,
+				windows: [],
+				notes: [],
+				error: toErrorMessage(error),
+				fetchedAt: Date.now(),
+			};
+		}
+	}
+
+	/**
+	 * Token plus base URL for one fetch. Registry-backed resolution runs first
+	 * (it refreshes OAuth tokens); auth.json is the fallback. Custom providers
+	 * without a stored credential get an empty token — they authenticate via
+	 * their own configured headers.
+	 */
+	private async resolveRunCredential(providerId: string): Promise<ResolvedCredential> {
+		const stored = readStoredCredential(this.agentDir, providerId);
+		if (!stored) {
+			if (this.credentialResolver) {
+				return this.credentialResolver(providerId).catch(() => ({ token: "" }));
+			}
+			return { token: "" };
+		}
+		if (this.credentialResolver) {
+			try {
+				const resolved = await this.credentialResolver(providerId);
+				if (resolved.token) return resolved;
+			} catch {
+				// Registry lookup failed (unknown provider, refresh error); fall back.
+			}
+		}
+		const token = await resolveProviderToken(providerId, undefined, this.agentDir);
+		return { token };
+	}
+
+	private notifyListeners(): void {
+		for (const listener of this.listeners) {
+			try {
+				listener();
+			} catch {
+				// Listener errors must not break refresh bookkeeping.
+			}
+		}
+	}
+}

package/src/session-usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Session consumption aggregation, mirroring pi's footer accounting: sum of
+ * usage across assistant messages, tool results, branch summaries, and
+ * compaction entries of the current session.
+ */
+
+export interface UsageLike {
+	totalTokens?: number;
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: { total?: number };
+}
+
+export interface SessionEntryLike {
+	type: string;
+	message?: { role?: string; usage?: UsageLike };
+	usage?: UsageLike;
+}
+
+export interface SessionUsageTotals {
+	tokens: number;
+	cost: number;
+}
+
+export function sumSessionUsage(entries: readonly SessionEntryLike[]): SessionUsageTotals {
+	const totals: SessionUsageTotals = { tokens: 0, cost: 0 };
+	for (const entry of entries) {
+		let usage: UsageLike | undefined;
+		if (entry.type === "message" && entry.message?.role === "assistant") {
+			usage = entry.message.usage;
+		} else if (entry.type === "message" && entry.message?.role === "toolResult") {
+			usage = entry.message.usage;
+		} else if (entry.type === "branch_summary" || entry.type === "compaction") {
+			usage = entry.usage;
+		}
+		if (!usage) continue;
+		totals.tokens += usageTotalTokens(usage);
+		totals.cost += usage.cost?.total ?? 0;
+	}
+	return totals;
+}
+
+function usageTotalTokens(usage: UsageLike): number {
+	if (typeof usage.totalTokens === "number") return usage.totalTokens;
+	return (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+}
+
+/** Same tiers as pi's footer formatTokens, so numbers match across rows. */
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(count / 1_000_000)}M`;
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared data model for pi-usage.
+ *
+ * Every provider adapter normalizes its API responses into `AccountBalance`;
+ * the panel and status line render that shape without provider-specific logic.
+ */
+
+import type { ProviderConfig } from "./config.ts";
+
+/** One usage window, e.g. a 5-hour or weekly subscription quota window. */
+export interface UsageWindow {
+	/** Short window label, e.g. "5h", "weekly", "MCP". */
+	label: string;
+	/** Used fraction in percent (0-100+, values above 100 are clamped when drawn). */
+	usedPercent: number;
+	/** Epoch milliseconds when the window resets, if the API reports one. */
+	resetsAt?: number;
+	/** Optional detail such as "880 of 1000 left". */
+	detail?: string;
+}
+
+/** Monetary balance (prepaid credits, account balance). */
+export interface MoneyBalance {
+	amount: number;
+	/** ISO currency code, e.g. "CNY", "USD". */
+	currency: string;
+	/** Optional breakdown text, e.g. "recharged ¥118.00 · spent ¥96.54". */
+	note?: string;
+}
+
+/** Normalized snapshot for one account. */
+export interface AccountBalance {
+	/** pi provider id, matching the key in auth.json. */
+	providerId: string;
+	/** Display name, e.g. "Codex". */
+	label: string;
+	/** Plan name if the API reports one, e.g. "Plus". */
+	plan?: string;
+	windows: UsageWindow[];
+	balance?: MoneyBalance;
+	/** Extra single-line facts rendered in the panel. */
+	notes: string[];
+	/** Fetch/parse failure; when set, windows /usage may be empty. */
+	error?: string;
+	/** Epoch milliseconds of the fetch attempt. */
+	fetchedAt: number;
+}
+
+/** Minimal HTTP client interface so adapters can be tested without network. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** Arguments handed to a provider adapter on each fetch. */
+export interface ProviderFetchArgs {
+	/**
+	 * Resolved bearer token or API key for the provider. Empty for custom
+	 * providers without a stored credential; those authenticate via their own
+	 * configured headers.
+	 */
+	token: string;
+	/** Provider base URL from pi's model registry, when known. */
+	baseUrl?: string;
+	signal?: AbortSignal;
+	fetchImpl: FetchLike;
+	/** Per-provider options from usage.json (`providers` section). */
+	options: ProviderConfig;
+}
+
+/** Normalizes one provider's usage /usage API into an AccountBalance. */
+export interface ProviderAdapter {
+	/** pi provider id, matching auth.json key / model registry provider id. */
+	id: string;
+	label: string;
+	fetch(args: ProviderFetchArgs): Promise<AccountBalance>;
+}
+
+/** Live credential plus the provider base URL (for auto-detection). */
+export interface ResolvedCredential {
+	token: string;
+	baseUrl?: string;
+}
+
+/** Resolves the live bearer token/API key (and base URL) for a provider id. */
+export type CredentialResolver = (providerId: string) => Promise<ResolvedCredential>;