@pify/usage 0.6.0 → 0.7.0

package/README.md

@@ -11,11 +11,13 @@ Spend is invisible until the invoice arrives, and by then you cannot tell which
 ## Live footer
 
 ```
-📊 12.3k tok · $0.45
+📊 12.3k tok · $0.45 · ctx ▰▰▰▱▱▱ 34%
 ```
 
 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.
 
+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 @@ History counts every usage-bearing entry in pi's session JSONL — assistant tur
 
 Per-project totals come for free: pi stores sessions one directory per project, so the dashboard can show where the money actually went.
 
-## `/usage context`
+## `/context` (or `/usage context`)
 
 ```
 Context window: 22.6k of 200.0k used (11%)

package/extensions/usage.ts

@@ -29,7 +29,7 @@ import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 import { buildBreakdown, formatBreakdown } from "../src/context.ts";
-import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
+import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
 import { scanSessions } from "../src/sessions.ts";
@@ -62,7 +62,13 @@ export default function usage(pi: ExtensionAPI) {
 
   function updateFooter(ctx: UiContext): void {
     if (!ctx.hasUI) return;
-    ctx.ui.setStatus("usage", footerText(session));
+    const base = footerText(session);
+    if (!base) {
+      ctx.ui.setStatus("usage", undefined);
+      return;
+    }
+    const gauge = contextGauge(contextPct(ctx));
+    ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
   }
 
   function contextPct(ctx: UiContext): number | null {
@@ -187,9 +193,15 @@ export default function usage(pi: ExtensionAPI) {
   }
 
   pi.registerCommand("usage", {
-    description: "Token and cost dashboard: /usage [quota]",
+    description: "Token and cost dashboard: /usage [context | quota]",
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
+      if ((args ?? "").trim().toLowerCase() === "context") {
+        // Documented since the breakdown landed, but never wired — the handler
+        // only knew "quota", so `/usage context` quietly showed the dashboard.
+        ctx.ui.notify(contextBreakdown(ctx), "info");
+        return;
+      }
       if ((args ?? "").trim().toLowerCase() === "quota") {
         // The one networked path in this package, and only when asked for.
         // Providers with no key are skipped entirely rather than reported as
@@ -225,6 +237,16 @@ export default function usage(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("context", {
+    description: "Where the context window went: /context",
+    handler: async (_args, ctx) => {
+      // The live footer gauge says how full the window is; this says spent on
+      // WHAT — the breakdown was built for the /usage dashboard's one-line note
+      // but the full bar view had no command to reach it until now.
+      if (ctx.hasUI) ctx.ui.notify(contextBreakdown(ctx), "info");
+    },
+  });
+
   pi.registerTool({
     name: "usage_status",
     label: "Usage status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.6.0",
+  "version": "0.7.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/format.ts

@@ -19,6 +19,25 @@ export function footerText(session: UsageTotals): string | undefined {
   return `📊 ${formatTokens(session.totalTokens)} tok · ${formatCost(session.cost)}`;
 }
 
+const GAUGE_CELLS = 6;
+
+/**
+ * A compact live context gauge for the footer: a filled/empty bar and the
+ * percentage of the window in use. The footer already carries tokens and cost;
+ * this answers the third question you have mid-session — how close am I to the
+ * wall — which was computed for the /usage dashboard but never shown live. It
+ * warns once the window is nearly full, because that is when the number stops
+ * being trivia and starts being a decision. Empty when there is no window to
+ * measure against (e.g. under `-p`, or before the first response).
+ */
+export function contextGauge(pct: number | null): string {
+  if (pct === null || !Number.isFinite(pct)) return "";
+  const clamped = Math.max(0, Math.min(100, pct));
+  const filled = Math.round((clamped / 100) * GAUGE_CELLS);
+  const bar = "▰".repeat(filled) + "▱".repeat(GAUGE_CELLS - filled);
+  return `${clamped >= 90 ? "⚠ " : ""}ctx ${bar} ${Math.round(clamped)}%`;
+}
+
 export function sessionBlock(session: UsageTotals, contextPct: number | null): string {
   const lines = [
     "Session",