pi-minimal-footer 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-05
+
+### Added
+
+- Usage limits for the selected provider: OpenAI Codex, Claude OAuth, GitHub Copilot, Gemini CLI, MiniMax (global/CN), Kimi Coding, and OpenCode Go
+- Show the shortest available quota window, including weekly/monthly when no shorter quota exists; omit reset time when the provider does not report it
+- Compact five-cell Braille quota bar with nine bottom-up fill states (`⠀`, `⡀`, `⣀`, `⣄`, `⣤`, `⣦`, `⣶`, `⣷`, `⣿`), 2.5% steps, and green/amber/red usage colors
+- Absolute local reset time marked with `↻` in 24-hour format, e.g. `⣿⣶⠀⠀⠀ ↻16:40`, without provider/window labels or numeric percentages
+- Passive Codex/Claude quota updates from provider responses, with four-minute usage-endpoint fallback and reset-time refresh using Pi's existing credentials
+- Immediate quota clearing and request/timer cancellation on provider switch; ignore late results and dim only the current provider's cached quota after temporary refresh failures
+- Hide usage for local/unsupported models, missing credentials, or absent applicable limits; stop quota work on footer teardown, disable, and session shutdown
+- README examples and documentation for the complete usage feature, its shading, reset time, refresh behavior, and edge cases
+- Honorable mention to Can Celik (@ogulcancelik): provider usage-fetching and quota-parsing logic copied and adapted from [@ogulcancelik/pi-minimal-footer](https://pi.dev/packages/@ogulcancelik/pi-minimal-footer), with upstream MIT attribution retained
+
+### Changed
+
+- Group directory and git branch on the left; keep extension statuses, model, context, and quota on the right in one line, with extra spacing before quota
+- Shorten location and statuses on narrow terminals, shrink quota before truncating model/context, and preserve the reset time
+- Simplify quota header parsing and footer width calculations; remove the unused duplicate Claude header parser
+
+### Fixed
+
+- Release stalled quota authentication, fetch, and response-body waits after five seconds so scheduled polling can recover; ignore late results after timeout or provider switch
+- Merge partial Codex/Claude quota signals without replacing a cached shorter window or postponing its four-minute refresh when only longer windows update
+- Preserve dim cached usage after malformed responses, while explicit empty/unlimited quotas clear it; retain valid usage when optional reset metadata is invalid
+- Accept Kimi used-only quotas and week/month durations, and derive Codex reset times from relative endpoint delays when an absolute timestamp is unavailable
+- Clear cached quota when Pi reports missing credentials; retain dim cached usage for temporary authentication failures and recover after credentials are restored
+
 ## [0.1.3] - 2026-10-05
 
 ### Added
@@ -86,7 +114,8 @@ First npm-ready release.
 
 - Project scaffold — `extensions/index.ts` with basic footer structure, `package.json` with pi extension manifest, `README.md`, `LICENSE` (MIT)
 
-[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.1.0...v0.1.1

package/README.md

@@ -15,10 +15,10 @@
   </a>
 </p>
 
-A clean, compact one-line footer for [Pi](https://github.com/earendil-works/pi).
+An opinionated, clean, compact footer for [Pi](https://github.com/earendil-works/pi).
 
 ```
-~/path/to/dir                (status1 | status2)   main  sonnet  12/128k
+~/git/pi-minimal-footer   main       (icarus | goal running)  gpt-5.6-sol  12/128k    ⣿⣶⠀⠀⠀ ↻16:40
 ```
 
 ![pi-minimal-footer screenshot](media/github-preview.png)
@@ -52,11 +52,78 @@ Requires Node.js >=22.19.0. Run `npm ci`, `npm run check`, and `npm test`. Pi lo
 - **Git branch** — current branch name
 - **Model** — active model ID
 - **Context usage** — tokens used / context window (e.g., `12/128k`). After compaction, Pi reports usage as unknown (`?`) until a subsequent model response.
+- **Provider quota** — the right end shows the selected provider's shortest available quota as a Braille bar and local reset time in 24-hour `HH:mm` format, when reported.
 
-On narrow terminals, the footer shrinks or drops the path, then drops extension statuses and the git branch before truncating model/context. The remaining segments stay right-aligned.
+The directory and git branch stay together on the left. Extension statuses, model, context usage, and quota stay on the right, with extra spacing before the quota. Statuses and location are muted; the model is bold.
+
+On narrow terminals, the directory and statuses shorten or disappear, then the branch disappears. The quota bar shrinks before model/context is shortened, preserving the reset time. The footer always uses one line.
 
 The footer appears only in Pi's interactive terminal UI, not in print, JSON, or RPC modes.
 
+### Provider usage limits
+
+The footer displays only the selected provider's shortest available quota window, typically five hours. If only a weekly or monthly quota is available, it displays that quota. This measures account quota used, separately from the model's context usage (`12/128k`).
+
+| Provider | Quota selection |
+|---|---|
+| OpenAI Codex (`openai-codex`) | Shortest primary/secondary window |
+| Claude (`anthropic`, OAuth) | Five-hour window, or weekly if that is all that is reported |
+| GitHub Copilot (`github-copilot`) | Limited premium/chat quota; unlimited buckets are hidden |
+| Gemini CLI (`google-gemini-cli`) | Selected model's quota, with Pro/Flash family fallback |
+| MiniMax (`minimax`, `minimax-cn`) | General text bucket's shortest interval/weekly window |
+| Kimi Coding (`kimi-coding`) | Shortest reported window, or weekly fallback |
+| OpenCode Go (`opencode-go`) | Shortest rolling/weekly/monthly window |
+
+The adapters reuse the selected provider's authentication from Pi. Claude subscription quota requires OAuth; ordinary Claude API keys do not expose it. Copilot's quota endpoint uses the GitHub login token from Pi's configured agent directory or `COPILOT_GITHUB_TOKEN`. Gemini CLI needs a configured provider/model; Pi 1.0.3 does not include that provider in its built-in catalog.
+
+The usage segment contains only a five-cell Braille bar and its reset time:
+
+```text
+⣿⣶⠀⠀⠀ ↻16:40
+```
+
+This example shows 35% used. `↻16:40` means the quota resets at 16:40 in your local timezone: an absolute 24-hour time, not a countdown. No provider name, window label, percentage, or date is displayed.
+
+If the provider does not report a reset time, only the bar is shown:
+
+```text
+⣿⣶⠀⠀⠀
+```
+
+Each cell uses comic-style dot shading, starting from the bottom:
+
+| Cell | Fill |
+|---|---|
+| `⠀` | Empty |
+| `⡀` | One-eighth |
+| `⣀` | Quarter |
+| `⣄` | Three-eighths |
+| `⣤` | Half |
+| `⣦` | Five-eighths |
+| `⣶` | Three-quarter |
+| `⣷` | Seven-eighths |
+| `⣿` | Full |
+
+Each step adds one dot from the bottom upward. Five cells provide 2.5% steps, rounded to the nearest step; only the last partially filled cell uses an intermediate state. Filled cells are green below 85%, amber from 85%, and red from 92%. On narrow terminals the bar shrinks to preserve the reset time, so its steps become coarser.
+
+Usage refreshes from Codex response headers/stream events and Claude quota response headers when available. Otherwise, the footer checks the selected provider's usage endpoint on startup or provider switch, then every four minutes without a fresh response update. It also checks when a reported reset time arrives. These checks make no model requests.
+
+Partial response updates are merged with cached windows. A weekly-only update keeps the cached five-hour quota visible and does not postpone its refresh. Authentication, fetching, and response parsing share a five-second timeout; a stalled lookup or body read releases the request and allows the next scheduled attempt. Late results cannot restore a previous provider's quota.
+
+Codex endpoint responses can supply either an absolute reset timestamp or a relative reset delay. Kimi quotas accept either used or remaining counts, including week/month durations. Invalid optional reset metadata leaves the bar visible without a time.
+
+Switching providers immediately clears the previous quota, cancels its requests and timers, and ignores late results. Switching back fetches fresh data. Gemini model switches also refresh the model-specific quota. A previous provider's bar never remains visible while the new provider loads.
+
+Local models, unsupported providers, and sessions without a selected model show no usage segment and make no usage requests. Missing credentials or a successful usage response without an applicable quota hide the segment, including any previously cached bar. Zero usage still displays an empty bar, with its reset time when available.
+
+If a refresh fails temporarily or returns malformed quota data, the current provider's last known bar is dimmed until fresh data arrives; without cached data, the segment stays hidden. Explicit empty or unlimited quota responses clear the cached bar. Requests and timers also stop when the footer is disabled, disposed, or the session shuts down. Custom proxy endpoints are not polled. Live quota availability depends on each provider's endpoint; unavailable endpoints stay silent.
+
+The adapters have automated parsing and lifecycle coverage, but authenticated provider endpoints have not been tested live. In particular, OpenCode Go's bearer-token response format and Copilot's public quota endpoint and enterprise compatibility remain unverified. The comparison with [mtrojnar/pi-usage](https://github.com/mtrojnar/pi-usage) informed the timeout, validation, and partial-update handling; its OpenCode implementation uses an authenticated dashboard instead.
+
+### Credits
+
+Honorable mention and thanks to **Can Celik (@ogulcancelik)**: the provider usage-fetching and quota-parsing logic was **copied and adapted from [@ogulcancelik/pi-minimal-footer](https://pi.dev/packages/@ogulcancelik/pi-minimal-footer)**. This footer keeps its minimal layout, five-cell bottom-up Braille display, and four-minute refresh behavior. The upstream MIT copyright and license are retained in [extensions/lib/LICENSE](extensions/lib/LICENSE).
+
 ## Commands
 
 | Command | Description |

package/extensions/index.ts

@@ -1,7 +1,7 @@
 /**
  * Minimal footer — replaces pi's default footer with a clean status line:
  *
- *   ~/path/to/dir                (skill1 | skill2)   main  sonnet  12/128k
+ *   ~/path/to/dir   main       (status1 | status2)  sonnet  12/128k    ⣿⣶⠀⠀⠀ ↻16:40
  *
  * Settings are persisted in the agent directory (usually ~/.pi/agent)
  * settings.json under "minFooter".
@@ -17,6 +17,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname, sep } from "node:path";
 import { homedir } from "node:os";
+import { UsageLimits } from "./lib/usage-limits.js";
 
 // ── Settings ──────────────────────────────────────────────────────────
 
@@ -123,32 +124,60 @@ function updateState(ctx: ExtensionContext, state: FooterState): void {
 
 // ── Layout ────────────────────────────────────────────────────────────
 //
-// Priority when space runs out:
-//   1. drop/truncate the path first (truncate, then drop entirely)
-//   2. drop extension statuses
-//   3. drop the git branch
-//   4. retain model/context as long as possible
-//   5. last resort: truncate the remaining model/context to fit
-//
-// Every returned line is guaranteed to fit `width` (visible-width safe).
-
-function buildLine(width: number, path: string, statuses: string, branch: string, model: string, context: string): string {
+// Keep quota and reset time together; shorten location/statuses before model/context.
+// All segment measurements use visible widths, including ANSI and wide characters.
+
+const SEGMENT_GAP = "  ";
+const QUOTA_GAP = "    ";
+const LOCATION_GAP_WIDTH = 3;
+const FULL_QUOTA_WIDTH = 12;
+const COMPACT_QUOTA_WIDTH = 11;
+const MIN_TEXT_WIDTH = 4;
+const MIN_STATUS_WIDTH = 12;
+
+function buildLine(width: number, path: string, statuses: string, branch: string, model: string, context: string,
+  usage: (available: number) => string | null): string {
   if (width <= 0) return "";
-  const core = [model, context].filter(Boolean).join("  ");
-  const right = [statuses, branch, core].filter(Boolean).join("  ");
-  const rightWidth = visibleWidth(right);
-
-  if (rightWidth < width) {
-    const left = path ? truncateToWidth(path, width - rightWidth - 1, "...", true) : " ".repeat(width - rightWidth - 1);
-    return `${left} ${right}`;
+  let core = [model, context].filter(Boolean).join(SEGMENT_GAP);
+  let quota = usage(Math.min(FULL_QUOTA_WIDTH, width)) ?? "";
+  const availableQuotaWidth = width - visibleWidth(core) - QUOTA_GAP.length;
+  if (quota && visibleWidth(quota) > availableQuotaWidth) {
+    const compactWidth = Math.min(width, Math.max(COMPACT_QUOTA_WIDTH, availableQuotaWidth));
+    quota = usage(compactWidth) ?? "";
   }
-
-  // Drop the path, then extension statuses, then git; protect model/context until last.
-  let remaining = right;
-  if (rightWidth > width) remaining = [branch, core].filter(Boolean).join("  ");
-  if (visibleWidth(remaining) > width) remaining = core;
-  remaining = truncateToWidth(remaining, width, "...");
-  return " ".repeat(width - visibleWidth(remaining)) + remaining;
+  const quotaGapWidth = quota && core ? QUOTA_GAP.length : 0;
+  const coreBudget = Math.max(0, width - visibleWidth(quota) - quotaGapWidth);
+  if (quota && coreBudget < MIN_TEXT_WIDTH) {
+    core = "";
+    quota = usage(Math.min(FULL_QUOTA_WIDTH, width)) ?? "";
+  } else if (visibleWidth(core) > coreBudget) {
+    const modelGapWidth = model && context ? SEGMENT_GAP.length : 0;
+    const modelBudget = coreBudget - visibleWidth(context) - modelGapWidth;
+    if (modelBudget > 0) {
+      core = [truncateToWidth(model, modelBudget, "..."), context].filter(Boolean).join(SEGMENT_GAP);
+    } else {
+      core = truncateToWidth(context || model, coreBudget, "...");
+    }
+  }
+  const protectedRight = [core, quota].filter(Boolean).join(QUOTA_GAP);
+  const branchReservation = branch ? visibleWidth(branch) + LOCATION_GAP_WIDTH : 0;
+  const statusBudget = width - visibleWidth(protectedRight) - branchReservation - SEGMENT_GAP.length;
+  let fittedStatuses = "";
+  if (statusBudget >= MIN_STATUS_WIDTH) {
+    fittedStatuses = statuses;
+    if (visibleWidth(statuses) > statusBudget) {
+      fittedStatuses = truncateToWidth(statuses, statusBudget - 1, "...") + ")";
+    }
+  }
+  const right = [fittedStatuses, protectedRight].filter(Boolean).join(SEGMENT_GAP);
+  const locationGapWidth = right ? LOCATION_GAP_WIDTH : 0;
+  const leftBudget = Math.max(0, width - visibleWidth(right) - locationGapWidth);
+  const fittedBranch = visibleWidth(branch) <= leftBudget ? branch : "";
+  const pathGapWidth = fittedBranch && path ? SEGMENT_GAP.length : 0;
+  const pathBudget = leftBudget - visibleWidth(fittedBranch) - pathGapWidth;
+  const fittedPath = pathBudget >= MIN_TEXT_WIDTH ? truncateToWidth(path, pathBudget, "...") : "";
+  const left = [fittedPath, fittedBranch].filter(Boolean).join(SEGMENT_GAP);
+  return left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right;
 }
 
 // ── Extension ─────────────────────────────────────────────────────────
@@ -159,13 +188,15 @@ export default function (pi: ExtensionAPI) {
   const state: FooterState = { cwd: process.cwd(), model: "no-model", context: "?" };
   let requestRender: (() => void) | null = null;
   let disposeFooter: (() => void) | null = null;
+  const usageLimits = new UsageLimits(() => requestRender?.());
 
   function install(ctx: ExtensionContext): void {
     config = readConfig();
     enabled = config.enabled !== false;
-    if (ctx.mode !== "tui") return;
+    if (ctx.mode !== "tui") { usageLimits.stop(); return; }
 
     if (!enabled) {
+      usageLimits.stop();
       if (disposeFooter) ctx.ui.setFooter(undefined);
       return;
     }
@@ -179,7 +210,10 @@ export default function (pi: ExtensionAPI) {
         if (disposed) return;
         disposed = true;
         unsub();
-        if (requestRender === request) requestRender = null;
+        if (requestRender === request) {
+          requestRender = null;
+          usageLimits.stop();
+        }
         if (disposeFooter === dispose) disposeFooter = null;
       };
       disposeFooter = dispose;
@@ -192,18 +226,20 @@ export default function (pi: ExtensionAPI) {
           const branch = config.showGitBranch ? footerData.getGitBranch() : null;
           const line = buildLine(
             width,
-            config.showPath ? abbreviateHome(state.cwd, homedir()) : "",
-            skills.length ? `(${skills.join(" | ")})` : "",
-            branch ? ` ${branch}` : "",
+            config.showPath ? theme.fg("dim", abbreviateHome(state.cwd, homedir())) : "",
+            skills.length ? theme.fg("dim", `(${skills.join(" | ")})`) : "",
+            branch ? theme.fg("dim", ` ${branch}`) : "",
             config.showModel ? theme.bold(state.model) : "",
-            config.showContext ? theme.bold(state.context) : "",
+            config.showContext ? theme.fg("dim", theme.bold(state.context)) : "",
+            (available) => usageLimits.line(available, theme),
           );
-          return [theme.fg("dim", line)];
+          return [line];
         },
         invalidate(): void {},
         dispose,
       };
     });
+    usageLimits.select(ctx, enabled);
   }
 
   /** Cheap refresh: update plain state and request one render. */
@@ -215,14 +251,24 @@ export default function (pi: ExtensionAPI) {
   // ── Lifecycle events (passive; no footer re-install) ────────────────
 
   pi.on("session_start", async (_event, ctx) => {
+    usageLimits.stop();
     refresh(ctx);
     install(ctx);
   });
 
   pi.on("model_select", async (_event, ctx) => {
+    usageLimits.select(ctx, enabled);
     refresh(ctx);
   });
 
+  pi.on("after_provider_response", (event, ctx) => {
+    if (ctx.model) usageLimits.headers(ctx.model.provider, event.headers);
+  });
+
+  pi.on("provider_stream_event", (event) => {
+    usageLimits.stream(event.provider, event.model, event.data);
+  });
+
   pi.on("turn_end", async (_event, ctx) => {
     refresh(ctx);
   });
@@ -240,6 +286,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_shutdown", async () => {
+    usageLimits.stop();
     disposeFooter?.();
   });
 

package/extensions/lib/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Can Celik
+
+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/extensions/lib/quota-providers.ts

@@ -0,0 +1,264 @@
+// Provider endpoint and parsing logic copied and adapted from:
+// https://pi.dev/packages/@ogulcancelik/pi-minimal-footer
+// Copyright (c) 2025 Can Celik. MIT license: ./LICENSE.
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface QuotaWindow {
+  used: number;
+  seconds: number | null;
+  resetAt: number | null;
+}
+
+export function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function number(value: unknown): number | undefined {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "string" && value.trim()) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return undefined;
+}
+
+function resetSeconds(value: unknown): number | undefined {
+  const n = typeof value === "string" && !Number.isFinite(Number(value)) ? Date.parse(value) / 1000 : number(value);
+  const seconds = n === undefined ? undefined : n > 100_000_000_000 ? n / 1000 : n;
+  return seconds !== undefined && seconds > 0 && Number.isFinite(new Date(seconds * 1000).getTime()) ? seconds : undefined;
+}
+
+export function windowFrom(used: unknown, seconds: unknown, reset: unknown): QuotaWindow | null {
+  if (typeof used !== "number" || !Number.isFinite(used) || used < 0 || used > 100) return null;
+  if (seconds != null && (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0)) return null;
+  const validReset = typeof reset === "number" && reset > 0 && Number.isFinite(new Date(reset * 1000).getTime());
+  return { used, seconds: typeof seconds === "number" ? seconds : null, resetAt: validReset ? reset * 1000 : null };
+}
+
+export function shortest(windows: (QuotaWindow | null)[]): QuotaWindow | null {
+  return windows.filter((w): w is QuotaWindow => w !== null)
+    .sort((a, b) => (a.seconds ?? Infinity) - (b.seconds ?? Infinity) || b.used - a.used)[0] ?? null;
+}
+
+const ENDPOINTS: Record<string, string> = {
+  "openai-codex": "https://chatgpt.com/backend-api/wham/usage",
+  anthropic: "https://api.anthropic.com/api/oauth/usage",
+  "github-copilot": "https://api.github.com/copilot_internal/user",
+  "google-gemini-cli": "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
+  minimax: "https://api.minimax.io/v1/token_plan/remains",
+  "minimax-cn": "https://api.minimaxi.com/v1/token_plan/remains",
+  "kimi-coding": "https://api.kimi.com/coding/v1/usages",
+  "opencode-go": "https://opencode.ai/zen/go/v1/usage",
+};
+
+export function supportedOrigin(provider: string, baseUrl: string | undefined): boolean {
+  if (!ENDPOINTS[provider] || !baseUrl) return false;
+  try {
+    const url = new URL(baseUrl);
+    if (provider === "github-copilot") return url.protocol === "https:" && !url.port &&
+      (url.hostname === "githubcopilot.com" || url.hostname.endsWith(".githubcopilot.com"));
+    return url.origin === new URL(ENDPOINTS[provider]).origin;
+  } catch { return false; }
+}
+
+function storedOAuth(provider: string): Record<string, unknown> {
+  try {
+    const entry = record(record(JSON.parse(readFileSync(join(getAgentDir(), "auth.json"), "utf8")))[provider]);
+    return entry.type === "oauth" ? entry : {};
+  } catch { return {}; }
+}
+
+export async function usageRequest(ctx: ExtensionContext, model: NonNullable<ExtensionContext["model"]>): Promise<{ url: string; init: RequestInit } | null> {
+  const provider = model.provider;
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) {
+    // Pi exposes missing credentials as a message, alongside transient OAuth errors.
+    if (auth.error === `No API key found for "${provider}"`) return null;
+    throw new Error(auth.error);
+  }
+  if (!supportedOrigin(provider, auth.baseUrl ?? model.baseUrl)) return null;
+  const authorization = Object.entries(auth.headers ?? {}).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+  let token = typeof authorization === "string" ? /^Bearer\s+(.+)$/i.exec(authorization)?.[1] ?? auth.apiKey : auth.apiKey;
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (provider === "openai-codex") {
+    try {
+      const payload = record(JSON.parse(Buffer.from(token?.split(".")[1] ?? "", "base64url").toString("utf8")));
+      const id = record(payload["https://api.openai.com/auth"]).chatgpt_account_id;
+      if (typeof id !== "string" || !id) return null;
+      headers["ChatGPT-Account-Id"] = id;
+    } catch { return null; }
+  } else if (provider === "anthropic") {
+    if (!ctx.modelRegistry.isUsingOAuth?.(model) && !token?.startsWith("sk-ant-oat")) return null;
+    headers["anthropic-beta"] = "oauth-2025-04-20";
+  } else if (provider === "github-copilot") {
+    // Quota API needs the GitHub login token, not the exchanged inference token.
+    const refresh = storedOAuth(provider).refresh;
+    token = auth.env?.COPILOT_GITHUB_TOKEN ?? process.env.COPILOT_GITHUB_TOKEN ?? (typeof refresh === "string" ? refresh : undefined);
+    Object.assign(headers, { "Editor-Version": "vscode/1.96.2", "User-Agent": "GitHubCopilotChat/0.26.7", "X-Github-Api-Version": "2025-04-01" });
+  } else if (provider === "google-gemini-cli" && token?.startsWith("{")) {
+    const credentials = record(JSON.parse(token));
+    token = typeof credentials.token === "string" ? credentials.token : typeof credentials.accessToken === "string" ? credentials.accessToken : undefined;
+  }
+  if (!token) return null;
+  headers.Authorization = `${provider === "github-copilot" ? "token" : "Bearer"} ${token}`;
+  const init: RequestInit = { headers };
+  if (provider === "google-gemini-cli") {
+    init.method = "POST";
+    init.body = "{}";
+    headers["Content-Type"] = "application/json";
+  }
+  return { url: ENDPOINTS[provider], init };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function relativeReset(value: unknown): number | undefined {
+  const delay = number(value);
+  return delay !== undefined && delay >= 0 ? resetSeconds(Date.now() / 1000 + delay) : undefined;
+}
+
+export function parseUsageWindows(provider: string, model: string, payload: unknown): Record<string, QuotaWindow> | null {
+  if (!ENDPOINTS[provider]) return null;
+  const windows: Record<string, QuotaWindow> = {};
+  let recognized = false;
+  let malformed = !isObject(payload);
+  const data = record(payload);
+  const add = (key: string, value: unknown, parse: (w: Record<string, unknown>) => QuotaWindow | null) => {
+    if (value === undefined) return;
+    recognized = true;
+    if (value === null) return;
+    const window = isObject(value) ? parse(value) : null;
+    if (window) windows[key] = window;
+    else malformed = true;
+  };
+  const finish = () => {
+    if (Object.keys(windows).length) return windows;
+    if (recognized && !malformed) return null;
+    throw new Error(`${provider} usage response malformed`);
+  };
+  if (provider === "openai-codex") {
+    if (Object.hasOwn(data, "rate_limit")) {
+      recognized = true;
+      if (data.rate_limit !== null && !isObject(data.rate_limit)) malformed = true;
+      const limits = record(data.rate_limit);
+      for (const [key, name] of [["primary", "primary_window"], ["secondary", "secondary_window"]]) {
+        add(key, limits[name], (w) => windowFrom(number(w.used_percent),
+          Object.hasOwn(w, "limit_window_seconds") ? number(w.limit_window_seconds) ?? NaN : undefined,
+          resetSeconds(w.reset_at) ?? relativeReset(w.reset_after_seconds)));
+      }
+      if (isObject(data.rate_limit) && Object.keys(limits).length &&
+          !Object.hasOwn(limits, "primary_window") && !Object.hasOwn(limits, "secondary_window")) malformed = true;
+    }
+    return finish();
+  }
+  if (provider === "anthropic") {
+    for (const [name, seconds] of [["five_hour", 18000], ["seven_day", 604800]] as const) {
+      add(name, data[name], (w) => windowFrom(number(w.utilization), seconds, resetSeconds(w.resets_at)));
+    }
+    return finish();
+  }
+  if (provider === "minimax" || provider === "minimax-cn") {
+    const status = number(record(data.base_resp).status_code);
+    if (status !== undefined && status !== 0) throw new Error("MiniMax usage unavailable");
+    if (Object.hasOwn(data, "model_remains")) {
+      recognized = true;
+      if (data.model_remains !== null && !Array.isArray(data.model_remains)) malformed = true;
+    }
+    const buckets = Array.isArray(data.model_remains) ? data.model_remains.map(record) : [];
+    const w = buckets.find((b) => b.model_name === "general" && number(b.current_interval_status) === 1)
+      ?? buckets.find((b) => b.model_name === "general") ?? buckets.find((b) => number(b.current_interval_status) === 1) ?? buckets[0];
+    if (w) {
+      let supplied = false;
+      for (const [key, prefix, startKey, endKey, fallback] of [
+        ["interval", "current_interval", "start_time", "end_time", 18000],
+        ["weekly", "current_weekly", "weekly_start_time", "weekly_end_time", 604800],
+      ] as const) {
+        if (!Object.hasOwn(w, `${prefix}_remaining_percent`)) continue;
+        supplied = true;
+        const remaining = number(w[`${prefix}_remaining_percent`]);
+        const start = resetSeconds(w[startKey]), end = resetSeconds(w[endKey]);
+        add(key, w, () => windowFrom(remaining === undefined ? undefined : 100 - remaining,
+          start !== undefined && end !== undefined ? end - start : fallback, end));
+      }
+      if (!supplied) malformed = true;
+    }
+    return finish();
+  }
+  if (provider === "kimi-coding") {
+    const usedPercent = (detail: Record<string, unknown>) => {
+      const limit = number(detail.limit);
+      const used = Object.hasOwn(detail, "used") ? number(detail.used) : undefined;
+      const remaining = number(detail.remaining);
+      const count = Object.hasOwn(detail, "used") ? used : limit !== undefined && remaining !== undefined ? limit - remaining : undefined;
+      return limit !== undefined && limit > 0 && count !== undefined && count >= 0 && count <= limit ? count / limit * 100 : undefined;
+    };
+    const units: Record<string, number> = { TIME_UNIT_SECOND: 1, TIME_UNIT_MINUTE: 60, TIME_UNIT_HOUR: 3600, TIME_UNIT_DAY: 86400, TIME_UNIT_WEEK: 604800, TIME_UNIT_MONTH: 2592000 };
+    if (Object.hasOwn(data, "limits")) {
+      recognized = true;
+      if (data.limits !== null && !Array.isArray(data.limits)) malformed = true;
+    }
+    for (const value of Array.isArray(data.limits) ? data.limits : []) {
+      if (!isObject(value)) {
+        malformed = true;
+        continue;
+      }
+      const w = record(value), time = record(w.window), detail = record(w.detail);
+      const duration = number(time.duration), unit = typeof time.timeUnit === "string" ? time.timeUnit : "";
+      const seconds = duration !== undefined && units[unit] ? duration * units[unit] : NaN;
+      add(`${duration}:${unit}`, value, () => windowFrom(usedPercent(detail), seconds, resetSeconds(detail.resetTime)));
+    }
+    add("weekly", data.usage, (w) => windowFrom(usedPercent(w), 604800, resetSeconds(w.resetTime)));
+    return finish();
+  }
+  if (provider === "opencode-go") {
+    for (const [name, seconds] of [["rollingUsage", 18000], ["weeklyUsage", 604800], ["monthlyUsage", 2592000]] as const) {
+      add(name, data[name], (w) => windowFrom(number(w.usagePercent), seconds, relativeReset(w.resetInSec)));
+    }
+    return finish();
+  }
+  if (provider === "github-copilot") {
+    if (Object.hasOwn(data, "quota_snapshots")) {
+      recognized = true;
+      if (data.quota_snapshots !== null && !isObject(data.quota_snapshots)) malformed = true;
+    }
+    for (const [name, value] of Object.entries(isObject(data.quota_snapshots) ? data.quota_snapshots : {})) {
+      if (record(value).unlimited === true) continue;
+      add(name, value, (w) => {
+        const remaining = number(w.percent_remaining);
+        return windowFrom(remaining === undefined ? undefined : 100 - remaining, 2592000, resetSeconds(data.quota_reset_date_utc));
+      });
+    }
+    return finish();
+  }
+  // Gemini only exposes quotas for the selected model, or a recognizable model family.
+  if (Object.hasOwn(data, "buckets")) {
+    recognized = true;
+    if (data.buckets !== null && !Array.isArray(data.buckets)) malformed = true;
+  }
+  const buckets = Array.isArray(data.buckets) ? data.buckets.map(record) : [];
+  const valid = buckets.filter((b) => {
+    const remaining = number(b.remainingFraction);
+    const ok = typeof b.modelId === "string" && b.modelId.length > 0 && remaining !== undefined && remaining >= 0 && remaining <= 1;
+    if (!ok) malformed = true;
+    return ok;
+  });
+  const hasExact = buckets.some((b) => b.modelId === model);
+  const family = model.toLowerCase().includes("flash") ? "flash" : model.toLowerCase().includes("pro") ? "pro" : null;
+  const selected = valid.filter((b) => hasExact ? b.modelId === model : family && String(b.modelId).toLowerCase().includes(family));
+  for (const b of selected) {
+    const identity = `${b.modelId}:${typeof b.tokenType === "string" ? b.tokenType : ""}`;
+    let key = identity, duplicate = 2;
+    while (Object.hasOwn(windows, key)) key = `${identity}:${duplicate++}`;
+    add(key, b, () => windowFrom((1 - number(b.remainingFraction)!) * 100, undefined, resetSeconds(b.resetTime)));
+  }
+  return finish();
+}
+
+export function parseUsage(provider: string, model: string, payload: unknown): QuotaWindow | null {
+  return shortest(Object.values(parseUsageWindows(provider, model, payload) ?? {}));
+}

package/extensions/lib/usage-limits.ts

@@ -0,0 +1,225 @@
+// Usage logic copied and adapted from https://pi.dev/packages/@ogulcancelik/pi-minimal-footer.
+// Copyright (c) 2025 Can Celik. MIT license: ./LICENSE.
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+
+import { parseUsageWindows, record, shortest, supportedOrigin, usageRequest, windowFrom } from "./quota-providers.js";
+import type { QuotaWindow } from "./quota-providers.js";
+
+const REFRESH_MS = 4 * 60_000;
+
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(new Error("Usage request aborted"));
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    // Observe late failures even after abort has settled the caller's await.
+    promise.then((value) => {
+      signal.removeEventListener("abort", abort);
+      resolve(value);
+    }, (error) => {
+      signal.removeEventListener("abort", abort);
+      reject(error);
+    });
+  });
+}
+
+function passiveNumber(value: unknown): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && value.trim()) return Number(value);
+  return NaN;
+}
+
+function passiveWindow(used: unknown, seconds: number | undefined, reset: unknown, cached: QuotaWindow | undefined): QuotaWindow | null {
+  const window = windowFrom(used, seconds === undefined ? cached?.seconds : seconds, reset);
+  // Omitted metadata belongs to the same window only while its duration agrees.
+  if (window && reset === undefined && window.seconds === cached?.seconds) window.resetAt = cached.resetAt;
+  return window;
+}
+
+function fromHeaders(provider: string, headers: Record<string, string>, cached: Record<string, QuotaWindow>): Record<string, QuotaWindow> {
+  const windows: Record<string, QuotaWindow> = {};
+  let definitions: readonly (readonly [string, string, number?])[];
+  if (provider === "openai-codex") {
+    definitions = [["primary", "primary"], ["secondary", "secondary"]];
+  } else if (provider === "anthropic") {
+    definitions = [["five_hour", "5h", 18000], ["seven_day", "7d", 604800]];
+  } else {
+    return windows;
+  }
+  const codex = provider === "openai-codex";
+  const usedSuffix = codex ? "used-percent" : "utilization";
+  const resetSuffix = codex ? "reset-at" : "reset";
+  for (const [key, name, defaultSeconds] of definitions) {
+    const prefix = codex ? `x-codex-${name}` : `anthropic-ratelimit-unified-${name}`;
+    const used = passiveNumber(headers[`${prefix}-${usedSuffix}`]) * (codex ? 1 : 100);
+    const durationKey = `${prefix}-window-minutes`;
+    const resetKey = `${prefix}-${resetSuffix}`;
+    const seconds = Object.hasOwn(headers, durationKey) ? passiveNumber(headers[durationKey]) * 60 : defaultSeconds;
+    const reset = Object.hasOwn(headers, resetKey) ? passiveNumber(headers[resetKey]) : undefined;
+    const window = passiveWindow(used, seconds, reset, cached[key]);
+    if (window) windows[key] = window;
+  }
+  return windows;
+}
+
+function fromStream(data: unknown, cached: Record<string, QuotaWindow>): Record<string, QuotaWindow> {
+  const event = record(data);
+  if (event.type !== "codex.rate_limits") return {};
+  // Other metered pools may be specific to a different model.
+  const pool = event.metered_limit_name ?? event.limit_name;
+  if (pool !== undefined && pool !== "codex") return {};
+  const limits = record(event.rate_limits);
+  const windows: Record<string, QuotaWindow> = {};
+  for (const key of ["primary", "secondary"]) {
+    const w = record(limits[key]);
+    const window = passiveWindow(passiveNumber(w.used_percent),
+      Object.hasOwn(w, "window_minutes") ? passiveNumber(w.window_minutes) * 60 : undefined,
+      Object.hasOwn(w, "reset_at") ? passiveNumber(w.reset_at) : undefined, cached[key]);
+    if (window) windows[key] = window;
+  }
+  return windows;
+}
+
+/** Owns quota requests and timers for the currently displayed footer. */
+export class UsageLimits {
+  private provider: string | null = null;
+  private selection: string | null = null;
+  private ctx: ExtensionContext | null = null;
+  private windows: Record<string, QuotaWindow> = {};
+  private updatedAt: Record<string, number> = {};
+  private stale = false;
+  private attemptedAt = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private request: AbortController | null = null;
+
+  constructor(private readonly render: () => void) {}
+
+  stop(): void {
+    this.ctx = null;
+    this.provider = null;
+    this.selection = null;
+    this.windows = {};
+    this.updatedAt = {};
+    this.stale = false;
+    this.attemptedAt = 0;
+    this.cancelRequest();
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  select(ctx: ExtensionContext, enabled: boolean): void {
+    const model = ctx.model;
+    if (!enabled || ctx.mode !== "tui" || !model || !supportedOrigin(model.provider, model.baseUrl)) {
+      this.stop();
+      return;
+    }
+    const selection = model.provider + (model.provider === "google-gemini-cli" ? ":" + model.id : "");
+    if (this.selection === selection) { this.ctx = ctx; return; }
+    this.stop();
+    this.ctx = ctx;
+    this.provider = model.provider;
+    this.selection = selection;
+    void this.poll();
+  }
+
+  headers(provider: string, headers: Record<string, string>): void {
+    if (provider !== this.provider) return;
+    const lower = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+    this.accept(fromHeaders(provider, lower, this.windows));
+  }
+
+  stream(provider: string, model: string, data: unknown): void {
+    if (provider !== "openai-codex" || provider !== this.provider || model !== this.ctx?.model?.id) return;
+    this.accept(fromStream(data, this.windows));
+  }
+
+  private cancelRequest(): void {
+    this.request?.abort();
+    this.request = null;
+  }
+
+  private selectedWindow(): [string, QuotaWindow] | null {
+    const window = shortest(Object.values(this.windows));
+    return window ? Object.entries(this.windows).find(([, value]) => value === window)! : null;
+  }
+
+  private accept(windows: Record<string, QuotaWindow>): void {
+    if (!this.ctx || !Object.keys(windows).length) return;
+    Object.assign(this.windows, windows);
+    for (const key of Object.keys(windows)) this.updatedAt[key] = Date.now();
+    const selected = this.selectedWindow()!;
+    if (Object.hasOwn(windows, selected[0])) {
+      // Only a response for the displayed window supersedes its background refresh.
+      this.cancelRequest();
+      this.stale = false;
+    }
+    this.schedule();
+    this.render();
+  }
+
+  private schedule(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    if (!this.ctx || this.request) return;
+    const selected = this.selectedWindow();
+    let next = Math.max(this.attemptedAt, selected ? this.updatedAt[selected[0]] : 0) + REFRESH_MS;
+    const resetAt = selected?.[1].resetAt;
+    if (resetAt != null && resetAt > this.attemptedAt) next = Math.min(next, resetAt);
+    this.timer = setTimeout(() => { this.timer = null; void this.poll(); }, Math.max(1, next - Date.now()));
+    this.timer.unref();
+  }
+
+  private async poll(): Promise<void> {
+    const ctx = this.ctx;
+    const model = ctx?.model;
+    if (!ctx || !model || this.request) return;
+    const provider = this.provider!;
+    const modelId = model.id;
+    const controller = new AbortController();
+    this.request = controller;
+    this.attemptedAt = Date.now();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    timeout.unref();
+    try {
+      const request = await abortable(usageRequest(ctx, model), controller.signal);
+      if (this.request !== controller) return;
+      if (controller.signal.aborted) throw new Error("Usage authentication timed out");
+      if (!request) { this.windows = {}; this.updatedAt = {}; return; }
+      const response = await abortable(fetch(request.url, { ...request.init, signal: controller.signal, redirect: "error" }), controller.signal);
+      if (!response.ok) { await abortable(Promise.resolve(response.body?.cancel()), controller.signal); throw new Error("Usage unavailable"); }
+      const windows = parseUsageWindows(provider, modelId, await abortable(response.json(), controller.signal));
+      if (this.request !== controller) return;
+      if (controller.signal.aborted) throw new Error("Usage request timed out");
+      this.windows = windows ?? {};
+      this.updatedAt = Object.fromEntries(Object.keys(this.windows).map((key) => [key, this.attemptedAt]));
+      this.stale = false;
+    } catch {
+      if (this.request === controller) this.stale = true;
+    } finally {
+      clearTimeout(timeout);
+      if (this.request === controller) {
+        this.request = null;
+        this.schedule();
+        this.render();
+      }
+    }
+  }
+
+  line(width: number, theme: Theme): string | null {
+    const window = this.selectedWindow()?.[1];
+    if (!this.ctx || !window || width < (window.resetAt === null ? 1 : 6)) return null;
+    const date = window.resetAt === null ? null : new Date(window.resetAt);
+    const time = date ? `↻${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}` : "";
+    const cells = Math.min(5, Math.max(0, width - (time ? 7 : 0)));
+    const steps = Math.round(window.used / 100 * cells * 8);
+    const filled = "⣿".repeat(Math.floor(steps / 8)) + ["", "⡀", "⣀", "⣄", "⣤", "⣦", "⣶", "⣷"][steps % 8];
+    const empty = "⠀".repeat(cells - Math.ceil(steps / 8));
+    const stale = this.stale || (window.resetAt !== null && Date.now() >= window.resetAt);
+    const color = stale ? "dim" : window.used >= 92 ? "error" : window.used >= 85 ? "warning" : "success";
+    const bar = cells ? theme.fg(color, filled) + theme.fg("dim", empty) + (time ? " " : "") : "";
+    return bar + theme.fg("dim", time);
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-minimal-footer",
-  "version": "0.1.3",
-  "description": "A minimal footer extension for pi — clean status line with path, skills, model, and context usage.",
+  "version": "0.2.0",
+  "description": "An opinionated minimal footer extension for Pi — clean status line with path, extension statuses, model, and context usage.",
   "keywords": [
     "pi-package",
     "pi-extension",