pi-minimal-footer 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-10-06
+
+### Changed
+
+- Rename provider quota terminology to subscription usage in documentation, code, and tests; behavior is unchanged
+
 ## [0.3.1] - 2026-10-06
 
 ### Fixed
@@ -141,7 +147,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.3.1...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.0...v0.3.1
 [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

package/README.md

@@ -9,11 +9,7 @@
 
 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 and branch on the left; extension statuses, model, context, and provider quota on the right. Shrinks to fit narrow terminals. Interactive terminal UI only.
+Path and branch on the left; extension statuses, model, context, and subscription usage bar 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)
 
@@ -57,15 +53,15 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
 - 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
+## Reading subscription usage
 
-`⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h` shows **account quota used**, not context usage.
+`⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h` shows **subscription allowance 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.
+- Shows the shortest available usage window for the selected provider. Missing credentials, unsupported/local models, or absent limits hide the usage bar. 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.
+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 usage. Provider availability varies; authenticated endpoints remain unverified live.
 
 ## Development & design
 

package/VISION.md

@@ -10,15 +10,15 @@ The [README](README.md) is the user manual. This document records current design
 
 - 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.
+- Model, context, and subscription usage form the rightmost group, separated by ` · `. Model identifies the running engine; context describes its usage; the usage bar 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.
+Reserve the usage bar 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.
+Lay out other fields with a five-cell usage 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 the usage bar 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:
 
@@ -36,14 +36,14 @@ Five cells give 2.5% steps; ten give 1.25%. Fill rounds to the nearest eighth-ce
 
 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
+## Subscription usage contract
 
-Display only the selected provider's shortest applicable window. Account quota and model context usage are separate measurements.
+Display only the selected provider's shortest applicable window. Subscription usage 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 |
+| Claude (`anthropic`, OAuth) | Five-hour window, or weekly fallback; ordinary API keys do not expose subscription usage |
 | 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 |
@@ -58,9 +58,9 @@ Reuse Pi's selected-provider credentials. Copilot uses the GitHub login token fr
 - 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.
+- Provider switches clear usage immediately, cancel pending work, and invalidate late results. Gemini model switches also refresh model-specific usage.
+- Missing credentials and explicit empty/unlimited responses clear usage. Temporary authentication, network, or parsing failures retain only the current provider's cached usage, dimmed; without cache, hide it.
+- Invalid optional reset metadata must not discard otherwise valid usage. Zero usage is an empty bar, not an absent usage bar.
 - Stop requests and timers on disable, disposal, and session shutdown.
 
 ### Verification limits
@@ -93,14 +93,14 @@ 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.
+- `extensions/lib/usage-limits.ts`: usage refresh, cache, cancellation, and bar/reset rendering.
+- `extensions/lib/usage-providers.ts`: authentication, endpoint selection, and response normalization.
+- `tests/`: loader-based lifecycle/layout regression tests and usage 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.
+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. Subscription usage 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

@@ -129,11 +129,11 @@ function updateState(ctx: ExtensionContext, state: FooterState): void {
 
 // ── Layout ────────────────────────────────────────────────────────────
 //
-// Keep quota and reset time together; shorten location/statuses before model/context.
+// Keep the usage bar and reset time together; shorten location/statuses before model/context.
 // All segment measurements use visible widths, including ANSI and wide characters.
 
 const MODEL_GAP = " · ";
-const QUOTA_GAP = " · ";
+const USAGE_GAP = " · ";
 const LOCATION_GAP_WIDTH = 3;
 const MIN_TEXT_WIDTH = 4;
 const MIN_STATUS_WIDTH = 12;
@@ -146,10 +146,10 @@ function buildLine(
   if (width <= 0) return "";
   let core = [model, context].filter(Boolean).join(MODEL_GAP);
   // Budget the compact bar first; its expanded size must not drive truncation decisions.
-  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) {
+  const usageBar = usage(width) ?? "";
+  const usageGapWidth = usageBar && core ? USAGE_GAP.length : 0;
+  const coreBudget = Math.max(0, width - visibleWidth(usageBar) - usageGapWidth);
+  if (usageBar && coreBudget < MIN_TEXT_WIDTH) {
     core = "";
   } else if (visibleWidth(core) > coreBudget) {
     const modelGapWidth = model && context ? MODEL_GAP.length : 0;
@@ -160,7 +160,7 @@ function buildLine(
       core = truncateToWidth(context || model, coreBudget, "...");
     }
   }
-  const protectedRight = [core, quota].filter(Boolean).join(QUOTA_GAP);
+  const protectedRight = [core, usageBar].filter(Boolean).join(USAGE_GAP);
   const branchReservation = branch ? visibleWidth(branch) + LOCATION_GAP_WIDTH : 0;
   const statusBudget = width - visibleWidth(protectedRight) - branchReservation - visibleWidth(statusSeparator);
   let fittedStatuses = "";
@@ -178,12 +178,12 @@ function buildLine(
   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) {
-    // A dropped left group needs no divider; those columns belong to the quota bar instead.
+  if (usageBar) {
+    // A dropped left group needs no divider; those columns belong to the usage bar instead.
     const interGroupGapWidth = left && right ? LOCATION_GAP_WIDTH : 0;
     const spareWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - interGroupGapWidth);
-    const expandedQuota = usage(visibleWidth(quota) + spareWidth, MAX_BAR_CELLS) ?? quota;
-    const expandedCore = [core, expandedQuota].filter(Boolean).join(QUOTA_GAP);
+    const expandedUsageBar = usage(visibleWidth(usageBar) + spareWidth, MAX_BAR_CELLS) ?? usageBar;
+    const expandedCore = [core, expandedUsageBar].filter(Boolean).join(USAGE_GAP);
     right = [fittedStatuses, expandedCore].filter(Boolean).join(statusSeparator);
   }
   return left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right;
@@ -225,7 +225,7 @@ export default function (pi: ExtensionAPI) {
         if (disposed) return;
         disposed = true;
         unsub();
-        // A superseded renderer must not stop its replacement's quota polling.
+        // A superseded renderer must not stop its replacement's usage polling.
         if (requestRender === request) {
           requestRender = null;
           usageLimits.stop();

package/extensions/lib/usage-limits.ts

@@ -2,8 +2,8 @@
 // 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";
+import { parseUsageWindows, record, shortest, supportedOrigin, usageRequest, windowFrom } from "./usage-providers.js";
+import type { UsageWindow } from "./usage-providers.js";
 
 const REFRESH_MS = 4 * 60_000;
 const REQUEST_TIMEOUT_MS = 5000;
@@ -55,15 +55,15 @@ function passiveNumber(value: unknown): number {
   return NaN;
 }
 
-function passiveWindow(used: unknown, seconds: number | undefined, reset: unknown, cached: QuotaWindow | undefined): QuotaWindow | null {
+function passiveWindow(used: unknown, seconds: number | undefined, reset: unknown, cached: UsageWindow | undefined): UsageWindow | 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> = {};
+function fromHeaders(provider: string, headers: Record<string, string>, cached: Record<string, UsageWindow>): Record<string, UsageWindow> {
+  const windows: Record<string, UsageWindow> = {};
   let definitions: readonly (readonly [string, string, number?])[];
   if (provider === "openai-codex") {
     definitions = [["primary", "primary"], ["secondary", "secondary"]];
@@ -88,14 +88,14 @@ function fromHeaders(provider: string, headers: Record<string, string>, cached:
   return windows;
 }
 
-function fromStream(data: unknown, cached: Record<string, QuotaWindow>): Record<string, QuotaWindow> {
+function fromStream(data: unknown, cached: Record<string, UsageWindow>): Record<string, UsageWindow> {
   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> = {};
+  const windows: Record<string, UsageWindow> = {};
   for (const key of ["primary", "secondary"]) {
     const w = record(limits[key]);
     const window = passiveWindow(passiveNumber(w.used_percent),
@@ -106,12 +106,12 @@ function fromStream(data: unknown, cached: Record<string, QuotaWindow>): Record<
   return windows;
 }
 
-/** Owns quota requests and timers for the currently displayed footer. */
+/** Owns usage 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 windows: Record<string, UsageWindow> = {};
   private updatedAt: Record<string, number> = {};
   private stale = false;
   private attemptedAt = 0;
@@ -164,12 +164,12 @@ export class UsageLimits {
     this.request = null;
   }
 
-  private selectedWindow(): [string, QuotaWindow] | null {
+  private selectedWindow(): [string, UsageWindow] | 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 {
+  private accept(windows: Record<string, UsageWindow>): 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();
@@ -202,7 +202,7 @@ export class UsageLimits {
     const provider = this.provider!;
     const modelId = model.id;
     const controller = new AbortController();
-    // Identity checks below keep late responses from restoring a replaced provider's quota.
+    // Identity checks below keep late responses from restoring a replaced provider's usage.
     this.request = controller;
     this.attemptedAt = Date.now();
     const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);

package/extensions/lib/{quota-providers.ts → usage-providers.ts}

@@ -6,7 +6,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-export interface QuotaWindow {
+export interface UsageWindow {
   used: number;
   seconds: number | null;
   resetAt: number | null;
@@ -31,15 +31,15 @@ function resetSeconds(value: unknown): number | undefined {
   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 {
+export function windowFrom(used: unknown, seconds: unknown, reset: unknown): UsageWindow | 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)
+export function shortest(windows: (UsageWindow | null)[]): UsageWindow | null {
+  return windows.filter((w): w is UsageWindow => w !== null)
     .sort((a, b) => (a.seconds ?? Infinity) - (b.seconds ?? Infinity) || b.used - a.used)[0] ?? null;
 }
 
@@ -122,13 +122,13 @@ function relativeReset(value: unknown): number | undefined {
   return delay !== undefined && delay >= 0 ? resetSeconds(Date.now() / 1000 + delay) : undefined;
 }
 
-export function parseUsageWindows(provider: string, model: string, payload: unknown): Record<string, QuotaWindow> | null {
+export function parseUsageWindows(provider: string, model: string, payload: unknown): Record<string, UsageWindow> | null {
   if (!ENDPOINTS[provider]) return null;
-  const windows: Record<string, QuotaWindow> = {};
+  const windows: Record<string, UsageWindow> = {};
   let recognized = false;
   let malformed = !isObject(payload);
   const data = record(payload);
-  const add = (key: string, value: unknown, parse: (w: Record<string, unknown>) => QuotaWindow | null) => {
+  const add = (key: string, value: unknown, parse: (w: Record<string, unknown>) => UsageWindow | null) => {
     if (value === undefined) return;
     recognized = true;
     if (value === null) return;
@@ -259,6 +259,6 @@ export function parseUsageWindows(provider: string, model: string, payload: unkn
   return finish();
 }
 
-export function parseUsage(provider: string, model: string, payload: unknown): QuotaWindow | null {
+export function parseUsage(provider: string, model: string, payload: unknown): UsageWindow | null {
   return shortest(Object.values(parseUsageWindows(provider, model, payload) ?? {}));
 }

package/package.json

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