@pify/usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @pify/usage
+
+Token and cost reporting for [pi](https://github.com/earendil-works/pi) sessions — a live footer, a `/usage` dashboard, and an agent-callable status tool. Entirely local: no network calls, no LLM tokens spent asking about tokens.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install usage`](https://github.com/pifydev/cli) or `pi install npm:@pify/usage`.
+
+## What it does
+
+- **Live footer**: `📊 12.3k tok · $0.45` — folded from each message's `usage.cost` that pi already computes; survives `/reload` by replaying the session branch.
+- **`/usage` dashboard**:
+
+```
+Session
+  tokens   in 120.3k · out 8.2k · cache 1.1M read / 0 write
+  cost     $0.45 (23 responses)
+  context  ~34% of the window
+
+History (214 local session files)
+  today    $1.23 · 450.2k tok
+  7 days   $8.90 · 3.2M tok
+  30 days  $21.40 · 9.8M tok
+By model (all time)
+  anthropic/claude-fable-5  $12.30 · 4.1M tok
+  openai/gpt-5.5            $9.10 · 5.7M 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.
+- **`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).
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/usage.ts

@@ -0,0 +1,118 @@
+/**
+ * @pify/usage — token and cost reporting for pi sessions.
+ *
+ * Live session tracking in the footer (📊 12.3k tok · $0.45, folded from
+ * each message's usage.cost that pi already computes) and a /usage dashboard
+ * combining the current session with local history aggregated from pi's
+ * session JSONL files — zero network calls, zero LLM tokens spent
+ * (aporcelli's principle). History counts every usage-bearing entry
+ * (assistant turns plus pi 0.81+'s persisted tool-result/compaction usage,
+ * 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.
+ */
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { join } from "node:path";
+
+import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
+import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
+import { scanSessions } from "../src/sessions.ts";
+import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
+
+type UiContext = ExtensionContext;
+
+export default function usage(pi: ExtensionAPI) {
+  let session: UsageTotals = emptyTotals();
+  /** input+cacheRead of the most recent assistant message ≈ context size. */
+  let lastPromptTokens = 0;
+
+  function updateFooter(ctx: UiContext): void {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("usage", footerText(session));
+  }
+
+  function contextPct(ctx: UiContext): number | null {
+    const window = (ctx.model as { contextWindow?: number } | null)?.contextWindow;
+    if (!window || lastPromptTokens === 0) return null;
+    return Math.min(100, (lastPromptTokens / window) * 100);
+  }
+
+  function dashboard(ctx: UiContext): string {
+    const history = aggregate(...(() => {
+      const scan = scanSessions(join(getAgentDir(), "sessions"));
+      return [scan.records, scan.files] as const;
+    })());
+    return [sessionBlock(session, contextPct(ctx)), historyBlock(history, Date.now())].join("\n\n");
+  }
+
+  // ── Live tracking ────────────────────────────────────────────────────
+
+  pi.on("message_end", async (event, ctx) => {
+    const record = recordFromEntry({ message: (event as { message?: unknown }).message });
+    if (!record) return;
+    addRecord(session, record);
+    const message = (event as { message?: { role?: string; usage?: unknown } }).message;
+    if (message?.role === "assistant" && isRecord(message.usage)) {
+      const input = message.usage.input;
+      const cacheRead = message.usage.cacheRead;
+      lastPromptTokens =
+        (typeof input === "number" ? input : 0) + (typeof cacheRead === "number" ? cacheRead : 0);
+    }
+    updateFooter(ctx);
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    // Rebuild the session totals from the branch so /reload keeps the count.
+    session = emptyTotals();
+    lastPromptTokens = 0;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const record = recordFromEntry(entry);
+      if (record) addRecord(session, record);
+    }
+    updateFooter(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setStatus("usage", undefined);
+  });
+
+  // ── Command & tool ───────────────────────────────────────────────────
+
+  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");
+    },
+  });
+
+  pi.registerTool({
+    name: "usage_status",
+    label: "Usage status",
+    description:
+      "Current session token/cost totals plus today's local aggregate. Use when deciding whether " +
+      "an expensive approach (large reads, many subagents) is proportionate.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const scan = scanSessions(join(getAgentDir(), "sessions"));
+      const history = aggregate(scan.records, scan.files);
+      const today = windowTotals(history.byDay, 1, Date.now());
+      const text = [
+        `Session: ${formatTokens(session.totalTokens)} tokens, ${formatCost(session.cost)} across ${session.messages} responses.`,
+        `Today (all sessions): ${formatTokens(today.totalTokens)} tokens, ${formatCost(today.cost)}.`,
+      ].join("\n");
+      void ctx;
+      return {
+        content: [{ type: "text", text }],
+        details: { session, today },
+      };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pify/usage",
+  "version": "0.1.0",
+  "description": "Token and cost reporting for pi sessions: live footer, /usage dashboard over local session history, zero network",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "usage",
+    "tokens",
+    "cost"
+  ],
+  "homepage": "https://github.com/pifydev/usage#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/usage/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/usage.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/usage.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/usage/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: usage
+description: Use when cost or token consumption matters to a decision - before expensive operations (large reads, many subagents, long loops) or when the user asks about spend - explains usage_status and /usage
+---
+
+# Usage awareness
+
+This project has the `@pify/usage` extension installed: a live footer
+(tokens + cost for this session) and local history aggregation.
+
+## When to check (usage_status)
+
+- Before an expensive plan: fanning out subagents, reading many large
+  files, or long automatic loops — confirm the spend is proportionate.
+- When the user asks "how much has this cost?" — answer from usage_status,
+  never estimate from memory.
+
+## Notes
+
+- All numbers are computed locally from pi's session files and the current
+  session's message usage — no network, no tokens spent asking.
+- `/usage` (user command) shows the full dashboard: session breakdown,
+  today/7d/30d history, and per-model totals.
+- Costs come from pi's own per-message usage.cost; if a model has no price
+  configured, its cost reads as $0 while tokens still count.

package/src/aggregate.ts

@@ -0,0 +1,112 @@
+import {
+  emptyTotals,
+  finite,
+  isRecord,
+  type HistoryAggregate,
+  type UsageRecord,
+  type UsageTotals,
+} from "./types.ts";
+
+/** Fold one record into a totals accumulator (mutates and returns it). */
+export function addRecord(totals: UsageTotals, record: UsageRecord): UsageTotals {
+  totals.input += record.input;
+  totals.output += record.output;
+  totals.cacheRead += record.cacheRead;
+  totals.cacheWrite += record.cacheWrite;
+  totals.totalTokens += record.totalTokens;
+  totals.cost += record.cost;
+  totals.messages += 1;
+  return totals;
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Local calendar day key (matches the suite's local-day discipline). */
+export function dayKey(timestamp: number): string {
+  const d = new Date(timestamp);
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+export function aggregate(records: UsageRecord[], files: number): HistoryAggregate {
+  const byDay = new Map<string, UsageTotals>();
+  const byModel = new Map<string, UsageTotals>();
+  const total = emptyTotals();
+
+  for (const record of records) {
+    addRecord(total, record);
+    const day = dayKey(record.timestamp);
+    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);
+  }
+
+  return { byDay, byModel, total, files };
+}
+
+/** Sum totals for days within the trailing window (inclusive of today). */
+export function windowTotals(byDay: Map<string, UsageTotals>, days: number, now: number): UsageTotals {
+  const totals = emptyTotals();
+  const cutoff = new Set<string>();
+  for (let i = 0; i < days; i++) {
+    cutoff.add(dayKey(now - i * 86_400_000));
+  }
+  for (const [day, t] of byDay) {
+    if (!cutoff.has(day)) continue;
+    totals.input += t.input;
+    totals.output += t.output;
+    totals.cacheRead += t.cacheRead;
+    totals.cacheWrite += t.cacheWrite;
+    totals.totalTokens += t.totalTokens;
+    totals.cost += t.cost;
+    totals.messages += t.messages;
+  }
+  return totals;
+}
+
+/**
+ * Extract a usage record from one parsed session-JSONL entry. Counts any
+ * entry whose message carries a usage block (assistant turns dominate; pi
+ * 0.81+ also persists tool-result/compaction usage the same way). Returns
+ * null for entries without usage. Negative/NaN fields clamp to 0.
+ */
+export function recordFromEntry(entry: unknown): UsageRecord | null {
+  if (!isRecord(entry)) return null;
+  const message = entry.message;
+  if (!isRecord(message) || !isRecord(message.usage)) return null;
+  const usage = message.usage;
+  const total = finite(usage.totalTokens);
+  const cost = isRecord(usage.cost) ? finite(usage.cost.total) : 0;
+  if (total === 0 && cost === 0) return null;
+
+  const ts =
+    typeof entry.timestamp === "string"
+      ? Date.parse(entry.timestamp)
+      : typeof message.timestamp === "number"
+        ? message.timestamp
+        : Number.NaN;
+
+  return {
+    timestamp: Number.isFinite(ts) ? ts : 0,
+    model: typeof message.model === "string" ? message.model : "unknown",
+    provider: typeof message.provider === "string" ? message.provider : "unknown",
+    input: finite(usage.input),
+    output: finite(usage.output),
+    cacheRead: finite(usage.cacheRead),
+    cacheWrite: finite(usage.cacheWrite),
+    totalTokens: total,
+    cost,
+  };
+}
+
+/** Parse one JSONL line into a usage record, or null. */
+export function recordFromLine(line: string): UsageRecord | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    return recordFromEntry(JSON.parse(trimmed));
+  } catch {
+    return null;
+  }
+}

package/src/format.ts

@@ -0,0 +1,58 @@
+import type { HistoryAggregate, UsageTotals } from "./types.ts";
+import { windowTotals } from "./aggregate.ts";
+
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+
+export function formatCost(n: number): string {
+  if (n === 0) return "$0";
+  if (n < 0.01) return `<$0.01`;
+  return `$${n.toFixed(2)}`;
+}
+
+/** Footer text: short, live. Null clears the indicator. */
+export function footerText(session: UsageTotals): string | undefined {
+  if (session.messages === 0) return undefined;
+  return `📊 ${formatTokens(session.totalTokens)} tok · ${formatCost(session.cost)}`;
+}
+
+export function sessionBlock(session: UsageTotals, contextPct: number | null): string {
+  const lines = [
+    "Session",
+    `  tokens   in ${formatTokens(session.input)} · out ${formatTokens(session.output)} · cache ${formatTokens(session.cacheRead)} read / ${formatTokens(session.cacheWrite)} write`,
+    `  cost     ${formatCost(session.cost)} (${session.messages} responses)`,
+  ];
+  if (contextPct !== null) {
+    lines.push(`  context  ~${Math.round(contextPct)}% of the window`);
+  }
+  return lines.join("\n");
+}
+
+export function historyBlock(history: HistoryAggregate, now: number): string {
+  const today = windowTotals(history.byDay, 1, now);
+  const week = windowTotals(history.byDay, 7, now);
+  const month = windowTotals(history.byDay, 30, now);
+
+  const lines = [
+    `History (${history.files} local session files)`,
+    `  today    ${formatCost(today.cost)} · ${formatTokens(today.totalTokens)} tok`,
+    `  7 days   ${formatCost(week.cost)} · ${formatTokens(week.totalTokens)} tok`,
+    `  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`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/sessions.ts

@@ -0,0 +1,70 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { recordFromLine } from "./aggregate.ts";
+import type { UsageRecord } from "./types.ts";
+
+/**
+ * Scan pi's session store for usage records. Zero network, zero LLM tokens
+ * (aporcelli's principle): everything is computed from local JSONL files.
+ * Per-file mtime+size cache keeps repeat scans cheap.
+ */
+
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+
+const cache = new Map<string, { mtimeMs: number; size: number; records: UsageRecord[] }>();
+
+export function clearScanCache(): void {
+  cache.clear();
+}
+
+function listJsonlFiles(dir: string, depth: number): string[] {
+  if (depth > 4) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const files: string[] = [];
+  for (const name of names) {
+    const full = join(dir, name);
+    try {
+      const stat = statSync(full);
+      if (stat.isDirectory()) files.push(...listJsonlFiles(full, depth + 1));
+      else if (name.endsWith(".jsonl") && stat.size <= MAX_FILE_BYTES) files.push(full);
+    } catch {
+      // race/permission — skip
+    }
+  }
+  return files;
+}
+
+export interface ScanResult {
+  records: UsageRecord[];
+  files: number;
+}
+
+export function scanSessions(sessionsDir: string): ScanResult {
+  const files = listJsonlFiles(sessionsDir, 0);
+  const records: UsageRecord[] = [];
+  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);
+      }
+      cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, records: fileRecords });
+      records.push(...fileRecords);
+    } catch {
+      // unreadable — skip
+    }
+  }
+  return { records, files: files.length };
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Local structural types for @pify/usage.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export interface UsageTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: number;
+  messages: number;
+}
+
+export function emptyTotals(): UsageTotals {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: 0, messages: 0 };
+}
+
+/** One usage-bearing record extracted from a session file or live event. */
+export interface UsageRecord {
+  /** Epoch ms. */
+  timestamp: number;
+  model: string;
+  provider: string;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: number;
+}
+
+export interface HistoryAggregate {
+  byDay: Map<string, UsageTotals>;
+  byModel: Map<string, UsageTotals>;
+  total: UsageTotals;
+  files: number;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function finite(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}