@pify/usage 0.9.2 → 0.11.0

package/README.md

@@ -18,6 +18,10 @@ 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.
+
+On a Claude subscription (OAuth Pro/Max) the footer also carries the wall you are approaching: the headers `/usage quota` reads were already captured on every response, but only that command showed them, so the weekly or 5-hour limit used to arrive as a stalled turn. Now a `⚠ 7d 8% · resets 14:05` segment appears once the binding window is below 15%, or whenever Anthropic marks the subscription as anything but allowed, and stays out of the way otherwise. Other providers carry no such headers, so they never show it.
+
 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`

package/extensions/usage.ts

@@ -31,10 +31,11 @@ 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";
-import { parseRateLimit, formatRateLimit, type RateLimitSnapshot } from "../src/ratelimit.ts";
+import { parseRateLimit, formatRateLimit, type RateLimitSnapshot, footerQuotaSegment } from "../src/ratelimit.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
 type UiContext = ExtensionContext;
@@ -66,15 +67,26 @@ 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;
     }
     const gauge = contextGauge(contextInfo(ctx).pct);
-    ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
+    // The subscription wall, from the headers already captured for this
+    // provider: quiet while healthy, a short warning once it is close.
+    const quota = footerQuotaSegment(rateLimits.get((ctx.model as { provider?: string } | null)?.provider ?? ""));
+    ctx.ui.setStatus("usage", [base, gauge, quota].filter(Boolean).join(" · "));
   }
 
   /**
@@ -105,7 +117,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 +136,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 +186,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.2",
+  "version": "0.11.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/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`);
   }

package/src/ratelimit.ts

@@ -166,6 +166,46 @@ function formatReset(snap: RateLimitSnapshot): string {
   return raw;
 }
 
+/** A reset time short enough for the footer: HH:MM today, otherwise MM-DD HH:MM; "" when unknown or unwieldy. */
+export function shortReset(snap: RateLimitSnapshot, now: number = Date.now()): string {
+  const raw = snap.resets;
+  if (!raw) return "";
+  if (snap.source === "anthropic" && /^\d{9,}$/.test(raw)) {
+    const d = new Date(Number.parseInt(raw, 10) * 1000);
+    if (!Number.isFinite(d.getTime())) return "";
+    const hm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    const sameDay = new Date(now).toDateString() === d.toDateString();
+    return sameDay ? hm : `${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${hm}`;
+  }
+  return raw.length <= 12 ? raw : "";
+}
+
+/** Below this share of the binding window left, the footer starts warning. */
+export const FOOTER_WARN_FRACTION = 0.15;
+
+/**
+ * The footer's quota warning, or "" while the session is healthy. A Claude
+ * subscription user used to learn about the 5h/7d wall only when a turn
+ * stalled, or by opening `/usage quota` — the headers were captured either
+ * way. This shows the binding window once it is nearly gone, or whenever
+ * Anthropic marks the subscription as anything but "allowed". Non-Anthropic
+ * providers carry none of these fields, so it stays empty for them.
+ */
+export function footerQuotaSegment(snap: RateLimitSnapshot | null | undefined, now: number = Date.now()): string {
+  if (!snap) return "";
+  const binding =
+    snap.unifiedBinding ?? (snap.unified7dRemaining !== null ? "7d" : snap.unified5hRemaining !== null ? "5h" : null);
+  const remaining = binding === "7d" ? snap.unified7dRemaining : binding === "5h" ? snap.unified5hRemaining : null;
+  const walled = Boolean(snap.unifiedStatus && snap.unifiedStatus !== "allowed");
+  const low = remaining !== null && remaining < FOOTER_WARN_FRACTION;
+  if (!walled && !low) return "";
+  const parts = [`⚠ ${binding ?? "subscription"}`];
+  if (remaining !== null) parts.push(`${Math.max(0, Math.round(remaining * 100))}%`);
+  if (walled) parts.push(snap.unifiedStatus!.replace(/_/g, " "));
+  const reset = shortReset(snap, now);
+  return reset ? `${parts.join(" ")} · resets ${reset}` : parts.join(" ");
+}
+
 /** One human line for the /usage quota report; null when nothing was captured. */
 export function formatRateLimit(snap: RateLimitSnapshot | null): string | null {
   if (!snap) return null;