@pify/usage 0.11.0 → 0.12.0

package/README.md

@@ -44,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,9 +32,13 @@ 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 { 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";
 
@@ -112,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");
@@ -128,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.
@@ -143,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(() => {
@@ -297,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.
@@ -361,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.11.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/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 };
 }