@narumitw/pi-usage 0.34.0 → 0.39.0

package/README.md

@@ -2,20 +2,21 @@
 
 [![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.
+`@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, GitHub Copilot allowances, 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 GitHub Copilot AI Credits, legacy premium requests, Free chat quota, additional usage, percentage, and reset time.
 - 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.
+- Resolves runtime credentials through Pi; for Copilot only, reads Pi's stored OAuth credential through Pi's public credential API and verifies that it matches the active runtime account.
 
 ## 📦 Install
 
@@ -45,7 +46,8 @@ Run:
 /usage
 ```
 
-The menu first queries the current model provider and presents its state with these actions:
+In TUI or RPC mode, the standard menu first queries the current model provider and presents its state
+with these actions:
 
 ```text
 Refresh current usage
@@ -54,7 +56,11 @@ 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.
+There are intentionally no `/usage --refresh`, `/usage <provider>`, or `/usage --all` argument paths.
+Cross-provider traffic requires an explicit interactive choice. Escape returns from provider selection
+and closes the root menu. Print and JSON modes reject `/usage` observably because they cannot host the
+interactive flow. The cancellable live-query progress view remains extension-owned because it streams
+provider work and supports in-flight abort rather than presenting a standard menu screen.
 
 ## 📋 Provider semantics
 
@@ -68,6 +74,16 @@ There are intentionally no `/usage --refresh`, `/usage <provider>`, or `/usage -
 
 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.
 
+### GitHub Copilot
+
+- Provider ID: `github-copilot`
+- Semantics: the allowance reported for the active Copilot plan—AI credits for current usage-based billing, premium requests for legacy annual billing, or chat requests for Copilot Free's limited response shape
+- Source: GitHub's undocumented `GET /copilot_internal/user` endpoint
+- Displayed data: entitlement, remaining allowance, percentage, reset time, plan, and any additional usage beyond the included allowance
+- Statusline examples: `copilot credits 1200/1500 80%`, `copilot 245/300 82%`, or `copilot chat 40/50 80%`
+
+GitHub's quota endpoint requires the original GitHub OAuth token rather than the short-lived Copilot inference token exposed by runtime auth. `pi-usage` therefore supports Copilot accounts created through Pi's `/login` flow, reads that stored credential through Pi's public API, and uses it only when its short-lived access token matches the active runtime credential. API-key credentials, account mismatches, GitHub Enterprise accounts, and proxy/custom provider origins fail closed. The detailed report follows the endpoint's `token_based_billing` marker so AI credits are not mislabeled as legacy premium requests, and it reports overage without treating a negative included balance as a malformed response.
+
 ### OpenRouter
 
 - Provider ID: `openrouter`
@@ -110,7 +126,8 @@ Behavior changes:
 
 ## 🚧 Limitations
 
-- Only providers with a stable, meaningful usage source and Pi-resolvable runtime auth are supported.
+- Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
+- GitHub Copilot quota uses an undocumented GitHub endpoint that may change without notice.
 - 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.
@@ -127,7 +144,7 @@ extensions/pi-usage/
 │   ├── 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
+│   ├── providers/     # Codex, GitHub Copilot, and OpenRouter normalization adapters
 │   └── types.ts       # Common presentation and adapter contracts
 ├── test/
 ├── README.md
@@ -140,7 +157,7 @@ extensions/pi-usage/
 
 ## 🔎 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.
+Pi extension, Pi coding agent, usage, quota, OpenAI Codex usage, ChatGPT subscription limits, GitHub Copilot AI credits, GitHub Copilot premium requests, OpenRouter credits, API-key spend limits, TypeScript Pi package, npm Pi extension.
 
 ## 📄 License
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.34.0",
-	"description": "Pi extension that shows current-account usage across supported model providers.",
+	"version": "0.39.0",
+	"description": "Pi extension that shows current-account usage for Codex, GitHub Copilot, and OpenRouter.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -12,6 +12,7 @@
 		"usage",
 		"quota",
 		"codex",
+		"copilot",
 		"openrouter"
 	],
 	"files": [
@@ -33,14 +34,17 @@
 		"@earendil-works/pi-coding-agent": ">=0.81.0"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.5",
-		"@earendil-works/pi-coding-agent": "0.82.1",
-		"@types/node": "26.1.1",
+		"@biomejs/biome": "2.5.6",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@types/node": "26.1.2",
 		"typescript": "7.0.2"
 	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
 		"directory": "extensions/pi-usage"
+	},
+	"dependencies": {
+		"@narumitw/pi-tui-kit": "<1"
 	}
 }

package/src/format.ts

@@ -16,6 +16,7 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
 	lines.push(`Semantics: ${report.semantics.label}`, "");
 
 	if (report.providerId === "openai-codex") formatCodexReport(lines, report);
+	else if (report.providerId === "github-copilot") formatGitHubCopilotReport(lines, report);
 	else if (report.providerId === "openrouter") formatOpenRouterReport(lines, report);
 	else formatGenericReport(lines, report);
 
@@ -27,6 +28,7 @@ export function formatUsageReport(report: UsageReport, displayState: UsageDispla
 
 export function formatUsageStatusline(report: UsageReport, model?: UsageModel): string | undefined {
 	if (report.providerId === "openai-codex") return formatCodexStatusline(report, model);
+	if (report.providerId === "github-copilot") return formatGitHubCopilotStatusline(report);
 	if (report.providerId === "openrouter") {
 		const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
 		if (limit?.remaining !== undefined) return `openrouter ${formatUsd(limit.remaining)} left`;
@@ -75,6 +77,52 @@ function formatCodexReport(lines: string[], report: UsageReport): void {
 	}
 }
 
+function formatGitHubCopilotReport(lines: string[], report: UsageReport): void {
+	const quota = findGitHubCopilotQuota(report);
+	if (!quota || quota.limit === undefined || quota.remaining === undefined) {
+		lines.push(`${`${quota?.label ?? "Copilot quota"}:`.padEnd(VALUE_COLUMN)}unlimited`);
+		return;
+	}
+	const percent = percentRemaining(quota);
+	const reset = quota.resetsAt ? ` (resets ${formatReset(quota.resetsAt)})` : "";
+	lines.push(
+		`${`${quota.label}:`.padEnd(VALUE_COLUMN)}${quota.remaining} of ${quota.limit} left · ${percent}%${reset}`,
+	);
+	const overage = report.metrics.find((metric) => metric.id === "overage-used");
+	if (typeof overage?.value === "number" && overage.value > 0) {
+		lines.push(`${"Additional usage:".padEnd(VALUE_COLUMN)}${overage.value} ${quota.label}`);
+	}
+}
+
+function formatGitHubCopilotStatusline(report: UsageReport): string {
+	const quota = findGitHubCopilotQuota(report);
+	const kind = compactGitHubCopilotQuotaKind(quota);
+	if (!quota || quota.limit === undefined || quota.remaining === undefined) {
+		return `copilot ${kind} unlimited`;
+	}
+	const overage = report.metrics.find((metric) => metric.id === "overage-used");
+	const overageSuffix =
+		typeof overage?.value === "number" && overage.value > 0 ? ` +${overage.value} over` : "";
+	return `copilot ${kind === "premium" ? "" : `${kind} `}${quota.remaining}/${quota.limit} ${percentRemaining(quota)}%${overageSuffix}`;
+}
+
+function findGitHubCopilotQuota(report: UsageReport): UsageBucket | undefined {
+	return report.buckets.find((bucket) =>
+		["ai-credits", "premium-requests", "chat-requests"].includes(bucket.id),
+	);
+}
+
+function compactGitHubCopilotQuotaKind(bucket: UsageBucket | undefined): string {
+	if (bucket?.id === "ai-credits") return "credits";
+	if (bucket?.id === "chat-requests") return "chat";
+	return "premium";
+}
+
+function percentRemaining(bucket: UsageBucket): number {
+	if (!bucket.limit || bucket.remaining === undefined) return 0;
+	return Math.round(clampPercent((bucket.remaining / bucket.limit) * 100));
+}
+
 function formatOpenRouterReport(lines: string[], report: UsageReport): void {
 	const limit = report.buckets.find((bucket) => bucket.id === "key-limit");
 	if (limit) {

package/src/index.ts

@@ -10,6 +10,7 @@ export {
 } from "./core.js";
 export { formatProviderStates, formatUsageReport, formatUsageStatusline } from "./format.js";
 export { normalizeCodexBackendPayload } from "./providers/codex.js";
+export { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
 export { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
 export {
 	adapterForProvider,

package/src/providers/github-copilot.ts

@@ -0,0 +1,120 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { GitHubCopilotUsagePayload, UsageBucket, UsageReport } from "../types.js";
+
+export function normalizeGitHubCopilotUsagePayload(
+	payload: GitHubCopilotUsagePayload,
+	capturedAt: number,
+): UsageReport {
+	const snapshots = asObject(payload.quota_snapshots);
+	const premium = asObject(snapshots?.premium_interactions);
+	const metrics: UsageReport["metrics"] = [];
+	let semanticsLabel: string;
+	let bucket: UsageBucket;
+
+	if (premium) {
+		const tokenBasedBilling = premium.token_based_billing === true;
+		const id = tokenBasedBilling ? "ai-credits" : "premium-requests";
+		const label = tokenBasedBilling ? "AI credits" : "Premium requests";
+		semanticsLabel = tokenBasedBilling
+			? "GitHub Copilot AI Credits allowance"
+			: "GitHub Copilot premium request quota";
+
+		if (premium.unlimited === true) {
+			bucket = { id, label, unit: "count" };
+		} else {
+			const entitlement = asNonnegativeNumber(premium.entitlement);
+			const rawRemaining =
+				asFiniteNumber(premium.remaining) ?? asFiniteNumber(premium.quota_remaining);
+			if (entitlement === undefined || rawRemaining === undefined) {
+				throw new Error(`GitHub Copilot ${label.toLowerCase()} quota was incomplete.`);
+			}
+			const overageUsed = Math.max(
+				asNonnegativeNumber(premium.overage_count) ?? 0,
+				Math.max(0, -rawRemaining),
+			);
+			if (overageUsed > 0) {
+				metrics.push({
+					id: "overage-used",
+					label: "Additional usage",
+					value: overageUsed,
+					unit: "count",
+				});
+			}
+			bucket = {
+				id,
+				label,
+				used: asNonnegativeNumber(premium.credits_used) ?? Math.max(0, entitlement - rawRemaining),
+				remaining: Math.max(0, rawRemaining),
+				limit: entitlement,
+				unit: "count",
+				period: "monthly",
+				...resetTimestamp(payload),
+			};
+		}
+	} else {
+		const limited = asObject(payload.limited_user_quotas);
+		const monthly = asObject(payload.monthly_quotas);
+		const remaining = asNonnegativeNumber(limited?.chat);
+		const entitlement = asNonnegativeNumber(monthly?.chat);
+		if (remaining === undefined || entitlement === undefined) {
+			throw new Error("GitHub Copilot usage response contained no supported quota.");
+		}
+		semanticsLabel = "GitHub Copilot Free chat quota";
+		bucket = {
+			id: "chat-requests",
+			label: "Chat requests",
+			used: Math.max(0, entitlement - remaining),
+			remaining,
+			limit: entitlement,
+			unit: "count",
+			period: "monthly",
+			...resetTimestamp(payload),
+		};
+	}
+
+	const notes: string[] = [];
+	const plan = asString(payload.copilot_plan) ?? asString(payload.access_type_sku);
+	if (plan) notes.push(`Plan: ${plan}`);
+
+	return {
+		providerId: "github-copilot",
+		providerName: "GitHub Copilot",
+		capturedAt,
+		source: "github-copilot-user",
+		semantics: { kind: "consumer-subscription", label: semanticsLabel },
+		accountLabel: asString(payload.login),
+		buckets: [bucket],
+		metrics,
+		...(notes.length > 0 ? { notes } : {}),
+	};
+}
+
+function resetTimestamp(payload: GitHubCopilotUsagePayload): { resetsAt?: number } {
+	const raw =
+		asString(payload.quota_reset_date_utc) ??
+		asString(payload.quota_reset_date) ??
+		asString(payload.limited_user_reset_date);
+	if (!raw) return {};
+	const milliseconds = Date.parse(raw);
+	return Number.isNaN(milliseconds) ? {} : { resetsAt: Math.floor(milliseconds / 1000) };
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	return sanitizeDisplayText(value, 80) || undefined;
+}
+
+function asFiniteNumber(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return value;
+}
+
+function asNonnegativeNumber(value: unknown): number | undefined {
+	const number = asFiniteNumber(value);
+	return number === undefined || number < 0 ? undefined : number;
+}

package/src/query.ts

@@ -1,10 +1,12 @@
 import { randomBytes } from "node:crypto";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionContext, readStoredCredential } from "@earendil-works/pi-coding-agent";
 import { errorMessage, fingerprintResolvedAuth, redactUsageError } from "./core.js";
 import { normalizeCodexBackendPayload } from "./providers/codex.js";
+import { normalizeGitHubCopilotUsagePayload } from "./providers/github-copilot.js";
 import { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
 import type {
 	CodexBackendPayload,
+	GitHubCopilotUsagePayload,
 	OpenRouterKeyPayload,
 	PiModel,
 	ResolvedUsageAuth,
@@ -13,6 +15,7 @@ import type {
 } from "./types.js";
 
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const GITHUB_COPILOT_USAGE_URL = "https://api.github.com/copilot_internal/user";
 const OPENROUTER_KEY_URL = "https://openrouter.ai/api/v1/key";
 const MAX_SUCCESS_BODY_BYTES = 64 * 1024;
 const MAX_ERROR_BODY_BYTES = 4 * 1024;
@@ -38,6 +41,24 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 			return normalizeCodexBackendPayload(payload as CodexBackendPayload, Date.now());
 		},
 	},
+	{
+		id: "github-copilot",
+		displayName: "GitHub Copilot",
+		semantics: {
+			kind: "consumer-subscription",
+			label: "GitHub Copilot account allowance",
+		},
+		async query(auth, signal, timeoutMs) {
+			const payload = await fetchProviderJson(
+				GITHUB_COPILOT_USAGE_URL,
+				auth,
+				signal,
+				timeoutMs,
+				"GitHub Copilot usage endpoint",
+			);
+			return normalizeGitHubCopilotUsagePayload(payload as GitHubCopilotUsagePayload, Date.now());
+		},
+	},
 	{
 		id: "openrouter",
 		displayName: "OpenRouter",
@@ -72,6 +93,7 @@ export async function resolveUsageAuth(
 	ctx: ExtensionContext,
 	adapter: UsageProviderAdapter,
 	salt: Uint8Array = AUTH_FINGERPRINT_SALT,
+	credentialReader: StoredCredentialReader = readStoredCredential,
 ): Promise<ResolvedUsageAuth | undefined> {
 	if (ctx.model?.provider === adapter.id && !hasOfficialOrigin(ctx.model, adapter.id)) {
 		throw new Error(
@@ -104,6 +126,9 @@ export async function resolveUsageAuth(
 	}
 	const auth = modelAuth ?? providerResult?.auth;
 	if (!auth) return undefined;
+	if (adapter.id === "github-copilot") {
+		return resolveGitHubCopilotUsageAuth(auth, model, salt, credentialReader);
+	}
 	const authorization = authorizationFrom(auth);
 	if (!authorization) return undefined;
 	const headers = { Authorization: authorization };
@@ -262,6 +287,8 @@ type RequestAuth = {
 	headers?: Record<string, string | null>;
 };
 
+type StoredCredentialReader = (providerId: string) => unknown;
+
 type UsageAuthRegistry = {
 	getApiKeyAndHeaders?(
 		model: PiModel,
@@ -274,6 +301,51 @@ type UsageAuthRegistry = {
 	>;
 };
 
+function resolveGitHubCopilotUsageAuth(
+	auth: RequestAuth,
+	model: PiModel,
+	salt: Uint8Array,
+	credentialReader: StoredCredentialReader,
+): ResolvedUsageAuth {
+	const credential = asObject(credentialReader("github-copilot"));
+	if (credential?.type !== "oauth") {
+		throw new Error(
+			"GitHub Copilot usage requires the OAuth account configured through Pi /login.",
+		);
+	}
+	if (
+		typeof credential.enterpriseUrl === "string" &&
+		credential.enterpriseUrl &&
+		!isPublicGitHubDomain(credential.enterpriseUrl)
+	) {
+		throw new Error("GitHub Copilot usage does not yet support GitHub Enterprise accounts.");
+	}
+	const refresh = typeof credential.refresh === "string" ? credential.refresh : undefined;
+	const storedAccess = typeof credential.access === "string" ? credential.access : undefined;
+	const resolvedAccess = bearerToken(headerValue(auth.headers, "Authorization")) ?? auth.apiKey;
+	if (!refresh || !storedAccess || !resolvedAccess) {
+		throw new Error("GitHub Copilot OAuth credentials were incomplete.");
+	}
+	if (storedAccess !== resolvedAccess) {
+		throw new Error(
+			"The active GitHub Copilot runtime account does not match Pi's stored OAuth account.",
+		);
+	}
+
+	const authorization = `Bearer ${refresh}`;
+	const headers = {
+		Authorization: authorization,
+		"X-GitHub-Api-Version": "2025-05-01",
+	};
+	return {
+		apiKey: refresh,
+		headers,
+		fingerprint: fingerprintResolvedAuth({ headers }, salt),
+		secrets: [refresh, storedAccess, resolvedAccess, authorization],
+		model,
+	};
+}
+
 function authorizationFrom(auth: RequestAuth): string | undefined {
 	return (
 		headerValue(auth.headers, "Authorization") ??
@@ -281,14 +353,40 @@ function authorizationFrom(auth: RequestAuth): string | undefined {
 	);
 }
 
+function bearerToken(authorization: string | undefined): string | undefined {
+	const match = /^Bearer\s+(.+)$/iu.exec(authorization ?? "");
+	return match?.[1];
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as Record<string, unknown>;
+}
+
+function isPublicGitHubDomain(value: string): boolean {
+	try {
+		const url = new URL(value.includes("://") ? value : `https://${value}`);
+		return url.hostname.toLowerCase() === "github.com";
+	} catch {
+		return false;
+	}
+}
+
 function hasOfficialOrigin(model: PiModel, providerId: string): boolean {
 	return hasOfficialUrlOrigin(model.baseUrl, providerId);
 }
 
 function hasOfficialUrlOrigin(value: string, providerId: string): boolean {
-	const expected = providerId === "openai-codex" ? "https://chatgpt.com" : "https://openrouter.ai";
 	try {
-		return new URL(value).origin === expected;
+		const url = new URL(value);
+		if (providerId === "openai-codex") return url.origin === "https://chatgpt.com";
+		if (providerId === "openrouter") return url.origin === "https://openrouter.ai";
+		if (providerId === "github-copilot") {
+			return (
+				url.protocol === "https:" && /^api\.[a-z0-9-]+\.githubcopilot\.com$/u.test(url.hostname)
+			);
+		}
+		return false;
 	} catch {
 		return false;
 	}

package/src/types.ts

@@ -77,6 +77,18 @@ export type ProviderUsageState =
 			message: string;
 	  };
 
+export type GitHubCopilotUsagePayload = {
+	login?: unknown;
+	copilot_plan?: unknown;
+	access_type_sku?: unknown;
+	limited_user_quotas?: unknown;
+	limited_user_reset_date?: unknown;
+	monthly_quotas?: unknown;
+	quota_reset_date?: unknown;
+	quota_reset_date_utc?: unknown;
+	quota_snapshots?: unknown;
+};
+
 export type OpenRouterKeyPayload = {
 	data?: unknown;
 };

package/src/usage.ts

@@ -4,6 +4,7 @@ import {
 	type ExtensionCommandContext,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import {
 	awaitWithDeadline,
 	errorMessage,
@@ -39,7 +40,6 @@ const REFRESH_CURRENT = "Refresh current usage";
 const VIEW_ANOTHER = "View another configured provider…";
 const VIEW_ALL = "View all configured providers…";
 const CLOSE = "Close";
-const MENU_ACTIONS = [REFRESH_CURRENT, VIEW_ANOTHER, VIEW_ALL, CLOSE];
 
 type QueryOutcome = {
 	state: ProviderUsageState;
@@ -455,11 +455,9 @@ export default function usageExtension(pi: ExtensionAPI) {
 	};
 
 	const showMenu = async (ctx: ExtensionCommandContext): Promise<void> => {
-		if (!ctx.hasUI) {
-			ctx.ui.notify("/usage requires an interactive Pi mode.", "warning");
-			return;
-		}
+		if (!ctx.hasUI) throw new Error("/usage requires TUI or RPC mode.");
 		statusGeneration += 1;
+		const menuGeneration = statusGeneration;
 		statusController?.abort();
 		statusController = undefined;
 		clearStatusTimer();
@@ -476,115 +474,149 @@ export default function usageExtension(pi: ExtensionAPI) {
 			publishStableCurrent(ctx, stableCurrent);
 			let current = stableCurrent.outcome;
 			let visibleStates: ProviderUsageState[] = [current.state];
-
-			while (!controller.signal.aborted) {
-				const action = await ctx.ui.select(formatProviderStates(visibleStates), [...MENU_ACTIONS], {
-					signal: controller.signal,
-				});
-				if (!action || action === CLOSE) return;
-				if (action === REFRESH_CURRENT) {
-					stableCurrent = await queryStableCurrent(
-						ctx,
-						true,
-						controller,
-						"Refreshing current usage…",
-					);
-					if (!stableCurrent) continue;
-					publishStableCurrent(ctx, stableCurrent);
-					current = stableCurrent.outcome;
-					visibleStates = [current.state];
-					continue;
-				}
-				if (action === VIEW_ANOTHER) {
-					const others = configuredAdapters(ctx).filter(
-						(adapter) => adapter.id !== ctx.model?.provider,
-					);
-					if (others.length === 0) {
-						ctx.ui.notify("No other supported provider has configured runtime auth.", "info");
-						continue;
-					}
-					const choice = await ctx.ui.select(
-						"Select a configured provider",
-						others.map((adapter) => adapter.displayName),
-						{ signal: controller.signal },
-					);
-					const adapter = others.find((candidate) => candidate.displayName === choice);
-					if (!adapter) continue;
-					const outcome = await runMenuOperation(
-						ctx,
-						`Checking ${adapter.displayName} usage…`,
-						controller.signal,
-						(signal) => queryAdapterState(ctx, adapter, "configured", false, signal),
-					);
-					if (!outcome) continue;
-					const revalidated = await queryStableCurrent(
-						ctx,
-						false,
-						controller,
-						"Revalidating current usage…",
-					);
-					if (!revalidated) continue;
-					stableCurrent = revalidated;
-					current = revalidated.outcome;
-					visibleStates =
-						outcome.state.providerId === current.state.providerId
-							? [current.state]
-							: [current.state, { ...outcome.state, displayState: "configured" }];
-					continue;
-				}
-				if (action === VIEW_ALL) {
-					const adapters = configuredAdapters(ctx);
-					const currentProviderId = ctx.model?.provider;
-					const settled = await runMenuOperation(
-						ctx,
-						"Checking configured provider usage…",
-						controller.signal,
-						(signal) =>
-							runWithConcurrency(
-								adapters,
-								ALL_PROVIDER_CONCURRENCY,
-								(adapter, _index, workerSignal) =>
-									queryAdapterState(
-										ctx,
-										adapter,
-										adapter.id === currentProviderId ? "current" : "configured",
-										true,
-										workerSignal,
-									),
-								signal,
-							),
-					);
-					if (!settled) continue;
-					const queriedStates: ProviderUsageState[] = settled.map((result, index) => {
-						if (result.status === "fulfilled") {
-							return { ...result.value.state, displayState: "configured" };
+			type Screen = "main" | "providers";
+			type Action = "refresh" | "another" | "all" | "provider";
+			const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
+				start: "main",
+				screens: {
+					main: () => ({
+						kind: "actions",
+						title: "Provider usage",
+						lines: formatProviderStates(visibleStates).split("\n"),
+						items: [
+							{ id: "refresh", label: REFRESH_CURRENT, action: "refresh" },
+							{ id: "another", label: VIEW_ANOTHER, action: "another" },
+							{ id: "all", label: VIEW_ALL, action: "all" },
+							{ id: "close", label: CLOSE, close: true },
+						],
+						hint: "close",
+					}),
+					providers: () => ({
+						kind: "actions",
+						title: "Select a configured provider",
+						items: configuredAdapters(ctx)
+							.filter((adapter) => adapter.id !== ctx.model?.provider)
+							.map((adapter) => ({
+								id: adapter.id,
+								label: adapter.displayName,
+								action: "provider" as const,
+							})),
+						hint: "back",
+					}),
+				},
+				actions: {
+					refresh: async () => {
+						const refreshed = await queryStableCurrent(
+							ctx,
+							true,
+							controller,
+							"Refreshing current usage…",
+						);
+						if (!refreshed) return { kind: "stay" };
+						stableCurrent = refreshed;
+						publishStableCurrent(ctx, refreshed);
+						current = refreshed.outcome;
+						visibleStates = [current.state];
+						return { kind: "stay" };
+					},
+					another: async () => {
+						const others = configuredAdapters(ctx).filter(
+							(adapter) => adapter.id !== ctx.model?.provider,
+						);
+						if (others.length === 0) {
+							ctx.ui.notify("No other supported provider has configured runtime auth.", "info");
+							return { kind: "stay" };
 						}
-						const adapter = adapters[index] as UsageProviderAdapter;
-						return {
-							providerId: adapter.id,
-							providerName: adapter.displayName,
-							displayState: "configured",
-							status: "query-failed",
-							message: errorMessage(result.reason),
-						};
-					});
-					const revalidated = await queryStableCurrent(
-						ctx,
-						false,
-						controller,
-						"Revalidating current usage…",
-					);
-					if (!revalidated) continue;
-					stableCurrent = revalidated;
-					current = revalidated.outcome;
-					visibleStates = [
-						current.state,
-						...queriedStates.filter((state) => state.providerId !== current.state.providerId),
-					];
-				}
-			}
+						return { kind: "to", screen: "providers" };
+					},
+					provider: async ({ itemId }) => {
+						const adapter = configuredAdapters(ctx).find(
+							(candidate) => candidate.id === itemId && candidate.id !== ctx.model?.provider,
+						);
+						if (!adapter) return { kind: "back" };
+						const outcome = await runMenuOperation(
+							ctx,
+							`Checking ${adapter.displayName} usage…`,
+							controller.signal,
+							(signal) => queryAdapterState(ctx, adapter, "configured", false, signal),
+						);
+						if (!outcome) return { kind: "back" };
+						const revalidated = await queryStableCurrent(
+							ctx,
+							false,
+							controller,
+							"Revalidating current usage…",
+						);
+						if (!revalidated) return { kind: "back" };
+						stableCurrent = revalidated;
+						current = revalidated.outcome;
+						visibleStates = [
+							outcome.state.providerId === current.state.providerId
+								? current.state
+								: { ...outcome.state, displayState: "configured" },
+						];
+						return { kind: "back" };
+					},
+					all: async () => {
+						const adapters = configuredAdapters(ctx);
+						const currentProviderId = ctx.model?.provider;
+						const settled = await runMenuOperation(
+							ctx,
+							"Checking configured provider usage…",
+							controller.signal,
+							(signal) =>
+								runWithConcurrency(
+									adapters,
+									ALL_PROVIDER_CONCURRENCY,
+									(adapter, _index, workerSignal) =>
+										queryAdapterState(
+											ctx,
+											adapter,
+											adapter.id === currentProviderId ? "current" : "configured",
+											true,
+											workerSignal,
+										),
+									signal,
+								),
+						);
+						if (!settled) return { kind: "stay" };
+						const queriedStates: ProviderUsageState[] = settled.map((result, index) => {
+							if (result.status === "fulfilled") {
+								return { ...result.value.state, displayState: "configured" };
+							}
+							const adapter = adapters[index] as UsageProviderAdapter;
+							return {
+								providerId: adapter.id,
+								providerName: adapter.displayName,
+								displayState: "configured",
+								status: "query-failed",
+								message: errorMessage(result.reason),
+							};
+						});
+						const revalidated = await queryStableCurrent(
+							ctx,
+							false,
+							controller,
+							"Revalidating current usage…",
+						);
+						if (!revalidated) return { kind: "stay" };
+						stableCurrent = revalidated;
+						current = revalidated.outcome;
+						visibleStates = [
+							current.state,
+							...queriedStates.filter((state) => state.providerId !== current.state.providerId),
+						];
+						return { kind: "stay" };
+					},
+				},
+			});
+			await runMenu(ctx, menu, {
+				getState: () => undefined,
+				signal: controller.signal,
+				isCurrent: () => statusGeneration === menuGeneration && !controller.signal.aborted,
+			});
 		} finally {
-			controller.abort();
+			controller.abort(new DOMException("Usage menu closed", "AbortError"));
 			activeControllers.delete(controller);
 		}
 	};