@cad0p/pi-usage 0.11.3 → 0.11.4-20261103.1

package/bin/piquota.js

@@ -19,6 +19,7 @@ import { parseArgs } from "../src/cli/args.js";
 import { runAuthCommand } from "../src/cli/commands/auth.js";
 import { runGentlePiCommand } from "../src/cli/commands/gentle-pi.js";
 import { runOmarchyCommand } from "../src/cli/commands/omarchy.js";
+import { runStatsCommand } from "../src/cli/commands/stats.js";
 import { explainLines, resolveFamilies } from "../src/cli/explain.js";
 import { err, out } from "../src/cli/output.js";
 import { collectQuota, enabledFamilies, normalizeClaudeSourceMode } from "../src/engine.js";
@@ -35,6 +36,20 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
  */
 const CACHE_KEY = `claude-source:${normalizeClaudeSourceMode(process.env.PI_QUOTA_CLAUDE_SOURCE)}`;
 
+/**
+ * Local token statistics from Pi's session files are on for the CLI: the Omarchy
+ * records and /usage both show them. `PI_QUOTA_LOCAL_STATS=0` turns the scan
+ * off (e.g. on a machine where the session store is huge and network quota is
+ * all that matters), and the budget keeps a first full scan from delaying a
+ * report past the 30 s the /usage extension allows.
+ */
+const LOCAL_STATS_BUDGET_MS = Number(process.env.PI_QUOTA_LOCAL_STATS_BUDGET_MS);
+const LOCAL_STATS = process.env.PI_QUOTA_LOCAL_STATS === "0"
+  ? false
+  : LOCAL_STATS_BUDGET_MS > 0
+    ? { budgetMs: LOCAL_STATS_BUDGET_MS }
+    : {};
+
 const HELP = `piquota ${VERSION} — read-only quota from Pi's provider credentials
 
 Usage:
@@ -42,6 +57,7 @@ Usage:
   piquota auth <opencode|status> [flags]
   piquota gentle-pi <status|apply|revert>
   piquota omarchy
+  piquota stats [--json] [--month YYYY-MM] [--rebuild-totals]
 
 Quota:
   --json             Emit the normalized report as JSON (for rp-host and automations)
@@ -56,6 +72,8 @@ Quota:
   --no-refresh       Never refresh Antigravity's token in memory
   --explain          Show which stores/fields are read (names only)
   --clear-cache      Delete the local cache and exit
+  --rebuild-totals   With \`stats\`: rebuild the token-history totals from its month files
+  --month YYYY-MM    With \`stats\`: read one month (default: the current local month)
   --version          Print the version and exit
 
 Auth (OpenCode Go session, the only credential Pi does not store):
@@ -66,18 +84,35 @@ Auth (OpenCode Go session, the only credential Pi does not store):
   piquota auth opencode --wait <s> how long to wait for the login (default 180)
   piquota auth status              report every credential source
 
+Stats:
+  piquota stats                    summarise the durable token history
+                                   (dir: \${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage)
+  piquota stats --json [--month]   read-only JSON: months (the live month always),
+                                   one month's days per family/slot/model, all-time
+                                   totals, notes
+  piquota stats --rebuild-totals   recompute totals.json from the frozen month files
+
 Omarchy:
   piquota omarchy                  write pi-<family>.json records for Omarchy's Agents bar panel
                                    (dir: $PI_QUOTA_OMARCHY_DIR or $XDG_STATE_HOME/omarchy/agents/usage)
                                    run it on a timer: ./install.sh --omarchy-timer
 
+Environment:
+  PI_QUOTA_LOCAL_STATS=0          skip the token scan of Pi's session files
+  PI_QUOTA_LOCAL_STATS_BUDGET_MS  wall-clock budget for that scan (default 12000)
+  PI_QUOTA_ACCOUNT_CONCURRENCY    accounts of one provider queried at once (1-32, default 8)
+
 Guarantees:
   * ~/.pi/agent/auth.json is opened read-only. Never written, synced or refreshed.
+  * Pi's session files are opened read-only too; the token scan keeps only
+    aggregate counts per day and model, never prompt text or session paths.
   * Antigravity's access token may be refreshed in memory; it is never persisted.
   * Browser cookie databases are copied and opened read-only; values are never logged.
-  * Only percentages, window labels, reset times and plan names leave this machine.
+  * Only percentages, window labels, reset times, plan names and aggregate token
+    counts leave this machine.
   * \`omarchy\` (opt-in) writes only pi-*.json records, atomically, into Omarchy's usage dir;
-    records hold plan names, percentages, window labels and reset times, never accounts.
+    records hold plan names, percentages, window labels, reset times and aggregate
+    token counts, never prompt text or accounts.
   * \`gentle-pi\` is the one file this tool edits outside its own state: it appends
     piQuota's part to gentle-pi's rail allowlist so the card can be painted there.
     The edit is one array literal, it is reversible with \`piquota gentle-pi revert\`,
@@ -122,10 +157,30 @@ async function main() {
     return runGentlePiCommand(sub);
   }
 
+  if (args.rebuildTotals && command !== "stats") {
+    // The flag repairs one thing (the all-time rollup) and reads nothing else,
+    // so running it beside `piquota` or `piquota omarchy` would silently skip
+    // the command the user asked for.
+    err("--rebuild-totals only works with `piquota stats`\n");
+    process.stdout.write(HELP);
+    return 2;
+  }
+
+  if (args.month && command !== "stats") {
+    err("--month only works with \`piquota stats\`\n");
+    process.stdout.write(HELP);
+    return 2;
+  }
+
+  if (command === "stats") {
+    return runStatsCommand({ rebuild: args.rebuildTotals, json: args.json, month: args.month, env: process.env });
+  }
+
   if (command === "omarchy") {
     const load = async () => {
       const everyFamily = enabledFamilies({ env: process.env });
-      const loadFresh = () => collectQuota({ families: everyFamily, timeoutMs: args.timeoutMs, refresh, force: args.force });
+      const loadFresh = () =>
+        collectQuota({ families: everyFamily, timeoutMs: args.timeoutMs, refresh, force: args.force, localStats: LOCAL_STATS });
       const fresh = args.noCache
         ? await loadFresh()
         : (await withCache({ ttlMs: args.ttlMs, force: args.force, families: everyFamily, key: CACHE_KEY }, loadFresh)).report;
@@ -149,7 +204,8 @@ async function main() {
     requested: families.length > 0 ? families : undefined,
     explicit,
   });
-  const load = () => collectQuota({ families: selected, explicit, timeoutMs: args.timeoutMs, refresh, force: args.force });
+  const load = () =>
+    collectQuota({ families: selected, explicit, timeoutMs: args.timeoutMs, refresh, force: args.force, localStats: LOCAL_STATS });
 
   let report;
   let cached = false;