pi-editor-footer 0.12.2 → 0.12.3

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# Changelog
+
+## [0.12.3](https://github.com/Rianico/pi-editor-footer/compare/v0.12.2...v0.12.3) (2026-09-17)
+
+### Bug Fixes
+
+* **footer:** count total input tokens in footer statistics ([a2153a1](https://github.com/Rianico/pi-editor-footer/commit/a2153a1f0f4884e3879a610744a9e664a9124053))
+
+### Documentation
+
+* **agents:** mark agent-run token accounting a scope boundary ([ffbbee2](https://github.com/Rianico/pi-editor-footer/commit/ffbbee29300a40d6963e0916c7526e0a1ce49881))
+* document total input token semantics for the footer ([9480bf9](https://github.com/Rianico/pi-editor-footer/commit/9480bf9f1508930d75a5e53b94d944d00d1f6a2a))
+
+<!-- markdownlint-configure-file { "MD004": { "style": "asterisk" } } -->
+<!-- Bullets stay `*`: semantic-release's preset writes `*`, and this file is excluded from the
+     formatters so they cannot normalize them to `-`. Keep `# Changelog` as the FIRST line:
+     @semantic-release/changelog rewrites the title in place only while the file starts with
+     the configured `changelogTitle`, and prepends release notes above it otherwise. Do not
+     move this title below the comments, and do not remove the title. -->
+
+All notable changes to this project will be documented in this file.
+
 ## [0.12.2](https://github.com/Rianico/pi-editor-footer/compare/v0.12.1...v0.12.2) (2026-09-13)
 
 ### Bug Fixes
@@ -24,10 +46,6 @@
 * allow pnpm builds for esbuild and genai ([36e139e](https://github.com/Rianico/pi-editor-footer/commit/36e139e9443ef928a4366c3d7c8afe494b6e0850))
 * make prepare tolerant to missing husky for pi install ([23ebb62](https://github.com/Rianico/pi-editor-footer/commit/23ebb62cd8d732656fd113da27c807ffa34579fc))
 
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
 ## [0.11.0] - 2026-08-29
 
 ### Changed

package/README.md

@@ -12,8 +12,8 @@ A [pi](https://pi.dev) extension that turns the editor chrome into a project-awa
 
 **Footer** — single line below the input, responsive via `fitSegmentsByPriority` and `alignRight`:
 - Left: `cwd` (`·` `git branch` + status `[! ? + ↑↓]` + stashed/conflicted) `•` `runtime` (`node`/`python`/`rust`/`go`… + version) `•` `timer` (`working`/`done`)
-- Right: `tokens` (` input |  output |  $cost`) immediately next to `context` (` [bar] % · tokens/contextWindow`)
-- Separators: `·` between `cwd` and `git`, `•` as default between other left components; `tokens` sits directly left of the context bar
+- Right: `tokens` (`↑ <total input> · ↓ <output> · $<cost>`) — `↑` counts every billed input token (uncached input + cache read + cache write), so it tracks the context bar's token figure instead of `usage.input` alone
+- Separators: `·` between `cwd` and `git`, `•` as default between other left components; the `context` bar (`<pct> · <tokens>/<window> | c <hit%>`) sits on the top border next to the model label, not in the footer
 - `cwd` respects `workspaceDisplay` (`~/development/ai/pi-skill-desc` vs `pi-skill-desc`, switchable in settings)
 - `context` bar uses `stressColor` and `renderBar` (12 cols max) with `•`/`·` handling
 - Extension statuses line (`wrapTextWithAnsi`) when `footerSegments.extensionStatuses`

package/dist/ansi-color.js

@@ -16,11 +16,11 @@ const BASIC16 = [
     [0, 255, 255],
     [255, 255, 255],
 ];
-/** 6x6x6 colour-cube channel values (indices 0-5). */
+/** 6x6x6 color-cube channel values (indices 0-5). */
 const CUBE_VALUES = [0, 95, 135, 175, 215, 255];
 /** Grayscale ramp values (indices 232-255: 24 grays from 8 to 238). */
 const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10);
-/** Anything but the truecolor marker means the 256-colour ramp. */
+/** Anything but the truecolor marker means the 256-color ramp. */
 export function normalizeColorMode(mode) {
     return mode === "truecolor" ? "truecolor" : "256color";
 }
@@ -74,7 +74,7 @@ function colorDistance(r1, g1, b1, r2, g2, b2) {
     // Weighted Euclidean distance (the eye is more sensitive to green).
     return dr * dr * 0.299 + dg * dg * 0.587 + db * db * 0.114;
 }
-/** Quantise RGB to the closest xterm-256 index (same rule as the theme loader). */
+/** Quantize RGB to the closest xterm-256 index (same rule as the theme loader). */
 export function rgbTo256(r, g, b) {
     const rIdx = findClosestCubeIndex(r);
     const gIdx = findClosestCubeIndex(g);
@@ -90,7 +90,7 @@ export function rgbTo256(r, g, b) {
     const grayIndex = 232 + grayIdx;
     const grayDist = colorDistance(r, g, b, grayValue, grayValue, grayValue);
     const spread = Math.max(r, g, b) - Math.min(r, g, b);
-    // Only consider grayscale when the colour is nearly neutral AND closer.
+    // Only consider grayscale when the color is nearly neutral AND closer.
     if (spread < 10 && grayDist < cubeDist)
         return grayIndex;
     return cubeIndex;
@@ -126,14 +126,14 @@ export function parseFgAnsiToRgb(theme, color) {
         return indexToRgb(Number(palette[1]));
     return null;
 }
-/** SGR foreground sequence for an RGB value at the terminal's colour fidelity. */
+/** SGR foreground sequence for an RGB value at the terminal's color fidelity. */
 export function rgbToFgAnsi({ r, g, b }, mode) {
     return normalizeColorMode(mode) === "truecolor"
         ? `\x1b[38;2;${r};${g};${b}m`
         : `\x1b[38;5;${rgbTo256(r, g, b)}m`;
 }
 /**
- * Colour `s` with an exact hex, bypassing the theme's named-token lookup.
+ * Color `s` with an exact hex, bypassing the theme's named-token lookup.
  * Returned painter resets only the foreground (`\x1b[39m`), matching `theme.fg`.
  */
 export function hexFg(hex, mode) {

package/dist/chrome-composition.js

@@ -8,7 +8,7 @@
  * thus required touching 3-4 modules with no locality.
  *
  * Depth: one small interface (glyphs + isAscii + fg/dim/glow + format* helpers) hides
- * icon-mode resolution, the SAFETY theme cast, colour application, and the chrome format
+ * icon-mode resolution, the SAFETY theme cast, color application, and the chrome format
  * entry points (context bar, telemetry, tokens, run activity, stall). Callers learn one
  * shape; LiveBorder's islands become thin lookups.
  *
@@ -26,7 +26,7 @@ import { hexFg } from "./ansi-color.js";
  * Read the live pi theme into a typed { fg, fgHex } surface. The cast is a SAFETY
  * seam — a pi theme missing `fg` degrades to identity rather than throwing, keeping
  * the chrome resilient. `fgHex` needs no theme call at all: the named-token lookup
- * rejects raw hex, so hex is rendered straight to SGR at the theme's colour mode.
+ * rejects raw hex, so hex is rendered straight to SGR at the theme's color mode.
  */
 export function adaptTheme(rawTheme) {
     const t = rawTheme;
@@ -62,7 +62,7 @@ export class ChromeComposition {
         this.theme = adaptTheme(rawTheme);
         this.glow = opts.glow ?? resolveGlow(rawTheme);
     }
-    /** Colour a string with a theme style (derived once, cast cached). */
+    /** Color a string with a theme style (derived once, cast cached). */
     fg(style, s) {
         return this.theme.fg(style, s);
     }

package/dist/chrome-state.js

@@ -23,7 +23,7 @@ import { fmtTokens } from "./format.js";
 // ---------------------------------------------------------------------------
 /**
  * Painter for one context tier: exact hex when the live theme can emit raw hex,
- * else the nearest semantic token (tests/mocks, themes without colour mode).
+ * else the nearest semantic token (tests/mocks, themes without color mode).
  */
 function contextPainter(theme, tier) {
     const hex = CONTEXT_TIER_HEX[tier];

package/dist/footer.js

@@ -1,5 +1,5 @@
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { getUsageTotals } from "./state.js";
+import { getUsageTotals, totalInputTokens } from "./state.js";
 import { runtimeSymbol } from "./icons.js";
 import { ChromeComposition } from "./chrome-composition.js";
 import { alignRight, fitSegmentsByPriority, } from "./layout.js";
@@ -141,7 +141,9 @@ export function renderFooter(width, state, config, theme, ctx) {
     }
     const stats = [];
     if (segments.tokens) {
-        stats.push(theme.fg("accent", `${glyphs.input} ${fmtTokens(totals.input)}`));
+        // Total input billed for the model — includes the cached prompt prefix, not just
+        // `usage.input` (which excludes cacheRead/cacheWrite). See totalInputTokens.
+        stats.push(theme.fg("accent", `${glyphs.input} ${fmtTokens(totalInputTokens(totals))}`));
         stats.push(theme.fg("success", `${glyphs.output} ${fmtTokens(totals.output)}`));
     }
     if (segments.cost) {

package/dist/model-info.js

@@ -6,7 +6,7 @@
  * TrackingEditor — which owns the editor slot for this extension — can keep
  * rendering the model label and thinking-level border glow that the original
  * widget provided. Self-contained apart from pi-tui width utils, the shared
- * ANSI quantiser (ansi-color.ts) and stripAnsi (format.ts).
+ * ANSI quantizer (ansi-color.ts) and stripAnsi (format.ts).
  *
  * The port is intentional: pi allows exactly ONE custom editor (last
  * `setEditorComponent` writer wins). pi-skill-desc must own the slot to track
@@ -41,7 +41,7 @@ const LABEL_PAD = 1;
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
 // Color helpers: theme token ANSI → RGB → boosted glow ANSI
-// (RGB/256 quantisation lives in ansi-color.ts, shared with the chrome tiers)
+// (RGB/256 quantization lives in ansi-color.ts, shared with the chrome tiers)
 // ---------------------------------------------------------------------------
 /**
  * Build a border color function for a thinking level: takes the theme's

package/dist/state.js

@@ -1,6 +1,15 @@
 import { emptyGitStatus } from "./git.js";
 import { fmtTokens } from "./format.js";
 import { formatProviderLabel } from "./format.js";
+/**
+ * Total input tokens billed to the model: uncached input + cache read + cache write.
+ *
+ * pi-ai `Usage.input` excludes the cached prompt prefix (it lives in cacheRead/cacheWrite),
+ * so `input` alone under-reports the prompt by the whole cached history on every turn.
+ */
+export function totalInputTokens(totals) {
+    return totals.input + totals.cacheRead + totals.cacheWrite;
+}
 let usageCache;
 function entriesKey(ctx) {
     const entries = ctx.sessionManager?.getEntries() ?? [];
@@ -8,9 +17,7 @@ function entriesKey(ctx) {
     return `${entries.length}:${String(last?.id ?? "")}:${String(last?.timestamp ?? "")}`;
 }
 export function getUsageTotals(ctx) {
-    const key = entriesKey(
-    // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-    ctx);
+    const key = entriesKey(ctx);
     if (usageCache && usageCache.key === key)
         return usageCache.totals;
     const totals = {
@@ -21,23 +28,36 @@ export function getUsageTotals(ctx) {
         cost: 0,
         latestCacheHitRate: undefined,
     };
-    const entries = 
-    // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-    ctx.sessionManager?.getEntries() ?? [];
-    for (const entry of entries) {
+    const addUsage = (usage) => {
+        totals.input += usage.input ?? 0;
+        totals.output += usage.output ?? 0;
+        totals.cacheRead += usage.cacheRead ?? 0;
+        totals.cacheWrite += usage.cacheWrite ?? 0;
+        totals.cost += usage.cost?.total ?? 0;
+    };
+    for (const entry of ctx.sessionManager?.getEntries() ?? []) {
+        // Assistant turns carry the cache split the hit rate is derived from; tool results
+        // and summaries are usage from nested model calls — billed, so they count toward the
+        // session totals (parity with pi core's addUsageToTotals loop).
         if (entry.type === "message" && entry.message?.role === "assistant") {
-            const u = entry.message.usage;
-            if (!u)
+            const usage = entry.message.usage;
+            if (!usage)
                 continue;
-            totals.input += u.input ?? 0;
-            totals.output += u.output ?? 0;
-            totals.cacheRead += u.cacheRead ?? 0;
-            totals.cacheWrite += u.cacheWrite ?? 0;
-            totals.cost += u.cost?.total ?? 0;
-            const promptTokens = (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+            addUsage(usage);
+            const promptTokens = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
             if (promptTokens > 0) {
-                totals.latestCacheHitRate = ((u.cacheRead ?? 0) / promptTokens) * 100;
+                totals.latestCacheHitRate = ((usage.cacheRead ?? 0) / promptTokens) * 100;
             }
+            continue;
+        }
+        if (entry.type === "message" && entry.message?.role === "toolResult") {
+            if (entry.message.usage)
+                addUsage(entry.message.usage);
+            continue;
+        }
+        if (entry.type === "branch_summary" || entry.type === "compaction") {
+            if (entry.usage)
+                addUsage(entry.usage);
         }
     }
     usageCache = { key, totals };

package/package.json

@@ -33,7 +33,7 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "version": "0.12.2",
+  "version": "0.12.3",
   "files": [
     "dist",
     "src",

package/src/footer.ts

@@ -2,8 +2,8 @@ import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works
 import type { ThemeConfig } from "./config.js";
 import type { GitStatus } from "./git.js";
 import type { RuntimeInfo } from "./runtime.js";
-import type { FooterState, ModelMeta, UsageTotals } from "./state.js";
-import { getUsageTotals } from "./state.js";
+import type { FooterState, ModelMeta, UsageTotals, UsageTotalsSource } from "./state.js";
+import { getUsageTotals, totalInputTokens } from "./state.js";
 import type { IconGlyphs } from "./icons.js";
 import { runtimeSymbol } from "./icons.js";
 import { ChromeComposition } from "./chrome-composition.js";
@@ -191,7 +191,9 @@ export function renderFooter(
 
   const stats: string[] = [];
   if (segments.tokens) {
-    stats.push(theme.fg("accent", `${glyphs.input} ${fmtTokens(totals.input)}`));
+    // Total input billed for the model — includes the cached prompt prefix, not just
+    // `usage.input` (which excludes cacheRead/cacheWrite). See totalInputTokens.
+    stats.push(theme.fg("accent", `${glyphs.input} ${fmtTokens(totalInputTokens(totals))}`));
     stats.push(theme.fg("success", `${glyphs.output} ${fmtTokens(totals.output)}`));
   }
   if (segments.cost) {
@@ -273,24 +275,7 @@ export function installFooter(
     const totals = getUsageTotals(
       // ast-grep-ignore: require-safety-comment-for-as-unknown-as
       // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-      /* SAFETY: intentional unsafe cast — validated at runtime */ ctx as unknown as {
-        // SAFETY: intentional unsafe cast — validated at runtime
-        sessionManager?: {
-          getEntries(): {
-            type: string;
-            message?: {
-              role: string;
-              usage?: {
-                input?: number;
-                output?: number;
-                cacheRead?: number;
-                cacheWrite?: number;
-                cost?: { total?: number };
-              };
-            };
-          }[];
-        };
-      },
+      /* SAFETY: intentional unsafe cast — validated at runtime */ ctx as unknown as UsageTotalsSource,
     );
     return renderFooter(width, state, config, themeStub, {
       cwd,
@@ -357,24 +342,7 @@ export function installFooter(
           const totals = getUsageTotals(
             // ast-grep-ignore: require-safety-comment-for-as-unknown-as
             // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-            /* SAFETY: intentional unsafe cast — validated at runtime */ ctx as unknown as {
-              // SAFETY: intentional unsafe cast — validated at runtime
-              sessionManager?: {
-                getEntries(): {
-                  type: string;
-                  message?: {
-                    role: string;
-                    usage?: {
-                      input?: number;
-                      output?: number;
-                      cacheRead?: number;
-                      cacheWrite?: number;
-                      cost?: { total?: number };
-                    };
-                  };
-                }[];
-              };
-            },
+            /* SAFETY: intentional unsafe cast — validated at runtime */ ctx as unknown as UsageTotalsSource,
           );
           return renderFooter(width, state, config, theme, {
             cwd,

package/src/state.ts

@@ -21,35 +21,55 @@ export interface UsageTotals {
   latestCacheHitRate: number | undefined;
 }
 
+/** Raw provider usage block as persisted on a session entry. */
+export interface EntryUsage {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+}
+
+/**
+ * Session entry slice read by getUsageTotals — the pi seam, validated at runtime.
+ * `usage` sits at the top level on branch_summary / compaction entries and inside
+ * `message` on message entries.
+ */
+export interface UsageSessionEntry {
+  type: string;
+  id?: string;
+  timestamp?: string;
+  message?: { role: string; usage?: EntryUsage };
+  usage?: EntryUsage;
+}
+
+/** Minimal session-manager seam getUsageTotals reads entries through. */
+export interface UsageTotalsSource {
+  sessionManager?: { getEntries(): UsageSessionEntry[] };
+}
+
+/**
+ * Total input tokens billed to the model: uncached input + cache read + cache write.
+ *
+ * pi-ai `Usage.input` excludes the cached prompt prefix (it lives in cacheRead/cacheWrite),
+ * so `input` alone under-reports the prompt by the whole cached history on every turn.
+ */
+export function totalInputTokens(
+  totals: Pick<UsageTotals, "input" | "cacheRead" | "cacheWrite">,
+): number {
+  return totals.input + totals.cacheRead + totals.cacheWrite;
+}
+
 let usageCache: { key: string; totals: UsageTotals } | undefined;
 
-function entriesKey(ctx: { sessionManager?: { getEntries(): unknown[] } }): string {
+function entriesKey(ctx: UsageTotalsSource): string {
   const entries = ctx.sessionManager?.getEntries() ?? [];
-  const last = entries.at(-1) as { id?: string; timestamp?: string } | undefined;
+  const last = entries.at(-1);
   return `${entries.length}:${String(last?.id ?? "")}:${String(last?.timestamp ?? "")}`;
 }
 
-export function getUsageTotals(ctx: {
-  sessionManager?: {
-    getEntries(): {
-      type: string;
-      message?: {
-        role: string;
-        usage?: {
-          input?: number;
-          output?: number;
-          cacheRead?: number;
-          cacheWrite?: number;
-          cost?: { total?: number };
-        };
-      };
-    }[];
-  };
-}): UsageTotals {
-  const key = entriesKey(
-    // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-    ctx as unknown as { sessionManager?: { getEntries(): unknown[] } },
-  );
+export function getUsageTotals(ctx: UsageTotalsSource): UsageTotals {
+  const key = entriesKey(ctx);
   if (usageCache && usageCache.key === key) return usageCache.totals;
 
   const totals: UsageTotals = {
@@ -60,40 +80,33 @@ export function getUsageTotals(ctx: {
     cost: 0,
     latestCacheHitRate: undefined,
   };
-  const entries =
-    // SAFETY: pi seam — intentional unsafe cast, validated at runtime
-    (
-      ctx as unknown as {
-        sessionManager?: {
-          getEntries(): {
-            type: string;
-            message?: {
-              role: string;
-              usage?: {
-                input?: number;
-                output?: number;
-                cacheRead?: number;
-                cacheWrite?: number;
-                cost?: { total?: number };
-              };
-            };
-          }[];
-        };
-      }
-    ).sessionManager?.getEntries() ?? [];
-  for (const entry of entries) {
+  const addUsage = (usage: EntryUsage): void => {
+    totals.input += usage.input ?? 0;
+    totals.output += usage.output ?? 0;
+    totals.cacheRead += usage.cacheRead ?? 0;
+    totals.cacheWrite += usage.cacheWrite ?? 0;
+    totals.cost += usage.cost?.total ?? 0;
+  };
+  for (const entry of ctx.sessionManager?.getEntries() ?? []) {
+    // Assistant turns carry the cache split the hit rate is derived from; tool results
+    // and summaries are usage from nested model calls — billed, so they count toward the
+    // session totals (parity with pi core's addUsageToTotals loop).
     if (entry.type === "message" && entry.message?.role === "assistant") {
-      const u = entry.message.usage;
-      if (!u) continue;
-      totals.input += u.input ?? 0;
-      totals.output += u.output ?? 0;
-      totals.cacheRead += u.cacheRead ?? 0;
-      totals.cacheWrite += u.cacheWrite ?? 0;
-      totals.cost += u.cost?.total ?? 0;
-      const promptTokens = (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+      const usage = entry.message.usage;
+      if (!usage) continue;
+      addUsage(usage);
+      const promptTokens = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
       if (promptTokens > 0) {
-        totals.latestCacheHitRate = ((u.cacheRead ?? 0) / promptTokens) * 100;
+        totals.latestCacheHitRate = ((usage.cacheRead ?? 0) / promptTokens) * 100;
       }
+      continue;
+    }
+    if (entry.type === "message" && entry.message?.role === "toolResult") {
+      if (entry.message.usage) addUsage(entry.message.usage);
+      continue;
+    }
+    if (entry.type === "branch_summary" || entry.type === "compaction") {
+      if (entry.usage) addUsage(entry.usage);
     }
   }
   usageCache = { key, totals };