@hk_net/pi-usage-bars 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [0.3.0] - 2026-07-22
+
+### Breaking changes
+
+- Renamed the npm package to `@hk_net/pi-usage-bars`; install it with `pi install npm:@hk_net/pi-usage-bars`.
+- Updated the minimum supported Pi release to 0.81.1.
+- Removed Google Gemini CLI and Google Antigravity usage support, matching their removal from Pi 0.71.0.
+- Refactored core usage orchestration to accept resolved provider tokens instead of reading or refreshing Pi credentials directly.
+
+### Added
+
+- Added ZAI Coding Plan (China) provider and quota endpoint support.
+- Added abort-aware polling and provider requests.
+- Added strict TypeScript checking, a current-Pi smoke test, pinned development dependencies, and reproducible npm installs.
+- Added Pi package gallery image metadata and documented endpoint/security behavior.
+
+### Changed
+
+- Authentication now goes through `ctx.modelRegistry.getProviderAuth()`, allowing Pi to safely resolve and refresh credentials with its canonical locked credential store.
+- Renamed Z.AI to the current Pi labels, ZAI Coding Plan (Global) and ZAI Coding Plan (China).
+- Limited polling and custom `/usage` UI to interactive TUI mode.
+- Made startup and model-change polling non-blocking and added complete session shutdown cleanup.
+- Updated the selector to use typed TUI APIs, explicit render requests, abortable loading, and theme-safe invalidation.
+
+### Fixed
+
+- Fixed OAuth refresh failures on Pi 0.81.1 caused by the removed runtime `getOAuthApiKey` export.
+- Fixed potential credential races and permission changes caused by direct `auth.json` writes.
+- Fixed in-flight polling and selector requests surviving session shutdown or dialog disposal.
+
+## [0.2.3] - 2026-06-10
+
+### Fixed
+
+- **`DynamicBorder` is not defined** — added missing import of `DynamicBorder` from `@earendil-works/pi-coding-agent`. This fixes the `DynamicBorder is not defined` error when calling `/usage`.
+
+### Changed
+
+- Updated repository URLs from `ajarellanod` to `hknet` in `package.json` and `README.md`.
+- Updated README image URLs to point to the `hknet` repository.
+- Updated LICENSE copyright to `ajarellanod (secondary: hknet)`.
+
+### Removed
+
+- Removed stale tgz build artifacts and `package-lock.json` from the repository.
+- Removed `NOTE.md` compliance report (development artifact).
+
+## [0.2.2] - 2026-06-10
+
+### Fixed
+
+- **Keybinding violation in `UsageSelectorComponent`** — replaced `getKeybindings()` with the `keybindings` parameter injected by `ctx.ui.custom()`. Per the Pi extension docs, custom components must use the injected `KeybindingsManager` directly rather than calling `getKeybindings()` or `setKeybindings()`. This fixes a compliance issue that could cause unexpected behavior under custom keybinding configurations.

package/LICENSE

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

package/README.md

@@ -0,0 +1,91 @@
+# pi-usage-bars
+
+Subscription usage indicators for [Pi](https://github.com/earendil-works/pi).
+
+![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
+
+It adds:
+
+- a footer status bar for the active subscription provider
+- a `/usage` command showing every configured supported subscription
+
+## Supported providers
+
+| Provider | Pi provider ID | Authentication |
+| --- | --- | --- |
+| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
+| Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
+| ZAI Coding Plan (Global) | `zai` | ZAI API key |
+| ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
+
+Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
+
+## Requirements
+
+- Pi 0.81.1 or newer
+- Node.js 22.19 or newer when using the npm-distributed Pi CLI
+
+Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
+
+## Install
+
+Install the npm package:
+
+```bash
+pi install npm:@hk_net/pi-usage-bars
+```
+
+Or install the latest source directly from GitHub:
+
+```bash
+pi install https://github.com/hknet/pi-usage-bars
+```
+
+Restart Pi after installation, or use `/reload` when the package is already installed.
+
+## Use
+
+### Footer usage bars
+
+When the active model belongs to a configured supported provider, the footer shows session and weekly usage with reset countdowns when available.
+
+![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
+
+Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.
+
+### `/usage`
+
+Run `/usage` to open a searchable list of configured supported providers.
+
+![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
+
+## Endpoint configuration
+
+The ZAI monitoring endpoints can be overridden:
+
+| Variable | Default |
+| --- | --- |
+| `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
+| `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
+
+**Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
+
+The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
+
+## Development
+
+Install Node.js 22.19+ and Bun 1.3, then run:
+
+```bash
+npm install
+npm run check
+```
+
+`npm run check` performs a strict TypeScript check, runs the Bun test suite, and smoke-loads the extension with the pinned current Pi release.
+
+## Credits
+
+This extension is based on and inspired by:
+
+- [CodexBar](https://github.com/steipete/CodexBar)
+- [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)

package/extensions/usage-bars/core.ts

@@ -0,0 +1,653 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type ProviderKey = "codex" | "claude" | "zai" | "zai-cn";
+export type PiProviderId = "openai-codex" | "anthropic" | "zai" | "zai-coding-cn";
+
+export interface UsageData {
+  session: number;
+  weekly: number;
+  sessionResetsIn?: string;
+  weeklyResetsIn?: string;
+  sessionResetsAt?: string;
+  weeklyResetsAt?: string;
+  extraSpend?: number;
+  extraLimit?: number;
+  warning?: string;
+  stale?: boolean;
+  fetchedAt?: number;
+  error?: string;
+}
+
+export type UsageByProvider = Record<ProviderKey, UsageData | null>;
+export type UsageTokens = Partial<Record<ProviderKey, string>>;
+
+export interface UsageEndpoints {
+  zai: string;
+  zaiCn: string;
+}
+
+export interface HeadersLike {
+  get(name: string): string | null;
+}
+
+export interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  headers?: HeadersLike;
+  json(): Promise<unknown>;
+}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<FetchResponseLike>;
+
+export interface RequestConfig {
+  fetchFn?: FetchLike;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface FetchConfig extends RequestConfig {
+  endpoints?: UsageEndpoints;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface FetchAllUsagesConfig extends FetchConfig {
+  cacheFile?: string;
+  nowMs?: number;
+}
+
+export interface ClaudeUsageFetchConfig extends RequestConfig {
+  cacheFile?: string;
+  nowMs?: number;
+}
+
+interface JsonRequestSuccess {
+  ok: true;
+  data: unknown;
+  status: number;
+  headers?: HeadersLike;
+}
+
+interface JsonRequestError {
+  ok: false;
+  error: string;
+  status: number | null;
+  headers?: HeadersLike;
+}
+
+type JsonRequestResult = JsonRequestSuccess | JsonRequestError;
+
+interface ClaudeUsageAttemptResult {
+  usage: UsageData;
+  status: number | null;
+  retryAfterMs: number | null;
+}
+
+interface ClaudeUsageCacheState {
+  lastSuccess?: UsageData;
+  lastSuccessAt?: number;
+  cooldownUntil?: number;
+  consecutive429s?: number;
+  lastError?: string;
+}
+
+interface UsageBarsCacheFile {
+  version: 1;
+  claude?: ClaudeUsageCacheState;
+}
+
+const DEFAULT_FETCH_TIMEOUT_MS = 12_000;
+const CLAUDE_SHARED_FRESH_TTL_MS = 2 * 60 * 1000;
+const CLAUDE_BASE_BACKOFF_MS = 2 * 60 * 1000;
+const CLAUDE_MAX_BACKOFF_MS = 30 * 60 * 1000;
+const CLAUDE_LOCK_WAIT_MS = 4_000;
+const CLAUDE_LOCK_POLL_MS = 125;
+const CLAUDE_LOCK_STALE_MS = 20_000;
+
+export const DEFAULT_USAGE_CACHE_FILE = path.join(os.tmpdir(), "pi", "usage-bars-cache.json");
+export const DEFAULT_ZAI_USAGE_ENDPOINT = "https://api.z.ai/api/monitor/usage/quota/limit";
+export const DEFAULT_ZAI_CN_USAGE_ENDPOINT = "https://open.bigmodel.cn/api/monitor/usage/quota/limit";
+
+export function resolveUsageEndpoints(env: NodeJS.ProcessEnv = process.env): UsageEndpoints {
+  const configured = (value: string | undefined, fallback: string) => {
+    const trimmed = value?.trim();
+    return trimmed || fallback;
+  };
+
+  return {
+    zai: configured(env.PI_ZAI_USAGE_ENDPOINT, DEFAULT_ZAI_USAGE_ENDPOINT),
+    zaiCn: configured(env.PI_ZAI_CODING_CN_USAGE_ENDPOINT, DEFAULT_ZAI_CN_USAGE_ENDPOINT),
+  };
+}
+
+function toErrorMessage(error: unknown, externalSignal?: AbortSignal): string {
+  if (error instanceof Error) {
+    if (error.name === "AbortError") {
+      return externalSignal?.aborted ? "request cancelled" : "request timeout";
+    }
+    return error.message || String(error);
+  }
+  return String(error);
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") return null;
+  return value as Record<string, unknown>;
+}
+
+function normalizeUsagePair(session: number, weekly: number): { session: number; weekly: number } {
+  const clean = (value: number) => Number.isFinite(value) ? Number(value.toFixed(2)) : 0;
+  return { session: clean(session), weekly: clean(weekly) };
+}
+
+function getHeader(headers: HeadersLike | undefined, name: string): string | null {
+  if (!headers) return null;
+  try {
+    return headers.get(name);
+  } catch {
+    return null;
+  }
+}
+
+function combineSignals(timeoutSignal: AbortSignal | undefined, externalSignal: AbortSignal | undefined): AbortSignal | undefined {
+  if (timeoutSignal && externalSignal) return AbortSignal.any([timeoutSignal, externalSignal]);
+  return timeoutSignal ?? externalSignal;
+}
+
+async function requestJson(url: string, init: RequestInit, config: RequestConfig = {}): Promise<JsonRequestResult> {
+  const fetchFn = config.fetchFn ?? (fetch as unknown as FetchLike);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+  const timeoutController = timeoutMs > 0 ? new AbortController() : undefined;
+  const timeout = timeoutController
+    ? setTimeout(() => timeoutController.abort(), timeoutMs)
+    : undefined;
+  const signal = combineSignals(timeoutController?.signal, config.signal);
+
+  try {
+    if (config.signal?.aborted) {
+      return { ok: false, error: "request cancelled", status: null };
+    }
+
+    const response = await fetchFn(url, { ...init, signal });
+    if (!response.ok) {
+      return { ok: false, error: `HTTP ${response.status}`, status: response.status, headers: response.headers };
+    }
+
+    try {
+      return { ok: true, data: await response.json(), status: response.status, headers: response.headers };
+    } catch {
+      return { ok: false, error: "invalid JSON response", status: response.status, headers: response.headers };
+    }
+  } catch (error) {
+    return { ok: false, error: toErrorMessage(error, config.signal), status: null };
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
+export function formatDuration(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds <= 0) return "now";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  if (days > 0 && hours > 0) return `${days}d ${hours}h`;
+  if (days > 0) return `${days}d`;
+  if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
+  if (hours > 0) return `${hours}h`;
+  if (minutes > 0) return `${minutes}m`;
+  return "<1m";
+}
+
+export function formatResetsAt(isoDate: string, nowMs = Date.now()): string {
+  const resetTime = new Date(isoDate).getTime();
+  if (!Number.isFinite(resetTime)) return "";
+  return formatDuration(Math.max(0, resetTime - nowMs) / 1000);
+}
+
+export function parseRetryAfterMs(value: string | null | undefined, nowMs = Date.now()): number | null {
+  if (!value) return null;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric) && numeric >= 0) return numeric * 1000;
+  const dateMs = new Date(value).getTime();
+  return Number.isFinite(dateMs) ? Math.max(0, dateMs - nowMs) : null;
+}
+
+function readUsageCache(cacheFile = DEFAULT_USAGE_CACHE_FILE): UsageBarsCacheFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFile, "utf-8"));
+    if (parsed?.version === 1 && typeof parsed === "object") return parsed as UsageBarsCacheFile;
+  } catch {
+    // Invalid or missing caches are treated as empty.
+  }
+  return { version: 1 };
+}
+
+function writeUsageCache(cache: UsageBarsCacheFile, cacheFile = DEFAULT_USAGE_CACHE_FILE): boolean {
+  try {
+    const directory = path.dirname(cacheFile);
+    if (!fs.existsSync(directory)) fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporaryPath = `${cacheFile}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(temporaryPath, JSON.stringify(cache, null, 2), { mode: 0o600 });
+    fs.renameSync(temporaryPath, cacheFile);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new DOMException("Aborted", "AbortError"));
+    }, { once: true });
+  });
+}
+
+function ensureParentDir(filePath: string): void {
+  const directory = path.dirname(filePath);
+  if (!fs.existsSync(directory)) fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+}
+
+function safeUnlink(filePath: string): void {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // Ignore cleanup races.
+  }
+}
+
+async function acquireFileLock(lockFile: string, signal?: AbortSignal): Promise<(() => void) | null> {
+  ensureParentDir(lockFile);
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt <= CLAUDE_LOCK_WAIT_MS) {
+    if (signal?.aborted) return null;
+    try {
+      const fd = fs.openSync(lockFile, "wx", 0o600);
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+      fs.closeSync(fd);
+      return () => safeUnlink(lockFile);
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") return null;
+      try {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - stat.mtimeMs >= CLAUDE_LOCK_STALE_MS) {
+          safeUnlink(lockFile);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      try {
+        await sleep(CLAUDE_LOCK_POLL_MS, signal);
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function readPercentCandidate(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  if (value >= 0 && value <= 1) return Number.isInteger(value) ? value : value * 100;
+  return value >= 0 && value <= 100 ? value : null;
+}
+
+export function readLimitPercent(limit: unknown): number | null {
+  const value = asObject(limit);
+  const direct = [
+    value?.percentage,
+    value?.utilization,
+    value?.used_percent,
+    value?.usedPercent,
+    value?.usagePercent,
+    value?.usage_percent,
+  ].map(readPercentCandidate).find((candidate) => candidate !== null);
+  if (direct !== undefined) return direct;
+
+  const current = typeof value?.currentValue === "number" ? value.currentValue : null;
+  const remaining = typeof value?.remaining === "number" ? value.remaining : null;
+  if (current !== null && remaining !== null && current + remaining > 0) {
+    return (current / (current + remaining)) * 100;
+  }
+  return null;
+}
+
+export function extractUsageFromPayload(payload: unknown): { session: number; weekly: number } | null {
+  const data = payload as any;
+  const limitArrays = [data?.data?.limits, data?.limits, data?.quota?.limits, data?.data?.quota?.limits];
+  const limits = limitArrays.find(Array.isArray) as unknown[] | undefined;
+
+  if (limits) {
+    const byType = (types: string[]) => limits.find((entry) => {
+      const type = String((entry as any)?.type || "").toUpperCase();
+      return types.includes(type);
+    });
+    const session = readLimitPercent(byType(["TIME_LIMIT", "SESSION_LIMIT", "REQUEST_LIMIT", "RPM_LIMIT", "RPD_LIMIT"]));
+    const weekly = readLimitPercent(byType(["TOKENS_LIMIT", "TOKEN_LIMIT", "WEEK_LIMIT", "WEEKLY_LIMIT", "TPM_LIMIT", "DAILY_LIMIT"]));
+    if (session !== null && weekly !== null) return normalizeUsagePair(session, weekly);
+  }
+
+  const sessionCandidates = [
+    data?.session,
+    data?.sessionPercent,
+    data?.session_percent,
+    data?.five_hour?.utilization,
+    data?.rate_limit?.primary_window?.used_percent,
+    data?.limits?.session?.utilization,
+    data?.usage?.session,
+    data?.data?.session,
+    data?.data?.sessionPercent,
+    data?.data?.session_percent,
+    data?.data?.usage?.session,
+    data?.quota?.session?.percentage,
+    data?.data?.quota?.session?.percentage,
+  ];
+  const weeklyCandidates = [
+    data?.weekly,
+    data?.weeklyPercent,
+    data?.weekly_percent,
+    data?.seven_day?.utilization,
+    data?.rate_limit?.secondary_window?.used_percent,
+    data?.limits?.weekly?.utilization,
+    data?.usage?.weekly,
+    data?.data?.weekly,
+    data?.data?.weeklyPercent,
+    data?.data?.weekly_percent,
+    data?.data?.usage?.weekly,
+    data?.quota?.weekly?.percentage,
+    data?.data?.quota?.weekly?.percentage,
+    data?.quota?.daily?.percentage,
+    data?.data?.quota?.daily?.percentage,
+  ];
+
+  const session = sessionCandidates.map(readPercentCandidate).find((candidate) => candidate !== null);
+  const weekly = weeklyCandidates.map(readPercentCandidate).find((candidate) => candidate !== null);
+  return session === undefined || weekly === undefined ? null : normalizeUsagePair(session, weekly);
+}
+
+function hydrateUsageResets(usage: UsageData, nowMs = Date.now()): UsageData {
+  return {
+    ...usage,
+    sessionResetsIn: usage.sessionResetsAt ? formatResetsAt(usage.sessionResetsAt, nowMs) : usage.sessionResetsIn,
+    weeklyResetsIn: usage.weeklyResetsAt ? formatResetsAt(usage.weeklyResetsAt, nowMs) : usage.weeklyResetsIn,
+  };
+}
+
+function snapshotUsage(usage: UsageData, nowMs = Date.now()): UsageData {
+  return {
+    session: usage.session,
+    weekly: usage.weekly,
+    sessionResetsAt: usage.sessionResetsAt,
+    weeklyResetsAt: usage.weeklyResetsAt,
+    sessionResetsIn: usage.sessionResetsIn,
+    weeklyResetsIn: usage.weeklyResetsIn,
+    extraSpend: usage.extraSpend,
+    extraLimit: usage.extraLimit,
+    fetchedAt: usage.fetchedAt ?? nowMs,
+  };
+}
+
+function staleCachedUsage(cached: UsageData, warning: string, nowMs = Date.now()): UsageData {
+  return { ...hydrateUsageResets(snapshotUsage(cached, nowMs), nowMs), stale: true, warning };
+}
+
+function readClaudeCacheState(cacheFile = DEFAULT_USAGE_CACHE_FILE): ClaudeUsageCacheState {
+  return readUsageCache(cacheFile).claude ?? {};
+}
+
+function writeClaudeCacheState(state: ClaudeUsageCacheState, cacheFile = DEFAULT_USAGE_CACHE_FILE): boolean {
+  const cache = readUsageCache(cacheFile);
+  cache.claude = state;
+  return writeUsageCache(cache, cacheFile);
+}
+
+function clearClaudeCooldown(state: ClaudeUsageCacheState): ClaudeUsageCacheState {
+  return { ...state, cooldownUntil: undefined, consecutive429s: 0, lastError: undefined };
+}
+
+function computeClaudeBackoffMs(state: ClaudeUsageCacheState, retryAfterMs: number | null): number {
+  if (retryAfterMs !== null && retryAfterMs > 0) {
+    return Math.min(CLAUDE_MAX_BACKOFF_MS, Math.max(CLAUDE_BASE_BACKOFF_MS, retryAfterMs));
+  }
+  const count = Math.max(1, state.consecutive429s ?? 0);
+  return Math.min(CLAUDE_MAX_BACKOFF_MS, CLAUDE_BASE_BACKOFF_MS * 2 ** Math.max(0, count - 1));
+}
+
+function cooldownMessage(untilMs: number, nowMs = Date.now()): string {
+  return `rate limited; retry in ${formatDuration(Math.max(0, untilMs - nowMs) / 1000)}`;
+}
+
+function readClaudeCacheOutcome(cacheFile = DEFAULT_USAGE_CACHE_FILE, nowMs = Date.now()): UsageData | null {
+  const state = readClaudeCacheState(cacheFile);
+  if (state.cooldownUntil && state.cooldownUntil > nowMs) {
+    const warning = cooldownMessage(state.cooldownUntil, nowMs);
+    return state.lastSuccess
+      ? staleCachedUsage(state.lastSuccess, warning, nowMs)
+      : { session: 0, weekly: 0, error: warning };
+  }
+  if (state.lastSuccess && state.lastSuccessAt && nowMs - state.lastSuccessAt <= CLAUDE_SHARED_FRESH_TTL_MS) {
+    return hydrateUsageResets(snapshotUsage(state.lastSuccess, state.lastSuccessAt), nowMs);
+  }
+  return null;
+}
+
+export async function fetchCodexUsage(token: string, config: RequestConfig = {}): Promise<UsageData> {
+  const result = await requestJson(
+    "https://chatgpt.com/backend-api/wham/usage",
+    { headers: { Authorization: `Bearer ${token}` } },
+    config,
+  );
+  if (!result.ok) return { session: 0, weekly: 0, error: result.error };
+
+  const data = result.data as any;
+  const primary = data?.rate_limit?.primary_window;
+  const secondary = data?.rate_limit?.secondary_window;
+  return {
+    session: readPercentCandidate(primary?.used_percent) ?? 0,
+    weekly: readPercentCandidate(secondary?.used_percent) ?? 0,
+    sessionResetsIn: typeof primary?.reset_after_seconds === "number" ? formatDuration(primary.reset_after_seconds) : undefined,
+    weeklyResetsIn: typeof secondary?.reset_after_seconds === "number" ? formatDuration(secondary.reset_after_seconds) : undefined,
+  };
+}
+
+async function fetchClaudeUsageAttempt(
+  token: string,
+  config: RequestConfig = {},
+  nowMs = Date.now(),
+): Promise<ClaudeUsageAttemptResult> {
+  const result = await requestJson(
+    "https://api.anthropic.com/api/oauth/usage",
+    {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "anthropic-beta": "oauth-2025-04-20",
+      },
+    },
+    config,
+  );
+  const retryAfterMs = parseRetryAfterMs(getHeader(result.headers, "retry-after"), nowMs);
+  if (!result.ok) {
+    return { usage: { session: 0, weekly: 0, error: result.error }, status: result.status, retryAfterMs };
+  }
+
+  const data = result.data as any;
+  const usage: UsageData = hydrateUsageResets({
+    session: readPercentCandidate(data?.five_hour?.utilization) ?? 0,
+    weekly: readPercentCandidate(data?.seven_day?.utilization) ?? 0,
+    sessionResetsAt: typeof data?.five_hour?.resets_at === "string" ? data.five_hour.resets_at : undefined,
+    weeklyResetsAt: typeof data?.seven_day?.resets_at === "string" ? data.seven_day.resets_at : undefined,
+    fetchedAt: nowMs,
+  }, nowMs);
+
+  if (data?.extra_usage?.is_enabled) {
+    usage.extraSpend = typeof data.extra_usage.used_credits === "number" ? data.extra_usage.used_credits : undefined;
+    usage.extraLimit = typeof data.extra_usage.monthly_limit === "number" ? data.extra_usage.monthly_limit : undefined;
+  }
+  return { usage, status: result.status, retryAfterMs };
+}
+
+export async function fetchClaudeUsage(token: string, config: RequestConfig = {}): Promise<UsageData> {
+  return (await fetchClaudeUsageAttempt(token, config)).usage;
+}
+
+export async function fetchClaudeUsageWithFallback(
+  token: string,
+  config: ClaudeUsageFetchConfig = {},
+): Promise<UsageData> {
+  const cacheFile = config.cacheFile ?? DEFAULT_USAGE_CACHE_FILE;
+  const nowMs = config.nowMs ?? Date.now();
+  const cachedOutcome = readClaudeCacheOutcome(cacheFile, nowMs);
+  if (cachedOutcome) return cachedOutcome;
+  if (config.signal?.aborted) return { session: 0, weekly: 0, error: "request cancelled" };
+
+  const lockFile = `${cacheFile}.claude.lock`;
+  const releaseLock = await acquireFileLock(lockFile, config.signal);
+  if (!releaseLock) {
+    const waitedOutcome = readClaudeCacheOutcome(cacheFile, nowMs);
+    if (waitedOutcome) return waitedOutcome;
+    if (config.signal?.aborted) return { session: 0, weekly: 0, error: "request cancelled" };
+  }
+
+  try {
+    const lockOutcome = readClaudeCacheOutcome(cacheFile, nowMs);
+    if (lockOutcome) return lockOutcome;
+
+    let state = readClaudeCacheState(cacheFile);
+    const attempt = await fetchClaudeUsageAttempt(token, config, nowMs);
+    if (!attempt.usage.error) {
+      state = clearClaudeCooldown(state);
+      state.lastSuccess = snapshotUsage(attempt.usage, nowMs);
+      state.lastSuccessAt = nowMs;
+      writeClaudeCacheState(state, cacheFile);
+      return attempt.usage;
+    }
+
+    if (attempt.status === 429) {
+      const consecutive429s = Math.max(1, (state.consecutive429s ?? 0) + 1);
+      const cooldownUntil = nowMs + computeClaudeBackoffMs({ ...state, consecutive429s }, attempt.retryAfterMs);
+      state = { ...state, cooldownUntil, consecutive429s, lastError: attempt.usage.error };
+      writeClaudeCacheState(state, cacheFile);
+      return state.lastSuccess
+        ? staleCachedUsage(state.lastSuccess, cooldownMessage(cooldownUntil, nowMs), nowMs)
+        : { session: 0, weekly: 0, error: `${attempt.usage.error}; ${cooldownMessage(cooldownUntil, nowMs)}` };
+    }
+
+    return attempt.usage;
+  } finally {
+    releaseLock?.();
+  }
+}
+
+/** Parse ZAI limits where unit 3 is the five-hour window and unit 6 the weekly window. */
+export function extractZaiUsageFromPayload(payload: unknown, nowMs = Date.now()): UsageData | null {
+  const data = payload as any;
+  const arrays = [data?.data?.limits, data?.limits, data?.quota?.limits, data?.data?.quota?.limits];
+  const limits = arrays.find(Array.isArray) as any[] | undefined;
+  if (!limits?.length) return null;
+
+  const tokenLimits = limits.filter((entry) => String(entry?.type || "").toUpperCase() === "TOKENS_LIMIT");
+  const sessionEntry = tokenLimits.find((entry) => entry?.unit === 3);
+  const weeklyEntry = tokenLimits.find((entry) => entry?.unit === 6);
+  if (!sessionEntry || !weeklyEntry) return null;
+
+  const session = readPercentCandidate(sessionEntry.percentage);
+  const weekly = readPercentCandidate(weeklyEntry.percentage);
+  if (session === null || weekly === null) return null;
+  const normalized = normalizeUsagePair(session, weekly);
+
+  return {
+    ...normalized,
+    sessionResetsIn: typeof sessionEntry.nextResetTime === "number" && sessionEntry.nextResetTime > 0
+      ? formatDuration(Math.max(0, sessionEntry.nextResetTime - nowMs) / 1000)
+      : undefined,
+    weeklyResetsIn: typeof weeklyEntry.nextResetTime === "number" && weeklyEntry.nextResetTime > 0
+      ? formatDuration(Math.max(0, weeklyEntry.nextResetTime - nowMs) / 1000)
+      : undefined,
+  };
+}
+
+export async function fetchZaiUsage(
+  token: string,
+  provider: "zai" | "zai-cn" = "zai",
+  config: FetchConfig = {},
+): Promise<UsageData> {
+  const endpoints = config.endpoints ?? resolveUsageEndpoints(config.env);
+  const endpoint = provider === "zai-cn" ? endpoints.zaiCn : endpoints.zai;
+  const result = await requestJson(endpoint, { headers: { Authorization: `Bearer ${token}` } }, config);
+  if (!result.ok) return { session: 0, weekly: 0, error: result.error };
+
+  const zaiUsage = extractZaiUsageFromPayload(result.data);
+  if (zaiUsage) return zaiUsage;
+  return extractUsageFromPayload(result.data) ?? { session: 0, weekly: 0, error: "unrecognized response shape" };
+}
+
+export function detectProvider(
+  model: { provider?: string } | string | undefined | null,
+): ProviderKey | null {
+  if (!model || typeof model === "string") return null;
+  switch ((model.provider || "").toLowerCase()) {
+    case "openai-codex": return "codex";
+    case "anthropic": return "claude";
+    case "zai": return "zai";
+    case "zai-coding-cn": return "zai-cn";
+    default: return null;
+  }
+}
+
+export function providerToPiProviderId(provider: ProviderKey): PiProviderId {
+  switch (provider) {
+    case "codex": return "openai-codex";
+    case "claude": return "anthropic";
+    case "zai": return "zai";
+    case "zai-cn": return "zai-coding-cn";
+  }
+}
+
+export function clampPercent(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+export function colorForPercent(value: number): "success" | "warning" | "error" {
+  if (value >= 90) return "error";
+  if (value >= 70) return "warning";
+  return "success";
+}
+
+export async function fetchAllUsages(
+  tokens: UsageTokens,
+  config: FetchAllUsagesConfig = {},
+): Promise<UsageByProvider> {
+  const endpoints = config.endpoints ?? resolveUsageEndpoints(config.env);
+  const results: UsageByProvider = { codex: null, claude: null, zai: null, "zai-cn": null };
+  const tasks: Promise<void>[] = [];
+
+  const assign = (provider: ProviderKey, request: Promise<UsageData>) => {
+    tasks.push(request.then((usage) => {
+      results[provider] = usage;
+    }).catch((error) => {
+      results[provider] = { session: 0, weekly: 0, error: toErrorMessage(error, config.signal) };
+    }));
+  };
+
+  if (tokens.codex) assign("codex", fetchCodexUsage(tokens.codex, config));
+  if (tokens.claude) {
+    assign("claude", fetchClaudeUsageWithFallback(tokens.claude, {
+      ...config,
+      cacheFile: config.cacheFile,
+      nowMs: config.nowMs,
+    }));
+  }
+  if (tokens.zai) assign("zai", fetchZaiUsage(tokens.zai, "zai", { ...config, endpoints }));
+  if (tokens["zai-cn"]) assign("zai-cn", fetchZaiUsage(tokens["zai-cn"], "zai-cn", { ...config, endpoints }));
+
+  await Promise.all(tasks);
+  return results;
+}

package/extensions/usage-bars/index.ts

@@ -0,0 +1,517 @@
+/** Usage bars for subscription-backed providers supported by current Pi releases. */
+
+import {
+  DynamicBorder,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type KeybindingsManager,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Spacer,
+  Text,
+  type Focusable,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import {
+  clampPercent,
+  colorForPercent,
+  detectProvider,
+  fetchAllUsages,
+  fetchClaudeUsageWithFallback,
+  fetchCodexUsage,
+  fetchZaiUsage,
+  providerToPiProviderId,
+  resolveUsageEndpoints,
+  type ProviderKey,
+  type UsageByProvider,
+  type UsageData,
+  type UsageTokens,
+} from "./core";
+
+const POLL_INTERVAL_MS = 2 * 60 * 1000;
+const STATUS_KEY = "usage-bars";
+const PROVIDERS: readonly ProviderKey[] = ["codex", "claude", "zai", "zai-cn"];
+
+const PROVIDER_LABELS: Record<ProviderKey, string> = {
+  codex: "Codex",
+  claude: "Claude",
+  zai: "ZAI Coding Plan (Global)",
+  "zai-cn": "ZAI Coding Plan (China)",
+};
+
+interface SubscriptionItem {
+  name: string;
+  provider: ProviderKey;
+  data: UsageData;
+  isActive: boolean;
+}
+
+interface CredentialResolution {
+  token?: string;
+  error?: string;
+}
+
+class UsageSelectorComponent extends Container implements Focusable {
+  private readonly searchInput: Input;
+  private readonly listContainer: Container;
+  private readonly hintText: Text;
+  private readonly requestController = new AbortController();
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly keybindings: KeybindingsManager;
+  private readonly onCancelCallback: () => void;
+  private readonly activeProvider: ProviderKey | null;
+  private readonly fetchAllFn: (signal: AbortSignal) => Promise<UsageByProvider>;
+  private allItems: SubscriptionItem[] = [];
+  private filteredItems: SubscriptionItem[] = [];
+  private selectedIndex = 0;
+  private loading = true;
+  private hint: "loading" | "ready" | "error" = "loading";
+  private disposed = false;
+  private _focused = false;
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    keybindings: KeybindingsManager,
+    activeProvider: ProviderKey | null,
+    fetchAll: (signal: AbortSignal) => Promise<UsageByProvider>,
+    onCancel: () => void,
+  ) {
+    super();
+    this.tui = tui;
+    this.theme = theme;
+    this.keybindings = keybindings;
+    this.activeProvider = activeProvider;
+    this.fetchAllFn = fetchAll;
+    this.onCancelCallback = onCancel;
+
+    this.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+    this.addChild(new Spacer(1));
+    this.hintText = new Text("", 0, 0);
+    this.addChild(this.hintText);
+    this.addChild(new Spacer(1));
+    this.searchInput = new Input();
+    this.addChild(this.searchInput);
+    this.addChild(new Spacer(1));
+    this.listContainer = new Container();
+    this.addChild(this.listContainer);
+    this.addChild(new Spacer(1));
+    this.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+
+    this.updateHint();
+    this.updateList();
+    void this.load();
+  }
+
+  private async load(): Promise<void> {
+    try {
+      const results = await this.fetchAllFn(this.requestController.signal);
+      if (this.disposed || this.requestController.signal.aborted) return;
+      this.loading = false;
+      this.hint = "ready";
+      this.buildItems(results);
+    } catch {
+      if (this.disposed || this.requestController.signal.aborted) return;
+      this.loading = false;
+      this.hint = "error";
+    }
+    this.updateHint();
+    this.updateList();
+    this.tui.requestRender();
+  }
+
+  private updateHint(): void {
+    if (this.hint === "loading") {
+      this.hintText.setText(this.theme.fg("dim", "Fetching usage from configured subscription providers…"));
+    } else if (this.hint === "error") {
+      this.hintText.setText(this.theme.fg("error", "Failed to fetch usage data"));
+    } else {
+      this.hintText.setText(
+        this.theme.fg("muted", "Only showing configured subscription providers. ") +
+          this.theme.fg("dim", "✓ = active provider"),
+      );
+    }
+  }
+
+  private buildItems(results: UsageByProvider): void {
+    this.allItems = PROVIDERS.flatMap((provider) => {
+      const data = results[provider];
+      return data
+        ? [{
+            name: PROVIDER_LABELS[provider],
+            provider,
+            data,
+            isActive: this.activeProvider === provider,
+          }]
+        : [];
+    });
+    this.filteredItems = this.allItems;
+    this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.filteredItems.length - 1));
+  }
+
+  private filterItems(query: string): void {
+    const normalized = query.trim().toLowerCase();
+    this.filteredItems = normalized
+      ? this.allItems.filter((item) =>
+          item.name.toLowerCase().includes(normalized) || item.provider.includes(normalized))
+      : this.allItems;
+    this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.filteredItems.length - 1));
+  }
+
+  private renderBar(percent: number, width = 16): string {
+    const value = clampPercent(percent);
+    const filled = Math.round((value / 100) * width);
+    return this.theme.fg(colorForPercent(value), "█".repeat(filled)) +
+      this.theme.fg("dim", "░".repeat(width - filled));
+  }
+
+  private renderItem(item: SubscriptionItem, selected: boolean): void {
+    const theme = this.theme;
+    const pointer = selected ? theme.fg("accent", "→ ") : "  ";
+    const activeBadge = item.isActive ? theme.fg("success", " ✓") : "";
+    const name = selected ? theme.fg("accent", theme.bold(item.name)) : item.name;
+    this.listContainer.addChild(new Text(`${pointer}${name}${activeBadge}`, 0, 0));
+
+    const indent = "    ";
+    if (item.data.error) {
+      this.listContainer.addChild(new Text(indent + theme.fg("error", item.data.error), 0, 0));
+    } else {
+      const session = clampPercent(item.data.session);
+      const weekly = clampPercent(item.data.weekly);
+      const sessionReset = item.data.sessionResetsIn
+        ? theme.fg("dim", `  resets in ${item.data.sessionResetsIn}`)
+        : "";
+      const weeklyReset = item.data.weeklyResetsIn
+        ? theme.fg("dim", `  resets in ${item.data.weeklyResetsIn}`)
+        : "";
+
+      this.listContainer.addChild(new Text(
+        indent + theme.fg("muted", "Session  ") + this.renderBar(session) + " " +
+          theme.fg(colorForPercent(session), `${session}%`.padStart(4)) + sessionReset,
+        0,
+        0,
+      ));
+      this.listContainer.addChild(new Text(
+        indent + theme.fg("muted", "Weekly   ") + this.renderBar(weekly) + " " +
+          theme.fg(colorForPercent(weekly), `${weekly}%`.padStart(4)) + weeklyReset,
+        0,
+        0,
+      ));
+
+      if (typeof item.data.extraSpend === "number" && typeof item.data.extraLimit === "number") {
+        this.listContainer.addChild(new Text(
+          indent + theme.fg("muted", "Extra    ") +
+            theme.fg("dim", `$${item.data.extraSpend.toFixed(2)} / $${item.data.extraLimit}`),
+          0,
+          0,
+        ));
+      }
+      if (item.data.warning) {
+        this.listContainer.addChild(new Text(indent + theme.fg("warning", `⚠ ${item.data.warning}`), 0, 0));
+      }
+    }
+    this.listContainer.addChild(new Spacer(1));
+  }
+
+  private updateList(): void {
+    this.listContainer.clear();
+    if (this.loading) {
+      this.listContainer.addChild(new Text(this.theme.fg("muted", "  Loading…"), 0, 0));
+      return;
+    }
+    if (this.filteredItems.length === 0) {
+      this.listContainer.addChild(new Text(this.theme.fg("muted", "  No matching configured providers"), 0, 0));
+      return;
+    }
+    this.filteredItems.forEach((item, index) => this.renderItem(item, index === this.selectedIndex));
+  }
+
+  private refresh(): void {
+    this.updateList();
+    this.tui.requestRender();
+  }
+
+  handleInput(keyData: string): void {
+    if (this.keybindings.matches(keyData, "tui.select.up")) {
+      if (this.filteredItems.length > 0) {
+        this.selectedIndex = this.selectedIndex === 0
+          ? this.filteredItems.length - 1
+          : this.selectedIndex - 1;
+        this.refresh();
+      }
+      return;
+    }
+    if (this.keybindings.matches(keyData, "tui.select.down")) {
+      if (this.filteredItems.length > 0) {
+        this.selectedIndex = this.selectedIndex === this.filteredItems.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+        this.refresh();
+      }
+      return;
+    }
+    if (
+      this.keybindings.matches(keyData, "tui.select.cancel") ||
+      this.keybindings.matches(keyData, "tui.select.confirm")
+    ) {
+      this.onCancelCallback();
+      return;
+    }
+
+    this.searchInput.handleInput(keyData);
+    this.filterItems(this.searchInput.getValue());
+    this.refresh();
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.updateHint();
+    this.updateList();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.requestController.abort();
+  }
+}
+
+interface UsageState extends UsageByProvider {
+  activeProvider: ProviderKey | null;
+  available: Partial<Record<ProviderKey, boolean>>;
+}
+
+export default function (pi: ExtensionAPI): void {
+  const endpoints = resolveUsageEndpoints();
+  const state: UsageState = {
+    codex: null,
+    claude: null,
+    zai: null,
+    "zai-cn": null,
+    activeProvider: null,
+    available: {},
+  };
+
+  let pollTimer: ReturnType<typeof setInterval> | undefined;
+  let pollInFlight: Promise<void> | undefined;
+  let pollQueued = false;
+  let currentContext: ExtensionContext | undefined;
+  let sessionController: AbortController | undefined;
+
+  const renderPercent = (theme: Theme, value: number) => {
+    const percent = clampPercent(value);
+    return theme.fg(colorForPercent(percent), `${percent}%`);
+  };
+
+  const renderBar = (theme: Theme, value: number) => {
+    const percent = clampPercent(value);
+    const width = 8;
+    const filled = Math.round((percent / 100) * width);
+    return theme.fg(colorForPercent(percent), "█".repeat(filled)) +
+      theme.fg("dim", "░".repeat(width - filled));
+  };
+
+  function updateStatus(): void {
+    const ctx = currentContext;
+    if (!ctx || ctx.mode !== "tui") return;
+    const provider = state.activeProvider;
+    if (!provider || state.available[provider] === false) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    const data = state[provider];
+    const theme = ctx.ui.theme;
+    const label = PROVIDER_LABELS[provider];
+    if (!data) {
+      ctx.ui.setStatus(STATUS_KEY, theme.fg("dim", `${label} usage: loading…`));
+      return;
+    }
+    if (data.error) {
+      ctx.ui.setStatus(STATUS_KEY, theme.fg("warning", `${label} usage unavailable (${data.error})`));
+      return;
+    }
+
+    const session = clampPercent(data.session);
+    const weekly = clampPercent(data.weekly);
+    const status =
+      theme.fg("dim", `${label} `) +
+      theme.fg("muted", "S ") + renderBar(theme, session) + " " + renderPercent(theme, session) +
+      (data.sessionResetsIn ? theme.fg("dim", ` ⟳ ${data.sessionResetsIn}`) : "") +
+      theme.fg("muted", " W ") + renderBar(theme, weekly) + " " + renderPercent(theme, weekly) +
+      (data.weeklyResetsIn ? theme.fg("dim", ` ⟳ ${data.weeklyResetsIn}`) : "") +
+      (data.stale ? theme.fg("warning", " stale") : "") +
+      (data.warning && !data.stale ? theme.fg("warning", " ⚠") : "");
+    ctx.ui.setStatus(STATUS_KEY, status);
+  }
+
+  function updateProviderFrom(model: ExtensionContext["model"]): boolean {
+    const previous = state.activeProvider;
+    state.activeProvider = detectProvider(model);
+    if (previous !== state.activeProvider) {
+      updateStatus();
+      return true;
+    }
+    return false;
+  }
+
+  async function resolveCredential(ctx: ExtensionContext, provider: ProviderKey): Promise<CredentialResolution> {
+    const providerId = providerToPiProviderId(provider);
+    if (!ctx.modelRegistry.getProvider(providerId)) return {};
+    const status = ctx.modelRegistry.getProviderAuthStatus(providerId);
+    if (!status.configured) return {};
+
+    try {
+      const resolved = await ctx.modelRegistry.getProviderAuth(providerId);
+      if (provider === "claude" && resolved?.source !== "OAuth") return {};
+      const token = resolved?.auth.apiKey;
+      return token ? { token } : { error: "configured authentication did not resolve a token" };
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  async function fetchProvider(
+    ctx: ExtensionContext,
+    provider: ProviderKey,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const credential = await resolveCredential(ctx, provider);
+    if (signal.aborted) return;
+    state.available[provider] = Boolean(credential.token || credential.error);
+    if (credential.error) {
+      state[provider] = { session: 0, weekly: 0, error: `auth resolution failed (${credential.error})` };
+      return;
+    }
+    if (!credential.token) {
+      state[provider] = null;
+      return;
+    }
+
+    if (provider === "codex") state.codex = await fetchCodexUsage(credential.token, { signal });
+    if (provider === "claude") state.claude = await fetchClaudeUsageWithFallback(credential.token, { signal });
+    if (provider === "zai") state.zai = await fetchZaiUsage(credential.token, "zai", { endpoints, signal });
+    if (provider === "zai-cn") state["zai-cn"] = await fetchZaiUsage(credential.token, "zai-cn", { endpoints, signal });
+  }
+
+  async function runPoll(): Promise<void> {
+    const ctx = currentContext;
+    const signal = sessionController?.signal;
+    const provider = state.activeProvider;
+    if (!ctx || !signal || signal.aborted || ctx.mode !== "tui" || !provider) {
+      updateStatus();
+      return;
+    }
+
+    await fetchProvider(ctx, provider, signal);
+    if (signal.aborted) return;
+    const data = state[provider];
+    if (data && !data.error) pi.events.emit("usage:update", { provider, ...data });
+    updateStatus();
+  }
+
+  async function poll(): Promise<void> {
+    if (pollInFlight) {
+      pollQueued = true;
+      return pollInFlight;
+    }
+    do {
+      pollQueued = false;
+      pollInFlight = runPoll().catch(() => undefined).finally(() => {
+        pollInFlight = undefined;
+      });
+      await pollInFlight;
+    } while (pollQueued && !sessionController?.signal.aborted);
+  }
+
+  async function fetchAllForContext(ctx: ExtensionContext, signal: AbortSignal): Promise<UsageByProvider> {
+    const resolutions = await Promise.all(PROVIDERS.map(async (provider) =>
+      [provider, await resolveCredential(ctx, provider)] as const));
+    if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+
+    const tokens: UsageTokens = {};
+    const authErrors: Partial<Record<ProviderKey, string>> = {};
+    for (const [provider, resolution] of resolutions) {
+      if (resolution.token) tokens[provider] = resolution.token;
+      if (resolution.error) authErrors[provider] = resolution.error;
+    }
+
+    const results = await fetchAllUsages(tokens, { endpoints, signal });
+    for (const provider of PROVIDERS) {
+      const error = authErrors[provider];
+      if (error) results[provider] = { session: 0, weekly: 0, error: `auth resolution failed (${error})` };
+    }
+    return results;
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    currentContext = ctx;
+    sessionController?.abort();
+    sessionController = new AbortController();
+    updateProviderFrom(ctx.model);
+
+    if (pollTimer) clearInterval(pollTimer);
+    pollTimer = undefined;
+    if (ctx.mode !== "tui") return;
+
+    updateStatus();
+    void poll();
+    pollTimer = setInterval(() => void poll(), POLL_INTERVAL_MS);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    sessionController?.abort();
+    sessionController = undefined;
+    pollQueued = false;
+    if (pollTimer) clearInterval(pollTimer);
+    pollTimer = undefined;
+    if (ctx.mode === "tui") ctx.ui.setStatus(STATUS_KEY, undefined);
+    currentContext = undefined;
+  });
+
+  pi.on("turn_start", (_event, ctx) => {
+    currentContext = ctx;
+    if (updateProviderFrom(ctx.model)) void poll();
+  });
+
+  pi.on("model_select", (event, ctx) => {
+    currentContext = ctx;
+    updateProviderFrom(event.model);
+    void poll();
+  });
+
+  pi.registerCommand("usage", {
+    description: "Show subscription usage for configured providers",
+    handler: async (_args, ctx) => {
+      currentContext = ctx;
+      updateProviderFrom(ctx.model);
+      if (ctx.mode !== "tui") {
+        if (ctx.hasUI) ctx.ui.notify("/usage is available in interactive mode", "warning");
+        return;
+      }
+
+      await ctx.ui.custom<void>((tui, theme, keybindings, done) =>
+        new UsageSelectorComponent(
+          tui,
+          theme,
+          keybindings,
+          state.activeProvider,
+          (signal) => fetchAllForContext(ctx, signal),
+          () => done(),
+        ));
+      void poll();
+    },
+  });
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@hk_net/pi-usage-bars",
+  "version": "0.3.0",
+  "description": "Subscription usage bars for current Pi providers (Codex, Claude, and ZAI Coding Plan)",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "usage",
+    "codex",
+    "anthropic",
+    "zai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hknet/pi-usage-bars.git"
+  },
+  "homepage": "https://github.com/hknet/pi-usage-bars#readme",
+  "bugs": {
+    "url": "https://github.com/hknet/pi-usage-bars/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc --noEmit",
+    "smoke": "pi -e ./extensions/usage-bars/index.ts --list-models",
+    "check": "npm run typecheck && npm test && npm run smoke",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.81.1",
+    "@earendil-works/pi-tui": ">=0.81.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.81.1",
+    "@earendil-works/pi-tui": "0.81.1",
+    "@types/bun": "1.3.14",
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/usage-bars/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png"
+  }
+}