pi-sub-quota 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# pi-sub-quota
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See your coding-plan quota — and your prepaid balance — right in the [pi](https://github.com/earendil-works/pi) footer. Nothing to run: while a supported provider is active, the numbers are simply there:
+
+```
+↑1.2k ↓3.4k 38%/200k                    (zai-coding-cn 13% 58%) glm-5.3 • max
+↑1.2k ↓3.4k 38%/200k                 (zai-coding-cn 96% 41m 58%) glm-5.3 • max
+↑960 ↓1.2k 38%/200k                      (deepseek ¥18.67+¥1.00) deepseek-flash • max
+```
+
+- The two percentages are your plan's usage windows — the 5-hour one first, then the 7-day one. Green means plenty left, amber means watch out, red means nearly gone.
+- The countdown (`41m`) appears on its own when a window needs attention: it is nearly used up (≥ 80%) or about to reset (within 30 minutes). Quiet windows stay quiet and show only their percentage.
+- DeepSeek has no usage windows; you see your balance instead, split into what you topped up and what was granted (`¥18.67+¥1.00`), exact to the cent. Accounts with several currencies show one balance per currency.
+
+## Install
+
+```bash
+pi install npm:pi-sub-quota
+```
+
+Restart pi (or run `/reload`). There is nothing to configure: the extension reuses the credentials pi already stored, so the quota always belongs to the account pi is actually running with. When no supported provider is active — or there is no data yet — the footer stays exactly as pi built it.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/quota` | quota for every configured provider, as a panel |
+| `/quota refresh` | fetch fresh numbers for the active provider now |
+| `/quota mode inline\|line\|off` | how — and whether — the footer shows quota |
+| `/quota help` | list options |
+
+Everything completes with Tab. `inline` is the default, and your choice is remembered across sessions; `off` restores the built-in footer.
+
+## The two display modes
+
+**inline** (default) — the numbers live inside the provider prefix:
+
+```
+(zai-coding-cn 96% 41m 58%)
+               │   │   └ 7d window
+               │   └ countdown — only while it matters
+               └ 5h window
+```
+
+When the terminal gets narrow, the balance folds into a single exact total (`¥19.67`), then the quota drops away, then the prefix — your stats are never sacrificed.
+
+**line** — a dedicated quota line under the stats, always in full detail:
+
+```
+~/dev/project (main)
+↑1.2k ↓3.4k 38%/200k                            (zai-coding-cn) glm-5.3 • max
+(Max) 5h ▓▓▓▓▓▓▓▓▓▓ 96% 41m · 58%
+```
+
+Every window always shows its label, meter, percentage, and reset, and the line opens with your plan tier (`(Max)`). The meters shrink automatically on narrow terminals.
+
+## The /quota panel
+
+`/quota` shows all configured providers at once — the active one first:
+
+```
+zai-coding-cn  coding plan · Max · active
+  5h  ▓▓▓▓░░░░░░   62% left   reset 13:47
+  7d  ▓▓▓▓▓░░░░░   55% left   reset Fri 15:00
+
+deepseek  pay as you go · ¥19.67 + ¥1.00 granted · $2.50
+
+kimi-coding  coding plan · Allegretto · booster ¥100.00/¥200.00
+  5h  ▓▓▓▓▓▓▓░░░   30% left   reset 17:10
+  7d  ▓░░░░░░░░░   89% left   reset Mon 00:00
+
+/quota refresh · /quota mode line|inline|off · /quota help
+```
+
+The footer shows how much you have used; the panel shows what is left, as a meter and a percentage, with each reset as a concrete local time (`13:47` today, `Fri 15:00` this week, `Sep 01` later).
+
+## Supported providers
+
+| Provider | What you see |
+| --- | --- |
+| ZAI / GLM coding plans — `zai-coding-cn`, `zai-coding`, GLM and bigmodel aliases | 5h / 7d usage windows with resets, your plan tier (Lite / Pro / Max) |
+| Kimi — `kimi-coding` | 5h / 7d usage windows (+ 30d monthly pool on plans that report one), membership tier (Andante / Moderato / Allegretto) from the account endpoint, and the booster wallet balance (`booster ¥5.00/¥20.00`) once topped up |
+| DeepSeek — `deepseek` | prepaid balance per currency, topped-up + granted split |
+
+Custom providers work without configuration too: detection falls back to the model's base URL host (`bigmodel.cn`, `*.z.ai` with a `/coding` path, `*.kimi.com` / `*.kimi.ai` with a `/coding` path, `*.deepseek.com`).
+
+## Good to know
+
+- Numbers refresh at most every five minutes; countdowns tick every minute without touching the network.
+- A failed refresh never breaks anything: the last numbers stay, marked `~`, until the next success — and `/quota` says why a provider failed (`quota unavailable (HTTP 401)`).
+- Several pi sessions on the same machine share one cache safely.
+- A lapsed Kimi OAuth token is skipped with a note — it refreshes the next time pi itself calls Kimi.
+- Credentials come only from pi's own store; no environment variables are read, and a key can never be sent to the wrong host.
+- While quota is displayed, the footer is a re-implementation of pi's and drops a few rare markers (the virtual-model routing arrow, `xp`, `(auto)`). Everything else renders the same.
+
+## License
+
+MIT © 2026 Ning. See [LICENSE](LICENSE).

package/cache.ts

@@ -0,0 +1,127 @@
+/**
+ * Disk cache for quota snapshots, one file shared by all providers and keyed
+ * by provider kind. Parsing and validation are pure so they can be tested;
+ * file I/O lives in the extension entry.
+ */
+
+import { type McpToolUsage, PROVIDER_KINDS, type ProviderKind, type QuotaItem, type QuotaSnapshot } from "./providers/index.ts";
+
+export const CACHE_VERSION = 2;
+
+export interface QuotaCacheFile {
+	version: number;
+	snapshots: Partial<Record<ProviderKind, QuotaSnapshot>>;
+}
+
+export function emptyCache(): QuotaCacheFile {
+	return { version: CACHE_VERSION, snapshots: {} };
+}
+
+/** Per-tool usage rows must all carry a string code and a finite count. */
+function isValidTools(value: unknown): value is McpToolUsage[] {
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(tool) =>
+				typeof tool === "object" &&
+				tool !== null &&
+				typeof (tool as McpToolUsage).modelCode === "string" &&
+				typeof (tool as McpToolUsage).usage === "number" &&
+				Number.isFinite((tool as McpToolUsage).usage),
+		)
+	);
+}
+
+function isValidItem(value: unknown): boolean {
+	if (typeof value !== "object" || value === null) return false;
+	const item = value as Partial<QuotaItem> & { type?: unknown };
+	if (item.type === "window") {
+		return (
+			typeof item.label === "string" &&
+			(item.resource === "tokens" || item.resource === "mcp") &&
+			typeof item.usedPercent === "number" &&
+			Number.isFinite(item.usedPercent) &&
+			(item.resetAt === undefined || (typeof item.resetAt === "number" && Number.isFinite(item.resetAt))) &&
+			(item.durationMs === undefined || (typeof item.durationMs === "number" && Number.isFinite(item.durationMs))) &&
+			(item.tools === undefined || isValidTools(item.tools))
+		);
+	}
+	if (item.type === "balance") {
+		return (
+			typeof item.symbol === "string" &&
+			typeof item.total === "number" &&
+			Number.isFinite(item.total) &&
+			typeof item.granted === "number" &&
+			Number.isFinite(item.granted)
+		);
+	}
+	return false;
+}
+
+function isValidSnapshot(value: unknown): value is QuotaSnapshot {
+	if (typeof value !== "object" || value === null) return false;
+	const snap = value as Partial<QuotaSnapshot>;
+	return (
+		typeof snap.kind === "string" &&
+		(PROVIDER_KINDS as readonly string[]).includes(snap.kind) &&
+		typeof snap.fetchedAt === "number" &&
+		Number.isFinite(snap.fetchedAt) &&
+		(snap.planLevel === undefined || typeof snap.planLevel === "string") &&
+		Array.isArray(snap.items) &&
+		// Item-level corruption must not reach the renderers: a hand-edited or
+		// foreign-written cache file is user-visible, and view code trusts item
+		// shapes (calls .map/.charAt/.padEnd on their fields).
+		snap.items.every(isValidItem)
+	);
+}
+
+/**
+ * Parse cache file text. Tolerates a missing file, invalid JSON, or an
+ * unexpected shape by returning an empty cache instead of throwing.
+ */
+export function parseCache(text: string | undefined): QuotaCacheFile {
+	if (!text) return emptyCache();
+	try {
+		const raw: unknown = JSON.parse(text);
+		if (typeof raw !== "object" || raw === null) return emptyCache();
+		const file = raw as { version?: unknown; snapshots?: unknown };
+		if (file.version !== CACHE_VERSION || typeof file.snapshots !== "object" || file.snapshots === null) {
+			return emptyCache();
+		}
+		const snapshots: Partial<Record<ProviderKind, QuotaSnapshot>> = {};
+		for (const [kind, snapshot] of Object.entries(file.snapshots)) {
+			if ((PROVIDER_KINDS as readonly string[]).includes(kind) && isValidSnapshot(snapshot)) {
+				snapshots[kind as ProviderKind] = snapshot;
+			}
+		}
+		return { version: CACHE_VERSION, snapshots };
+	} catch {
+		return emptyCache();
+	}
+}
+
+export function serializeCache(cache: QuotaCacheFile): string {
+	return `${JSON.stringify(cache, null, "\t")}\n`;
+}
+
+/**
+ * True when the text is a cache file written by a newer format. Such a file
+ * owns the data on disk: rewriting it as this version would silently discard
+ * whatever that format stored, so writers must leave it alone.
+ */
+export function isNewerCacheFile(text: string | undefined): boolean {
+	if (!text) return false;
+	try {
+		const raw: unknown = JSON.parse(text);
+		if (typeof raw !== "object" || raw === null) return false;
+		const version = (raw as { version?: unknown }).version;
+		return typeof version === "number" && Number.isFinite(version) && version > CACHE_VERSION;
+	} catch {
+		return false;
+	}
+}
+
+/** True when the snapshot was fetched within the TTL window. */
+export function freshSnapshot(snapshot: QuotaSnapshot | undefined, now: number, ttlMs: number): snapshot is QuotaSnapshot {
+	return snapshot !== undefined && now - snapshot.fetchedAt < ttlMs;
+}

package/footer.ts

@@ -0,0 +1,244 @@
+/**
+ * Custom footer with two alert-driven quota display modes. Quiet windows
+ * show only their percentage; a reset countdown appears only when a window
+ * is alerting — usage ≥ USAGE_ALERT_PERCENT or a reset within RESET_ALERT_MS.
+ *
+ * Mode "line" keeps a dedicated quota line under the stats whenever a
+ * snapshot exists, with every window in full detail — label, meter,
+ * percentage, and reset countdown — because the space is there:
+ *
+ *   ↑1.2k ↓3.4k 38%/200k                            (zai-coding-cn) glm-5.3 • max
+ *   (Max) 5h ▓▓▓▓▓▓▓▓▓▓ 96% 41m · 58%
+ *
+ * Mode "inline" keeps the built-in layout and carries the quota inside the
+ * provider prefix, which keeps the real provider id exactly like the built-in
+ * footer:
+ *
+ *   ~/dev/project (main)
+ *   ↑1.2k ↓3.4k 38%/200k        (zai-coding-cn 96% 41m 58%) glm-5.3 • max
+ *
+ * When width is tight the quota drops from the prefix entirely (back to the
+ * built-in `(zai-coding-cn)`), then the prefix drops before the model info.
+ *
+ * Known deviations while the custom footer is installed: no virtual-model
+ * routing arrow, no experimental "xp" marker, no "(auto)" compaction suffix,
+ * and "(sub)" only for kimi-coding (OAuth subscription detection is not
+ * reachable from extensions). Everything else renders the same way. With no
+ * snapshot data at all, the built-in footer stays untouched.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { QuotaSnapshot } from "./providers/index.ts";
+import type { QuotaMode } from "./settings.ts";
+import { computeSessionStats, formatCwd, formatTokens, type SessionStats } from "./stats.ts";
+import { buildQuotaInline, buildQuotaLine, type QuotaStyle } from "./view.ts";
+
+/** The factory `ctx.ui.setFooter` expects, derived from its signature so TUI/Theme types need no import. */
+export type FooterFactory = NonNullable<Parameters<ExtensionContext["ui"]["setFooter"]>[0]>;
+
+/** Meter width for the "line" mode, keyed by minimum terminal width. */
+const METER_WIDTHS: readonly { minWidth: number; cells: number }[] = [
+	{ minWidth: 80, cells: 10 },
+	{ minWidth: 60, cells: 6 },
+	{ minWidth: 48, cells: 4 },
+	{ minWidth: 0, cells: 0 },
+];
+
+/** Mirrors the built-in footer's status sanitizer: collapse whitespace and control characters. */
+function sanitizeStatusText(text: string): string {
+	return text
+		.replace(/[\r\n\t]/g, " ")
+		.replace(/ +/g, " ")
+		.trim();
+}
+
+interface StatsCache {
+	entryCount: number;
+	leafId: string | null;
+	/** Model object identity: a different model can carry a different context window. */
+	model: ExtensionContext["model"];
+	/** Cached ctx.getContextUsage(): it rebuilds the session projection (O(entries)) per call. */
+	contextUsage: ReturnType<ExtensionContext["getContextUsage"]>;
+	stats: SessionStats;
+}
+
+export interface QuotaFooterSource {
+	/** Latest in-memory snapshot, refreshed by the extension entry. */
+	getSnapshot(): QuotaSnapshot | undefined;
+	/** True when the shown snapshot is older than the TTL (last fetch failed). */
+	isStale(): boolean;
+	/** Current display mode; read every render so switching is immediate. */
+	getMode(): QuotaMode;
+	/** Notified whenever the snapshot, staleness, or mode changes so the footer can re-render. */
+	onQuotaChange(callback: () => void): () => void;
+}
+
+export function createQuotaFooter(ctx: ExtensionContext, source: QuotaFooterSource): FooterFactory {
+	return (tui, theme, footerData) => {
+		const unsubscribeBranch = footerData.onBranchChange(() => tui.requestRender());
+		// Snapshots land asynchronously after the footer mounts; without this the
+		// quota would only appear the next time something else triggers a render.
+		const unsubscribeQuota = source.onQuotaChange(() => tui.requestRender());
+		const style: QuotaStyle = (color, text) => theme.fg(color, text);
+		const dim = (text: string) => theme.fg("dim", text);
+		let cache: StatsCache | undefined;
+
+		const sessionStats = () => {
+			const manager = ctx.sessionManager;
+			const entries = manager.getEntries();
+			const leafId = manager.getLeafId();
+			const model = ctx.model;
+			if (!cache || cache.entryCount !== entries.length || cache.leafId !== leafId || cache.model !== model) {
+				// Entries are append-only and every append moves the leaf, so these
+				// keys bound every input of both scans — the totals and the context
+				// usage projection. The footer renders on every frame, so neither may
+				// run per frame; the built-in footer caches them the same way.
+				cache = {
+					entryCount: entries.length,
+					leafId,
+					model,
+					contextUsage: ctx.getContextUsage(),
+					stats: computeSessionStats(entries),
+				};
+			}
+			return cache;
+		};
+
+		return {
+			dispose: () => {
+				unsubscribeBranch();
+				unsubscribeQuota();
+			},
+			invalidate() {},
+			render(width: number): string[] {
+				const model = ctx.model;
+				const { stats, contextUsage } = sessionStats();
+				const { totals, latestCacheHitRate } = stats;
+
+				// Line 1: cwd (+ branch, session name), dim like the built-in footer.
+				let pwd = formatCwd(ctx.sessionManager.getCwd(), process.env.HOME || process.env.USERPROFILE);
+				const branch = footerData.getGitBranch();
+				if (branch) pwd += ` (${branch})`;
+				const sessionName = ctx.sessionManager.getSessionName();
+				if (sessionName) pwd += ` • ${sessionName}`;
+
+				// Stats segments, styled per part so color resets cannot clear the dim baseline.
+				const parts: string[] = [];
+				if (totals.input) parts.push(dim(`↑${formatTokens(totals.input)}`));
+				if (totals.output) parts.push(dim(`↓${formatTokens(totals.output)}`));
+				if (totals.cacheRead) parts.push(dim(`R${formatTokens(totals.cacheRead)}`));
+				if (totals.cacheWrite) parts.push(dim(`W${formatTokens(totals.cacheWrite)}`));
+				if ((totals.cacheRead > 0 || totals.cacheWrite > 0) && latestCacheHitRate !== undefined) {
+					parts.push(dim(`CH${latestCacheHitRate.toFixed(1)}%`));
+				}
+				// Kimi Coding is subscription-backed despite API-key auth; same marker as the built-in footer.
+				const usingSubscription = model?.provider === "kimi-coding";
+				if (totals.cost || usingSubscription) {
+					parts.push(dim(`$${totals.cost.toFixed(3)}${usingSubscription ? " (sub)" : ""}`));
+				}
+
+				// Context segment, colored by pressure like the built-in footer.
+				// Built-in parity: an unknown percent (post-compaction) reads "?/200k"
+				// with no percent sign, while absent usage data reads "0.0%/0k".
+				const contextWindow = contextUsage?.contextWindow ?? model?.contextWindow ?? 0;
+				const percent = contextUsage?.percent ?? null;
+				const percentText = percent !== null ? `${percent.toFixed(1)}%` : contextUsage ? "?" : "0.0%";
+				const contextDisplay = `${percentText}/${formatTokens(contextWindow)}`;
+				const contextPart =
+					percent !== null && percent > 90
+						? theme.fg("error", contextDisplay)
+						: percent !== null && percent > 70
+							? theme.fg("warning", contextDisplay)
+							: dim(contextDisplay);
+
+				// Right side: model name and thinking level, optionally behind a provider prefix.
+				let modelInfo = model?.id ?? "no-model";
+				if (model?.reasoning) {
+					const level = ctx.thinkingLevel ?? "off";
+					modelInfo = level === "off" ? `${modelInfo} • thinking off` : `${modelInfo} • ${level}`;
+				}
+				const showsPrefix = model !== undefined && footerData.getAvailableProviderCount() > 1;
+
+				const now = Date.now();
+				const snapshot = source.getSnapshot();
+				const stale = source.isStale();
+				const lines: string[] = [truncateToWidth(theme.fg("dim", pwd), width, theme.fg("dim", "..."))];
+
+				/**
+				 * Fit the stats line like the built-in footer: the first candidate that
+				 * fits with at least two spaces of padding wins; on tight widths the
+				 * bare model info is truncated from the right instead of dropped; and
+				 * when even the stats alone exceed the width they are truncated with an
+				 * ellipsis (built-in parity) rather than overflowing the terminal.
+				 */
+				const fitStatsLine = (candidates: readonly string[]): string => {
+					let left = [...parts, contextPart].filter(Boolean).join(" ");
+					let leftWidth = visibleWidth(left);
+					// Built-in parity: stats wider than the terminal are truncated with an
+					// ellipsis instead of overflowing the line.
+					if (leftWidth > width) {
+						left = truncateToWidth(left, width, "...");
+						leftWidth = visibleWidth(left);
+					}
+					for (const candidate of candidates) {
+						const rightWidth = visibleWidth(candidate);
+						if (leftWidth + 2 + rightWidth <= width) {
+							return left + " ".repeat(width - leftWidth - rightWidth) + candidate;
+						}
+					}
+					const availableForRight = width - leftWidth - 2;
+					if (availableForRight > 0) {
+						const truncated = truncateToWidth(candidates[candidates.length - 1], availableForRight, "");
+						return left + " ".repeat(Math.max(0, width - leftWidth - visibleWidth(truncated))) + truncated;
+					}
+					return left;
+				};
+
+				if (source.getMode() === "line") {
+					// Line mode: the stats line keeps the built-in shape; the quota line is
+					// always present while a snapshot exists and renders every window in
+					// full detail — label, meter, percentage, countdown.
+					const candidates: string[] = [];
+					if (model && showsPrefix) candidates.push(dim(`(${model.provider}) ${modelInfo}`));
+					candidates.push(dim(modelInfo));
+					lines.push(fitStatsLine(candidates));
+
+					const meterWidth = METER_WIDTHS.find((entry) => width >= entry.minWidth)?.cells ?? 0;
+					const quotaLine = buildQuotaLine(snapshot, now, style, meterWidth, { stale });
+					if (quotaLine) lines.push(truncateToWidth(quotaLine, width, dim("...")));
+				} else {
+					// Inline mode: the prefix carries the quota behind the real provider id
+					// (never a renamed one). Styled in segments so the colored quota does
+					// not break the dim baseline. Countdowns appear only on alerting
+					// windows; a granted balance degrades from "¥18.67+¥1.00" to the
+					// exact total "¥19.67" when tight, then the quota drops to the
+					// built-in prefix.
+					const candidates: string[] = [];
+					if (model) {
+						const hasBalanceBreakdown = (snapshot?.items ?? []).some((item) => item.type === "balance" && item.granted >= 0.01);
+						for (const balanceDetail of hasBalanceBreakdown ? [true, false] : [false]) {
+							const inline = buildQuotaInline(snapshot, now, style, { stale, balanceDetail });
+							if (inline) candidates.push(dim(`(${model.provider} `) + inline + dim(`) ${modelInfo}`));
+						}
+					}
+					if (model && showsPrefix) candidates.push(dim(`(${model.provider}) ${modelInfo}`));
+					// Bare model info is always the last resort, as in the built-in footer.
+					candidates.push(dim(modelInfo));
+					lines.push(fitStatsLine(candidates));
+				}
+
+				// Extension statuses keep their own line, as in the built-in footer.
+				const statuses = footerData.getExtensionStatuses();
+				if (statuses.size > 0) {
+					const statusLine = [...statuses.entries()]
+						.sort(([a], [b]) => a.localeCompare(b))
+						.map(([, text]) => sanitizeStatusText(text))
+						.join(" ");
+					lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
+				}
+				return lines;
+			},
+		};
+	};
+}