pi-minimal-footer 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-06
+
+### Added
+
+- `minFooter.powerlineSeparator` (default `true`); set to `false` for a single-space fallback when the terminal font lacks Powerline glyphs
+
+### Changed
+
+- Keep README focused on installation and daily use; move design constraints, developer guidance, and provider details into `VISION.md`
+- Separate directory and git branch with ``; render each extension status as its own `` tab, without footer-added parentheses or pipes
+- Group model, context, and quota with spaced ` · ` separators
+- Join the quota bar and reset label without an intervening space
+- Show reset labels as local `↻HH:mm` through 24 hours, remaining whole days/hours above 24 hours (e.g., `↻1d8h`), and whole days above 10 days (e.g., `↻12d`)
+- Grow the quota bar from five to ten cells using spare footer columns, improving steps from 2.5% to 1.25% without shortening other fields; retain the smaller fallback on very narrow terminals
+
+## [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 +129,9 @@ 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.3.0...HEAD
+[0.3.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.2.0...v0.3.0
+[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

@@ -1,75 +1,45 @@
 # pi-minimal-footer
 
 <p>
-  <a href="https://www.npmjs.com/package/pi-minimal-footer">
-    <img src="https://img.shields.io/npm/v/pi-minimal-footer" alt="npm version">
-  </a>
-  <a href="https://www.npmjs.com/package/pi-minimal-footer">
-    <img src="https://img.shields.io/npm/dt/pi-minimal-footer" alt="npm downloads">
-  </a>
-  <a href="LICENSE">
-    <img src="https://img.shields.io/npm/l/pi-minimal-footer" alt="license">
-  </a>
-  <a href="https://pi.dev/packages/pi-minimal-footer">
-    <img src="https://img.shields.io/badge/pi-package-1a1a2e" alt="pi package">
-  </a>
+  <a href="https://www.npmjs.com/package/pi-minimal-footer"><img src="https://img.shields.io/npm/v/pi-minimal-footer" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/pi-minimal-footer"><img src="https://img.shields.io/npm/dt/pi-minimal-footer" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/pi-minimal-footer" alt="license"></a>
+  <a href="https://pi.dev/packages/pi-minimal-footer"><img src="https://img.shields.io/badge/pi-package-1a1a2e" alt="pi package"></a>
 </p>
 
-A clean, compact one-line footer for [Pi](https://github.com/earendil-works/pi).
+An opinionated, compact one-line footer for [Pi](https://github.com/earendil-works/pi).
 
+```text
+~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · ⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h
 ```
-~/path/to/dir                (status1 | status2)   main  sonnet  12/128k
-```
 
-![pi-minimal-footer screenshot](media/github-preview.png)
+Path and branch on the left; extension statuses, model, context, and provider quota on the right. Shrinks to fit narrow terminals. Interactive terminal UI only.
+
+![Footer preview: ~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · ⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h](media/github-preview.png)
+
+*Screenshot shows an earlier layout; the text preview reflects current source.*
 
 ## Install
 
-Available on the [Pi package gallery](https://pi.dev/packages/pi-minimal-footer).
+Requires Node.js >=22.19.0.
 
 ```bash
-# From npm (recommended)
 pi install npm:pi-minimal-footer
-
-# From git
+# Or install from source:
 pi install git:github.com/Ryu-CZ/pi-minimal-footer
-
-# Manual — copy into your extensions directory
-cp -r extensions/* ~/.pi/agent/extensions/
-
-# Development — symlink for live edits
-ln -s "$PWD/extensions" ~/.pi/agent/extensions/minimal-footer
 ```
 
-## Development
-
-Requires Node.js >=22.19.0. Run `npm ci`, `npm run check`, and `npm test`. Pi loads TypeScript directly; no build is needed. For an isolated local preview, run `pi --no-extensions -e ./extensions/index.ts`. After source edits, use `/reload` in Pi. Tests use Pi 1.0.3 and make no provider requests.
-
-## Features
-
-- **Working directory** — home abbreviated as `~`; paths outside home remain absolute
-- **Extension statuses** — text reported by extensions through Pi's status API (`showSkills` retains its existing setting name; it does not discover installed skills)
-- **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.
-
-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 footer appears only in Pi's interactive terminal UI, not in print, JSON, or RPC modes.
-
 ## Commands
 
-| Command | Description |
+| Command | Action |
 |---|---|
-| `/minfooter` | Toggle the extension on/off |
+| `/minfooter` | Toggle footer |
 | `/minfooter on` | Enable |
 | `/minfooter off` | Disable |
 
-> The `/minfooter` command only toggles the `enabled` flag. To show or hide individual segments, edit the agent settings file directly.
-
-## Configuration
+## Settings
 
-Settings live in Pi's configured agent directory, in `settings.json` under the `minFooter` key (normally `~/.pi/agent/settings.json`). The footer reads settings on session start and when `/minfooter` is run; external edits do not take effect until one of those actions (there is no file watcher). Unrelated settings are preserved when toggling.
+Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.json`). All defaults are shown below. Apply edits with `/reload` or `/minfooter on`.
 
 ```json
 {
@@ -79,7 +49,30 @@ Settings live in Pi's configured agent directory, in `settings.json` under the `
     "showSkills": true,
     "showPath": true,
     "showModel": true,
-    "showContext": true
+    "showContext": true,
+    "powerlineSeparator": true
   }
 }
 ```
+
+- `showSkills` shows **extension status text**, not installed skills. The footer does not add the example statuses itself.
+- Set `powerlineSeparator` to `false` for plain spaces instead of `` / `` if your font lacks those glyphs. The git icon `` also needs a compatible font; hide it with `showGitBranch: false` if needed.
+- Context `42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
+
+## Reading quota
+
+`⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h` shows **account quota used**, not context usage.
+
+- Bar: 5–10 cells, expanding into spare space; green below 85%, amber from 85%, red from 92%. Dim means cached after a refresh failure. Very narrow terminals may show fewer cells or only the reset label.
+- Reset: local `↻HH:mm` through 24 hours; whole days/hours above 24 hours (`↻1d8h`); whole days above 10 days (`↻12d`). Remaining durations round down. No reset reported means bar only.
+- Shows the shortest available quota window for the selected provider. Missing credentials, unsupported/local models, or absent limits hide quota. Custom proxy endpoints are not polled.
+
+Supported adapters: **OpenAI Codex, Claude OAuth, GitHub Copilot, Gemini CLI, MiniMax, Kimi Coding, and OpenCode Go**. Uses Pi's existing credentials; ordinary Claude API keys do not expose subscription quota. Provider availability varies; authenticated endpoints remain unverified live.
+
+## Development & design
+
+See [VISION.md](VISION.md) for design constraints, local development, provider details, and verification limits. Release history: [CHANGELOG.md](CHANGELOG.md).
+
+## Credits
+
+Provider usage-fetching and parsing logic **copied and adapted from [Can Celik (@ogulcancelik)'s pi-minimal-footer](https://pi.dev/packages/@ogulcancelik/pi-minimal-footer)**. Upstream MIT attribution is retained in [extensions/lib/LICENSE](extensions/lib/LICENSE).

package/VISION.md

@@ -0,0 +1,106 @@
+# Vision & developer guide
+
+## Purpose
+
+An opinionated footer that answers three questions at a glance: where am I, what is running, and how close am I to a limit? Keep one line, avoid redundant labels, and never exceed the terminal width.
+
+The [README](README.md) is the user manual. This document records current design and contributor guidance—not a speculative roadmap.
+
+## Layout contract
+
+- Directory and git branch form the left group, separated by ``.
+- Each extension status is its own `` tab. Preserve the supplied text; do not invent status labels, parentheses, or pipes.
+- Model, context, and quota form the rightmost group, separated by ` · `. Model identifies the running engine; context describes its usage; quota stays anchored at the right edge.
+- Powerline separators are dim. `powerlineSeparator: false` replaces them with a single space. Font availability cannot be detected reliably.
+- Measure terminal columns with `visibleWidth`, not string length. Preserve ANSI styling and wide-character accounting when truncating.
+
+### Space allocation
+
+Reserve quota and model/context before allocating location and statuses. Statuses and location may shorten or disappear; on sufficiently narrow terminals, model/context can also shorten or disappear.
+
+Lay out other fields with a five-cell quota bar first. Grow the bar only into leftover columns, up to ten cells—never truncate another field solely to enlarge it. At extreme widths, shrink below five cells, show only the reset label, or hide quota if the label cannot fit.
+
+Five cells give 2.5% steps; ten give 1.25%. Fill rounds to the nearest eighth-cell step. Only the final partially filled cell uses an intermediate shade:
+
+| Cell | Fill |
+|---|---|
+| `⠀` | Empty |
+| `⡀` | One-eighth |
+| `⣀` | Quarter |
+| `⣄` | Three-eighths |
+| `⣤` | Half |
+| `⣦` | Five-eighths |
+| `⣶` | Three-quarter |
+| `⣷` | Seven-eighths |
+| `⣿` | Full |
+
+The bar and reset label have no intervening space. Reset formatting uses local clock time through 24 hours, remaining whole days/hours above 24 hours, and whole days above 10 days. Exactly 24 hours stays clock time; exactly 10 days is `↻10d0h`. Missing reset metadata leaves the bar visible without a label.
+
+## Quota contract
+
+Display only the selected provider's shortest applicable window. Account quota and model context usage are separate measurements.
+
+| Provider | Selection / caveat |
+|---|---|
+| OpenAI Codex (`openai-codex`) | Shortest primary/secondary window; supports absolute reset timestamps and relative reset delays |
+| Claude (`anthropic`, OAuth) | Five-hour window, or weekly fallback; ordinary API keys do not expose subscription quota |
+| GitHub Copilot (`github-copilot`) | Most-used limited quota bucket; unlimited buckets hidden |
+| Gemini CLI (`google-gemini-cli`) | Selected model, with Pro/Flash family fallback; needs a configured provider/model |
+| MiniMax (`minimax`, `minimax-cn`) | Prefer general bucket, then active bucket, then first bucket; shortest interval/weekly window |
+| Kimi Coding (`kimi-coding`) | Shortest available window; accepts used or remaining counts and week/month durations |
+| OpenCode Go (`opencode-go`) | Shortest rolling/weekly/monthly window |
+
+Reuse Pi's selected-provider credentials. Copilot uses the GitHub login token from Pi's configured agent directory or `COPILOT_GITHUB_TOKEN`. Pi 1.0.3 does not include Gemini CLI in its built-in model catalog. Do not poll custom proxy endpoints or make model requests to obtain usage.
+
+### Refresh and failure behavior
+
+- Consume passive Codex response headers/stream events and Claude quota headers when available.
+- Otherwise fetch on startup/provider switch, then every four minutes without a fresh response update; also refresh at the reported reset time.
+- Merge partial windows. A weekly-only signal must not replace a cached shorter window or postpone its refresh.
+- Bound authentication, fetch, and response-body parsing by a shared five-second timeout. Release stalled work so polling can recover.
+- Provider switches clear quota immediately, cancel pending work, and invalidate late results. Gemini model switches also refresh model-specific quota.
+- Missing credentials and explicit empty/unlimited responses clear quota. Temporary authentication, network, or parsing failures retain only the current provider's cached quota, dimmed; without cache, hide it.
+- Invalid optional reset metadata must not discard otherwise valid usage. Zero usage is an empty bar, not an absent quota.
+- Stop requests and timers on disable, disposal, and session shutdown.
+
+### Verification limits
+
+Parsing and lifecycle behavior have automated coverage. Authenticated provider endpoints have **not** been tested live. OpenCode Go's bearer-token response format and Copilot's public endpoint/enterprise compatibility remain unverified.
+
+The comparison with [mtrojnar/pi-usage](https://github.com/mtrojnar/pi-usage) informed timeout, validation, and partial-update handling; its OpenCode implementation uses an authenticated dashboard rather than this adapter's bearer-token endpoint.
+
+## Local development
+
+Requires Node.js >=22.19.0. Tests currently use Pi 1.0.3 and mock provider requests.
+
+```bash
+npm ci
+npm run check
+npm test
+
+# Isolated interactive preview; Pi loads TypeScript directly, no build needed:
+pi --no-extensions -e ./extensions/index.ts
+```
+
+Use `/reload` after edits. For a persistent development install:
+
+```bash
+ln -s "$PWD/extensions" ~/.pi/agent/extensions/minimal-footer
+```
+
+For a manual install, copy `extensions/*` into `~/.pi/agent/extensions/`.
+
+### Code map
+
+- `extensions/index.ts`: settings, state refresh, layout, footer lifecycle, and `/minfooter`.
+- `extensions/lib/usage-limits.ts`: quota refresh, cache, cancellation, and bar/reset rendering.
+- `extensions/lib/quota-providers.ts`: authentication, endpoint selection, and response normalization.
+- `tests/`: loader-based lifecycle/layout regression tests and quota parsing tests.
+
+Settings live under `minFooter` in Pi's configured agent directory. Read them at session start or explicit toggle; ordinary refreshes use cached settings. Preserve unrelated settings on writes. Only install the footer in interactive terminal mode.
+
+### Checking changes
+
+For behavior changes, run `npm run check` and `npm test`. Layout tests should cover narrow widths, ANSI text, wide Unicode, field priority, and both separator modes. Quota changes should cover provider switches, timeouts, stale cache, partial updates, and malformed/missing metadata as applicable. Preview in a real terminal for font-dependent appearance; automated width checks cannot prove glyph availability.
+
+Keep release notes in [CHANGELOG.md](CHANGELOG.md), and keep the README focused on installation and daily use. Preserve [upstream MIT attribution](extensions/lib/LICENSE) when changing adapted provider code.

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 ──────────────────────────────────────────────────────────
 
@@ -28,6 +29,7 @@ interface Settings {
     showPath?: boolean;
     showModel?: boolean;
     showContext?: boolean;
+    powerlineSeparator?: boolean;
   };
 }
 
@@ -40,6 +42,7 @@ const DEFAULT_SETTINGS: FooterSettings = {
   showPath: true,
   showModel: true,
   showContext: true,
+  powerlineSeparator: true,
 };
 
 function settingsPath(): string {
@@ -123,32 +126,58 @@ 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).
+// Keep quota and reset time together; shorten location/statuses before model/context.
+// All segment measurements use visible widths, including ANSI and wide characters.
 
-function buildLine(width: number, path: string, statuses: string, branch: string, model: string, context: string): string {
-  if (width <= 0) return "";
-  const core = [model, context].filter(Boolean).join("  ");
-  const right = [statuses, branch, core].filter(Boolean).join("  ");
-  const rightWidth = visibleWidth(right);
+const MODEL_GAP = " · ";
+const QUOTA_GAP = " · ";
+const LOCATION_GAP_WIDTH = 3;
+const MIN_TEXT_WIDTH = 4;
+const MIN_STATUS_WIDTH = 12;
 
-  if (rightWidth < width) {
-    const left = path ? truncateToWidth(path, width - rightWidth - 1, "...", true) : " ".repeat(width - rightWidth - 1);
-    return `${left} ${right}`;
+function buildLine(width: number, path: string, statuses: string, branch: string, model: string, context: string,
+  usage: (available: number, maxCells?: number) => string | null, statusSeparator: string, locationSeparator: string): string {
+  if (width <= 0) return "";
+  let core = [model, context].filter(Boolean).join(MODEL_GAP);
+  const quota = usage(width) ?? "";
+  const quotaGapWidth = quota && core ? QUOTA_GAP.length : 0;
+  const coreBudget = Math.max(0, width - visibleWidth(quota) - quotaGapWidth);
+  if (quota && coreBudget < MIN_TEXT_WIDTH) {
+    core = "";
+  } else if (visibleWidth(core) > coreBudget) {
+    const modelGapWidth = model && context ? MODEL_GAP.length : 0;
+    const modelBudget = coreBudget - visibleWidth(context) - modelGapWidth;
+    if (modelBudget > 0) {
+      core = [truncateToWidth(model, modelBudget, "..."), context].filter(Boolean).join(MODEL_GAP);
+    } else {
+      core = truncateToWidth(context || model, coreBudget, "...");
+    }
   }
-
-  // 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 protectedRight = [core, quota].filter(Boolean).join(QUOTA_GAP);
+  const branchReservation = branch ? visibleWidth(branch) + LOCATION_GAP_WIDTH : 0;
+  const statusBudget = width - visibleWidth(protectedRight) - branchReservation - visibleWidth(statusSeparator);
+  let fittedStatuses = "";
+  if (statusBudget >= MIN_STATUS_WIDTH) {
+    fittedStatuses = statuses;
+    if (visibleWidth(statuses) > statusBudget) {
+      fittedStatuses = truncateToWidth(statuses, statusBudget, "...");
+    }
+  }
+  let right = [fittedStatuses, protectedRight].filter(Boolean).join(statusSeparator);
+  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 ? visibleWidth(locationSeparator) : 0;
+  const pathBudget = leftBudget - visibleWidth(fittedBranch) - pathGapWidth;
+  const fittedPath = pathBudget >= MIN_TEXT_WIDTH ? truncateToWidth(path, pathBudget, "...") : "";
+  const left = [fittedPath, fittedBranch].filter(Boolean).join(locationSeparator);
+  if (quota) {
+    const spareWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - locationGapWidth);
+    const expandedQuota = usage(visibleWidth(quota) + spareWidth, 10) ?? quota;
+    const expandedCore = [core, expandedQuota].filter(Boolean).join(QUOTA_GAP);
+    right = [fittedStatuses, expandedCore].filter(Boolean).join(statusSeparator);
+  }
+  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;
@@ -190,20 +224,25 @@ export default function (pi: ExtensionAPI) {
             ? [...footerData.getExtensionStatuses().values()].filter((s) => s.trim())
             : [];
           const branch = config.showGitBranch ? footerData.getGitBranch() : null;
+          const statusSeparator = config.powerlineSeparator ? theme.fg("dim", "  ") : " ";
           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 ? statusSeparator + skills.map((s) => theme.fg("dim", s)).join(statusSeparator) : "",
+            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, maxCells = 5) => usageLimits.line(available, theme, maxCells),
+            statusSeparator,
+            config.powerlineSeparator ? theme.fg("dim", "  ") : " ",
           );
-          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 +254,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 +289,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,234 @@
+// 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, maxCells = 10): string | null {
+    const window = this.selectedWindow()?.[1];
+    if (!this.ctx || !window) return null;
+    const now = Date.now();
+    const date = window.resetAt === null ? null : new Date(window.resetAt);
+    const remaining = window.resetAt === null ? 0 : window.resetAt - now;
+    const day = 24 * 60 * 60 * 1000;
+    let time = date ? `↻${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}` : "";
+    if (remaining > 10 * day) {
+      time = `↻${Math.floor(remaining / day)}d`;
+    } else if (remaining > day) {
+      time = `↻${Math.floor(remaining / day)}d${Math.floor(remaining % day / (60 * 60 * 1000))}h`;
+    }
+    if (width < (time ? time.length : 1)) return null;
+    const cells = Math.min(maxCells, Math.max(0, width - time.length));
+    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 && 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) : "";
+    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.3.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",
@@ -20,6 +20,7 @@
     "extensions/",
     "LICENSE",
     "README.md",
+    "VISION.md",
     "package.json",
     "media/"
   ],