@narumitw/pi-usage 0.24.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# 📊 pi-usage — Provider Usage for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-usage)](https://www.npmjs.com/package/@narumitw/pi-usage) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-usage` is a native [Pi coding agent](https://pi.dev) extension that adds one interactive `/usage` command for reading usage from the account Pi is actually using. It supports OpenAI Codex ChatGPT subscription windows and OpenRouter API-key spend limits without pretending those limits have the same semantics.
+
+## ✨ Features
+
+- Opens one interactive `/usage` menu with current state and next actions.
+- Automatically queries the selected model provider and active runtime account.
+- Supports OpenAI Codex subscription windows, resets, credits, and model-specific buckets.
+- Supports OpenRouter per-key credit limits plus daily, weekly, monthly, and all-time spend.
+- Provides explicit refresh, another-provider, and all-configured-provider actions.
+- Runs manually requested all-provider queries with concurrency limited to two and preserves partial results.
+- Labels only the selected model provider as `Current`; other results are `Configured`.
+- Keeps the compact statusline scoped to the current provider and runtime account.
+- Isolates its five-minute in-memory cache by provider and a process-salted credential fingerprint.
+- Resolves credentials through Pi and never reads Pi, account-extension, Codex CLI, or provider auth files.
+- Retains `/codex-status` as a temporary argument-free compatibility alias.
+
+## 📦 Install
+
+Requires Pi 0.81.0 or newer so the extension can validate the effective base URL attached to resolved provider auth before sending credentials to an official usage endpoint.
+
+```bash
+pi install npm:@narumitw/pi-usage
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-usage
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-usage
+```
+
+## 🚀 Usage
+
+Run:
+
+```text
+/usage
+```
+
+The menu first queries the current model provider and presents its state with these actions:
+
+```text
+Refresh current usage
+View another configured provider…
+View all configured providers…
+Close
+```
+
+There are intentionally no `/usage --refresh`, `/usage <provider>`, or `/usage --all` argument paths. Cross-provider traffic requires an explicit interactive choice.
+
+`/codex-status` opens the same menu during the migration period. Its former flags are not supported by `pi-usage`.
+
+## 📋 Provider semantics
+
+### OpenAI Codex
+
+- Provider ID: `openai-codex`
+- Semantics: ChatGPT consumer subscription limits
+- Source: the Codex usage endpoint using Pi's resolved runtime authorization
+- Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets
+- Statusline examples: `codex 59% 5h 61% wk` or `codex spark 100% 5h`
+
+The statusline selects a returned bucket that matches the current Codex model when one is available. Unlike `pi-codex-usage`, this successor intentionally has no Codex CLI fallback because the CLI may be logged into a different account than Pi's active runtime account.
+
+### OpenRouter
+
+- Provider ID: `openrouter`
+- Semantics: API-key spend and per-key credit limits—not consumer subscription quota
+- Source: OpenRouter's documented [`GET /api/v1/key`](https://openrouter.ai/docs/api/api-reference/api-keys/get-current-api-key) endpoint using Pi's resolved inference API key
+- Displayed data: key label when safely returned, optional per-key limit and remaining amount, reset period, and daily/weekly/monthly/all-time spend
+- Statusline examples: `openrouter $74.50 left` or `openrouter $25.50 used`
+
+The extension does not call OpenRouter's account-level `/credits` endpoint because that operation requires a separate management key. OpenRouter documents the distinction between credit and rate limits in its [API limits guide](https://openrouter.ai/docs/api_reference/limits).
+
+## 🧭 Current and configured accounts
+
+`Current` means the provider and credential used by Pi's selected model. `Configured` means Pi reports runtime auth for another supported provider; it does not mean that provider is active.
+
+The extension does not enumerate multiple accounts inside one provider and does not switch accounts. Account selection remains owned by Pi or an account-management extension. After the active runtime credential changes, the next command, turn, or scheduled refresh resolves auth again and cannot reuse another account's cached report.
+
+## 📊 Statusline behavior
+
+The `usage` status item is active only for the selected model provider. It refreshes every five minutes while the session remains on a supported provider and is cleared when the model changes to an unsupported provider.
+
+Manual another-provider and all-provider queries never publish to the statusline. `@narumitw/pi-statusline` supplies the default `📊` icon; `pi-usage` publishes text-only values.
+
+## 🔄 Migrating from pi-codex-usage
+
+`pi-codex-usage` remains available while this successor soaks. To migrate one installation:
+
+```bash
+pi remove npm:@narumitw/pi-codex-usage
+pi install npm:@narumitw/pi-usage
+```
+
+Do not load both packages together: both register `/codex-status`, so Pi must suffix duplicate commands and the two packages can publish overlapping usage status.
+
+Behavior changes:
+
+- Use `/usage` as the primary entry point.
+- `/codex-status` is an argument-free compatibility alias.
+- Refresh and cross-provider operations are menu actions rather than flags.
+- Codex CLI fallback is removed to preserve active-runtime-account correctness.
+- The status key changes from `codex-usage` to `usage`.
+
+## 🚧 Limitations
+
+- Only providers with a stable, meaningful usage source and Pi-resolvable runtime auth are supported.
+- Credentials resolved for custom provider base URLs are never forwarded to the providers' official usage endpoints; effective auth origin validation requires Pi 0.81.0 or newer.
+- Provider reports are snapshots and may themselves be delayed by the provider.
+- OpenRouter successful inference responses do not expose proactive request-rate counters; `/usage` reports the documented per-key credit/spend fields instead.
+- A provider may not return a safe human-readable account identity. In that case the provider and runtime credential state remain visible without exposing secrets.
+- Immediate account-change events are not available from Pi; auth is re-resolved before commands, turns, and scheduled refreshes.
+
+## 🗂️ Package layout
+
+```txt
+extensions/pi-usage/
+├── src/
+│   ├── usage.ts       # Pi entrypoint, menu, cache, and lifecycle orchestration
+│   ├── query.ts       # Runtime auth resolution and provider queries
+│   ├── format.ts      # Provider-aware notifications and statusline text
+│   ├── core.ts        # Cache, concurrency, fingerprint, and redaction helpers
+│   ├── providers/     # Codex and OpenRouter normalization adapters
+│   └── types.ts       # Common presentation and adapter contracts
+├── test/
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```
+
+Only `usage.ts` is a Pi entrypoint; other source modules are internal.
+
+## 🔎 Keywords
+
+Pi extension, Pi coding agent, usage, quota, OpenAI Codex usage, ChatGPT subscription limits, OpenRouter credits, API-key spend limits, TypeScript Pi package, npm Pi extension.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@narumitw/pi-usage",
+	"version": "0.24.0",
+	"description": "Pi extension that shows current-account usage across supported model providers.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"usage",
+		"quota",
+		"codex",
+		"openrouter"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/usage.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json README.md && npm run typecheck",
+		"format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json README.md",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.81.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.3",
+		"@earendil-works/pi-coding-agent": "0.81.0",
+		"@types/node": "26.1.1",
+		"typescript": "7.0.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-usage"
+	}
+}

package/src/core.ts

@@ -0,0 +1,217 @@
+import { createHmac } from "node:crypto";
+import type { UsageReport } from "./types.js";
+
+export class UsageCache {
+	private readonly entries = new Map<string, { createdAt: number; report: UsageReport }>();
+	private readonly ttlMs: number;
+	private readonly maxEntries: number;
+
+	constructor(ttlMs: number, maxEntries = 32) {
+		if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new Error("Cache TTL must be positive.");
+		if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+			throw new Error("Cache entry limit must be a positive integer.");
+		}
+		this.ttlMs = ttlMs;
+		this.maxEntries = maxEntries;
+	}
+
+	get size(): number {
+		return this.entries.size;
+	}
+
+	get(providerId: string, fingerprint: string, now = Date.now()): UsageReport | undefined {
+		this.sweepExpired(now);
+		return this.entries.get(cacheKey(providerId, fingerprint))?.report;
+	}
+
+	set(providerId: string, fingerprint: string, report: UsageReport, now = Date.now()): void {
+		this.sweepExpired(now);
+		const key = cacheKey(providerId, fingerprint);
+		this.entries.delete(key);
+		while (this.entries.size >= this.maxEntries) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === undefined) break;
+			this.entries.delete(oldest);
+		}
+		this.entries.set(key, { createdAt: now, report });
+	}
+
+	clearProvider(providerId: string): void {
+		for (const key of this.entries.keys()) {
+			if (key.startsWith(`${providerId}:`)) this.entries.delete(key);
+		}
+	}
+
+	clear(): void {
+		this.entries.clear();
+	}
+
+	private sweepExpired(now: number): void {
+		for (const [key, entry] of this.entries) {
+			if (now - entry.createdAt >= this.ttlMs) this.entries.delete(key);
+		}
+	}
+}
+
+export function fingerprintResolvedAuth(
+	auth: { apiKey?: string; headers?: Record<string, string> },
+	salt: Uint8Array,
+): string {
+	const headers = Object.entries(auth.headers ?? {})
+		.map(([name, value]) => [name.toLowerCase(), value] as const)
+		.sort(([left], [right]) => left.localeCompare(right));
+	const canonical = JSON.stringify({ apiKey: auth.apiKey ?? "", headers });
+	return createHmac("sha256", salt).update(canonical).digest("hex");
+}
+
+export async function runWithConcurrency<T, R>(
+	items: readonly T[],
+	limit: number,
+	worker: (item: T, index: number, signal: AbortSignal) => Promise<R>,
+	signal: AbortSignal,
+): Promise<PromiseSettledResult<R>[]> {
+	if (signal.aborted) throw abortError();
+	if (!Number.isSafeInteger(limit) || limit < 1)
+		throw new Error("Concurrency limit must be positive.");
+
+	const results = new Array<PromiseSettledResult<R>>(items.length);
+	let nextIndex = 0;
+	const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		while (nextIndex < items.length) {
+			if (signal.aborted) throw abortError();
+			const index = nextIndex;
+			nextIndex += 1;
+			try {
+				results[index] = {
+					status: "fulfilled",
+					value: await worker(items[index] as T, index, signal),
+				};
+			} catch (reason) {
+				results[index] = { status: "rejected", reason };
+			}
+		}
+	});
+
+	await Promise.all(runners);
+	if (signal.aborted) throw abortError();
+	return results;
+}
+
+export async function awaitWithDeadline<T>(
+	operation: Promise<T>,
+	signal: AbortSignal,
+	timeoutMs: number,
+	description: string,
+): Promise<T> {
+	if (signal.aborted) throw abortError();
+	const controller = new AbortController();
+	const abortFromCaller = () => controller.abort();
+	signal.addEventListener("abort", abortFromCaller, { once: true });
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await Promise.race([
+			operation,
+			new Promise<never>((_resolve, reject) => {
+				controller.signal.addEventListener(
+					"abort",
+					() => {
+						reject(
+							signal.aborted
+								? abortError()
+								: Object.assign(
+										new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s ${description}.`),
+										{ name: "TimeoutError" },
+									),
+						);
+					},
+					{ once: true },
+				);
+			}),
+		]);
+	} finally {
+		clearTimeout(timeout);
+		signal.removeEventListener("abort", abortFromCaller);
+	}
+}
+
+export function sanitizeDisplayText(value: string, maxChars = 160): string {
+	let result = "";
+	for (let index = 0; index < value.length; ) {
+		const codePoint = value.codePointAt(index) ?? 0;
+		const character = String.fromCodePoint(codePoint);
+		if (codePoint === 0x1b || codePoint === 0x9b || codePoint === 0x9d) {
+			index = skipTerminalEscape(value, index, codePoint);
+			continue;
+		}
+		if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+			if (codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d) result += " ";
+			index += character.length;
+			continue;
+		}
+		result += character;
+		index += character.length;
+	}
+	return truncate(result.replace(/\s+/gu, " ").trim(), maxChars);
+}
+
+export function redactUsageError(value: string, secrets: readonly string[] = []): string {
+	let redacted = value;
+	for (const secret of [...new Set(secrets)].filter(Boolean).sort((a, b) => b.length - a.length)) {
+		redacted = redacted.replace(new RegExp(escapeRegExp(secret), "g"), "<redacted>");
+	}
+	redacted = redacted
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer <redacted>")
+		.replace(/"(?:access_token|refresh_token|api_key)"\s*:\s*"[^"]+"/gi, (match) => {
+			const separator = match.indexOf(":");
+			return `${match.slice(0, separator + 1)}"<redacted>"`;
+		});
+	return sanitizeDisplayText(redacted, 600);
+}
+
+export function errorMessage(error: unknown): string {
+	return sanitizeDisplayText(error instanceof Error ? error.message : String(error), 600);
+}
+
+export function abortError(): Error {
+	return Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+}
+
+function skipTerminalEscape(value: string, start: number, codePoint: number): number {
+	let index = start + 1;
+	const next = value.charCodeAt(index);
+	const isOsc = codePoint === 0x9d || (codePoint === 0x1b && next === 0x5d);
+	if (isOsc) {
+		if (codePoint === 0x1b) index += 1;
+		while (index < value.length) {
+			const current = value.charCodeAt(index);
+			if (current === 0x07) return index + 1;
+			if (current === 0x1b && value.charCodeAt(index + 1) === 0x5c) return index + 2;
+			index += 1;
+		}
+		return index;
+	}
+	const isCsi = codePoint === 0x9b || (codePoint === 0x1b && next === 0x5b);
+	if (isCsi) {
+		if (codePoint === 0x1b) index += 1;
+		while (index < value.length) {
+			const current = value.charCodeAt(index);
+			index += 1;
+			if (current >= 0x40 && current <= 0x7e) break;
+		}
+		return index;
+	}
+	return Math.min(value.length, start + (codePoint === 0x1b ? 2 : 1));
+}
+
+function cacheKey(providerId: string, fingerprint: string): string {
+	return `${providerId}:${fingerprint}`;
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function truncate(value: string, maxChars: number): string {
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars - 1)}…`;
+}

package/src/format.ts

@@ -0,0 +1,249 @@
+import type {
+	ProviderUsageState,
+	UsageBucket,
+	UsageDisplayState,
+	UsageModel,
+	UsageReport,
+} from "./types.js";
+
+const BAR_SEGMENTS = 20;
+const VALUE_COLUMN = 29;
+
+export function formatUsageReport(report: UsageReport, displayState: UsageDisplayState): string {
+	const stateLabel = displayState === "current" ? "Current" : "Configured";
+	const lines = [`${report.providerName} Usage · ${stateLabel}`];
+	if (report.accountLabel) lines.push(`Account: ${report.accountLabel}`);
+	lines.push(`Semantics: ${report.semantics.label}`, "");
+
+	if (report.providerId === "openai-codex") formatCodexReport(lines, report);
+	else if (report.providerId === "openrouter") formatOpenRouterReport(lines, report);
+	else formatGenericReport(lines, report);
+
+	if (report.notes) {
+		for (const note of report.notes) lines.push(note);
+	}
+	return lines.join("\n").trimEnd();
+}
+
+export function formatUsageStatusline(report: UsageReport, model?: UsageModel): string | undefined {
+	if (report.providerId === "openai-codex") return formatCodexStatusline(report, model);
+	if (report.providerId === "openrouter") {
+		const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
+		if (limit?.remaining !== undefined) return `openrouter ${formatUsd(limit.remaining)} left`;
+		const total = report.metrics.find((metric) => metric.id === "usage-total");
+		if (typeof total?.value === "number") return `openrouter ${formatUsd(total.value)} used`;
+	}
+	return undefined;
+}
+
+export function formatProviderStates(states: readonly ProviderUsageState[]): string {
+	return states
+		.map((state) => {
+			if (state.status === "ready") return formatUsageReport(state.report, state.displayState);
+			const label = state.displayState === "current" ? "Current" : "Configured";
+			const status =
+				state.status === "auth-unavailable"
+					? "Authentication unavailable"
+					: state.status === "unsupported"
+						? "Unsupported"
+						: "Query failed";
+			return `${state.providerName} · ${label}\n${status}: ${state.message}`;
+		})
+		.join("\n\n");
+}
+
+function formatCodexReport(lines: string[], report: UsageReport): void {
+	let previousGroup: string | undefined;
+	for (const bucket of report.buckets) {
+		const group = bucket.groupId ?? bucket.id;
+		if (group !== previousGroup && group !== "codex") {
+			lines.push(`${bucket.groupLabel ?? group} limit:`);
+		}
+		previousGroup = group;
+		const fallback = bucket.id.endsWith(":secondary") ? "weekly" : "5h";
+		const label = `${formatWindowLabel(bucket.windowMinutes, fallback, false)} limit:`;
+		lines.push(`${label.padEnd(VALUE_COLUMN)}${formatPercentBucket(bucket)}`);
+	}
+	for (const metric of report.metrics) {
+		if (metric.id === "reset-credits") {
+			lines.push(`${"Usage limit resets:".padEnd(VALUE_COLUMN)}${metric.value} available`);
+		} else if (metric.id === "credits") {
+			lines.push(
+				`${"Credits:".padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`,
+			);
+		}
+	}
+}
+
+function formatOpenRouterReport(lines: string[], report: UsageReport): void {
+	const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
+	if (limit) {
+		const period = limit.period ? ` (${limit.period})` : "";
+		const value =
+			limit.remaining === undefined
+				? `${formatUsd(limit.limit ?? 0)} cap; remaining unavailable`
+				: `${formatUsd(limit.remaining)} of ${formatUsd(limit.limit ?? 0)} left`;
+		lines.push(`${`Key limit${period}:`.padEnd(VALUE_COLUMN)}${value}`);
+	}
+	for (const metric of report.metrics) {
+		lines.push(
+			`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`,
+		);
+	}
+}
+
+function formatGenericReport(lines: string[], report: UsageReport): void {
+	for (const bucket of report.buckets) {
+		lines.push(
+			`${`${bucket.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(bucket.remaining ?? bucket.used ?? "unavailable", bucket.unit)}`,
+		);
+	}
+	for (const metric of report.metrics) {
+		lines.push(
+			`${`${metric.label}:`.padEnd(VALUE_COLUMN)}${formatMetricValue(metric.value, metric.unit)}`,
+		);
+	}
+}
+
+function formatCodexStatusline(report: UsageReport, model?: UsageModel): string | undefined {
+	const group = selectCodexGroup(report, model);
+	if (!group) return formatCodexCreditsStatus(report);
+	const buckets = report.buckets.filter((bucket) => (bucket.groupId ?? bucket.id) === group);
+	const labelBucket = buckets[0];
+	const parts = [
+		group === "codex" ? "codex" : `codex ${compactLimitLabel(labelBucket?.groupLabel ?? group)}`,
+	];
+	for (const bucket of buckets) {
+		if (bucket.remaining === undefined) continue;
+		const fallback = bucket.id.endsWith(":secondary") ? "weekly" : "5h";
+		parts.push(
+			`${clampPercent(bucket.remaining).toFixed(0)}% ${formatWindowLabel(bucket.windowMinutes, fallback, true)}`,
+		);
+	}
+	return parts.length > 1 ? parts.join(" ") : formatCodexCreditsStatus(report);
+}
+
+function formatCodexCreditsStatus(report: UsageReport): string {
+	const credits = report.metrics.find((metric) => metric.id === "credits");
+	if (!credits) return "codex usage unavailable";
+	if (credits.value === "none") return "codex no credits";
+	if (credits.value === "available") return "codex credits available";
+	if (credits.value === "unlimited") return "codex credits unlimited";
+	return `codex ${formatMetricValue(credits.value, "count")} credits`;
+}
+
+function selectCodexGroup(report: UsageReport, model?: UsageModel): string | undefined {
+	const groups = [...new Set(report.buckets.map((bucket) => bucket.groupId ?? bucket.id))];
+	if (model?.provider !== "openai-codex") {
+		return groups.includes("codex") ? "codex" : groups[0];
+	}
+	const modelKeys = normalizedModelKeys(model);
+	for (const group of groups) {
+		const bucket = report.buckets.find(
+			(candidate) => (candidate.groupId ?? candidate.id) === group,
+		);
+		const keys = [group, bucket?.groupLabel, ...(bucket?.modelKeys ?? [])]
+			.map(normalizeKey)
+			.filter((key): key is string => key !== undefined);
+		if (keys.some((key) => modelKeys.has(key))) return group;
+	}
+	const variants = [...modelKeys]
+		.map((key) => key.match(/(?:^|-)codex-(.+)$/)?.[1])
+		.filter((value): value is string => Boolean(value));
+	for (const variant of variants) {
+		const matches = groups.filter((group) => {
+			if (group === "codex") return false;
+			const key = normalizeKey(group);
+			return key ? normalizedKeyHasToken(key, variant) : false;
+		});
+		if (matches.length === 1) return matches[0];
+	}
+	return groups.includes("codex") ? "codex" : groups[0];
+}
+
+function normalizedModelKeys(model: UsageModel): Set<string> {
+	const keys = new Set<string>();
+	for (const value of [model.id, model.name]) {
+		const key = normalizeKey(value);
+		if (!key) continue;
+		keys.add(key);
+		const index = key.indexOf("codex");
+		if (index >= 0) keys.add(key.slice(index));
+	}
+	return keys;
+}
+
+function normalizeKey(value: string | undefined): string | undefined {
+	const normalized = value
+		?.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return normalized || undefined;
+}
+
+function normalizedKeyHasToken(key: string, token: string): boolean {
+	return (
+		key === token ||
+		key.startsWith(`${token}-`) ||
+		key.endsWith(`-${token}`) ||
+		key.includes(`-${token}-`)
+	);
+}
+
+function compactLimitLabel(label: string): string {
+	const normalized = label.replace(/[_-]+/g, " ").trim();
+	return (normalized.match(/\bcodex\s+(.+)$/i)?.[1]?.trim() || normalized)
+		.toLowerCase()
+		.replace(/\s+/g, " ");
+}
+
+function formatPercentBucket(bucket: UsageBucket): string {
+	const remaining = clampPercent(bucket.remaining ?? 0);
+	const filled = Math.round((remaining / 100) * BAR_SEGMENTS);
+	const reset = bucket.resetsAt ? ` (resets ${formatReset(bucket.resetsAt)})` : "";
+	return `[${"█".repeat(filled)}${"░".repeat(BAR_SEGMENTS - filled)}] ${remaining.toFixed(0)}% left${reset}`;
+}
+
+function formatWindowLabel(
+	minutes: number | undefined,
+	fallback: "5h" | "weekly",
+	compact: boolean,
+): string {
+	if (!minutes || !Number.isFinite(minutes) || minutes <= 0) {
+		return compact && fallback === "weekly" ? "wk" : capitalize(fallback);
+	}
+	if (minutes === 10_080) return compact ? "wk" : "Weekly";
+	if (minutes % 10_080 === 0) return `${minutes / 10_080}w`;
+	if (minutes % 1_440 === 0) return `${minutes / 1_440}d`;
+	if (minutes % 60 === 0) return `${minutes / 60}h`;
+	return `${minutes}m`;
+}
+
+function formatMetricValue(value: number | string, unit: UsageBucket["unit"] | undefined): string {
+	if (unit === "usd" && typeof value === "number") return formatUsd(value);
+	return String(value);
+}
+
+function formatUsd(value: number): string {
+	return `$${value.toFixed(2)}`;
+}
+
+function formatReset(epochSeconds: number): string {
+	const reset = new Date(epochSeconds * 1000);
+	if (Number.isNaN(reset.getTime())) return "at an unknown time";
+	const time = `${reset.getHours().toString().padStart(2, "0")}:${reset
+		.getMinutes()
+		.toString()
+		.padStart(2, "0")}`;
+	const now = new Date();
+	if (reset.toDateString() === now.toDateString()) return time;
+	return `${time} on ${reset.getDate()} ${reset.toLocaleDateString(undefined, { month: "short" })}`;
+}
+
+function capitalize(value: string): string {
+	return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
+
+function clampPercent(value: number): number {
+	return Math.min(100, Math.max(0, value));
+}