@nothumanwork/pi-usage 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# Pi Usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**OpenAI ChatGPT and Claude subscription usage limits in Pi.**
+
+Run `/usage` for a scrollable view of each account's allowance and reset times—not tokens consumed in the current Pi session. OpenAI bars show **percent left**, like Codex. Claude bars show **percent used**, like Claude Code, including the five-hour session, all-models weekly, and Fable weekly limits.
+
+## Install
+
+From this checkout, after installing dependencies at the repository root:
+
+```sh
+pi install /path/to/pi-extensions/pi-usage
+```
+
+Then restart Pi or run `/reload`. For a one-session preview:
+
+```sh
+pi -e /path/to/pi-extensions/pi-usage/index.ts
+```
+
+Published releases:
+
+```sh
+pi install npm:@nothumanwork/pi-usage
+```
+
+Requires Pi 1.4.0's extension/auth APIs and Node.js 22.19+. No background polling, configuration file, or model tool is installed.
+
+## Sign in
+
+### OpenAI
+
+Keep using **`/login openai` → Sign in with ChatGPT** for inference. Add the separate credential used by Codex to read usage:
+
+```text
+/login openai-codex
+/usage
+```
+
+Choose the **same ChatGPT account/workspace** for both logins. The usage view displays the account belonging to the Codex credential; it does not automatically verify that it matches your inference account. Signing into the Codex provider does not require changing your selected model.
+
+Pi owns credential storage, refresh, and refresh-token locking. This extension does not create another OAuth client, copy tokens, read `~/.codex/auth.json`, or use browser cookies. An API key is not a fallback.
+
+#### Why the second OpenAI login?
+
+The newer Sign in with ChatGPT token-sharing login does not currently expose Codex-style account usage. Its token is not accepted by Codex's usage endpoint. See [OpenAI issue #54219](https://github.com/openai/codex/issues/54219) and [OpenAI's errors and recovery guide](https://developers.openai.com/siwc/token-sharing-open-source/errors-and-recovery).
+
+This extension reads **account allowance through Codex**. It deliberately **does not include Pi-specific app caps** on the newer login. An app-specific cap can therefore block Pi even when the account view shows allowance remaining. No allowance is inferred from session token counts or token expiry.
+
+### Claude: native Pi or Claude Code / pi-claude-bridge
+
+If already signed into Claude Code (including through `pi-claude-bridge`), just run:
+
+```text
+/usage claude
+```
+
+**No separate `/login anthropic` is needed for bridge users.** If Claude Code needs a login, run `claude auth login` in your terminal. Inference-only `claude setup-token` tokens may lack the profile permission needed for usage.
+
+Alternatively, use Pi's native subscription login:
+
+```text
+/login anthropic
+/usage claude
+```
+
+Select the Claude subscription/OAuth option, not an API key. An Anthropic API key is not a subscription-usage credential.
+
+#### Where authentication lives
+
+| Login | Credential store | Who resolves and refreshes it |
+| --- | --- | --- |
+| Pi native Anthropic | `anthropic` entry in `~/.pi/agent/auth.json`, or `$PI_CODING_AGENT_DIR/auth.json` | Pi's `modelRegistry.getProviderAuth("anthropic")` |
+| Claude Code / bridge on macOS | macOS Keychain, normally service `Claude Code-credentials`; fallback `~/.claude/.credentials.json` if Keychain storage is unavailable | Claude Code, through the Agent SDK |
+| Claude Code / bridge on Linux | `~/.claude/.credentials.json` | Claude Code, through the Agent SDK |
+| Claude Code / bridge on Windows | `%USERPROFILE%\.claude\.credentials.json` | Claude Code, through the Agent SDK |
+
+`CLAUDE_CONFIG_DIR` changes Claude Code's credentials-file directory **and** the macOS Keychain entry it selects. The SDK handles this, including config-specific Keychain naming; the extension does not duplicate that lookup or rotate Claude Code's tokens itself. The bridge passes the process environment to Claude Code and does not maintain a separate subscription login in Pi. See [Claude Code authentication](https://code.claude.com/docs/en/authentication) and the [bridge source](https://github.com/elidickinson/pi-claude-bridge).
+
+**Account selection:** if the selected Pi model uses `claude-bridge`, use Claude Code's login. Otherwise prefer native Pi Anthropic OAuth when present, falling back to Claude Code only when no native OAuth credential is configured (an API key also falls through). A failed selected login does **not** silently switch to another account. The view labels the source and shows identity when available.
+
+The Claude Code path inspects the stored **subscription**, not API billing: API-key, API-endpoint, profile, and third-party backend environment overrides are removed from the usage-only child. `CLAUDE_CONFIG_DIR` and an explicit `CLAUDE_CODE_OAUTH_TOKEN` remain respected; an inference-only token results in an unavailable state rather than a hidden account switch.
+
+The Agent SDK opens a short-lived Claude Code process in an empty temporary directory. It sends **no prompt**, enables no tools or MCP servers, disables ordinary hooks/settings, does not persist a conversation, and requests `skipBehaviors: true` to avoid scanning local transcripts. Claude Code's managed policies still apply. The process is closed and the temporary directory removed on success, failure, cancellation, or timeout. Credential refresh remains owned by Claude Code.
+
+Keep npm optional dependencies enabled: the Agent SDK supplies a platform-specific Claude Code binary. No separately installed CLI executable is required to read an existing login. The SDK is loaded lazily, only for this auth path.
+
+## Commands and controls
+
+| Command / key | Action |
+| --- | --- |
+| `/usage` | Fetch all supported providers |
+| `/usage openai` | Fetch only OpenAI |
+| `/usage claude` | Fetch only Claude subscription usage |
+| `/usage anthropic` | Alias for `/usage claude` |
+| `r` | Fetch a fresh snapshot |
+| Up / Down | Scroll |
+| Page Up / Page Down | Scroll a page |
+| Enter / Escape / `q` | Close; cancel pending work |
+
+The terminal view is an overlay. RPC clients receive the same information as a notification; run the command again to refresh. Print/JSON mode has no account-usage UI. Nothing is sent to the model or appended to session history.
+
+The view includes:
+
+- Account identity when available, plan when reported, credential source, and fetch time.
+- OpenAI usage windows returned by the server, including five-hour, weekly, and additional model limits when present.
+- Claude's **Current session (5h)**, **Current week (all models)**, and **Current week (Fable)**, plus other model-specific weekly limits when reported.
+- Local reset date/time and a relative duration.
+- Credit balance or unlimited-credit status when reported. Balances are not assumed to be dollars.
+- Links to [ChatGPT Settings → Usage](https://chatgpt.com/settings/usage) and [Claude Settings → Usage](https://claude.ai/settings/usage).
+
+Primary does **not** necessarily mean five-hour: some plans only report a weekly window. Labels follow the server's window duration. Missing/null values are shown as unknown, not zero usage or unlimited allowance. Expired reset timestamps prompt a refresh rather than inventing a replenished quota. Failed refreshes clear the previous snapshot.
+
+Requests happen only when opening or refreshing the view, with no extension background polling or retry loop. Claude Code manages its own authentication/network behavior. A 15-second overall timeout bounds the wait, including auth resolution and SDK startup; closing the view cancels the usage request or SDK process. Pi may finish its own already-started credential refresh independently. One failed provider does not suppress other providers.
+
+Claude's model-specific weekly limits are read from the SDK's `model_scoped` rows or the endpoint's `limits[]` rows—not an assumed `seven_day_fable` field. Missing Fable data remains **Not reported**, never 0% used. App/surface-specific caps and local behavior estimates are deliberately excluded.
+
+## Implementation and extension points
+
+```text
+index.ts                 Command registration and mode handling
+src/types.ts             Provider-neutral snapshots, windows, groups and errors
+src/service.ts           Independent provider collection, cancellation and timeouts
+src/providers/index.ts   Adapter registration
+src/providers/openai.ts  Pi auth + Codex usage adapter and normalization
+src/providers/claude.ts  Claude auth selection + native Pi OAuth HTTP adapter
+src/providers/claude-code.ts  Claude Agent SDK usage-only connection
+src/providers/claude-normalize.ts  Native/SDK quota normalization
+src/format.ts            Shared text presentation
+src/view.ts              Pi TUI overlay, refresh and scrolling
+```
+
+To add a provider:
+
+1. Implement `UsageProvider` from `src/types.ts`.
+2. Resolve credentials through Pi or the provider's own SDK and return a normalized `UsageSnapshot`. Set a window's `display: "used"` for Claude-style bars; the default is percent remaining.
+3. Use `UsageError` for safe, actionable error messages. Never include tokens, raw auth errors, or response bodies.
+4. Add the adapter to `createUsageProviders()` in `src/providers/index.ts` and add fixture-based tests.
+
+No changes to the command or view should be needed. Other extensions are not dynamically discovered as usage plugins in this first version.
+
+### SDKs and endpoint stability
+
+- **Pi SDK:** provider authentication and refresh; commands and UI.
+- **OpenAI and Anthropic JavaScript SDKs:** HTTP transport, error classification, timeouts and cancellation.
+- **Claude Agent SDK:** Claude Code credential management and the structured usage control request. Version **0.3.310 is pinned** because `usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET()` is explicitly experimental; the integration is isolated in one file.
+- **jose:** decode account claims for routing/display (the server validates the bearer token).
+- **Zod:** validate and normalize the usage response.
+
+The direct adapters use the API SDKs' generic `get()` methods: OpenAI reads `GET https://chatgpt.com/backend-api/wham/usage`, as used by [Codex's backend client](https://github.com/openai/codex/tree/main/codex-rs/backend-client); native Anthropic OAuth reads `GET https://api.anthropic.com/api/oauth/usage` with `anthropic-beta: oauth-2025-04-20`. An optional `/api/oauth/profile` request supplies native Claude account identity. These are **not stable public billing APIs** and may change. The Claude Code path uses the Agent SDK control API instead of duplicating its auth/storage integration.
+
+The direct adapters send credentials only to fixed provider endpoints; redirects and SDK logging are disabled. Account metadata is escaped for terminal display. The extension writes no token or usage cache. Pi and Claude Code may update their own original credential stores during refresh.
+
+## Develop
+
+Run from the repository root:
+
+```sh
+npm install --ignore-scripts
+npm run check --workspace @nothumanwork/pi-usage
+npm test --workspace @nothumanwork/pi-usage
+npm pack --workspace @nothumanwork/pi-usage --dry-run
+```
+
+Automated tests mock the network, credentials, and Claude Code process. They exercise the real API SDK transports and Pi extension loader, and cover both Claude auth paths, native/SDK quota schemas, account selection, used/remaining bars, errors, cancellation and process cleanup, multiple providers, narrow terminals, refresh, and scrolling. They do not make model requests or access a real account. Claude Code's usage-only SDK path has also been smoke-tested locally against a real subscription without any model requests.

package/index.ts

@@ -0,0 +1,58 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatUsage } from "./src/format.ts";
+import { createUsageProviders } from "./src/providers/index.ts";
+import { collectUsage } from "./src/service.ts";
+import type { UsageProvider } from "./src/types.ts";
+import { UsageView } from "./src/view.ts";
+
+export function registerUsage(pi: ExtensionAPI, providers: readonly UsageProvider[]): void {
+  let active: AbortController | undefined;
+  pi.on("session_shutdown", () => active?.abort());
+
+  pi.registerCommand("usage", {
+    description: "Show account usage limits and reset times (/usage [provider])",
+    getArgumentCompletions: (prefix) => providers
+      .filter((provider) => provider.id.startsWith(prefix.toLowerCase()))
+      .map((provider) => ({ value: provider.id, label: provider.label })),
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/usage requires interactive Pi or an RPC client with notifications.", "warning");
+        return;
+      }
+      const id = args.trim().toLowerCase();
+      const selected = id ? providers.filter((provider) => provider.id === id || provider.aliases?.includes(id)) : providers;
+      if (!selected.length) {
+        ctx.ui.notify(`Usage: /usage [${providers.map((provider) => provider.id).join("|")}]`, "warning");
+        return;
+      }
+      if (active) {
+        ctx.ui.notify("An account usage view is already open.", "info");
+        return;
+      }
+      const controller = new AbortController();
+      active = controller;
+      try {
+        if (ctx.mode === "tui") {
+          await ctx.ui.custom<void>((tui, theme, keys, done) => {
+            const view = new UsageView(tui, theme, keys, () => done(), (signal) =>
+              collectUsage(selected, ctx.modelRegistry, AbortSignal.any([signal, controller.signal]), { activeProvider: ctx.model?.provider }));
+            controller.signal.addEventListener("abort", () => view.close(), { once: true });
+            return view;
+          }, { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%" } });
+        } else {
+          const results = await collectUsage(selected, ctx.modelRegistry, controller.signal, { activeProvider: ctx.model?.provider });
+          if (!controller.signal.aborted) ctx.ui.notify(formatUsage(results), "info");
+        }
+      } catch {
+        if (!controller.signal.aborted) ctx.ui.notify("Could not display account usage. Try /usage again.", "error");
+      } finally {
+        controller.abort();
+        if (active === controller) active = undefined;
+      }
+    },
+  });
+}
+
+export default function usageExtension(pi: ExtensionAPI): void {
+  registerUsage(pi, createUsageProviders());
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@nothumanwork/pi-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "OpenAI ChatGPT and Claude subscription usage limits and reset times in Pi",
+  "keywords": [
+    "pi-package"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thehumanworks/pi-extensions.git",
+    "directory": "pi-usage"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.310",
+    "@anthropic-ai/sdk": "^1.3.0",
+    "jose": "^6.2.14",
+    "openai": "^7.19.0",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "^22.19.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/format.ts

@@ -0,0 +1,67 @@
+import { stripVTControlCharacters } from "node:util";
+import type { UsageResult, UsageWindow } from "./types.ts";
+
+/** Provider labels and account metadata are data, not terminal control sequences. */
+export function safeText(value: string): string {
+  return stripVTControlCharacters(value)
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, " ")
+    .slice(0, 240);
+}
+
+export function formatReset(resetsAt: number | undefined, now: number): string {
+  if (resetsAt === undefined) return "Reset time not reported";
+  if (resetsAt <= now) return "Reset time passed — refresh to update";
+  const minutes = Math.max(1, Math.ceil((resetsAt - now) / 60_000));
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor((minutes % 1440) / 60);
+  const mins = minutes % 60;
+  const relative = [days ? `${days}d` : "", hours ? `${hours}h` : "", mins ? `${mins}m` : ""].filter(Boolean).join(" ");
+  const date = new Date(resetsAt).toLocaleString(undefined, { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", timeZoneName: "short" });
+  return `Resets in ${relative} · ${date}`;
+}
+
+export function formatWindow(window: UsageWindow, now: number): string[] {
+  const label = safeText(window.label);
+  if (window.remainingPercent === undefined) return [`${label}: Not reported`, `  ${formatReset(window.resetsAt, now)}`];
+  const left = Math.max(0, Math.min(100, window.remainingPercent));
+  const percent = window.display === "used" ? 100 - left : left;
+  const filled = Math.round(percent / 5);
+  const bar = "█".repeat(filled) + "░".repeat(20 - filled);
+  return [
+    `${label}: [${bar}] ${Math.round(percent * 10) / 10}% ${window.display === "used" ? "used" : "left"}`,
+    `  ${formatReset(window.resetsAt, now)}`,
+  ];
+}
+
+export function formatUsage(results: readonly UsageResult[], now = Date.now()): string {
+  return results.map((result) => {
+    const lines = [safeText(result.provider.label)];
+    if (result.status !== "ok") {
+      lines.push(`${result.status === "unavailable" ? "Unavailable" : "Error"}: ${safeText(result.message)}`);
+    } else {
+      const data = result.snapshot;
+      lines.push(`Account: ${safeText(data.account)}`);
+      if (data.plan) lines.push(`Plan: ${safeText(data.plan)}`);
+      lines.push(`Source: ${safeText(data.source)}`);
+      lines.push(`Checked: ${new Date(data.fetchedAt).toLocaleString()}`);
+      if (!data.groups.length) lines.push("", "No allowance windows reported (not necessarily unlimited).");
+      for (const group of data.groups) {
+        lines.push("", safeText(group.label));
+        if (group.limitReached) lines.push("Limit reached / usage currently restricted");
+        if (!group.windows.length) lines.push("No allowance windows reported (not necessarily unlimited).");
+        for (const window of group.windows) lines.push(...formatWindow(window, now));
+      }
+      if (data.credits) {
+        const credits = data.credits;
+        const balance = credits.unlimited ? "Unlimited"
+          : credits.balance != null ? safeText(credits.balance)
+          : credits.hasCredits === false ? "None"
+          : credits.hasCredits === true ? "Available (balance not reported)" : "Not reported";
+        lines.push("", `Credits: ${balance}`);
+      }
+      lines.push("", ...data.notes.map(safeText));
+    }
+    lines.push(`Manage usage: ${safeText(result.provider.dashboardUrl)}`);
+    return lines.join("\n");
+  }).join("\n\n────────────────────────────────────────\n\n");
+}

package/src/providers/claude-code.ts

@@ -0,0 +1,96 @@
+import type { AccountInfo, Options, Query, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { UsageError, type UsageSnapshot } from "../types.ts";
+import { normalizeClaudeUsage } from "./claude-normalize.ts";
+
+const USAGE_METHOD = "usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET";
+export const CLAUDE_CODE_LOGIN_HINT = "Sign in with Claude Code (claude auth login), then retry /usage claude.";
+type UsageSession = Pick<Query, "accountInfo" | typeof USAGE_METHOD | "close">;
+export type StartUsageSession = (params: { prompt: AsyncIterable<SDKUserMessage>; options: Options }) => UsageSession;
+
+/** Inspect the subscription, not API billing or a gateway. Preserve Code's
+ * CLAUDE_CONFIG_DIR and explicit OAuth token; never substitute another account. */
+export function claudeUsageEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const child = { ...env };
+  for (const key of Object.keys(child)) {
+    if (key.startsWith("ANTHROPIC_") || key.startsWith("CLAUDE_CODE_USE_")) delete child[key];
+  }
+  return { ...child, ENABLE_CLAUDEAI_MCP_SERVERS: "0", DISABLE_TELEMETRY: "1", DISABLE_ERROR_REPORTING: "1" };
+}
+
+/** Keep stdin open for SDK control requests without ever submitting a prompt. */
+async function* noPrompts(signal: AbortSignal): AsyncGenerator<SDKUserMessage> {
+  if (!signal.aborted) await new Promise<void>((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+
+export async function fetchClaudeCodeUsage(signal: AbortSignal, options: {
+  start?: StartUsageSession;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+} = {}): Promise<UsageSnapshot> {
+  signal.throwIfAborted();
+  const controller = new AbortController();
+  let session: UsageSession | undefined;
+  let cwd: string | undefined;
+  let closed = false;
+  const stop = () => {
+    controller.abort();
+    if (session && !closed) {
+      closed = true;
+      try { session.close(); } catch { /* No raw SDK errors in logs/UI. */ }
+    }
+  };
+  signal.addEventListener("abort", stop, { once: true });
+  try {
+    // Root entry inlines its runtime dependencies. /core needs extra MCP peers.
+    // Pin this SDK version because the structured usage method is experimental.
+    const start: StartUsageSession = options.start ?? (await import("@anthropic-ai/claude-agent-sdk")).query;
+    signal.throwIfAborted();
+    cwd = await mkdtemp(join(tmpdir(), "pi-usage-claude-"));
+    signal.throwIfAborted();
+    session = start({
+      prompt: noPrompts(controller.signal),
+      options: {
+        cwd,
+        env: claudeUsageEnvironment(options.env ?? process.env),
+        abortController: controller,
+        persistSession: false,
+        settingSources: [],
+        settings: { disableAllHooks: true, autoMemoryEnabled: false },
+        tools: [],
+        mcpServers: {},
+        strictMcpConfig: true,
+        permissionMode: "dontAsk",
+        stderr: () => {},
+      },
+    });
+    const account: AccountInfo = await session.accountInfo();
+    signal.throwIfAborted();
+    if (account.apiProvider && account.apiProvider !== "firstParty") {
+      throw new UsageError(`Claude Code is not using a Claude subscription. ${CLAUDE_CODE_LOGIN_HINT}`, "unavailable");
+    }
+    const report = await session[USAGE_METHOD]({ skipBehaviors: true });
+    signal.throwIfAborted();
+    if (!report.rate_limits_available) {
+      throw new UsageError(`Claude subscription usage needs a login with profile access, not an API key or inference-only setup token. ${CLAUDE_CODE_LOGIN_HINT}`, "unavailable");
+    }
+    if (!report.rate_limits) {
+      throw new UsageError("Claude Code could not retrieve subscription limits. Check Claude Code /usage and try again later.");
+    }
+    return normalizeClaudeUsage(report.rate_limits, {
+      account: account.email || "Claude Code subscription (identity not reported)",
+      plan: report.subscription_type ?? account.subscriptionType,
+      source: "Claude Code login (Agent SDK; also used by pi-claude-bridge)",
+    }, options.now?.() ?? Date.now());
+  } catch (error) {
+    if (signal.aborted) throw signal.reason;
+    if (error instanceof UsageError) throw error;
+    throw new UsageError(`Could not read usage through the Claude Agent SDK. Ensure its optional platform package is installed. ${CLAUDE_CODE_LOGIN_HINT}`);
+  } finally {
+    signal.removeEventListener("abort", stop);
+    stop();
+    if (cwd) await rm(cwd, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/providers/claude-normalize.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { UsageError, type UsageSnapshot, type UsageWindow } from "../types.ts";
+
+const percent = z.number().finite().nonnegative().nullish();
+const windowSchema = z.object({ utilization: percent, resets_at: z.string().nullish() });
+const modelSchema = z.object({ display_name: z.string().min(1) });
+const payloadSchema = z.object({
+  five_hour: windowSchema.nullish(),
+  seven_day: windowSchema.nullish(),
+  seven_day_opus: windowSchema.nullish(),
+  seven_day_sonnet: windowSchema.nullish(),
+  // Claude Agent SDK get_usage normalizes the model rows into this field.
+  model_scoped: z.array(windowSchema.extend({ display_name: z.string().min(1) })).nullish(),
+  // Native Pi OAuth uses the endpoint directly. Fable lives here, NOT in an
+  // assumed seven_day_fable field. is_active is a headline pick, not a filter.
+  limits: z.array(z.object({
+    kind: z.string(),
+    percent,
+    resets_at: z.string().nullish(),
+    scope: z.object({ model: modelSchema.nullish(), surface: modelSchema.nullish() }).nullish(),
+  })).nullish(),
+}).refine((data) => Object.values(data).some((value) => value !== undefined));
+
+export interface ClaudeIdentity { account: string; plan?: string; source: string }
+
+function toWindow(label: string, value?: z.infer<typeof windowSchema> | null): UsageWindow {
+  // Invalid/absent reset times stay unknown. Never use OAuth expiry as a reset.
+  const validTime = z.iso.datetime({ offset: true }).safeParse(value?.resets_at);
+  const reset = validTime.success ? Date.parse(validTime.data) : NaN;
+  return {
+    label,
+    display: "used",
+    remainingPercent: value?.utilization == null ? undefined : Math.max(0, 100 - value.utilization),
+    resetsAt: Number.isFinite(reset) ? reset : undefined,
+  };
+}
+
+export function normalizeClaudeUsage(payload: unknown, identity: ClaudeIdentity, now = Date.now()): UsageSnapshot {
+  const parsed = payloadSchema.safeParse(payload);
+  if (!parsed.success) throw new UsageError("Claude returned an unrecognized usage response. Check Claude Code /usage or the usage dashboard.");
+  const data = parsed.data;
+  let session = data.five_hour;
+  let weekly = data.seven_day;
+  const models = new Map<string, { name: string; window: z.infer<typeof windowSchema> }>();
+  const addModel = (name: string, window: z.infer<typeof windowSchema>) => {
+    const key = name.trim().toLowerCase();
+    if (key && !models.has(key)) models.set(key, { name: name.trim(), window });
+  };
+  if (data.seven_day_opus) addModel("Opus", data.seven_day_opus);
+  if (data.seven_day_sonnet) addModel("Sonnet", data.seven_day_sonnet);
+  for (const model of data.model_scoped ?? []) addModel(model.display_name, model);
+  for (const limit of data.limits ?? []) {
+    const value = { utilization: limit.percent, resets_at: limit.resets_at };
+    if (limit.kind === "session" && !limit.scope?.model && !limit.scope?.surface) session ??= value;
+    if (limit.kind === "weekly_all" && !limit.scope?.model && !limit.scope?.surface) weekly ??= value;
+    if (limit.kind === "weekly_scoped" && limit.scope?.model && !limit.scope.surface) {
+      addModel(limit.scope.model.display_name, value);
+    }
+  }
+  const windows = [toWindow("Current session (5h)", session), toWindow("Current week (all models)", weekly)];
+  // Always expose the three requested buckets. A missing Fable row is unknown,
+  // not 0% used; extra plan-dependent model buckets follow it.
+  const fable = models.get("fable");
+  windows.push(toWindow("Current week (Fable)", fable?.window));
+  for (const [key, model] of models) {
+    if (key !== "fable") windows.push(toWindow(`Current week (${model.name})`, model.window));
+  }
+  return {
+    ...identity,
+    fetchedAt: now,
+    groups: [{ label: "Subscription allowance", windows, limitReached: windows.some((window) => window.remainingPercent === 0) }],
+    notes: ["Claude subscription usage, not this Pi session's token totals. App-specific caps are not included."],
+  };
+}

package/src/providers/claude.ts

@@ -0,0 +1,82 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { z } from "zod";
+import { UsageError, type AuthRegistry, type UsageProvider, type UsageSnapshot } from "../types.ts";
+import { fetchClaudeCodeUsage } from "./claude-code.ts";
+import { normalizeClaudeUsage } from "./claude-normalize.ts";
+
+const BASE_URL = "https://api.anthropic.com";
+const PI_LOGIN_HINT = "Run /login anthropic and choose the Claude subscription login, then retry /usage claude.";
+
+async function piToken(registry: AuthRegistry): Promise<string | undefined> {
+  if (!registry.getProvider("anthropic")) return undefined;
+  let auth;
+  try { auth = await registry.getProviderAuth("anthropic"); }
+  catch { throw new UsageError(`Could not refresh Pi's Anthropic login. ${PI_LOGIN_HINT}`); }
+  // API keys are not subscription credentials. Never resolve bridge's dummy key.
+  if (auth?.source !== "OAuth") return undefined;
+  if (!auth.auth.apiKey) throw new UsageError(`Pi's Anthropic OAuth login is incomplete. ${PI_LOGIN_HINT}`);
+  return auth.auth.apiKey;
+}
+
+async function fetchPiUsage(token: string, signal: AbortSignal, options: { fetch?: typeof globalThis.fetch; now?: () => number }): Promise<UsageSnapshot> {
+  const client = new Anthropic({
+    apiKey: null,
+    authToken: token,
+    baseURL: BASE_URL,
+    logLevel: "off",
+    maxRetries: 0,
+    timeout: 12_000,
+    fetch: options.fetch,
+    fetchOptions: { redirect: "error" },
+    defaultHeaders: { "anthropic-beta": "oauth-2025-04-20" },
+  });
+  let payload: unknown;
+  try {
+    // There is no generated subscription-quota method in the API SDK. Pi owns
+    // OAuth storage and refresh; the official SDK owns HTTP transport.
+    payload = await client.get<unknown>("/api/oauth/usage", { signal });
+  } catch (error) {
+    if (signal.aborted) throw signal.reason;
+    if (error instanceof Anthropic.APIError) {
+      if (error.status === 401) throw new UsageError(`Pi's Anthropic login was rejected. ${PI_LOGIN_HINT}`);
+      if (error.status === 403) throw new UsageError(`Claude usage needs subscription/profile permission. ${PI_LOGIN_HINT}`);
+      if (error.status === 429) throw new UsageError("Claude throttled the usage check. Wait before refreshing; this does not mean your subscription allowance is empty.");
+      if (error.status && error.status >= 500) throw new UsageError("Claude usage is temporarily unavailable. Try again later.");
+    }
+    if (error instanceof Anthropic.APIConnectionTimeoutError) throw new UsageError("Claude usage request timed out. Try again.");
+    throw new UsageError("Could not retrieve Claude usage. Check your connection or the usage dashboard.");
+  }
+  // Identity is supplementary: a profile failure must not hide known quotas.
+  // This uses the very same token, never account data from another login store.
+  const profile = await client.get<unknown>("/api/oauth/profile", { signal, timeout: 2_000 }).catch(() => undefined);
+  signal.throwIfAborted();
+  const parsed = z.object({ account: z.object({ email: z.string().min(1) }) }).safeParse(profile);
+  return normalizeClaudeUsage(payload, {
+    account: parsed.success ? parsed.data.account.email : "Pi Anthropic subscription (identity not reported)",
+    source: "Pi Anthropic OAuth login",
+  }, options.now?.() ?? Date.now());
+}
+
+export function createClaudeProvider(options: {
+  fetch?: typeof globalThis.fetch;
+  now?: () => number;
+  readCodeUsage?: (signal: AbortSignal) => Promise<UsageSnapshot>;
+} = {}): UsageProvider {
+  return {
+    id: "claude",
+    aliases: ["anthropic"],
+    label: "Anthropic · Claude",
+    dashboardUrl: "https://claude.ai/settings/usage",
+    async fetch({ registry, signal, activeProvider }) {
+      signal.throwIfAborted();
+      const readCode = options.readCodeUsage ?? ((signal) => fetchClaudeCodeUsage(signal, { now: options.now }));
+      // If both accounts exist, follow the selected bridge rather than silently
+      // showing a potentially different native Anthropic account. A chosen
+      // source failing is an error, not permission to switch accounts.
+      if (activeProvider === "claude-bridge") return readCode(signal);
+      const token = await piToken(registry);
+      signal.throwIfAborted();
+      return token ? fetchPiUsage(token, signal, options) : readCode(signal);
+    },
+  };
+}

package/src/providers/index.ts

@@ -0,0 +1,8 @@
+import type { UsageProvider } from "../types.ts";
+import { createOpenAIProvider } from "./openai.ts";
+import { createClaudeProvider } from "./claude.ts";
+
+// Add an adapter here; commands, collection, and rendering remain provider-neutral.
+export function createUsageProviders(): UsageProvider[] {
+  return [createOpenAIProvider(), createClaudeProvider()];
+}

package/src/providers/openai.ts

@@ -0,0 +1,181 @@
+import { decodeJwt } from "jose";
+import OpenAI from "openai";
+import { z } from "zod";
+import { UsageError, type AuthRegistry, type UsageGroup, type UsageProvider, type UsageSnapshot, type UsageWindow } from "../types.ts";
+
+export const CODEX_PROVIDER = "openai-codex";
+export const USAGE_BASE_URL = "https://chatgpt.com/backend-api";
+export const LOGIN_HINT = "Run /login openai-codex and choose the same ChatGPT account as your OpenAI login. Your inference login is unchanged.";
+
+const nonnegative = z.number().finite().nonnegative();
+const timestamp = nonnegative.max(8_640_000_000_000);
+const windowSchema = z.object({
+  used_percent: nonnegative.nullish(),
+  limit_window_seconds: nonnegative.nullish(),
+  reset_at: timestamp.nullish(),
+  reset_after_seconds: nonnegative.nullish(),
+});
+const limitSchema = z.object({
+  allowed: z.boolean().nullish(),
+  limit_reached: z.boolean().nullish(),
+  primary_window: windowSchema.nullish(),
+  secondary_window: windowSchema.nullish(),
+});
+
+// Codex's backend-client/OpenAPI models are the wire-contract reference. This is
+// an internal endpoint, not the public OpenAI organization/billing usage API.
+// Unknown fields are ignored; missing/null quotas stay unknown, never 0% used.
+const payloadSchema = z.object({
+  plan_type: z.string().min(1),
+  account_id: z.string().nullish(),
+  email: z.string().nullish(),
+  rate_limit: limitSchema.nullish(),
+  code_review_rate_limit: limitSchema.nullish(),
+  additional_rate_limits: z.array(z.object({
+    limit_name: z.string(),
+    metered_feature: z.string(),
+    rate_limit: limitSchema.nullish(),
+  })).nullish(),
+  credits: z.object({
+    has_credits: z.boolean().nullish(),
+    unlimited: z.boolean().nullish(),
+    balance: z.string().nullish(),
+    overage_limit_reached: z.boolean().nullish(),
+  }).nullish(),
+  spend_control: z.object({ reached: z.boolean().nullish() }).nullish(),
+});
+
+export interface CodexAccount { accessToken: string; accountId: string; email?: string }
+
+/** Decode only for account routing/display; OpenAI validates the token itself. */
+export function accountFromToken(accessToken: string): CodexAccount | undefined {
+  try {
+    const claims = decodeJwt(accessToken);
+    const auth = z.object({ chatgpt_account_id: z.string().regex(/^[\w-]+$/) })
+      .safeParse(claims["https://api.openai.com/auth"]);
+    if (!auth.success) return undefined;
+    const profile = z.object({ email: z.string().optional() })
+      .safeParse(claims["https://api.openai.com/profile"]);
+    return {
+      accessToken,
+      accountId: auth.data.chatgpt_account_id,
+      email: profile.success ? profile.data.email : undefined,
+    };
+  } catch { return undefined; }
+}
+
+export async function getCodexAccount(registry: AuthRegistry): Promise<CodexAccount> {
+  if (!registry.getProvider(CODEX_PROVIDER)) {
+    throw new UsageError(`This Pi build has no Codex login provider. ${LOGIN_HINT}`, "unavailable");
+  }
+  let result;
+  try { result = await registry.getProviderAuth(CODEX_PROVIDER); }
+  catch { throw new UsageError(`Could not refresh the Codex login. ${LOGIN_HINT}`); }
+  // Do not use API keys, the new SIWC token, ~/.codex/auth.json, or browser cookies.
+  if (result?.source !== "OAuth" || !result.auth.apiKey) {
+    throw new UsageError(`A Codex ChatGPT login is needed to read account limits. ${LOGIN_HINT}`, "unavailable");
+  }
+  const account = accountFromToken(result.auth.apiKey);
+  if (!account) throw new UsageError(`The Codex login has no usable ChatGPT account. ${LOGIN_HINT}`);
+  return account;
+}
+
+export function windowLabel(seconds: number | null | undefined, fallback: string): string {
+  if (!seconds) return fallback;
+  if (seconds === 604800) return "Weekly limit";
+  if (seconds % 86400 === 0) return `${seconds / 86400} day limit`;
+  if (seconds % 3600 === 0) return `${seconds / 3600} hour limit`;
+  if (seconds % 60 === 0) return `${seconds / 60} minute limit`;
+  return `${seconds} second limit`;
+}
+
+function normalizeWindow(window: z.infer<typeof windowSchema>, fallback: string, now: number): UsageWindow {
+  const reset = window.reset_at != null ? window.reset_at * 1000
+    : window.reset_after_seconds != null ? now + window.reset_after_seconds * 1000 : undefined;
+  return {
+    label: windowLabel(window.limit_window_seconds, fallback),
+    remainingPercent: window.used_percent == null ? undefined : Math.max(0, 100 - window.used_percent),
+    resetsAt: reset !== undefined && Number.isFinite(reset) && reset <= 8_640_000_000_000_000 ? reset : undefined,
+  };
+}
+
+function normalizeGroup(label: string, limit: z.infer<typeof limitSchema>, now: number): UsageGroup {
+  const windows: UsageWindow[] = [];
+  if (limit.primary_window) windows.push(normalizeWindow(limit.primary_window, "Primary limit", now));
+  if (limit.secondary_window) windows.push(normalizeWindow(limit.secondary_window, "Secondary limit", now));
+  return { label, windows, limitReached: limit.limit_reached === true || limit.allowed === false };
+}
+
+export function normalizeUsage(payload: unknown, account: CodexAccount, now = Date.now()): UsageSnapshot {
+  const parsed = payloadSchema.safeParse(payload);
+  if (!parsed.success) throw new UsageError("OpenAI returned an unrecognized usage response. Check the usage dashboard; the Codex endpoint may have changed.");
+  const data = parsed.data;
+  if (data.account_id && data.account_id !== account.accountId) {
+    throw new UsageError("OpenAI returned usage for a different account. No usage is displayed; check your Codex login.");
+  }
+  const groups: UsageGroup[] = [];
+  if (data.rate_limit) groups.push(normalizeGroup("Account allowance", data.rate_limit, now));
+  for (const extra of data.additional_rate_limits ?? []) {
+    if (extra.rate_limit) groups.push(normalizeGroup(extra.limit_name || extra.metered_feature, extra.rate_limit, now));
+  }
+  if (data.code_review_rate_limit) groups.push(normalizeGroup("Code review", data.code_review_rate_limit, now));
+  const email = data.email || account.email;
+  const notes = ["Account allowance via Codex; Pi-specific app caps are not included."];
+  if (data.spend_control?.reached) notes.push("An account/workspace spending limit has been reached.");
+  if (data.credits?.overage_limit_reached) notes.push("The credit overage limit has been reached.");
+  return {
+    account: email ? `${email} (${account.accountId})` : account.accountId,
+    plan: data.plan_type,
+    source: "Codex login (openai-codex)",
+    fetchedAt: now,
+    groups,
+    credits: data.credits ? {
+      unlimited: data.credits.unlimited ?? undefined,
+      hasCredits: data.credits.has_credits ?? undefined,
+      balance: data.credits.balance ?? undefined,
+    } : undefined,
+    notes,
+  };
+}
+
+export function createOpenAIProvider(options: { fetch?: typeof globalThis.fetch; now?: () => number } = {}): UsageProvider {
+  return {
+    id: "openai",
+    label: "OpenAI · ChatGPT",
+    dashboardUrl: "https://chatgpt.com/settings/usage",
+    async fetch({ registry, signal }) {
+      const account = await getCodexAccount(registry);
+      signal.throwIfAborted();
+      const client = new OpenAI({
+        apiKey: account.accessToken,
+        baseURL: USAGE_BASE_URL,
+        // Never pick up OPENAI_ORG_ID/PROJECT_ID or log credentials/response bodies.
+        organization: null,
+        project: null,
+        logLevel: "off",
+        maxRetries: 0,
+        timeout: 12_000,
+        fetch: options.fetch,
+        fetchOptions: { redirect: "error" },
+        defaultHeaders: { "ChatGPT-Account-Id": account.accountId },
+      });
+      let payload: unknown;
+      try {
+        // The official SDK's generic request API handles transport and cancellation.
+        // There is no generated quota method in the JavaScript SDK.
+        payload = await client.get<unknown>("/wham/usage", { signal });
+      } catch (error) {
+        if (signal.aborted) throw signal.reason;
+        if (error instanceof OpenAI.APIError) {
+          if (error.status === 401) throw new UsageError(`The Codex login was rejected. ${LOGIN_HINT}`);
+          if (error.status === 403) throw new UsageError("OpenAI denied access to Codex usage. Check the account and usage dashboard.");
+          if (error.status === 429) throw new UsageError("OpenAI throttled the usage check. Try again later; this does not mean your plan allowance is empty.");
+          if (error.status && error.status >= 500) throw new UsageError("OpenAI usage is temporarily unavailable. Try again later.");
+        }
+        if (error instanceof OpenAI.APIConnectionTimeoutError) throw new UsageError("OpenAI usage request timed out. Try again.");
+        throw new UsageError("Could not retrieve OpenAI usage. Check your connection or the usage dashboard.");
+      }
+      return normalizeUsage(payload, account, options.now?.() ?? Date.now());
+    },
+  };
+}

package/src/service.ts

@@ -0,0 +1,38 @@
+import { UsageError, type AuthRegistry, type UsageProvider, type UsageResult } from "./types.ts";
+
+/** Pi owns auth refresh, which has no command AbortSignal in 1.4.0. Stop waiting
+ * on dismissal/timeout without interfering with its locked token rotation. */
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    if (signal.aborted) abort();
+  });
+}
+
+export async function collectUsage(
+  providers: readonly UsageProvider[],
+  registry: AuthRegistry,
+  signal: AbortSignal,
+  options: { timeoutMs?: number; activeProvider?: string } = {},
+): Promise<UsageResult[]> {
+  signal.throwIfAborted();
+  const results = await Promise.all(providers.map(async (adapter): Promise<UsageResult> => {
+    const provider = { id: adapter.id, label: adapter.label, dashboardUrl: adapter.dashboardUrl };
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? 15_000);
+    const combined = AbortSignal.any([signal, timeout]);
+    try {
+      const snapshot = await abortable(Promise.resolve().then(() => adapter.fetch({ registry, signal: combined, activeProvider: options.activeProvider })), combined);
+      return { provider, status: "ok", snapshot };
+    } catch (error) {
+      if (signal.aborted) throw signal.reason;
+      if (timeout.aborted) return { provider, status: "error", message: "Usage check timed out. Try refreshing." };
+      if (error instanceof UsageError) return { provider, status: error.status, message: error.message };
+      // A provider must opt into a safe message. Do not render raw request errors.
+      return { provider, status: "error", message: "Could not retrieve usage for this provider. Try refreshing or check its dashboard." };
+    }
+  }));
+  signal.throwIfAborted();
+  return results;
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type AuthRegistry = Pick<ExtensionContext["modelRegistry"], "getProviderAuth" | "getProvider">;
+
+/** Provider adapters own auth and wire formats; the view only knows these types. */
+export interface UsageWindow {
+  label: string;
+  remainingPercent?: number;
+  /** Default is remaining (Codex); Claude displays used like Claude Code. */
+  display?: "remaining" | "used";
+  resetsAt?: number; // Unix milliseconds, not credential expiry.
+}
+
+export interface UsageGroup {
+  label: string;
+  windows: UsageWindow[];
+  limitReached?: boolean;
+}
+
+export interface UsageSnapshot {
+  account: string;
+  plan?: string;
+  source: string;
+  fetchedAt: number;
+  groups: UsageGroup[];
+  credits?: { unlimited?: boolean; hasCredits?: boolean; balance?: string };
+  notes: string[];
+}
+
+export interface UsageProvider {
+  id: string;
+  label: string;
+  aliases?: readonly string[];
+  dashboardUrl: string;
+  fetch(context: { registry: AuthRegistry; signal: AbortSignal; activeProvider?: string }): Promise<UsageSnapshot>;
+}
+
+export type UsageResult = {
+  provider: Pick<UsageProvider, "id" | "label" | "dashboardUrl">;
+} & (
+  | { status: "ok"; snapshot: UsageSnapshot }
+  | { status: "unavailable" | "error"; message: string }
+);
+
+/** Only static, user-safe messages belong here. Never wrap raw SDK/auth errors. */
+export class UsageError extends Error {
+  constructor(message: string, public readonly status: "unavailable" | "error" = "error") {
+    super(message);
+    this.name = "UsageError";
+  }
+}

package/src/view.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, ScrollView, Text, truncateToWidth, type Component, type KeybindingsManager, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { formatUsage } from "./format.ts";
+import type { UsageResult } from "./types.ts";
+
+/** Built from Pi's layout, wrapping, scroll and input components, not another TUI. */
+export class UsageView implements Component {
+  private readonly heading: Text;
+  private readonly body: Text;
+  private readonly scroll: ScrollView;
+  private request?: AbortController;
+  private disposed = false;
+  private results?: UsageResult[];
+  private loading = true;
+  private failed = false;
+
+  constructor(
+    private readonly tui: Pick<TUI, "requestRender"> & { terminal?: { rows: number } },
+    private readonly theme: Pick<Theme, "fg" | "bold">,
+    private readonly keys: Pick<KeybindingsManager, "matches">,
+    private readonly done: () => void,
+    private readonly load: (signal: AbortSignal) => Promise<UsageResult[]>,
+  ) {
+    const heading = new Text("", 0, 0);
+    const body = new Text("", 0, 0);
+    const scroll = new ScrollView(body, { scrollbar: "hidden", overscroll: "contain" });
+    this.heading = heading;
+    this.body = body;
+    this.scroll = scroll;
+    this.refresh();
+  }
+
+  refresh(): void {
+    if (this.disposed || this.request) return;
+    const request = new AbortController();
+    this.request = request;
+    this.loading = true;
+    this.failed = false;
+    this.results = undefined; // Never leave an old account snapshot looking current.
+    this.scroll.scrollToStart();
+    this.update();
+    void Promise.resolve().then(() => this.load(request.signal)).then(
+      (results) => { if (!this.disposed && !request.signal.aborted) this.results = results; },
+      () => { if (!this.disposed && !request.signal.aborted) this.failed = true; },
+    ).finally(() => {
+      if (this.request === request) this.request = undefined;
+      if (!this.disposed) {
+        this.loading = false;
+        this.update();
+      }
+    });
+  }
+
+  private update(): void {
+    this.invalidate();
+    this.tui.requestRender();
+  }
+
+  invalidate(): void {
+    // Rebuild themed strings on invalidation, including palette changes.
+    this.heading?.setText(this.theme.bold(this.theme.fg("accent", "Account usage")));
+    this.body?.setText(this.loading ? this.theme.fg("muted", "Loading account usage…")
+      : this.failed ? this.theme.fg("error", "Could not load usage. Press r to retry.")
+      : formatUsage(this.results ?? []));
+    this.heading?.invalidate();
+    this.body?.invalidate();
+  }
+
+  render(width: number): string[] {
+    // Pi 1.4 overlays call render() directly in BOTH screen modes, bypassing the
+    // layout engine. Supply the viewport to ScrollView and clip here so neither
+    // the footer nor later providers disappear below the overlay's maxHeight.
+    const height = Math.max(1, Math.floor((this.tui.terminal?.rows ?? 24) * 0.85));
+    const heading = height >= 4 ? this.heading.render(width).slice(0, 1) : [];
+    const footer = height >= 2 ? [truncateToWidth("r refresh · ↑/↓ scroll · PgUp/PgDn · Enter/Esc close", width)] : [];
+    const gap = height >= 8 ? [""] : [];
+    const viewport = Math.max(1, height - heading.length - footer.length - 2 * gap.length);
+    const content = this.scroll.render(width);
+    this.scroll.updateLayout(content.length, viewport, () => this.tui.requestRender());
+    const visible = content.slice(this.scroll.scrollTop, this.scroll.scrollTop + viewport);
+    if (footer.length) {
+      const position = content.length > viewport ? `${this.scroll.scrollTop + 1}–${Math.min(content.length, this.scroll.scrollTop + viewport)}/${content.length} · ` : "";
+      footer[0] = truncateToWidth(this.theme.fg("dim", position + "r refresh · ↑/↓ scroll · PgUp/PgDn · Enter/Esc close"), width);
+    }
+    return [...heading, ...gap, ...visible, ...gap, ...footer];
+  }
+
+  handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined {
+    if (event.type !== "wheel") return;
+    this.scroll.scrollBy(event.wheelDelta ?? 0);
+    this.tui.requestRender();
+    return { handled: true };
+  }
+
+  handleInput(data: string): void {
+    if (this.disposed) return;
+    if (this.keys.matches(data, "tui.select.cancel") || this.keys.matches(data, "tui.select.confirm") || matchesKey(data, "q")) {
+      this.close();
+      return;
+    }
+    if (matchesKey(data, "r")) this.refresh();
+    else if (this.keys.matches(data, "tui.select.up")) this.scroll.scrollBy(-1);
+    else if (this.keys.matches(data, "tui.select.down")) this.scroll.scrollBy(1);
+    else if (matchesKey(data, Key.pageUp)) this.scroll.scrollBy(-Math.max(1, this.scroll.viewportHeight - 1));
+    else if (matchesKey(data, Key.pageDown)) this.scroll.scrollBy(Math.max(1, this.scroll.viewportHeight - 1));
+    else return;
+    this.tui.requestRender();
+  }
+
+  close(): void {
+    if (this.disposed) return;
+    this.dispose();
+    this.done();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.request?.abort();
+  }
+}