@tmustier/pi-usage-extension 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.7.2] - 2026-07-17
+
+### Changed
+- **Insights view polish.** Section headers with rules (“Worth attention” in warning colour, “Where it went” in accent), alarm markers and stats in warning colour, the trailing “(x% of this period)” de-emphasised, content capped at 100 columns for readability on wide terminals, and an explicit all-clear line (✓) when no alarms fire. The stat column fits 6-character values (e.g. `$58.79`).
+- **Plain-language copy.** Insight headlines now state what happened rather than the cache mechanism (“spent re-sending conversations after a break” instead of “re-warming caches that expired during idle gaps”), advice avoids jargon, and vendor-specific cache details are gone.
+- The period · “independent lenses” note is folded into the subtitle: “Approximate, based on local sessions on this machine (these are independent and don't sum to 100%).”
+
+## [0.7.1] - 2026-07-17
+
+### Added
+- Descriptive loading messages with a live file counter while `/usage` opens: “Building your usage history for the first time…” on a fresh install, “Rebuilding your usage history — the cache format changed…” after an upgrade that bumps the cache version, and “Updating your usage history since \<date>…” for routine incremental refreshes. Warm opens with nothing to parse keep the plain spinner.
+- `collectUsageData` accepts an `onProgress` callback reporting mode (`first-run` / `rebuild` / `update`), files to parse, files parsed, and the newest already-ingested session activity timestamp.
+
 ## [0.7.0] - 2026-07-17
 
 ### Changed

package/README.md

@@ -69,12 +69,12 @@ In Pi, run:
 
 The **Insights** view has two sections:
 
-**Worth attention** — alarms that only appear when a wasteful pattern is material for the period. A quiet panel means nothing notable was detected.
+**Worth attention** — alarms that only appear when a wasteful pattern is material for the period. When nothing is flagged, the section shows an explicit all-clear.
 
 | Alarm | Fires when |
 |---|---|
-| TTL re-warm tax | ≥ 2% of the period's cost (and ≥ $1) went to messages that re-wrote a large context from scratch after a > 5 min idle gap — provider caches expire after a few minutes idle (Anthropic ~5 min) |
-| Prefix-change misses | ≥ 2% of cost (and ≥ $1) went to large-context cache misses with **no** idle gap — the request prefix changed mid-session. Messages right after a pi compaction are excluded, since compaction legitimately rewrites the prefix |
+| Re-sends after a break (cache TTL) | ≥ 2% of the period's cost (and ≥ $1) went to messages that re-sent a large conversation from scratch after a > 5 min idle gap — provider caches expire after a few minutes idle |
+| Mid-session re-sends (prefix change) | ≥ 2% of cost (and ≥ $1) went to large-context cache misses with **no** idle gap — the request prefix changed mid-session. Messages right after a pi compaction are excluded, since compaction legitimately rewrites the prefix |
 | Session concentration | the top 5 sessions account for ≥ 35% of the period's cost |
 | Upfront tax | ≥ 8% of cost was the first message of a session (session starts pay for their whole prompt uncached) |
 | Cache leverage floor | fewer than 5 cached tokens served per fresh token paid (shown only above $5 / 1M fresh tokens, to avoid noise) |
@@ -159,7 +159,7 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 - **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
 - **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
 - The cache is safe to delete at any time; it is rebuilt automatically. Corrupt or version-mismatched caches are ignored and rebuilt rather than trusted.
-- **0.7.0 bumps the cache format to v3** (adds session working directory and compaction markers; 0.6.0's v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild, then warm opens are fast again.
+- **0.7.0 bumps the cache format to v3** (adds session working directory and compaction markers; 0.6.0's v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild (with a progress message and live file counter), then warm opens are fast again.
 
 ## Provider Notes
 

package/data.ts

@@ -619,6 +619,7 @@ function getPeriodsForTimestamp(
 }
 
 const DAY_MS = 24 * HOUR_MS;
+const PROGRESS_REPORT_EVERY = 100;
 
 function addMessagesToUsageData(
 	data: UsageData,
@@ -727,8 +728,21 @@ const STAT_CONCURRENCY = 16;
 const DEFAULT_PARSE_CONCURRENCY = 4;
 const AGGREGATE_YIELD_EVERY_FILES = 200;
 
+export interface CollectProgress {
+	/** Why this pass needs to parse files. */
+	mode: "first-run" | "rebuild" | "update";
+	/** Session files that need parsing this pass (0 = fully warm). */
+	filesToParse: number;
+	/** Files parsed so far; reported in coarse increments. */
+	filesParsed: number;
+	/** Newest session activity already ingested (ms since epoch); null when starting fresh. */
+	sinceMs: number | null;
+}
+
 export interface CollectUsageOptions {
 	signal?: AbortSignal;
+	/** Called once before parsing begins and periodically while files are parsed. */
+	onProgress?: (progress: CollectProgress) => void;
 	/** Defaults to `<agentDir>/sessions`. */
 	sessionsDir?: string;
 	/** Defaults to `<agentDir>/usage-extension-cache.json`. Pass `null` to disable the on-disk cache. */
@@ -794,6 +808,15 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	if (signal?.aborted) return null;
 
 	// 3. Load the cache and decide which files actually need parsing.
+	let cacheFileExists = false;
+	if (cachePath) {
+		try {
+			await stat(cachePath);
+			cacheFileExists = true;
+		} catch {
+			// No cache file yet — first run.
+		}
+	}
 	const previous = cachePath ? await loadUsageCache(cachePath) : new Map<string, CachedFileState>();
 	if (signal?.aborted) return null;
 	const current = new Map<string, CachedFileState>();
@@ -818,6 +841,22 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 		}
 	}
 
+	// Progress reporting: distinguish a true first run from a format-change
+	// rebuild (cache file present but unusable) and a routine incremental update.
+	const progressMode: CollectProgress["mode"] =
+		previous.size > 0 ? "update" : cacheFileExists ? "rebuild" : "first-run";
+	let sinceMs: number | null = null;
+	if (progressMode === "update") {
+		for (const state of previous.values()) {
+			if (state.mtimeMs > (sinceMs ?? 0)) sinceMs = state.mtimeMs;
+		}
+	}
+	let filesParsed = 0;
+	const reportProgress = (): void => {
+		options.onProgress?.({ mode: progressMode, filesToParse: toParse.length, filesParsed, sinceMs });
+	};
+	reportProgress();
+
 	// 4. Parse new/changed files with bounded concurrency.
 	{
 		let next = 0;
@@ -831,11 +870,16 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 					try {
 						buffer = await readFile(filePath);
 					} catch {
+						filesParsed++;
 						continue; // File vanished — skip it.
 					}
 					const parsed = await parseSessionBuffer(buffer, signal);
 					if (signal?.aborted) return; // Never cache a partial parse.
 					current.set(filePath, { size: st.size, mtimeMs: st.mtimeMs, parsed });
+					filesParsed++;
+					if (filesParsed % PROGRESS_REPORT_EVERY === 0 || filesParsed === toParse.length) {
+						reportProgress();
+					}
 				}
 			})
 		);
@@ -1001,9 +1045,9 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.ttlMissCost),
-			headline: `spent re-warming caches that expired during idle gaps (${fmtPercent(ttlPct)} of this period)`,
+			headline: `spent re-sending conversations after a break (${fmtPercent(ttlPct)} of this period)`,
 			advice:
-				"Provider caches expire after a few minutes idle (Anthropic ~5min); the next message re-writes the whole context at premium rates. Batching replies instead of trickling them keeps caches warm.",
+				"Sent context is only reusable for a few minutes. After a longer pause, the next message pays to send the whole conversation again. Replying while a session is fresh avoids this.",
 		});
 	}
 
@@ -1012,9 +1056,9 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.prefixMissCost),
-			headline: `spent on cache misses with no idle gap (${fmtPercent(prefixPct)} of this period)`,
+			headline: `spent re-sending conversations mid-session (${fmtPercent(prefixPct)} of this period)`,
 			advice:
-				"The request prefix changed mid-session (compaction excluded), so cached context was re-sent at full price. If this stays high, something in the workflow is defeating provider caching.",
+				"These messages paid full price for context that had already been sent, without a pause to explain it. Usually a tool or workflow is restarting or rewriting conversations. Worth a look if it stays high.",
 		});
 	}
 
@@ -1027,7 +1071,7 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 				kind: "alarm",
 				stat: fmtPercent(topPct),
 				headline: `of this period's cost came from just ${TOP_SESSION_COUNT} sessions (of ${raw.sessionCosts.size})`,
-				advice: "Spend is unusually concentrated. The graph view's filters can pinpoint what those sessions were doing.",
+				advice: "A handful of sessions drove most of the spend. The graph view can show what they were doing.",
 			});
 		}
 	}
@@ -1037,9 +1081,8 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		insights.push({
 			kind: "alarm",
 			stat: fmtPercent(upfrontPct),
-			headline: "of cost was the first message of a session",
-			advice:
-				"Session starts pay for their whole prompt uncached. Fewer, longer-lived sessions amortize that setup cost.",
+			headline: "of cost went on the opening message of new sessions",
+			advice: "A session's first message sends everything from scratch. Fewer, longer sessions cut this overhead.",
 		});
 	}
 
@@ -1049,9 +1092,9 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 			insights.push({
 				kind: "alarm",
 				stat: `${leverage.toFixed(1)}×`,
-				headline: "cache leverage — cached tokens served per fresh token paid",
+				headline: "tokens reused from history for every token paid at full price",
 				advice:
-					"Healthy interactive use typically sees 10×+. Low leverage means context is being re-sent uncached — look for workflows that restart conversations.",
+					"Typical interactive use reuses 10× or more. A low number means conversations keep being sent from scratch — look for workflows that restart sessions.",
 			});
 		}
 	}
@@ -1065,13 +1108,13 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 			const avgLow = raw.ctxLow.messages > 0 ? raw.ctxLow.cost / raw.ctxLow.messages : 0;
 			const cmp =
 				avgLow > 0
-					? ` — averaging ${fmtMoney(avgHigh)}/msg vs ${fmtMoney(avgLow)} under ${formatThresholdTokens(CTX_LOW_THRESHOLD)}`
+					? ` — ${fmtMoney(avgHigh)}/msg vs ${fmtMoney(avgLow)} under ${formatThresholdTokens(CTX_LOW_THRESHOLD)}`
 					: "";
 			insights.push({
 				kind: "structure",
 				stat: fmtPercent(pct),
-				headline: `of your cost was at ≥${formatThresholdTokens(CTX_TAX_THRESHOLD)} context${cmp}`,
-				advice: "Context size is the main cost driver. /compact mid-task and /clear between tasks to reset it.",
+				headline: `of your cost came from messages with ≥${formatThresholdTokens(CTX_TAX_THRESHOLD)} tokens loaded${cmp}`,
+				advice: "Long conversations cost more per message. /compact mid-task and /clear between tasks keep them lean.",
 			});
 		}
 	}
@@ -1099,9 +1142,9 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 			insights.push({
 				kind: "structure",
 				stat: fmtPercent(reasoningPct),
-				headline: "of your output tokens were invisible reasoning",
+				headline: "of your output tokens were hidden reasoning",
 				advice:
-					"Reasoning is billed as output but never displayed. Recorded by pi 0.80.3+ (June 2026) only, so older periods understate it.",
+					"Models charge for their behind-the-scenes thinking as output tokens. pi records this only from 0.80.3 (June 2026), so older periods understate it.",
 			});
 		}
 	}
@@ -1110,9 +1153,9 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		const ratio = trend.last7Cost / trend.priorWeeklyPace;
 		const advice =
 			ratio >= TREND_HIGH_RATIO
-				? "Spend is accelerating vs your own baseline — the graph view shows what changed."
+				? "Spending is up against your own baseline — the graph view shows what changed."
 				: ratio <= TREND_LOW_RATIO
-					? "Spend is well below your recent baseline."
+					? "Spending is well below your recent baseline."
 					: "";
 		insights.push({
 			kind: "structure",

package/index.ts

@@ -14,6 +14,7 @@ import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 import { collectUsageData, TAB_ORDER } from "./data";
+import type { CollectProgress } from "./data";
 import type { BaseStats, TabName, UsageData } from "./data";
 import {
 	buildGraphModel,
@@ -175,6 +176,18 @@ function seriesColor(index: number): string {
 	return SERIES_COLORS[index % SERIES_COLORS.length]!;
 }
 
+/** "14:32" if the timestamp is today, otherwise "16 Jul" (with year if not this year). */
+function formatSinceDate(ms: number): string {
+	const d = new Date(ms);
+	const now = new Date();
+	if (d.toDateString() === now.toDateString()) {
+		return d.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+	}
+	const opts: Intl.DateTimeFormatOptions = { day: "numeric", month: "short" };
+	if (d.getFullYear() !== now.getFullYear()) opts.year = "numeric";
+	return d.toLocaleDateString(undefined, opts);
+}
+
 function padLeft(s: string, len: number): string {
 	const vis = visibleWidth(s);
 	if (vis >= len) return s;
@@ -486,11 +499,14 @@ class UsageComponent {
 		const hasCost = stats.totals.cost > 0;
 		const lines: string[] = [];
 
-		lines.push("What's contributing to your cost?");
-		lines.push(th.fg("dim", "Approximate, based on local sessions on this machine."));
-		lines.push("");
-		const note = `${TAB_LABELS[this.activeTab]} · independent lenses — they overlap and don't sum to 100%`;
-		lines.push(th.fg("dim", note));
+		// Cap the content column so advice stays readable on very wide terminals.
+		const contentWidth = Math.max(Math.min(width, 100), 40);
+
+		lines.push(th.bold("What's contributing to your cost?"));
+		const subtitle = "Approximate, based on local sessions on this machine (these are independent and don't sum to 100%).";
+		for (const wrapped of wrapTextWithAnsi(subtitle, contentWidth)) {
+			lines.push(th.fg("dim", wrapped));
+		}
 		lines.push("");
 
 		if (!hasMessages) {
@@ -509,13 +525,24 @@ class UsageComponent {
 			return lines;
 		}
 
-		const indent = "       ";
-		const adviceWidth = Math.max(width - indent.length, 30);
+		// Columns: marker(2) + stat(6) + gap(1); advice aligns under the headline.
+		const indent = "         ";
+		const adviceWidth = Math.max(contentWidth - indent.length, 30);
+
+		const sectionHeader = (label: string, color: "warning" | "accent"): string => {
+			const rule = "─".repeat(Math.max(contentWidth - label.length - 1, 4));
+			return `${th.fg(color, th.bold(label))} ${th.fg("border", rule)}`;
+		};
 
 		const renderOne = (insight: (typeof insights)[number]): void => {
-			const marker = insight.kind === "alarm" ? "⚠ " : "  ";
-			const stat = th.fg("accent", th.bold(padLeft(insight.stat, 5)));
-			lines.push(`${marker}${stat} ${insight.headline}`);
+			const isAlarm = insight.kind === "alarm";
+			const marker = isAlarm ? th.fg("warning", "⚠ ") : "  ";
+			const statText = padLeft(insight.stat, 6);
+			const stat = isAlarm ? th.fg("warning", th.bold(statText)) : th.fg("accent", th.bold(statText));
+			// De-emphasise the trailing period-share parenthetical on alarm headlines.
+			const match = insight.headline.match(/^(.*?)\s*(\(\d[\d.,]*% of this period\))$/);
+			const headline = match ? `${match[1]} ${th.fg("dim", match[2]!)}` : insight.headline;
+			lines.push(`${marker}${stat} ${headline}`);
 			if (insight.advice) {
 				for (const wrapped of wrapTextWithAnsi(insight.advice, adviceWidth)) {
 					lines.push(`${indent}${th.fg("dim", wrapped)}`);
@@ -526,12 +553,15 @@ class UsageComponent {
 
 		const alarms = insights.filter((i) => i.kind === "alarm");
 		const structure = insights.filter((i) => i.kind === "structure");
+		lines.push(sectionHeader("Worth attention", "warning"));
 		if (alarms.length > 0) {
-			lines.push(th.fg("accent", "Worth attention"));
 			for (const insight of alarms) renderOne(insight);
+		} else {
+			lines.push(`  ${th.fg("success", padLeft("✓", 6))} ${th.fg("dim", "no waste patterns flagged for this period")}`);
+			lines.push("");
 		}
 		if (structure.length > 0) {
-			if (alarms.length > 0) lines.push(th.fg("dim", "Where it went"));
+			lines.push(sectionHeader("Where it went", "accent"));
 			for (const insight of structure) renderOne(insight);
 		}
 
@@ -722,7 +752,20 @@ export default function (pi: ExtensionAPI) {
 
 				loader.onAbort = () => finish(null);
 
-				collectUsageData({ signal: loader.signal })
+				const onProgress = (p: CollectProgress): void => {
+					if (finished || p.filesToParse === 0) return;
+					const files = `${p.filesParsed.toLocaleString()}/${p.filesToParse.toLocaleString()} files`;
+					if (p.mode === "update") {
+						const since = p.sinceMs !== null ? ` since ${formatSinceDate(p.sinceMs)}` : "";
+						loader.setMessage(`Updating your usage history${since}… (${files})`);
+					} else if (p.mode === "rebuild") {
+						loader.setMessage(`Rebuilding your usage history — the cache format changed… (${files})`);
+					} else {
+						loader.setMessage(`Building your usage history for the first time… (${files})`);
+					}
+				};
+
+				collectUsageData({ signal: loader.signal, onProgress })
 					.then(finish)
 					.catch(() => finish(null));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",