@nothumanwork/pi-usage 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,116 @@
-# 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.
+Account usage limits in Pi, starting with **OpenAI ChatGPT via the Codex login**.
+
+Run `/usage` for a scrollable view of the account, plan, percentage remaining, reset times, and credits reported by OpenAI. Bars fill with **remaining** allowance, as in Codex—not tokens consumed in the current Pi session.
+
+## 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
+```
+
+After publication:
+
+```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
+
+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 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.
+
+## Commands and controls
+
+| Command / key | Action |
+| --- | --- |
+| `/usage` | Fetch all supported providers |
+| `/usage openai` | Fetch only OpenAI |
+| `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:
+
+- Codex account identity, plan, source, and fetch time.
+- Usage windows returned by the server, including five-hour, weekly, and additional model limits when present.
+- Local reset date/time and a relative duration.
+- Credit balance or unlimited-credit status when reported. Balances are not assumed to be dollars.
+- A link to [ChatGPT Settings → Usage](https://chatgpt.com/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 automatic retries. A 15-second overall timeout bounds the wait, including auth resolution; closing the view cancels the usage request. Pi may finish its own already-started credential refresh independently. One failed provider does not suppress other providers.
+
+## 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/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 and return a normalized `UsageSnapshot`.
+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 JavaScript SDK:** HTTP transport, error classification, timeouts and cancellation.
+- **jose:** decode account claims for routing/display (the server validates the bearer token).
+- **Zod:** validate and normalize the usage response.
+
+The adapter uses the SDK's generic `get()` method because there is no typed JavaScript SDK quota method. It reads `GET https://chatgpt.com/backend-api/wham/usage`, the internal endpoint used by [Codex's backend client](https://github.com/openai/codex/tree/main/codex-rs/backend-client). This is **not a stable public billing API** and may change. The adapter is isolated for that reason.
+
+Credentials are sent only to the fixed ChatGPT endpoint. Redirects and SDK logging are disabled. Requests do not use API billing organization/project settings. Account metadata is escaped for terminal display. No token or usage cache is written to disk.
+
+## 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
+```
+
+Tests mock the network and credentials, exercise the real OpenAI SDK transport and Pi extension loader, and cover normalization, errors, cancellation, multiple providers, narrow terminals, refresh, and scrolling. They do not consume a ChatGPT allowance or verify a real account's live quota.

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) : 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])));
+            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);
+          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,50 @@
 {
   "name": "@nothumanwork/pi-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Account usage limits and reset times in Pi, starting with OpenAI ChatGPT via Codex login",
+  "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": {
+    "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,66 @@
+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 filled = Math.round(left / 5);
+  const bar = "█".repeat(filled) + "░".repeat(20 - filled);
+  return [
+    `${label}: [${bar}] ${Math.round(left * 10) / 10}% 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/index.ts

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

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,
+  timeoutMs = 15_000,
+): 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(timeoutMs);
+    const combined = AbortSignal.any([signal, timeout]);
+    try {
+      const snapshot = await abortable(Promise.resolve().then(() => adapter.fetch({ registry, signal: combined })), 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,48 @@
+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;
+  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;
+  dashboardUrl: string;
+  fetch(context: { registry: AuthRegistry; signal: AbortSignal }): 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();
+  }
+}