@pify/usage 0.9.1 → 0.10.0

package/README.md

@@ -18,6 +18,8 @@ Spend is invisible until the invoice arrives, and by then you cannot tell which
 
 Folded from each message's `usage.cost`, which pi already computes. It survives `/reload` by replaying the session branch rather than keeping a running total in memory.
 
+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.
+
 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`
@@ -40,7 +42,7 @@ By project (all time)
   D--project-shop-api       $6.60 · 3.6M tok
 ```
 
-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. Negative and NaN fields clamp to zero, days are your **local** calendar days, and a per-file mtime cache keeps repeat scans instant.
+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

@@ -31,6 +31,7 @@ import { readFileSync } from "node:fs";
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 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 { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
 import { scanSessions } from "../src/sessions.ts";
@@ -66,9 +67,17 @@ export default function usage(pi: ExtensionAPI) {
     if (snap) rateLimits.set(provider, snap);
   });
 
+  /**
+   * The ctx the footer is drawn into, for the child-spend listener: a child
+   * finishing a turn fires no pi event on the parent, so the tally calls back
+   * and the footer redraws into the latest session context.
+   */
+  let footerCtx: UiContext | null = null;
+  let stopChildSpend: (() => void) | null = null;
+
   function updateFooter(ctx: UiContext): void {
     if (!ctx.hasUI) return;
-    const base = footerText(session);
+    const base = footerText(session, childSpendTotal());
     if (!base) {
       ctx.ui.setStatus("usage", undefined);
       return;
@@ -105,7 +114,7 @@ export default function usage(pi: ExtensionAPI) {
       const scan = scanSessions(join(getAgentDir(), "sessions"));
       return [scan.records, scan.files] as const;
     })());
-    return [sessionBlock(session, contextInfo(ctx).pct), historyBlock(history, Date.now())].join("\n\n");
+    return [sessionBlock(session, contextInfo(ctx).pct, childSpendTotal()), historyBlock(history, Date.now())].join("\n\n");
   }
 
   // ── Live tracking ────────────────────────────────────────────────────
@@ -124,10 +133,23 @@ export default function usage(pi: ExtensionAPI) {
     updateFooter(ctx);
   });
 
-  pi.on("session_start", async (_event, ctx) => {
+  pi.on("session_start", async (event, ctx) => {
     // Rebuild the session totals from the branch so /reload keeps the count.
     session = emptyTotals();
     lastPromptTokens = 0;
+    // 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();
+    footerCtx = ctx;
+    stopChildSpend?.();
+    stopChildSpend = onChildSpend(() => {
+      if (!footerCtx) return;
+      try {
+        updateFooter(footerCtx);
+      } catch {
+        // a stale ctx after a switch; the next session_start rebinds it
+      }
+    });
     for (const entry of ctx.sessionManager.getBranch()) {
       const record = recordFromEntry(entry);
       if (record) addRecord(session, record);
@@ -161,6 +183,9 @@ export default function usage(pi: ExtensionAPI) {
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
+    stopChildSpend?.();
+    stopChildSpend = null;
+    footerCtx = null;
     if (ctx.hasUI) ctx.ui.setStatus("usage", undefined);
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.9.1",
+  "version": "0.10.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/aggregate.ts

@@ -76,18 +76,24 @@ export function windowTotals(byDay: Map<string, UsageTotals>, days: number, now:
  * summariser's usage one level up, on the compaction / branch_summary entry
  * itself (these entries have no `message`), so those are read from
  * `entry.usage` — otherwise the most expensive calls in a session go
- * uncounted. Returns null for entries without usage; negative/NaN fields clamp
- * to 0.
+ * uncounted. pi 0.87's standalone `usage` entries (cache warming) also carry
+ * their usage on the entry. 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 = isRecord(entry.message) ? entry.message : null;
   const entryType = typeof entry.type === "string" ? entry.type : "";
   const isSummary = entryType === "compaction" || entryType === "branch_summary";
+  // pi 0.87 adds a standalone UsageEntry ({type:"usage", kind:"cache_warm",
+  // provider, model, usage}) for spend that belongs to no message — the cache
+  // warmer writes one per refresh, and pi folds it into its own session
+  // totals. It carries its own provider/model, unlike the summaries.
+  const isUsageEntry = entryType === "usage";
   const usage =
     message && isRecord(message.usage)
       ? message.usage
-      : isSummary && isRecord(entry.usage)
+      : (isSummary || isUsageEntry) && isRecord(entry.usage)
         ? entry.usage
         : null;
   if (!usage) return null;
@@ -105,9 +111,17 @@ export function recordFromEntry(entry: unknown): UsageRecord | null {
 
   // A summary entry has no model/provider of its own; label the bucket by the
   // entry type rather than threading a running "last model" through the scan.
+  // A usage entry names its model/provider itself; fall back to its kind.
+  const own = message ?? (isUsageEntry ? entry : null);
   const model =
-    message && typeof message.model === "string" ? message.model : isSummary ? entryType : "unknown";
-  const provider = message && typeof message.provider === "string" ? message.provider : "unknown";
+    own && typeof own.model === "string"
+      ? own.model
+      : isSummary
+        ? entryType
+        : isUsageEntry && typeof entry.kind === "string"
+          ? entry.kind
+          : "unknown";
+  const provider = own && typeof own.provider === "string" ? own.provider : "unknown";
 
   return {
     timestamp: Number.isFinite(ts) ? ts : 0,

package/src/child-cost.ts

@@ -0,0 +1,78 @@
+/**
+ * What the children cost, across every @pify extension in the process.
+ *
+ * subagent, swarm and workflow run their children as separate in-memory pi
+ * sessions, so a child's spend never reaches the parent session's branch —
+ * and the usage footer, which folds the branch, under-reports every session
+ * that delegates. This is the one place they all add to and the footer reads.
+ *
+ * The state lives on `globalThis` under a cross-realm `Symbol.for` key, not
+ * in a module variable: pi's loader gives each extension its own module realm
+ * (jiti, `moduleCache: false`), so a module singleton would be a different
+ * object in every package that vendors this file. Same reasoning as
+ * ui-lock.ts. Vendored per package, byte-identical, zero dependencies; every
+ * function is safe to call whether or not any other package is installed.
+ */
+
+const KEY = Symbol.for("pify.child-cost");
+
+export interface ChildSpend {
+  /** USD, as pi priced each child message (usage.cost.total). */
+  cost: number;
+  /** usage.totalTokens summed over child messages. */
+  tokens: number;
+}
+
+interface Store {
+  bySource: Map<string, ChildSpend>;
+  listeners: Set<() => void>;
+}
+
+function store(): Store {
+  const g = globalThis as unknown as { [KEY]?: Store };
+  return (g[KEY] ??= { bySource: new Map(), listeners: new Set() });
+}
+
+/** Record one child message's spend under its package ("subagent", "swarm", "workflow"). Non-finite or negative parts are ignored. */
+export function addChildSpend(source: string, spend: { cost?: number; tokens?: number }): void {
+  const cost = typeof spend.cost === "number" && Number.isFinite(spend.cost) && spend.cost > 0 ? spend.cost : 0;
+  const tokens =
+    typeof spend.tokens === "number" && Number.isFinite(spend.tokens) && spend.tokens > 0 ? Math.round(spend.tokens) : 0;
+  if (cost === 0 && tokens === 0) return;
+  const s = store();
+  const prev = s.bySource.get(source) ?? { cost: 0, tokens: 0 };
+  s.bySource.set(source, { cost: prev.cost + cost, tokens: prev.tokens + tokens });
+  for (const listener of s.listeners) {
+    try {
+      listener();
+    } catch {
+      // A footer that cannot redraw is not the child's problem.
+    }
+  }
+}
+
+/** Everything the children have spent this session, and which packages spent it. */
+export function childSpendTotal(): ChildSpend & { sources: string[] } {
+  const s = store();
+  let cost = 0;
+  let tokens = 0;
+  for (const spend of s.bySource.values()) {
+    cost += spend.cost;
+    tokens += spend.tokens;
+  }
+  return { cost, tokens, sources: [...s.bySource.keys()].sort() };
+}
+
+/** Start a new tally — a new session's children, not the last one's. */
+export function resetChildSpend(): void {
+  store().bySource.clear();
+}
+
+/** Be told after every addition; returns the unsubscribe. */
+export function onChildSpend(listener: () => void): () => void {
+  const s = store();
+  s.listeners.add(listener);
+  return () => {
+    s.listeners.delete(listener);
+  };
+}

package/src/format.ts

@@ -14,9 +14,20 @@ export function formatCost(n: number): string {
 }
 
 /** 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)}`;
+/** Spend of child agent sessions (subagent/swarm/workflow), which is not in the session totals. */
+export interface ChildSpendLike {
+  cost: number;
+  tokens: number;
+}
+
+function hasChildSpend(children: ChildSpendLike | undefined): children is ChildSpendLike {
+  return !!children && (children.cost > 0 || children.tokens > 0);
+}
+
+export function footerText(session: UsageTotals, children?: ChildSpendLike): string | undefined {
+  const agents = hasChildSpend(children) ? ` · agents ${formatCost(children.cost)}` : "";
+  if (session.messages === 0) return agents ? `📊 0 tok · $0${agents}` : undefined;
+  return `📊 ${formatTokens(session.totalTokens)} tok · ${formatCost(session.cost)}${agents}`;
 }
 
 const GAUGE_CELLS = 6;
@@ -38,12 +49,17 @@ export function contextGauge(pct: number | null): string {
   return `${clamped >= 90 ? "⚠ " : ""}ctx ${bar} ${Math.round(clamped)}%`;
 }
 
-export function sessionBlock(session: UsageTotals, contextPct: number | null): string {
+export function sessionBlock(session: UsageTotals, contextPct: number | null, children?: ChildSpendLike): 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 (hasChildSpend(children)) {
+    // Child sessions of subagent/swarm/workflow run outside this branch; their
+    // spend is real and is NOT in the two lines above.
+    lines.push(`  agents   ${formatCost(children.cost)} · ${formatTokens(children.tokens)} tok in child sessions, on top of the above`);
+  }
   if (contextPct !== null) {
     lines.push(`  context  ~${Math.round(contextPct)}% of the window`);
   }