@tmustier/pi-usage-extension 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0] - 2026-07-17
+
+### Changed
+- **Cache-miss taxonomy split into three behaviours**, each with its own alarm: resuming a conversation after a break (cache expired), switching models mid-conversation (the previous model's cache doesn't transfer), and true mid-session prefix changes (no break, compaction, or model switch to explain them). Validated against a second public corpus (badlogicgames/pi-mono, 628 sessions).
+- **Insights sections reordered facts-first**: “Where it went” (structure) now comes before “Worth attention” (alarms).
+- **pi's built-in test providers excluded**: `faux-provider` and `fake-provider` never call a real API and no longer appear in tables, graphs, totals, or insights.
+
+## [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

package/README.md

@@ -67,17 +67,7 @@ In Pi, run:
 
 ### Insights
 
-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.
-
-| 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 |
-| 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) |
+The **Insights** view has two sections, facts first:
 
 **Where it went** — always-on structural lenses:
 
@@ -85,9 +75,22 @@ The **Insights** view has two sections:
 |---|---|
 | Context tax | share of cost spent at ≥ 150k context, with the average per-message cost vs messages under 100k |
 | Project mix | top 3 project directories by cost, derived from each session's working directory (worktrees collapse into their repository; hidden when one project is ≥ 90% — you already know) |
-| Reasoning share | share of output tokens that were invisible reasoning (recorded by pi 0.80.3+ only; hidden below 5%) |
+| Reasoning share | share of output tokens that were hidden reasoning (recorded by pi 0.80.3+ only; hidden below 5%) |
 | Burn trend | your last 7 days of spend vs your prior 4-week weekly pace (same on every tab) |
 
+**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. Large-context cache misses are split into three distinct behaviours:
+
+| Alarm | Fires when |
+|---|---|
+| Resuming after a break | ≥ 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 |
+| Switching models mid-conversation | ≥ 2% of cost (and ≥ $1) went to large-context misses right after the provider/model changed mid-session — the previous model's cache doesn't transfer |
+| Mid-session re-sends (prefix change) | ≥ 2% of cost (and ≥ $1) went to large-context misses with **no** idle gap, compaction, or model switch to explain them — something rewrote the request 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) |
+
+pi's built-in test providers (`faux-provider`, `fake-provider`) never call a real API and are excluded from all statistics, graphs, and insights.
+
 **Unit:** insights are weighted by recorded API cost (USD). Periods with no recorded cost show an explicit empty state rather than silently switching to a different unit.
 
 A note on reading them: cache-miss and context numbers are **observed cost, not promised savings** — big-context messages often do bigger work. Treat the alarms as "look here", not as an invoice for waste.

package/data.ts

@@ -76,9 +76,11 @@ interface PeriodRawData {
 	sessionCosts: Map<string, number>;
 	/** Cost of each session's first-ever message falling in this period. */
 	upfrontCost: number;
-	/** Cache misses after >TTL_GAP_MS idle — expired-cache re-warms. */
+	/** Cache misses after >TTL_GAP_MS idle — resuming after the cache expired. */
 	ttlMissCost: number;
-	/** Cache misses without an idle gap (compaction excluded) — prefix changes. */
+	/** Cache misses right after a mid-session model switch (no idle gap). */
+	modelSwitchMissCost: number;
+	/** Cache misses with no idle gap, compaction, or model switch — true prefix changes. */
 	prefixMissCost: number;
 	reasoningTokens: number;
 	outputTokens: number;
@@ -92,6 +94,8 @@ interface MessageMeta {
 	gapMs: number;
 	/** Context size of the previous assistant message in the same file; 0 when first. */
 	prevCtx: number;
+	/** True when the provider/model differs from the previous assistant message. */
+	modelSwitched: boolean;
 	/** True for the first deduped message of a session across all its files. */
 	isSessionStart: boolean;
 }
@@ -514,6 +518,7 @@ function emptyPeriodRawData(): PeriodRawData {
 		sessionCosts: new Map(),
 		upfrontCost: 0,
 		ttlMissCost: 0,
+		modelSwitchMissCost: 0,
 		prefixMissCost: 0,
 		reasoningTokens: 0,
 		outputTokens: 0,
@@ -640,6 +645,9 @@ function addMessagesToUsageData(
 		const msg = messages[mi]!;
 		const mm = meta[mi]!;
 
+		// pi's built-in test providers never call a real API — keep them out of stats.
+		if (EXCLUDED_PROVIDERS.has(msg.provider)) continue;
+
 		// Day-indexed cost totals power the burn-trend insight.
 		if (msg.timestamp > 0) {
 			const dayIdx = Math.floor((msg.timestamp - todayMs) / DAY_MS);
@@ -704,6 +712,7 @@ function addMessagesToUsageData(
 				msg.cacheRead < Math.min(MISS_MAX_CACHE_READ, 0.3 * mm.prevCtx)
 			) {
 				if (mm.gapMs > TTL_GAP_MS) raw.ttlMissCost += msg.cost;
+				else if (mm.gapMs >= 0 && mm.modelSwitched) raw.modelSwitchMissCost += msg.cost;
 				else if (mm.gapMs >= 0) raw.prefixMissCost += msg.cost;
 			}
 			raw.reasoningTokens += msg.reasoning;
@@ -943,6 +952,7 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 			meta.push({
 				gapMs: prev && prev.timestamp > 0 && m.timestamp > 0 ? m.timestamp - prev.timestamp : -1,
 				prevCtx: prev ? prev.input + prev.cacheRead + prev.cacheWrite : 0,
+				modelSwitched: prev !== null && (prev.provider !== m.provider || prev.model !== m.model),
 				isSessionStart: false,
 			});
 		}
@@ -1002,6 +1012,9 @@ const TREND_LOW_RATIO = 0.6;
 const TTL_GAP_MS = 5 * 60_000;
 const MISS_MIN_PREV_CONTEXT = 20_000;
 const MISS_MAX_CACHE_READ = 5_000;
+/** pi's built-in test providers never send anything to a real API. */
+const EXCLUDED_PROVIDERS = new Set(["faux-provider", "fake-provider"]);
+
 const CACHE_MISS_ALARM_PERCENT = 2;
 const CACHE_MISS_ALARM_MIN_COST = 1;
 // Concentration / upfront alarms
@@ -1045,9 +1058,20 @@ 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 resuming 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.",
+		});
+	}
+
+	const switchPct = (raw.modelSwitchMissCost / total) * 100;
+	if (switchPct >= CACHE_MISS_ALARM_PERCENT && raw.modelSwitchMissCost >= CACHE_MISS_ALARM_MIN_COST) {
+		insights.push({
+			kind: "alarm",
+			stat: fmtMoney(raw.modelSwitchMissCost),
+			headline: `spent switching models mid-conversation (${fmtPercent(switchPct)} of this period)`,
+			advice:
+				"Changing model re-sends the whole conversation at full price — the previous model's saved context doesn't transfer. Switching between tasks instead of mid-conversation avoids this.",
 		});
 	}
 
@@ -1056,9 +1080,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 — with no break, compaction, or model switch to explain it. Usually a tool or workflow is restarting or rewriting conversations. Worth a look if it stays high.",
 		});
 	}
 
@@ -1071,7 +1095,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.",
 			});
 		}
 	}
@@ -1081,9 +1105,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.",
 		});
 	}
 
@@ -1093,9 +1116,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.",
 			});
 		}
 	}
@@ -1109,13 +1132,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.",
 			});
 		}
 	}
@@ -1143,9 +1166,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.",
 			});
 		}
 	}
@@ -1154,9 +1177,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

@@ -499,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) {
@@ -522,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)}`);
@@ -539,14 +553,18 @@ class UsageComponent {
 
 		const alarms = insights.filter((i) => i.kind === "alarm");
 		const structure = insights.filter((i) => i.kind === "structure");
-		if (alarms.length > 0) {
-			lines.push(th.fg("accent", "Worth attention"));
-			for (const insight of alarms) renderOne(insight);
-		}
+		// Facts first, flagged waste second.
 		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);
 		}
+		lines.push(sectionHeader("Worth attention", "warning"));
+		if (alarms.length > 0) {
+			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("");
+		}
 
 		return lines;
 	}

package/package.json

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