@pify/usage 0.10.0 → 0.12.0

package/README.md

@@ -20,6 +20,8 @@ Folded from each message's `usage.cost`, which pi already computes. It survives
 
 When [`@pify/subagent`](https://github.com/pifydev/subagent), [`@pify/swarm`](https://github.com/pifydev/swarm) or [`@pify/workflow`](https://github.com/pifydev/workflow) run child agents, those children are separate in-memory sessions whose spend never reaches this branch — a session that delegates used to look cheaper than it was. Those packages now add every child message's cost to a process-wide tally, and the footer shows it as a separate ` · agents $0.12` beside the session's own figure (the `/usage` session block has the same line, with tokens). It is kept apart on purpose: the session numbers stay what the branch says, and the agents figure is what the delegation cost on top. The tally survives `/reload` and starts over with a new session.
 
+On a Claude subscription (OAuth Pro/Max) the footer also carries the wall you are approaching: the headers `/usage quota` reads were already captured on every response, but only that command showed them, so the weekly or 5-hour limit used to arrive as a stalled turn. Now a `⚠ 7d 8% · resets 14:05` segment appears once the binding window is below 15%, or whenever Anthropic marks the subscription as anything but allowed, and stays out of the way otherwise. Other providers carry no such headers, so they never show it.
+
 The gauge on the right is how full the context window is — the third mid-session question, next to tokens and cost. It was computed for the `/usage` dashboard but shown only there; now it is live. It appears once there is a window to measure against (so not under `-p`) and turns to `⚠` past 90%, the point where "how full" stops being trivia and becomes a decision. For the breakdown of what filled it, run `/context`.
 
 ## `/usage`
@@ -42,6 +44,12 @@ By project (all time)
   D--project-shop-api       $6.60 · 3.6M tok
 ```
 
+`/usage export` writes the history out — `by-model.csv`, `by-day.csv`, `by-project.csv` and `totals.json`, full precision — into a timestamped folder under the OS temp directory (or `PIFY_USAGE_EXPORT_DIR`), never into the repository or your home, and prints the path.
+
+The per-file scan cache is also kept on disk (`usage-scan-cache.json` next to pi's other state, keyed by size and mtime, versioned), so a fresh `pi` no longer pays the whole cold scan on its first `/usage`: it is read once before the first scan and rewritten after each completed one; a corrupt or older file is ignored and rebuilt, and only files the latest scan saw are kept.
+
+Once a session has shown a healthy prompt-cache hit rate on a large prompt, five large prompts in a row at ~0% hit raise one warning naming the likely causes — a model or thinking-level switch, a provider dropping its cache, something rewriting the start of the context each turn — because from then on every turn re-bills the whole prefix and the footer alone only shows the spend climbing.
+
 History counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result usage pi persists, and the summariser's own call, which pi records on the compaction and branch-summary entries themselves rather than on a message. Those summary calls are among the most expensive in a session, so counting them is what makes a session's total match what you were billed rather than what the visible messages add up to; they have no model of their own, so they group under a `compaction` / `branch_summary` label in the by-model view. The live footer and session totals fold the same summariser usage in as it happens (on compaction and tree navigation), so the number does not jump only after a reload. pi 0.87's cache warmer spends real money outside any message too, as standalone `usage` entries; those are counted under their own model on reload and in history (pi raises no extension event for them, so the live footer picks them up at the next session start). Negative and NaN fields clamp to zero, days are your **local** calendar days, and a per-file mtime cache keeps repeat scans instant.
 
 Per-project totals come for free: pi stores sessions one directory per project, so the dashboard can show where the money actually went.

package/extensions/usage.ts

@@ -32,10 +32,14 @@ import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggr
 import { buildBreakdown, contextTokensFromUsage, formatBreakdown, resolveUsedTokens } from "../src/context.ts";
 import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { childSpendTotal, onChildSpend, resetChildSpend } from "../src/child-cost.ts";
+import { buildByDayCsv, buildByModelCsv, buildByProjectCsv, buildTotalsJson } from "../src/export.ts";
+import { emptyCacheHealth, observeCacheHealth } from "../src/cache-health.ts";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
-import { scanSessions } from "../src/sessions.ts";
-import { parseRateLimit, formatRateLimit, type RateLimitSnapshot } from "../src/ratelimit.ts";
+import { scanSessions, persistScanCache, restoreScanCache } from "../src/sessions.ts";
+import { parseRateLimit, formatRateLimit, type RateLimitSnapshot, footerQuotaSegment } from "../src/ratelimit.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
 type UiContext = ExtensionContext;
@@ -83,7 +87,10 @@ export default function usage(pi: ExtensionAPI) {
       return;
     }
     const gauge = contextGauge(contextInfo(ctx).pct);
-    ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
+    // The subscription wall, from the headers already captured for this
+    // provider: quiet while healthy, a short warning once it is close.
+    const quota = footerQuotaSegment(rateLimits.get((ctx.model as { provider?: string } | null)?.provider ?? ""));
+    ctx.ui.setStatus("usage", [base, gauge, quota].filter(Boolean).join(" · "));
   }
 
   /**
@@ -109,9 +116,25 @@ export default function usage(pi: ExtensionAPI) {
     return { pct: Math.min(100, (used / window) * 100), window };
   }
 
+  /** The on-disk twin of the scan cache: read once before the first scan, written after each completed one. */
+  const scanCacheFile = () => join(getAgentDir(), "usage-scan-cache.json");
+  let scanCacheRestored = false;
+  function scanHistory() {
+    if (!scanCacheRestored) {
+      scanCacheRestored = true;
+      restoreScanCache(scanCacheFile());
+    }
+    const scan = scanSessions(join(getAgentDir(), "sessions"));
+    persistScanCache(scanCacheFile());
+    return scan;
+  }
+
+  /** Prompt-cache health for this session: warns once when a warm cache goes cold. */
+  let cacheHealth = emptyCacheHealth();
+
   function dashboard(ctx: UiContext): string {
     const history = aggregate(...(() => {
-      const scan = scanSessions(join(getAgentDir(), "sessions"));
+      const scan = scanHistory();
       return [scan.records, scan.files] as const;
     })());
     return [sessionBlock(session, contextInfo(ctx).pct, childSpendTotal()), historyBlock(history, Date.now())].join("\n\n");
@@ -125,6 +148,8 @@ export default function usage(pi: ExtensionAPI) {
     addRecord(session, record);
     const message = (event as { message?: { role?: string; usage?: unknown } }).message;
     if (message?.role === "assistant" && isRecord(message.usage)) {
+      const warning = observeCacheHealth(cacheHealth, message.usage as { input?: number; cacheRead?: number; cacheWrite?: number });
+      if (warning && ctx.hasUI) ctx.ui.notify(warning, "warning");
       // Use pi's own formula so the gauge cannot drift below pi's reading —
       // input+cacheRead alone dropped cacheWrite and output, a real slice of
       // every Anthropic prompt-cached turn.
@@ -140,6 +165,7 @@ export default function usage(pi: ExtensionAPI) {
     // Child spend is not in the branch, so a /reload must keep the tally; a
     // new, resumed or forked session starts its own.
     if ((event as { reason?: string }).reason !== "reload") resetChildSpend();
+    cacheHealth = emptyCacheHealth();
     footerCtx = ctx;
     stopChildSpend?.();
     stopChildSpend = onChildSpend(() => {
@@ -294,9 +320,31 @@ export default function usage(pi: ExtensionAPI) {
   }
 
   pi.registerCommand("usage", {
-    description: "Token and cost dashboard: /usage [context | quota]",
+    description: "Token and cost dashboard: /usage [context | quota | export]",
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
+      if ((args ?? "").trim().toLowerCase() === "export") {
+        // Hand the history off: CSV per model/day/project and a totals JSON,
+        // in the OS temp dir by default (never the repo or home), or
+        // PIFY_USAGE_EXPORT_DIR. Full precision; the reader rounds.
+        const scan = scanHistory();
+        const history = aggregate(scan.records, scan.files);
+        const now = Date.now();
+        const stamp = new Date(now).toISOString().replace(/[:.]/g, "-");
+        const dir = join(process.env.PIFY_USAGE_EXPORT_DIR?.trim() || join(tmpdir(), "pify-usage"), stamp);
+        try {
+          mkdirSync(dir, { recursive: true });
+          writeFileSync(join(dir, "by-model.csv"), buildByModelCsv(history.byModel));
+          writeFileSync(join(dir, "by-day.csv"), buildByDayCsv(history.byDay));
+          writeFileSync(join(dir, "by-project.csv"), buildByProjectCsv(history.byProject));
+          writeFileSync(join(dir, "totals.json"), buildTotalsJson(history.total, history.files, now));
+        } catch (err) {
+          ctx.ui.notify(`Export failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+          return;
+        }
+        ctx.ui.notify(`✓ Exported by-model.csv, by-day.csv, by-project.csv and totals.json to ${dir}`, "info");
+        return;
+      }
       if ((args ?? "").trim().toLowerCase() === "context") {
         // Documented since the breakdown landed, but never wired — the handler
         // only knew "quota", so `/usage context` quietly showed the dashboard.
@@ -358,7 +406,7 @@ export default function usage(pi: ExtensionAPI) {
       "is proportionate, or whether to /compact first.",
     parameters: Type.Object({}),
     async execute(_id, _params, _signal, _onUpdate, ctx) {
-      const scan = scanSessions(join(getAgentDir(), "sessions"));
+      const scan = scanHistory();
       const history = aggregate(scan.records, scan.files);
       const today = windowTotals(history.byDay, 1, Date.now());
       const lines = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",

package/src/cache-health.ts

@@ -0,0 +1,69 @@
+/**
+ * Noticing when the prompt cache stops working.
+ *
+ * A session that enjoyed a warm prefix cache can lose it mid-way — a model
+ * switch, a provider dropping its cached KV, a context edit that rewrote
+ * the prefix — and from then on every turn re-bills the whole prompt cold.
+ * The footer shows the spend climbing; nothing names the cause. This is a
+ * small state machine fed with each assistant message's usage: once the
+ * session has shown a healthy hit rate on a large prompt, a run of large
+ * prompts at ~0% hit trips one warning, and only one. Pure; the extension
+ * feeds it and resets it at session start. (billion-context's cache-warn,
+ * reduced to the in-process case — a restart is a new session here.)
+ */
+
+export const MIN_PROMPT_TOKENS = 8_000;
+export const HEALTHY_HIT = 0.5;
+export const COLLAPSED_HIT = 0.05;
+export const LOW_RUN = 5;
+
+export interface CacheHealthState {
+  sawHealthy: boolean;
+  lowRun: number;
+  warned: boolean;
+  lastHealthyHit: number;
+}
+
+export function emptyCacheHealth(): CacheHealthState {
+  return { sawHealthy: false, lowRun: 0, warned: false, lastHealthyHit: 0 };
+}
+
+export interface PromptUsageLike {
+  input?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/** The share of the prompt that came from the cache; null when the prompt is too small to judge. */
+export function cacheHit(usage: PromptUsageLike): number | null {
+  const input = Math.max(0, usage.input ?? 0);
+  const read = Math.max(0, usage.cacheRead ?? 0);
+  const write = Math.max(0, usage.cacheWrite ?? 0);
+  const prompt = input + read + write;
+  if (prompt < MIN_PROMPT_TOKENS) return null;
+  return read / prompt;
+}
+
+/** Feed one assistant message; returns the warning text exactly once, when the collapse is confirmed. */
+export function observeCacheHealth(state: CacheHealthState, usage: PromptUsageLike): string | null {
+  const hit = cacheHit(usage);
+  if (hit === null) return null;
+  if (hit >= HEALTHY_HIT) {
+    state.sawHealthy = true;
+    state.lastHealthyHit = hit;
+    state.lowRun = 0;
+    return null;
+  }
+  if (!state.sawHealthy || hit > COLLAPSED_HIT) {
+    state.lowRun = 0;
+    return null;
+  }
+  state.lowRun++;
+  if (state.lowRun < LOW_RUN || state.warned) return null;
+  state.warned = true;
+  return (
+    `Prompt cache collapsed: ${LOW_RUN} large prompts in a row at ~${Math.round(hit * 100)}% cache hit after a healthy ` +
+    `${Math.round(state.lastHealthyHit * 100)}%. Every turn is now re-billing the whole prefix. Likely causes: a model ` +
+    `or thinking-level switch, a provider dropping its cache, or something rewriting the start of the context each turn.`
+  );
+}

package/src/export.ts

@@ -0,0 +1,40 @@
+/**
+ * Handing the history off: CSV for a spreadsheet, JSON for a script.
+ * Pure builders over the aggregate the dashboard already computes; the
+ * extension owns the disk write. Full precision, no rounding — rounding is
+ * the reader's call.
+ */
+import type { UsageTotals } from "./types.ts";
+
+function csvCell(value: string | number): string {
+  const text = String(value);
+  return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+function totalsRow(key: string, t: UsageTotals): string {
+  return [key, t.messages, t.input, t.output, t.cacheRead, t.cacheWrite, t.totalTokens, t.cost].map(csvCell).join(",");
+}
+
+const HEADER = "input,output,cacheRead,cacheWrite,totalTokens,cost";
+
+/** One row per model, costliest first. */
+export function buildByModelCsv(byModel: ReadonlyMap<string, UsageTotals>): string {
+  const rows = [...byModel.entries()].sort((a, b) => b[1].cost - a[1].cost).map(([model, t]) => totalsRow(model, t));
+  return [`model,messages,${HEADER}`, ...rows].join("\n") + "\n";
+}
+
+/** One row per local calendar day, oldest first. */
+export function buildByDayCsv(byDay: ReadonlyMap<string, UsageTotals>): string {
+  const rows = [...byDay.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([day, t]) => totalsRow(day, t));
+  return [`day,messages,${HEADER}`, ...rows].join("\n") + "\n";
+}
+
+/** One row per project, costliest first. */
+export function buildByProjectCsv(byProject: ReadonlyMap<string, UsageTotals>): string {
+  const rows = [...byProject.entries()].sort((a, b) => b[1].cost - a[1].cost).map(([p, t]) => totalsRow(p || "(no project)", t));
+  return [`project,messages,${HEADER}`, ...rows].join("\n") + "\n";
+}
+
+export function buildTotalsJson(total: UsageTotals, files: number, generatedAt: number): string {
+  return `${JSON.stringify({ generatedAt: new Date(generatedAt).toISOString(), files, total }, null, 2)}\n`;
+}

package/src/ratelimit.ts

@@ -166,6 +166,46 @@ function formatReset(snap: RateLimitSnapshot): string {
   return raw;
 }
 
+/** A reset time short enough for the footer: HH:MM today, otherwise MM-DD HH:MM; "" when unknown or unwieldy. */
+export function shortReset(snap: RateLimitSnapshot, now: number = Date.now()): string {
+  const raw = snap.resets;
+  if (!raw) return "";
+  if (snap.source === "anthropic" && /^\d{9,}$/.test(raw)) {
+    const d = new Date(Number.parseInt(raw, 10) * 1000);
+    if (!Number.isFinite(d.getTime())) return "";
+    const hm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    const sameDay = new Date(now).toDateString() === d.toDateString();
+    return sameDay ? hm : `${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${hm}`;
+  }
+  return raw.length <= 12 ? raw : "";
+}
+
+/** Below this share of the binding window left, the footer starts warning. */
+export const FOOTER_WARN_FRACTION = 0.15;
+
+/**
+ * The footer's quota warning, or "" while the session is healthy. A Claude
+ * subscription user used to learn about the 5h/7d wall only when a turn
+ * stalled, or by opening `/usage quota` — the headers were captured either
+ * way. This shows the binding window once it is nearly gone, or whenever
+ * Anthropic marks the subscription as anything but "allowed". Non-Anthropic
+ * providers carry none of these fields, so it stays empty for them.
+ */
+export function footerQuotaSegment(snap: RateLimitSnapshot | null | undefined, now: number = Date.now()): string {
+  if (!snap) return "";
+  const binding =
+    snap.unifiedBinding ?? (snap.unified7dRemaining !== null ? "7d" : snap.unified5hRemaining !== null ? "5h" : null);
+  const remaining = binding === "7d" ? snap.unified7dRemaining : binding === "5h" ? snap.unified5hRemaining : null;
+  const walled = Boolean(snap.unifiedStatus && snap.unifiedStatus !== "allowed");
+  const low = remaining !== null && remaining < FOOTER_WARN_FRACTION;
+  if (!walled && !low) return "";
+  const parts = [`⚠ ${binding ?? "subscription"}`];
+  if (remaining !== null) parts.push(`${Math.max(0, Math.round(remaining * 100))}%`);
+  if (walled) parts.push(snap.unifiedStatus!.replace(/_/g, " "));
+  const reset = shortReset(snap, now);
+  return reset ? `${parts.join(" ")} · resets ${reset}` : parts.join(" ");
+}
+
 /** One human line for the /usage quota report; null when nothing was captured. */
 export function formatRateLimit(snap: RateLimitSnapshot | null): string | null {
   if (!snap) return null;

package/src/sessions.ts

@@ -1,5 +1,5 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { recordFromLine } from "./aggregate.ts";
 import type { UsageRecord } from "./types.ts";
 
@@ -12,9 +12,66 @@ import type { UsageRecord } from "./types.ts";
 const MAX_FILE_BYTES = 64 * 1024 * 1024;
 
 const cache = new Map<string, { mtimeMs: number; size: number; records: UsageRecord[] }>();
+/** Files the latest scan saw; only these are persisted, so a moved store does not grow the cache forever. */
+let lastSeen = new Set<string>();
 
 export function clearScanCache(): void {
   cache.clear();
+  lastSeen = new Set();
+}
+
+/** Bump when the cached record shape changes; an older file is ignored and rebuilt. */
+export const SCAN_CACHE_VERSION = 1;
+/** Entries kept on disk; beyond it the oldest-modified files are dropped. */
+export const SCAN_CACHE_MAX_ENTRIES = 5000;
+
+/**
+ * The in-process cache only ever helped within one pi process, and the
+ * dashboard is opened about once per session — so every fresh pi paid the
+ * whole cold scan (seconds, for a large store) on the first /usage. The
+ * same Map, written once after a completed scan and read back before the
+ * first, makes a warm open cheap. Keyed by size+mtime exactly like the
+ * in-memory check, so a stale entry is simply re-read; corrupt, missing or
+ * older-version files start empty. Last writer wins — no lock: the cost of
+ * a lost write is one cold scan. (pi-usage-extension's cache, simplified.)
+ */
+export function restoreScanCache(file: string): number {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return 0;
+  }
+  if (!raw || typeof raw !== "object" || (raw as { version?: unknown }).version !== SCAN_CACHE_VERSION) return 0;
+  const entries = (raw as { entries?: unknown }).entries;
+  if (!entries || typeof entries !== "object") return 0;
+  let loaded = 0;
+  for (const [path, value] of Object.entries(entries as Record<string, unknown>)) {
+    const v = value as { mtimeMs?: unknown; size?: unknown; records?: unknown };
+    if (typeof v?.mtimeMs !== "number" || typeof v.size !== "number" || !Array.isArray(v.records)) continue;
+    cache.set(path, { mtimeMs: v.mtimeMs, size: v.size, records: v.records as UsageRecord[] });
+    loaded++;
+  }
+  return loaded;
+}
+
+export function persistScanCache(file: string): number {
+  const kept = [...cache.entries()]
+    .filter(([path]) => lastSeen.has(path))
+    .sort((a, b) => b[1].mtimeMs - a[1].mtimeMs)
+    .slice(0, SCAN_CACHE_MAX_ENTRIES);
+  const entries: Record<string, { mtimeMs: number; size: number; records: UsageRecord[] }> = {};
+  for (const [path, value] of kept) entries[path] = value;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ version: SCAN_CACHE_VERSION, entries }));
+    renameSync(tmp, file);
+  } catch {
+    // An unwritable cache costs the next process one cold scan, nothing else.
+    return 0;
+  }
+  return kept.length;
 }
 
 function listJsonlFiles(dir: string, depth: number): string[] {
@@ -87,9 +144,11 @@ function groupByProject(sessionsDir: string): Array<{ project: string; files: st
 export function scanSessions(sessionsDir: string): ScanResult {
   const records: UsageRecord[] = [];
   let fileCount = 0;
+  const seen = new Set<string>();
   for (const { project, files } of groupByProject(sessionsDir)) {
     fileCount += files.length;
     for (const file of files) {
+      seen.add(file);
       try {
         const stat = statSync(file);
         const cached = cache.get(file);
@@ -109,5 +168,6 @@ export function scanSessions(sessionsDir: string): ScanResult {
       }
     }
   }
+  lastSeen = seen;
   return { records, files: fileCount };
 }