@tmustier/pi-usage-extension 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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) |

package/data.ts

@@ -1045,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.",
 		});
 	}
 
@@ -1056,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.",
 		});
 	}
 
@@ -1071,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.",
 			});
 		}
 	}
@@ -1081,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.",
 		});
 	}
 
@@ -1093,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.",
 			});
 		}
 	}
@@ -1109,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.",
 			});
 		}
 	}
@@ -1143,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.",
 			});
 		}
 	}
@@ -1154,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

@@ -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,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);
 		}
 

package/package.json

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