@tmustier/pi-usage-extension 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.1] - 2026-07-17
+
+### Changed
+- **Consistent units.** Every alarm in “Worth attention” now leads with dollars (the act-or-ignore number), with the period share in the dimmed parenthetical; “Where it went” keeps percentages (shares of the pie). Session concentration and upfront tax previously led with %.
+
+## [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

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. When nothing is flagged, the section shows an explicit all-clear.
-
-| Alarm | Fires when |
-|---|---|
-| 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) |
+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,12 +1058,23 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		insights.push({
 			kind: "alarm",
 			stat: fmtMoney(raw.ttlMissCost),
-			headline: `spent re-sending conversations after a break (${fmtPercent(ttlPct)} of this period)`,
+			headline: `spent resuming conversations after a break (${fmtPercent(ttlPct)} of this period)`,
 			advice:
 				"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.",
+		});
+	}
+
 	const prefixPct = (raw.prefixMissCost / total) * 100;
 	if (prefixPct >= CACHE_MISS_ALARM_PERCENT && raw.prefixMissCost >= CACHE_MISS_ALARM_MIN_COST) {
 		insights.push({
@@ -1058,7 +1082,7 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 			stat: fmtMoney(raw.prefixMissCost),
 			headline: `spent re-sending conversations mid-session (${fmtPercent(prefixPct)} of this period)`,
 			advice:
-				"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.",
+				"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.",
 		});
 	}
 
@@ -1069,8 +1093,8 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 		if (topPct >= CONCENTRATION_ALARM_PERCENT) {
 			insights.push({
 				kind: "alarm",
-				stat: fmtPercent(topPct),
-				headline: `of this period's cost came from just ${TOP_SESSION_COUNT} sessions (of ${raw.sessionCosts.size})`,
+				stat: fmtMoney(topWeight),
+				headline: `came from just ${TOP_SESSION_COUNT} of your ${raw.sessionCosts.size} sessions (${fmtPercent(topPct)} of this period)`,
 				advice: "A handful of sessions drove most of the spend. The graph view can show what they were doing.",
 			});
 		}
@@ -1080,8 +1104,8 @@ function computeInsights(raw: PeriodRawData, trend: TrendInfo | null): PeriodIns
 	if (upfrontPct >= UPFRONT_ALARM_PERCENT) {
 		insights.push({
 			kind: "alarm",
-			stat: fmtPercent(upfrontPct),
-			headline: "of cost went on the opening message of new sessions",
+			stat: fmtMoney(raw.upfrontCost),
+			headline: `spent on the opening message of new sessions (${fmtPercent(upfrontPct)} of this period)`,
 			advice: "A session's first message sends everything from scratch. Fewer, longer sessions cut this overhead.",
 		});
 	}

package/index.ts

@@ -553,6 +553,11 @@ class UsageComponent {
 
 		const alarms = insights.filter((i) => i.kind === "alarm");
 		const structure = insights.filter((i) => i.kind === "structure");
+		// Facts first, flagged waste second.
+		if (structure.length > 0) {
+			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);
@@ -560,10 +565,6 @@ class UsageComponent {
 			lines.push(`  ${th.fg("success", padLeft("✓", 6))} ${th.fg("dim", "no waste patterns flagged for this period")}`);
 			lines.push("");
 		}
-		if (structure.length > 0) {
-			lines.push(sectionHeader("Where it went", "accent"));
-			for (const insight of structure) renderOne(insight);
-		}
 
 		return lines;
 	}

package/package.json

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