pi-soly 2.3.3 → 2.4.0

package/index.ts

@@ -65,6 +65,9 @@ import { registerTools } from "./tools.ts";
 import { registerWorkflows } from "./workflows/index.ts";
 import { readGitContext, buildGitSection, type GitContext } from "./git.ts";
 import { startHotReload, type HotReloadHandle } from "./hotreload.ts";
+import { registerQuotaProvider } from "./quota/registry.ts";
+import { minimaxProvider } from "./quota/minimax.ts";
+import { startQuotaPoller, type QuotaPoller } from "./quota/poller.ts";
 import { detectEnv, buildEnvSection, type EnvSummary } from "./env.ts";
 import { buildCodeMap, buildCodeMapSection, type CodeMap } from "./codemap.ts";
 import { loadIntentDocs, buildIntentSection, loadInlineIntentBodies, type IntentDoc } from "./intent.ts";
@@ -101,6 +104,12 @@ When terminal text isn't the best medium, reach for these (details + when-NOT in
 - \`html_artifact\` — render HTML to a self-contained, browseable per-project gallery.`;
 
 export default function solyExtension(pi: ExtensionAPI) {
+	// ============================================================================
+	// Register built-in quota providers (MiniMax via mmx CLI).
+	// Adding a new provider = new adapter + registerQuotaProvider() here.
+	// ============================================================================
+	registerQuotaProvider(minimaxProvider);
+
 	// ============================================================================
 	// State (module-local, lives for the duration of one extension instance)
 	// ============================================================================
@@ -168,6 +177,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 
 	// Hot reload watcher for rules
 	let hotReload: HotReloadHandle | null = null;
+	let quotaPoller: QuotaPoller | null = null;
 
 	// Session stats (computed on demand)
 	let sessionStats: { turns: number; tokensEstimate: number } = { turns: 0, tokensEstimate: 0 };
@@ -536,6 +546,12 @@ export default function solyExtension(pi: ExtensionAPI) {
 				});
 			},
 		});
+
+		// Start the background quota poller (reads modelProvider from
+		// ChromeData each tick, resolves the registered adapter, writes
+		// quotaPercent/quotaResetsLabel back for the footer to render).
+		if (quotaPoller) quotaPoller.stop();
+		quotaPoller = startQuotaPoller(chrome.data, () => getActiveConfig().chrome.enabled);
 		// Editors save in bursts (write to .tmp, rename, touch). Coalesce
 		// those rapid reload events into a single sub-line event under the
 		// Working indicator (└─ reloaded 47 rules). Errors here are real
@@ -633,6 +649,11 @@ export default function solyExtension(pi: ExtensionAPI) {
 			hotReload.stop();
 			hotReload = null;
 		}
+		// Stop the background quota poller
+		if (quotaPoller) {
+			quotaPoller.stop();
+			quotaPoller = null;
+		}
 		// Restore pi's native footer/widgets/indicator before teardown
 		chrome.dispose(ctx.ui);
 		// Persist rule mtimes so the next session can show the diff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "2.3.3",
+  "version": "2.4.0",
   "description": "Workflow + project management for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker. One npm install, zero config. LLM drives the workflow inline via the soly_workflow tool — no external subagent plugin.",
   "type": "module",
   "main": "index.ts",
@@ -63,6 +63,7 @@
     "state.ts",
     "hotreload.ts",
     "built-in-rules",
+    "quota",
     ".assets"
   ],
   "keywords": [

package/quota/format.ts

@@ -0,0 +1,23 @@
+// =============================================================================
+// quota/format.ts — human-readable reset time
+// =============================================================================
+//
+// Turns a millisecond duration into a compact English label for the toolbar:
+//   1_200_000  → "in 20m"
+//   9_000_000  → "in 2h30m"
+//   3_600_000  → "in 1h"
+//   0          → "now"
+//
+// Kept pure (no DOM, no Date) so it's trivially testable.
+// =============================================================================
+
+/** Format a millisecond duration as a compact "in Nm" / "in Nh" / "in NhMm". */
+export function formatReset(ms: number): string {
+	const totalMin = Math.round(ms / 60_000);
+	if (totalMin <= 0) return "now";
+	if (totalMin < 60) return `in ${totalMin}m`;
+	const hours = Math.floor(totalMin / 60);
+	const mins = totalMin % 60;
+	if (mins === 0) return `in ${hours}h`;
+	return `in ${hours}h${mins}m`;
+}

package/quota/minimax.ts

@@ -0,0 +1,81 @@
+// =============================================================================
+// quota/minimax.ts — MiniMax quota provider (via mmx CLI)
+// =============================================================================
+//
+// Shells out to `mmx quota show --output json --quiet` every poll cycle.
+// Uses mmx (mmx-cli) because it already handles auth (~/.mmx/config.json),
+// region detection (global vs cn), and the billing endpoint. Reimplementing
+// that as direct HTTP would duplicate mmx's logic for no gain.
+//
+// The response shape (confirmed against a live MiniMax-M3 key):
+//   {
+//     "model_remains": [
+//       {
+//         "model_name": "general",          ← chat models (MiniMax-M3)
+//         "current_interval_remaining_percent": 53,
+//         "remains_time": 1639649,          ← ms until interval resets
+//         ...
+//       },
+//       { "model_name": "video", ... }
+//     ],
+//     "base_resp": { "status_code": 0, ... }
+//   }
+//
+// We pick the "general" entry — that's the quota bucket MiniMax-M3 (and all
+// text/chat models) draw from. Video/music have separate buckets.
+// =============================================================================
+
+import { execFile } from "node:child_process";
+import type { QuotaProvider, QuotaSnapshot } from "./types.ts";
+
+/** Minimal shape we read from `mmx quota show --output json`. */
+type MinimaxQuotaResponse = {
+	model_remains?: Array<{
+		model_name?: string;
+		current_interval_remaining_percent?: number;
+		remains_time?: number;
+	}>;
+	base_resp?: { status_code?: number };
+};
+
+/** Run mmx and capture stdout. Resolves to null on any failure
+ *  (mmx missing, non-zero exit, timeout, bad JSON). Never throws. */
+function runMmx(args: string[], timeoutMs: number): Promise<string | null> {
+	return new Promise((resolve) => {
+		execFile("mmx", args, { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+			if (err) resolve(null);
+			else resolve(stdout ?? "");
+		});
+	});
+}
+
+/** Parse the mmx quota response, returning the "general" model snapshot. */
+function parseGeneralQuota(raw: string): QuotaSnapshot | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null; // not valid JSON — mmx printed an error to stdout
+	}
+	// Cast at the boundary (single documented place, per code-style rules).
+	const data = parsed as MinimaxQuotaResponse;
+	if (data.base_resp?.status_code !== 0) return null;
+	const general = data.model_remains?.find((m) => m.model_name === "general");
+	if (!general) return null;
+	const pct = general.current_interval_remaining_percent;
+	if (typeof pct !== "number") return null;
+	return {
+		remainingPercent: pct,
+		resetsInMs: typeof general.remains_time === "number" ? general.remains_time : null,
+	};
+}
+
+/** MiniMax quota provider. Polls `mmx quota show`. */
+export const minimaxProvider: QuotaProvider = {
+	id: "minimax",
+	async fetch(): Promise<QuotaSnapshot | null> {
+		const stdout = await runMmx(["quota", "show", "--output", "json", "--quiet"], 15_000);
+		if (stdout === null) return null;
+		return parseGeneralQuota(stdout);
+	},
+};

package/quota/poller.ts

@@ -0,0 +1,99 @@
+// =============================================================================
+// quota/poller.ts — background quota polling loop
+// =============================================================================
+//
+// startQuotaPoller() reads the active model's provider id from ChromeData,
+// resolves it to a registered QuotaProvider, and calls fetch() on a timer.
+// The result is written back into ChromeData (quotaPercent / quotaResetsLabel)
+// which the footer reads live at render time.
+//
+// Design notes:
+// - setTimeout recursion (not setInterval) so a slow fetch can't pile up
+//   overlapping ticks. The next tick is scheduled only after the current
+//   fetch resolves.
+// - On fetch failure (null), the previous snapshot is kept — stale data is
+//   more useful than a flashing segment. The percent naturally drifts as
+//   the user consumes quota between successful polls.
+// - When the active provider has no registered adapter, the quota fields
+//   are cleared (no segment shown) — self-disabling for providers we don't
+//   support yet.
+// - The poller is started in session_start and stopped in session_shutdown.
+//   It only runs while a session is active.
+// =============================================================================
+
+import type { ChromeData } from "../visual/data.ts";
+import { resolveQuotaProvider } from "./registry.ts";
+import { formatReset } from "./format.ts";
+
+/** Default poll interval: 60 seconds. */
+const POLL_INTERVAL_MS = 60_000;
+
+/** A running poller handle. Call stop() to cancel the timer. */
+export type QuotaPoller = {
+	/** Cancel the timer. Idempotent. */
+	stop(): void;
+};
+
+/** Start the quota poller. Reads `data.modelProvider` each tick to pick the
+ *  right adapter. Returns a handle to stop the loop on session_shutdown.
+ *
+ *  @param data - the shared ChromeData (mutated in place with quota fields)
+ *  @param isEnabled - gate; return false to skip polling (e.g. chrome disabled)
+ *  @param intervalMs - override poll interval (default 60_000); for tests */
+export function startQuotaPoller(
+	data: ChromeData,
+	isEnabled: () => boolean,
+	intervalMs: number = POLL_INTERVAL_MS,
+): QuotaPoller {
+	let stopped = false;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const scheduleNext = (): void => {
+		if (stopped) return;
+		timer = setTimeout(tick, intervalMs);
+	};
+
+	const tick = async (): Promise<void> => {
+		if (stopped) return;
+		if (!isEnabled()) {
+			scheduleNext();
+			return;
+		}
+
+		const providerId = data.modelProvider;
+		if (!providerId) {
+			scheduleNext();
+			return;
+		}
+
+		const provider = resolveQuotaProvider(providerId);
+		if (!provider) {
+			// No adapter for this provider — clear and skip.
+			data.quotaPercent = null;
+			data.quotaResetsLabel = null;
+			scheduleNext();
+			return;
+		}
+
+		const snapshot = await provider.fetch();
+		if (snapshot) {
+			data.quotaPercent = snapshot.remainingPercent;
+			data.quotaResetsLabel = snapshot.resetsInMs !== null ? formatReset(snapshot.resetsInMs) : null;
+		}
+		// On null (fetch failed), keep the previous snapshot — don't clear.
+		scheduleNext();
+	};
+
+	// Fire immediately so the segment appears without waiting 60s.
+	tick();
+
+	return {
+		stop(): void {
+			stopped = true;
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		},
+	};
+}

package/quota/registry.ts

@@ -0,0 +1,39 @@
+// =============================================================================
+// quota/registry.ts — provider registry
+// =============================================================================
+//
+// A simple Map<id, QuotaProvider>. Providers register themselves at module
+// load (index.ts calls registerQuotaProvider for each built-in adapter).
+// The poller calls resolveQuotaProvider(providerId) which tries an exact
+// match first, then falls back to the base id before the first "-" (so
+// "minimax-cn" resolves to a "minimax" adapter).
+//
+// External extensions could also register providers by importing this
+// module — but pi-soly has no runtime deps, so in practice the built-in
+// adapters (minimax) are all that ship today.
+// =============================================================================
+
+import type { QuotaProvider } from "./types.ts";
+
+const providers = new Map<string, QuotaProvider>();
+
+/** Register a quota provider. Idempotent — re-registering overwrites. */
+export function registerQuotaProvider(provider: QuotaProvider): void {
+	providers.set(provider.id, provider);
+}
+
+/** Exact-match lookup. */
+export function getQuotaProvider(id: string): QuotaProvider | undefined {
+	return providers.get(id);
+}
+
+/** Resolve a provider id to its adapter. Tries exact match first, then
+ *  the base id before the first "-" (region-suffix fallback:
+ *  "minimax-cn" → "minimax"). Returns undefined if nothing matches. */
+export function resolveQuotaProvider(id: string): QuotaProvider | undefined {
+	const exact = providers.get(id);
+	if (exact) return exact;
+	const base = id.split("-")[0];
+	if (base !== id) return providers.get(base);
+	return undefined;
+}

package/quota/types.ts

@@ -0,0 +1,37 @@
+// =============================================================================
+// quota/types.ts — provider-agnostic quota snapshot
+// =============================================================================
+//
+// A QuotaProvider knows how to fetch "how much quota is left" for one model
+// provider (MiniMax, OpenAI, …). The poller (poller.ts) reads the active
+// model's provider id from ChromeData, looks up the registered adapter, and
+// polls it on a timer. Adding a new provider = implement this interface +
+// registerQuotaProvider() — no changes to the poller or footer.
+//
+// This is intentionally minimal: just the two numbers the toolbar needs.
+// Per-model breakdowns, weekly vs interval, cost in cents — none of that
+// belongs in a status-bar segment. If a provider can't report a field, it
+// returns null and the segment omits it.
+// =============================================================================
+
+/** What a provider reports about remaining quota. */
+export type QuotaSnapshot = {
+	/** Remaining quota as a percent (0–100). Drives the main number. */
+	readonly remainingPercent: number;
+	/** Milliseconds until the current quota window resets, or null if the
+	 *  provider doesn't expose a reset time. Rendered as "in 20m". */
+	readonly resetsInMs: number | null;
+};
+
+/** Adapter that fetches quota for one provider.
+ *
+ *  Implementations MUST NOT throw — return null on any failure (no
+ *  credentials, provider down, CLI missing, parse error). The poller
+ *  treats null as "no data" and leaves the previous snapshot in place. */
+export interface QuotaProvider {
+	/** Provider id matching `ctx.model.provider` (e.g. "minimax").
+	 *  Region-suffixed ids ("minimax-cn") fall back to the base id. */
+	readonly id: string;
+	/** Fetch the current snapshot, or null if unavailable. */
+	fetch(): Promise<QuotaSnapshot | null>;
+}

package/visual/data.ts

@@ -45,6 +45,11 @@ export type ChromeData = {
 	recentEvent: string | null;
 	/** Level of the recent event (used for glyph/color). */
 	recentEventLevel: "info" | "warning" | "error" | null;
+	/** Remaining quota percent (0–100) for the active provider, polled in
+	 *  the background by quota/poller.ts. null = no adapter / not polled. */
+	quotaPercent: number | null;
+	/** Human-readable reset time label (e.g. "in 20m"), or null. */
+	quotaResetsLabel: string | null;
 };
 
 /** A fresh ChromeData with everything empty/idle. */
@@ -66,5 +71,7 @@ export function emptyChromeData(): ChromeData {
 		artifactCount: 0,
 		recentEvent: null,
 		recentEventLevel: null,
+		quotaPercent: null,
+		quotaResetsLabel: null,
 	};
 }

package/visual/footer.ts

@@ -71,6 +71,12 @@ export function buildFooterLine(data: ChromeData, fd: FooterData, width: number,
 		left.push({ id: "git", text: styler.fg("muted", withGlyph("git", `${branch}${dirty}`, ascii)), priority: 7 });
 	}
 
+	if (data.quotaPercent !== null) {
+		const quotaText = ascii ? `${data.quotaPercent}%` : `⬢ ${data.quotaPercent}%`;
+		const label = data.quotaResetsLabel ? `${quotaText} · ${data.quotaResetsLabel}` : quotaText;
+		left.push({ id: "quota", text: styler.fg("muted", label), priority: 6 });
+	}
+
 	if (data.rulesActive > 0) {
 		const word = data.rulesActive === 1 ? "rule" : "rules";
 		const rulesText = ascii ? `${data.rulesActive} ${word}` : `${RULES_GLYPH} ${data.rulesActive}`;