@ohgodtamit/pi-usage 0.1.0-alpha.0

package/src/cache.ts

@@ -0,0 +1,100 @@
+/**
+ * Persistent, incremental scan cache.
+ *
+ * Re-reading and JSON-parsing every session file on each `/usage` open is the
+ * dominant cost (hundreds of files, hundreds of MB). Session files are almost
+ * all immutable once written, so we cache the *attributed turns* per session
+ * keyed by the file's mtime + size. A later scan only re-parses files whose
+ * mtime/size changed; everything else is reused from this cache.
+ *
+ * The cache is keyed by a `pricesKey` fingerprint too, because manual prices
+ * are baked into each turn's cost at parse time — if prices change, the whole
+ * cache is rebuilt.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelPrice } from "./config.ts";
+import type { ChildSessionSummary, SoftRecord, TurnEntry } from "./aggregate.ts";
+
+/** Bump when the cached entry shape changes, to invalidate stale caches. */
+const CACHE_VERSION = 6;
+
+export interface CachedSession {
+  mtimeMs: number;
+  size: number;
+  entries: TurnEntry[];
+  child?: ChildSessionSummary;
+  /** `subagents:record` metadata entries found in this transcript. */
+  records?: SoftRecord[];
+}
+
+export interface ScanCache {
+  version: number;
+  /** Fingerprint of the price table the cached costs were computed with. */
+  pricesKey: string;
+  /** Fingerprint of excluded project prefixes used during attribution. */
+  excludesKey: string;
+  /** Per-session-file cached attribution, keyed by absolute file path. */
+  sessions: Record<string, CachedSession>;
+}
+
+/** Stable fingerprint of the price table (key order-independent). */
+export function excludesFingerprint(excludes: string[] | undefined): string {
+  return (excludes ?? [])
+    .map((value) => value.replace(/\\/g, "/").toLowerCase())
+    .sort()
+    .join("|");
+}
+
+export function pricesFingerprint(prices: Record<string, ModelPrice> | undefined): string {
+  if (!prices) return "";
+  const keys = Object.keys(prices).sort();
+  const parts = keys.map((k) => {
+    const p = prices[k];
+    return `${k}:${p.input ?? 0},${p.output ?? 0},${p.cacheRead ?? 0},${p.cacheWrite ?? 0}`;
+  });
+  return parts.join("|");
+}
+
+function cachePath(): string {
+  return join(getAgentDir(), "usage-cache.json");
+}
+
+/** Load the scan cache; returns an empty cache on any error/missing file. */
+export function loadScanCache(): ScanCache {
+  const empty: ScanCache = {
+    version: CACHE_VERSION,
+    pricesKey: "",
+    excludesKey: "",
+    sessions: {},
+  };
+  const path = cachePath();
+  if (!existsSync(path)) return empty;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as ScanCache;
+    if (parsed.version !== CACHE_VERSION || typeof parsed.sessions !== "object") {
+      return empty;
+    }
+    return {
+      version: CACHE_VERSION,
+      pricesKey: parsed.pricesKey ?? "",
+      excludesKey: parsed.excludesKey ?? "",
+      sessions: parsed.sessions ?? {},
+    };
+  } catch (err) {
+    console.error(`[usage] Failed to read scan cache: ${err}`);
+    return empty;
+  }
+}
+
+/** Persist the scan cache. Never throws. */
+export function saveScanCache(cache: ScanCache): void {
+  const path = cachePath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cache), "utf8");
+  } catch (err) {
+    console.error(`[usage] Failed to write scan cache: ${err}`);
+  }
+}

package/src/config.ts

@@ -0,0 +1,93 @@
+/**
+ * Persistent configuration for the usage extension.
+ *
+ * Stored at ~/.pi/agent/usage.json so it survives restarts and is easy to
+ * edit by hand. Limits are expressed in USD; omit or set to 0 to disable a
+ * quota bar (the panel then shows raw spend without a limit).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MODEL_PRICES } from "./prices.ts";
+
+/**
+ * Manual price for a model, in USD per **million tokens**. Used to compute a
+ * cost for token-priced / proxied providers that pi records with cost 0
+ * (e.g. zai/GLM, 9Router `kr/…`, `cx/…`). Omitted fields count as 0.
+ */
+export interface ModelPrice {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+export interface UsageConfig {
+  /** USD budget for the rolling 5-hour window. 0/undefined disables the bar. */
+  fiveHourLimit?: number;
+  /** USD budget for the rolling 7-day (weekly) window. 0/undefined disables the bar. */
+  weeklyLimit?: number;
+  /** Token budget for the rolling 5-hour window (for token-priced providers like zai/GLM). */
+  fiveHourTokenLimit?: number;
+  /** Token budget for the rolling 7-day (weekly) window. */
+  weeklyTokenLimit?: number;
+  /** When true, show a compact one-line usage summary widget above the editor. */
+  showWidget?: boolean;
+  /** Project cwd prefixes to exclude from aggregation (e.g. throwaway dirs). */
+  excludeProjects?: string[];
+  /** Maximum number of session files to scan (safety cap for huge histories). */
+  maxSessions?: number;
+  /**
+   * Manual per-model prices ($/million tokens) used to fill in cost when pi
+   * recorded none. Keyed by model ID; an entry keyed by the base name (without
+   * a proxy prefix like `kr/`) matches all proxied variants.
+   */
+  modelPrices?: Record<string, ModelPrice>;
+}
+
+const DEFAULTS: UsageConfig = {
+  fiveHourLimit: 0,
+  weeklyLimit: 0,
+  fiveHourTokenLimit: 0,
+  weeklyTokenLimit: 0,
+  showWidget: false,
+  excludeProjects: [],
+  maxSessions: 1000,
+  modelPrices: {},
+};
+
+function configPath(): string {
+  return join(getAgentDir(), "usage.json");
+}
+
+/** Load config, merged with defaults. Never throws — returns defaults on error. */
+export function loadConfig(): UsageConfig {
+  const path = configPath();
+  if (!existsSync(path)) {
+    return { ...DEFAULTS, modelPrices: { ...DEFAULT_MODEL_PRICES } };
+  }
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as Partial<UsageConfig>;
+    // Bundled prices are defaults; the user's modelPrices override per-key.
+    return {
+      ...DEFAULTS,
+      ...parsed,
+      modelPrices: { ...DEFAULT_MODEL_PRICES, ...(parsed.modelPrices ?? {}) },
+    };
+  } catch (err) {
+    console.error(`[usage] Failed to read ${path}: ${err}`);
+    return { ...DEFAULTS, modelPrices: { ...DEFAULT_MODEL_PRICES } };
+  }
+}
+
+/** Persist config to disk. Creates the agent dir if needed. */
+export function saveConfig(config: UsageConfig): void {
+  const path = configPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  } catch (err) {
+    console.error(`[usage] Failed to write ${path}: ${err}`);
+  }
+}

package/src/format.ts

@@ -0,0 +1,166 @@
+/**
+ * Number, currency, and progress-bar formatting helpers for the usage panel.
+ *
+ * Kept dependency-free so it is easy to unit-test and reuse.
+ */
+
+/** Format a token count with k/M suffixes. */
+export function formatTokens(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return "0";
+  if (n < 1000) return `${Math.round(n)}`;
+  if (n < 1_000_000) return `${trim(n / 1000)}k`;
+  return `${trim(n / 1_000_000)}M`;
+}
+
+/** Format a USD cost. Small amounts get more precision. */
+export function formatCost(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return "$0.00";
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  if (n < 1) return `$${n.toFixed(3)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+/** Percentage of `part` relative to `total`, as a rounded integer string. */
+export function percent(part: number, total: number): string {
+  if (total <= 0) return "0%";
+  return `${Math.round((part / total) * 100)}%`;
+}
+
+/** Render a horizontal progress bar. Returns the bar string (without ANSI). */
+export function bar(ratio: number, width: number): string {
+  const w = Math.max(0, Math.floor(width));
+  const filled = Math.max(0, Math.min(w, Math.round(Math.max(0, Math.min(1, ratio)) * w)));
+  return "█".repeat(filled) + "░".repeat(w - filled);
+}
+
+/** Shorten an absolute path to a friendly project label (~/... style). */
+export function shortenPath(p: string, home: string): string {
+  if (!p) return "(unknown)";
+  let path = p.replace(/\\/g, "/");
+  const homeN = home.replace(/\\/g, "/");
+  if (homeN && path.toLowerCase().startsWith(homeN.toLowerCase())) {
+    path = `~${path.slice(homeN.length)}`;
+  }
+  // Show last two segments for very long paths.
+  const parts = path.split("/").filter(Boolean);
+  if (parts.length > 3) return parts.slice(-2).join("/");
+  return path || "(unknown)";
+}
+
+/**
+ * Derive a human-friendly plugin label from a resource's SourceInfo.
+ *
+ * Priority:
+ *   1. Package sources (npm:/git:/github:) → package name (ref stripped)
+ *   2. Local/auto skills → the `/skills/<group>/` segment from the path, so
+ *      e.g. `~/.claude/skills/bmad/core/bmad-master/SKILL.md` → "bmad" and
+ *      `~/.pi/agent/skills/frontend-design/SKILL.md` → "frontend-design".
+ *   3. Local extensions → last baseDir segment (skipping generic names)
+ *   4. fallback "other"
+ */
+export function sourceLabel(sourceInfo: {
+  source?: string;
+  baseDir?: string;
+  path?: string;
+}): string {
+  const { source, baseDir, path } = sourceInfo;
+
+  // 1. Package sources → package name.
+  if (source && /^(npm|git|github|file):/.test(source)) {
+    let s = source;
+    for (const prefix of ["npm:", "git:", "github:", "file:"]) {
+      if (s.startsWith(prefix)) s = s.slice(prefix.length);
+    }
+    s = s.replace(/@[^/]+$/, ""); // strip @version/@sha/@branch
+    const parts = s.split("/");
+    return parts[parts.length - 1] || s;
+  }
+
+  // 2. Local/auto skills: group by the segment right after "/skills/".
+  if (path) {
+    const p = path.replace(/\\/g, "/");
+    const m = p.match(/\/skills\/([^/]+)\//);
+    if (m?.[1]) return m[1];
+  }
+
+  // 3. Local extensions: last meaningful baseDir segment.
+  if (baseDir) {
+    const base = baseDir.replace(/\\/g, "/").replace(/\/$/, "").split("/").pop();
+    if (base && base !== "extensions" && base !== "skills" && base !== "agent") {
+      return base;
+    }
+  }
+
+  return "other";
+}
+
+function trim(n: number): string {
+  return (Math.round(n * 10) / 10).toString();
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+/** Human day label from a `YYYY-MM-DD` key, e.g. "Mon Jun 17". */
+export function formatDayLabel(dateKey: string): string {
+  const [y, m, d] = dateKey.split("-").map((n) => Number.parseInt(n, 10));
+  if (!y || !m || !d) return dateKey;
+  const date = new Date(y, m - 1, d);
+  return `${WEEKDAYS[date.getDay()]} ${MONTHS[m - 1]} ${`${d}`.padStart(2, "0")}`;
+}
+
+/** Short month name for a 1-based month index (1 = Jan). */
+export function monthLabel(month1: number): string {
+  return MONTHS[(month1 - 1 + 12) % 12] ?? "";
+}
+
+const SPARK_CHARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+
+/** Render a unicode sparkline for a series of non-negative values. */
+export function sparkline(values: number[]): string {
+  if (values.length === 0) return "";
+  const max = Math.max(...values);
+  if (max <= 0) return SPARK_CHARS[0].repeat(values.length);
+  return values
+    .map((v) => {
+      if (v <= 0) return " ";
+      const idx = Math.min(
+        SPARK_CHARS.length - 1,
+        Math.max(0, Math.round((v / max) * (SPARK_CHARS.length - 1))),
+      );
+      return SPARK_CHARS[idx];
+    })
+    .join("");
+}
+
+/** Heatmap glyphs per intensity level (0 = empty). */
+export const HEAT_CHARS = ["·", "▪", "▩", "▣", "█"] as const;
+
+/** Format an hour-of-day (0-23) as a friendly 12-hour label, e.g. "2pm". */
+export function formatHour(h: number): string {
+  const hour = ((h % 24) + 24) % 24;
+  if (hour === 0) return "12am";
+  if (hour === 12) return "12pm";
+  return hour < 12 ? `${hour}am` : `${hour - 12}pm`;
+}
+
+/** Format an integer with thousands separators (e.g. 24086 → "24,086"). */
+export function formatInt(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  return Math.round(n).toLocaleString("en-US");
+}
+
+/** Format a duration in ms as a compact human string (e.g. "2h 14m"). */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "—";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  if (h < 24) return rm ? `${h}h ${rm}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  const rh = h % 24;
+  return rh ? `${d}d ${rh}h` : `${d}d`;
+}

package/src/freshness.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory report-cache freshness decision.
+ *
+ * The usage panel reuses a scanned `Report` for up to `CACHE_TTL` to avoid
+ * re-reading hundreds of session files on every `/usage` open. That TTL is
+ * purely time-based — which is exactly the bug behind the trend graph looking
+ * frozen ("always the same"): a user who opens the panel, spends more tokens,
+ * and reopens within the TTL window gets the *same* stale snapshot back, even
+ * though the live session file on disk already has the new turns.
+ *
+ * The fix is to also invalidate the cache whenever a new assistant turn has
+ * landed since the cache was built. Because pi flushes each turn to disk in
+ * realtime, a fresh scan will then pick those turns up, so the trend (and every
+ * other panel view) reflects current usage instead of a snapshot from up to
+ * two minutes ago.
+ *
+ * This module is intentionally dependency-free so the decision is unit-testable
+ * in isolation.
+ */
+
+/** A cache entry carrying the epoch-ms timestamp it was built at. */
+export interface ReportCacheStamp {
+  at: number;
+}
+
+/**
+ * Is the in-memory report cache still fresh enough to reuse without rescanning?
+ *
+ * Fresh only when ALL of:
+ *   1. a cache exists,
+ *   2. we're still inside the TTL window, and
+ *   3. no assistant turn has arrived after the cache was built.
+ *
+ * Condition (3) is the realtime fix: a new turn means the on-disk session file
+ * changed, so the cached report is stale regardless of the TTL window.
+ *
+ * @param cached     The current in-memory cache stamp (or null when none yet).
+ * @param now        Current epoch-ms.
+ * @param lastTurnAt Epoch-ms of the most recent assistant turn seen this pi run,
+ *                   or 0 when no turn has been observed.
+ * @param ttlMs      Max age of a cache entry before it is considered stale.
+ */
+export function isReportCacheFresh(
+  cached: ReportCacheStamp | null,
+  now: number,
+  lastTurnAt: number,
+  ttlMs: number,
+): boolean {
+  if (!cached) return false;
+  if (now - cached.at >= ttlMs) return false;
+  // A turn that arrived after the cache was built invalidates it, regardless
+  // of the TTL window, so the next open re-reads the (fresh) session files.
+  if (lastTurnAt > cached.at) return false;
+  return true;
+}