@pify/usage 0.1.0 → 0.3.0

package/README.md

@@ -22,12 +22,28 @@ History (214 local session files)
 By model (all time)
   anthropic/claude-fable-5  $12.30 · 4.1M tok
   openai/gpt-5.5            $9.10 · 5.7M tok
+By project (all time)
+  D--project-pify-plugins   $14.80 · 6.2M tok
+  D--project-shop-api       $6.60 · 3.6M tok
 ```
 
 - **History done right** (tmustier's lessons): counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result/compaction usage pi 0.81+ persists; negative/NaN fields clamp to zero; days are your local calendar days; a per-file mtime cache keeps repeat scans instant.
+- **Per-project spend** (v0.2): pi stores sessions one directory per project, so the dashboard can show where the money actually went — the top 5 projects by cost, all time.
 - **`usage_status` tool**: the agent can check session + today totals before committing to expensive work (subagent fan-outs, large reads).
 
-Provider quota APIs (Codex windows, Copilot allowances, OpenRouter credits…) are deliberately out of v0.1 — they cost ~18k lines of per-provider contract maintenance (see `@narumitw/pi-usage` if you need them today).
+## `/usage quota` (v0.3)
+
+The one command in this package that touches the network, and only when you run it:
+
+```
+Quota (openrouter · sk-or-v1-395...563)
+  spent    $0.32 (no credit limit on this key)
+  window   day $0.32 · week $0.32 · month $0.32
+```
+
+The key is read from the same `~/.pi/agent/auth.json` pi already uses (or `OPENROUTER_API_KEY`) — no second place to configure credentials — and only the provider's own masked label is ever printed. An 8-second timeout, and any failure renders as `unavailable — HTTP 401` rather than throwing.
+
+Only OpenRouter is implemented. The other providers report opaque rate-limit windows rather than a balance, and chasing all of them costs ~18k lines of per-provider contract maintenance (see `@narumitw/pi-usage` if you need them today).
 
 ## License
 

package/extensions/usage.ts

@@ -10,9 +10,12 @@
  * tmustier's lesson) with a per-file mtime cache. The usage_status tool
  * lets the agent itself check consumption mid-session.
  *
- * Provider quota APIs (Codex windows, Copilot, OpenRouter…) are deliberately
- * v0.2 — @narumitw/pi-usage shows they cost ~18k lines of per-provider
- * contract maintenance.
+ * Everything above is local: no network, no LLM tokens. The single exception
+ * is /usage quota (v0.3), which asks OpenRouter what this key has spent —
+ * opt-in per call, 8s timeout, and a failure prints as "unavailable" beside
+ * the local numbers. Other providers stay out: @narumitw/pi-usage shows the
+ * full set costs ~18k lines of per-provider contract chasing, and OpenRouter
+ * is the one that reports a real balance rather than an opaque window.
  */
 import {
   getAgentDir,
@@ -21,9 +24,11 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { join } from "node:path";
+import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
+import { fetchOpenRouterQuota, quotaBlock } from "../src/quota.ts";
 import { scanSessions } from "../src/sessions.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
@@ -86,10 +91,33 @@ export default function usage(pi: ExtensionAPI) {
 
   // ── Command & tool ───────────────────────────────────────────────────
 
+  /**
+   * The key pi itself uses, read from the same auth.json — no second place to
+   * configure credentials, and no key is ever printed.
+   */
+  function providerKey(provider: string): string {
+    try {
+      const auth = JSON.parse(readFileSync(join(getAgentDir(), "auth.json"), "utf8")) as Record<string, unknown>;
+      const entry = auth[provider];
+      if (isRecord(entry) && typeof entry.key === "string") return entry.key;
+    } catch {
+      // no auth.json, or unreadable — fall through to the environment
+    }
+    return process.env.OPENROUTER_API_KEY ?? "";
+  }
+
   pi.registerCommand("usage", {
-    description: "Token and cost dashboard: current session + local history",
-    handler: async (_args, ctx) => {
-      if (ctx.hasUI) ctx.ui.notify(dashboard(ctx), "info");
+    description: "Token and cost dashboard: /usage [quota]",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+      if ((args ?? "").trim().toLowerCase() === "quota") {
+        // The one networked call in this package, and only when asked for.
+        ctx.ui.notify("Checking provider quota…", "info");
+        const result = await fetchOpenRouterQuota(providerKey("openrouter"));
+        ctx.ui.notify(quotaBlock(result), result.ok ? "info" : "warning");
+        return;
+      }
+      ctx.ui.notify(dashboard(ctx), "info");
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Token and cost reporting for pi sessions: live footer, /usage dashboard over local session history, zero network",
   "keywords": [
     "pi-package",

package/src/aggregate.ts

@@ -32,6 +32,7 @@ export function dayKey(timestamp: number): string {
 export function aggregate(records: UsageRecord[], files: number): HistoryAggregate {
   const byDay = new Map<string, UsageTotals>();
   const byModel = new Map<string, UsageTotals>();
+  const byProject = new Map<string, UsageTotals>();
   const total = emptyTotals();
 
   for (const record of records) {
@@ -40,9 +41,13 @@ export function aggregate(records: UsageRecord[], files: number): HistoryAggrega
     addRecord(byDay.get(day) ?? byDay.set(day, emptyTotals()).get(day)!, record);
     const model = `${record.provider}/${record.model}`;
     addRecord(byModel.get(model) ?? byModel.set(model, emptyTotals()).get(model)!, record);
+    if (record.project) {
+      const p = record.project;
+      addRecord(byProject.get(p) ?? byProject.set(p, emptyTotals()).get(p)!, record);
+    }
   }
 
-  return { byDay, byModel, total, files };
+  return { byDay, byModel, byProject, total, files };
 }
 
 /** Sum totals for days within the trailing window (inclusive of today). */
@@ -91,6 +96,7 @@ export function recordFromEntry(entry: unknown): UsageRecord | null {
     timestamp: Number.isFinite(ts) ? ts : 0,
     model: typeof message.model === "string" ? message.model : "unknown",
     provider: typeof message.provider === "string" ? message.provider : "unknown",
+    project: "",
     input: finite(usage.input),
     output: finite(usage.output),
     cacheRead: finite(usage.cacheRead),

package/src/format.ts

@@ -43,16 +43,24 @@ export function historyBlock(history: HistoryAggregate, now: number): string {
     `  30 days  ${formatCost(month.cost)} · ${formatTokens(month.totalTokens)} tok`,
   ];
 
-  const models = [...history.byModel.entries()]
-    .sort((a, b) => b[1].cost - a[1].cost)
-    .slice(0, 6);
-  if (models.length > 0) {
-    lines.push("By model (all time)");
-    const width = models.reduce((m, [name]) => Math.max(m, Math.min(name.length, 40)), 0);
-    for (const [name, totals] of models) {
-      const label = name.length > 40 ? `${name.slice(0, 39)}…` : name;
-      lines.push(`  ${label.padEnd(width)}  ${formatCost(totals.cost)} · ${formatTokens(totals.totalTokens)} tok`);
-    }
-  }
+  pushBreakdown(lines, "By model (all time)", history.byModel, 6);
+  pushBreakdown(lines, "By project (all time)", history.byProject, 5);
   return lines.join("\n");
 }
+
+/** One "name  $cost · N tok" table, biggest spend first. */
+function pushBreakdown(
+  lines: string[],
+  heading: string,
+  totals: Map<string, UsageTotals>,
+  limit: number,
+): void {
+  const rows = [...totals.entries()].sort((a, b) => b[1].cost - a[1].cost).slice(0, limit);
+  if (rows.length === 0) return;
+  lines.push(heading);
+  const width = rows.reduce((m, [name]) => Math.max(m, Math.min(name.length, 40)), 0);
+  for (const [name, t] of rows) {
+    const label = name.length > 40 ? `${name.slice(0, 39)}…` : name;
+    lines.push(`  ${label.padEnd(width)}  ${formatCost(t.cost)} · ${formatTokens(t.totalTokens)} tok`);
+  }
+}

package/src/quota.ts

@@ -0,0 +1,124 @@
+/**
+ * Provider quota (v0.3). Everything else in this package is computed from
+ * local files — this is the one place that talks to a network, so it is
+ * opt-in per call, short-timeout, and never blocks the dashboard: a provider
+ * that is slow or down shows as unavailable next to the local numbers.
+ *
+ * Only OpenRouter is implemented. @narumitw/pi-usage shows what the full set
+ * costs — roughly 18k lines of per-provider contract chasing — and OpenRouter
+ * is the one endpoint that reports a real balance rather than an opaque
+ * rate-limit window.
+ */
+
+import { finite, isRecord } from "./types.ts";
+
+export interface QuotaInfo {
+  provider: string;
+  /** Spend on this key, in USD, as the provider reports it. */
+  used: number | null;
+  /** Hard credit limit, when the key has one. */
+  limit: number | null;
+  remaining: number | null;
+  /** Rolling-window spend, when reported. */
+  daily: number | null;
+  weekly: number | null;
+  monthly: number | null;
+  label: string | null;
+  freeTier: boolean | null;
+}
+
+export type QuotaResult =
+  | { ok: true; quota: QuotaInfo }
+  | { ok: false; provider: string; reason: string };
+
+export const QUOTA_TIMEOUT_MS = 8000;
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Shape the /api/v1/key payload. OpenRouter reports `limit: null` for keys
+ * with no cap, so "no limit" and "limit of zero" must not collapse together.
+ */
+export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload)) return null;
+  // The endpoint wraps its fields in `data`; a flat body is accepted too, but
+  // a `data` that is present and not an object means the shape changed.
+  if ("data" in payload && !isRecord(payload.data)) return null;
+  const data = isRecord(payload.data) ? payload.data : payload;
+
+  const used = num(data.usage);
+  const limit = num(data.limit);
+  const remaining = num(data.limit_remaining) ?? (limit !== null && used !== null ? limit - used : null);
+
+  return {
+    provider: "openrouter",
+    used: used === null ? null : finite(used),
+    limit,
+    remaining,
+    daily: num(data.usage_daily),
+    weekly: num(data.usage_weekly),
+    monthly: num(data.usage_monthly),
+    label: typeof data.label === "string" ? data.label : null,
+    freeTier: typeof data.is_free_tier === "boolean" ? data.is_free_tier : null,
+  };
+}
+
+export type Fetcher = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}>;
+
+/** Fetch the OpenRouter key status. Never throws — failure is a result. */
+export async function fetchOpenRouterQuota(
+  apiKey: string,
+  fetcher: Fetcher = globalThis.fetch as unknown as Fetcher,
+  timeoutMs = QUOTA_TIMEOUT_MS,
+): Promise<QuotaResult> {
+  if (!apiKey.trim()) return { ok: false, provider: "openrouter", reason: "no API key configured" };
+  try {
+    const response = await fetcher("https://openrouter.ai/api/v1/key", {
+      headers: { Authorization: `Bearer ${apiKey.trim()}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+      return { ok: false, provider: "openrouter", reason: `HTTP ${response.status}` };
+    }
+    const quota = parseOpenRouterKey(await response.json());
+    if (!quota) return { ok: false, provider: "openrouter", reason: "unexpected response shape" };
+    return { ok: true, quota };
+  } catch (err) {
+    return {
+      ok: false,
+      provider: "openrouter",
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+function money(value: number | null): string {
+  if (value === null) return "—";
+  if (value === 0) return "$0";
+  if (Math.abs(value) < 0.01) return "<$0.01";
+  return `$${value.toFixed(2)}`;
+}
+
+export function quotaBlock(result: QuotaResult): string {
+  if (!result.ok) {
+    return `Quota (${result.provider})\n  unavailable — ${result.reason}`;
+  }
+  const q = result.quota;
+  const lines = [`Quota (${q.provider}${q.label ? ` · ${q.label}` : ""})`];
+  lines.push(
+    q.limit === null
+      ? `  spent    ${money(q.used)} (no credit limit on this key)`
+      : `  spent    ${money(q.used)} of ${money(q.limit)} · ${money(q.remaining)} left`,
+  );
+  if (q.daily !== null || q.weekly !== null || q.monthly !== null) {
+    lines.push(`  window   day ${money(q.daily)} · week ${money(q.weekly)} · month ${money(q.monthly)}`);
+  }
+  if (q.freeTier) lines.push("  tier     free");
+  return lines.join("\n");
+}

package/src/sessions.ts

@@ -44,27 +44,70 @@ export interface ScanResult {
   files: number;
 }
 
-export function scanSessions(sessionsDir: string): ScanResult {
-  const files = listJsonlFiles(sessionsDir, 0);
-  const records: UsageRecord[] = [];
-  for (const file of files) {
+const MAX_LABEL = 34;
+
+/**
+ * Readable name for a project directory. pi encodes the project path into the
+ * directory name (--D--project-pify-plugins--); the tail is the recognizable
+ * part, so long names keep their end.
+ */
+export function projectLabel(dirName: string): string {
+  const stripped = dirName.replace(/^-+|-+$/g, "");
+  if (!stripped) return "unknown";
+  return stripped.length > MAX_LABEL ? `…${stripped.slice(-(MAX_LABEL - 1))}` : stripped;
+}
+
+/** Session files grouped by the project directory they sit under. */
+function groupByProject(sessionsDir: string): Array<{ project: string; files: string[] }> {
+  let names: string[];
+  try {
+    names = readdirSync(sessionsDir);
+  } catch {
+    return [];
+  }
+  const groups: Array<{ project: string; files: string[] }> = [];
+  const loose: string[] = [];
+  for (const name of names) {
+    const full = join(sessionsDir, name);
     try {
-      const stat = statSync(file);
-      const cached = cache.get(file);
-      if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
-        records.push(...cached.records);
-        continue;
-      }
-      const fileRecords: UsageRecord[] = [];
-      for (const line of readFileSync(file, "utf8").split("\n")) {
-        const record = recordFromLine(line);
-        if (record) fileRecords.push(record);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        groups.push({ project: projectLabel(name), files: listJsonlFiles(full, 1) });
+      } else if (name.endsWith(".jsonl") && stat.size <= MAX_FILE_BYTES) {
+        loose.push(full);
       }
-      cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, records: fileRecords });
-      records.push(...fileRecords);
     } catch {
-      // unreadable — skip
+      // race/permission — skip
+    }
+  }
+  if (loose.length > 0) groups.push({ project: "", files: loose });
+  return groups;
+}
+
+export function scanSessions(sessionsDir: string): ScanResult {
+  const records: UsageRecord[] = [];
+  let fileCount = 0;
+  for (const { project, files } of groupByProject(sessionsDir)) {
+    fileCount += files.length;
+    for (const file of files) {
+      try {
+        const stat = statSync(file);
+        const cached = cache.get(file);
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+          records.push(...cached.records);
+          continue;
+        }
+        const fileRecords: UsageRecord[] = [];
+        for (const line of readFileSync(file, "utf8").split("\n")) {
+          const record = recordFromLine(line);
+          if (record) fileRecords.push({ ...record, project });
+        }
+        cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, records: fileRecords });
+        records.push(...fileRecords);
+      } catch {
+        // unreadable — skip
+      }
     }
   }
-  return { records, files: files.length };
+  return { records, files: fileCount };
 }

package/src/types.ts

@@ -23,6 +23,8 @@ export interface UsageRecord {
   timestamp: number;
   model: string;
   provider: string;
+  /** Project the session belongs to; "" when unknown (live events). */
+  project: string;
   input: number;
   output: number;
   cacheRead: number;
@@ -34,6 +36,7 @@ export interface UsageRecord {
 export interface HistoryAggregate {
   byDay: Map<string, UsageTotals>;
   byModel: Map<string, UsageTotals>;
+  byProject: Map<string, UsageTotals>;
   total: UsageTotals;
   files: number;
 }