@tmustier/pi-usage-extension 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.10.0] - 2026-10-26
+
+### Added
+- **This Month period.** New tab between Last Week and Last 30 Days covering the current calendar month from local midnight on the 1st, in the graph, table, insights, and exports. Useful when a usage budget resets on the 1st of each month.
+
+### Fixed
+- Collapse Windows home directories in project labels. Backslash paths are normalised, `C:\Users\<name>\...` collapses to `~/...` like `/Users/<name>` and `/home/<name>`, and other drive paths drop the drive letter (`D:\work\repo` becomes `work/repo`). Previously the project mix insight showed raw Windows paths.
+- Make the usage tests pass on Windows.
+
+Thanks to @mturley for This Month ([#114](https://github.com/tmustier/pi-extensions/pull/114), requested in [#107](https://github.com/tmustier/pi-extensions/issues/107)) and @dawidmachon for the Windows fix ([#110](https://github.com/tmustier/pi-extensions/pull/110)).
+
+## [0.9.5] - 2026-09-22
+
+### Changed
+- Treat Pi 0.87 `context_edit` entries as intentional request-prefix changes so they do not count as cache misses.
+
+### Internal
+- Cache format bumped to **v6**. The first `/usage` open after upgrading performs a one-off rebuild.
+
 ## [0.9.4] - 2026-07-22
 
 ### Changed

package/README.md

@@ -97,7 +97,7 @@ The **Insights** view has two sections, facts first:
 |---|---|
 | 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 |
+| Mid-session re-sends (prefix change) | ≥ 2% of cost (and ≥ $1) went to large-context misses with **no** idle gap, compaction, context edit, or model switch to explain them — something unexpectedly 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) |
@@ -136,7 +136,7 @@ The **Graphs** view plots usage over time for the active period as a braille lin
 - **Grouping** (`g` to cycle): by provider, by model, by thinking level, or total only. The top 6 series are shown individually; the rest merge into an `other` series. A bold **Total** line is always drawn.
 - **Cumulative vs per-bucket** (`c` to toggle): running total across the period (default), or the raw per-bucket rate.
 - **Filtering**: move the legend cursor with `↑`/`↓` and toggle series visibility with `Enter`/`Space` (`a` shows all again). The y-axis rescales to the visible series — hide the big lines to zoom into the small ones.
-- **Buckets**: hourly for Today / This Week / Last Week, daily for Last 30 Days / All Time.
+- **Buckets**: hourly for Today / This Week / Last Week (and This Month during its first 8 days), daily for This Month after its first 8 days / Last 30 Days / All Time.
 - **Line clipping**: every series (provider, model, thinking level, `other`, Total) is drawn only between its first and last bucket with usage, so late-starting or retired series don't drag a flat zero/flat tail across the whole period.
 
 Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Auxiliary usage has no reliable thinking-level attribution and appears as `Tools/summaries` in that grouping. Reasoning token counts come from `usage.reasoning` where providers report them; pi only records this field since **pi 0.80.3 (30 June 2026)**, so earlier sessions show zero reasoning tokens even though thinking models were in use.
@@ -148,6 +148,7 @@ Thinking levels are replayed from `thinking_level_change` entries in each sessio
 | **Today** | From midnight (00:00) today |
 | **This Week** | From Monday 00:00 of the current week |
 | **Last Week** | Previous week (Monday 00:00 → this Monday 00:00) |
+| **This Month** | From local midnight on the first day of the current month |
 | **Last 30 Days** | Rolling window: the last 30 calendar days including today (from midnight 29 days back) |
 | **All Time** | All recorded sessions |
 

package/data.ts

@@ -149,6 +149,7 @@ export interface PeriodBounds {
 	todayMs: number;
 	weekStartMs: number;
 	lastWeekStartMs: number;
+	thisMonthStartMs: number;
 	last30DaysStartMs: number;
 	nowMs: number;
 }
@@ -157,6 +158,7 @@ export interface UsageData {
 	today: TimeFilteredStats;
 	thisWeek: TimeFilteredStats;
 	lastWeek: TimeFilteredStats;
+	thisMonth: TimeFilteredStats;
 	last30Days: TimeFilteredStats;
 	allTime: TimeFilteredStats;
 	/** Deduped usage bucketed by hour start (ms) → series key → metrics. */
@@ -164,9 +166,9 @@ export interface UsageData {
 	bounds: PeriodBounds;
 }
 
-export type TabName = "today" | "thisWeek" | "lastWeek" | "last30Days" | "allTime";
+export type TabName = "today" | "thisWeek" | "lastWeek" | "thisMonth" | "last30Days" | "allTime";
 
-export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "last30Days", "allTime"];
+export const TAB_ORDER: TabName[] = ["today", "thisWeek", "lastWeek", "thisMonth", "last30Days", "allTime"];
 
 export type UsageSource = "assistant" | "auxiliary";
 
@@ -194,12 +196,8 @@ export interface SessionMessage extends UsageAmount {
 	/** Session entry id used to dedupe copied auxiliary entries; empty for assistant messages. */
 	sourceId: string;
 	timestamp: number;
-	/**
-	 * True when a compaction entry occurred between the previous assistant
-	 * message and this one. Compaction legitimately changes the request prefix,
-	 * so such messages are excluded from prefix-change cache-miss accounting.
-	 */
-	afterCompaction: boolean;
+	/** The request followed a compaction or context edit that intentionally changed its prefix. */
+	afterContextChange: boolean;
 }
 
 export interface ChildToolUsage {
@@ -300,6 +298,8 @@ const PATTERN_THINKING_COMPACT = Buffer.from('"type":"thinking_level_change"');
 const PATTERN_THINKING_SPACED = Buffer.from('"type": "thinking_level_change"');
 const PATTERN_COMPACTION_COMPACT = Buffer.from('"type":"compaction"');
 const PATTERN_COMPACTION_SPACED = Buffer.from('"type": "compaction"');
+const PATTERN_CONTEXT_EDIT_COMPACT = Buffer.from('"type":"context_edit"');
+const PATTERN_CONTEXT_EDIT_SPACED = Buffer.from('"type": "context_edit"');
 const PATTERN_BRANCH_SUMMARY_COMPACT = Buffer.from('"type":"branch_summary"');
 const PATTERN_BRANCH_SUMMARY_SPACED = Buffer.from('"type": "branch_summary"');
 // pi-subagents versions predating Pi 0.81 persisted child usage in details but
@@ -357,7 +357,7 @@ function auxiliaryMessage(usage: UsageAmount, timestamp: number, sourceId: strin
 		sourceId,
 		...usage,
 		timestamp,
-		afterCompaction: false,
+		afterContextChange: false,
 	};
 }
 
@@ -642,10 +642,12 @@ function lineMightBeRelevant(line: Buffer): boolean {
 		head.includes(PATTERN_SESSION_COMPACT) ||
 		head.includes(PATTERN_THINKING_COMPACT) ||
 		head.includes(PATTERN_COMPACTION_COMPACT) ||
+		head.includes(PATTERN_CONTEXT_EDIT_COMPACT) ||
 		head.includes(PATTERN_BRANCH_SUMMARY_COMPACT) ||
 		head.includes(PATTERN_SESSION_SPACED) ||
 		head.includes(PATTERN_THINKING_SPACED) ||
 		head.includes(PATTERN_COMPACTION_SPACED) ||
+		head.includes(PATTERN_CONTEXT_EDIT_SPACED) ||
 		head.includes(PATTERN_BRANCH_SUMMARY_SPACED)
 	);
 }
@@ -665,7 +667,7 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 	// message of a session. Replaying them in append order attributes each message
 	// to the level active when it was produced.
 	let thinkingLevel = "";
-	let compactionPending = false;
+	let contextChangePending = false;
 
 	let start = 0;
 	let lineNumber = 0;
@@ -700,7 +702,9 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 				} else if (entry.type === "compaction") {
 					const usage = parseUsageAmount(entry.usage);
 					if (usage) messages.push(auxiliaryMessage(usage, parsedTimestamp(undefined, entry.timestamp), typeof entry.id === "string" ? entry.id : ""));
-					compactionPending = true;
+					contextChangePending = true;
+				} else if (entry.type === "context_edit") {
+					contextChangePending = true;
 				} else if (entry.type === "branch_summary") {
 					const usage = parseUsageAmount(entry.usage);
 					if (usage) messages.push(auxiliaryMessage(usage, parsedTimestamp(undefined, entry.timestamp), typeof entry.id === "string" ? entry.id : ""));
@@ -721,9 +725,9 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 							cacheWrite: msg.usage.cacheWrite || 0,
 							reasoning: msg.usage.reasoning || 0,
 							timestamp: msg.timestamp || (Number.isNaN(fallbackTs) ? 0 : fallbackTs),
-							afterCompaction: compactionPending,
+							afterContextChange: contextChangePending,
 						});
-						compactionPending = false;
+						contextChangePending = false;
 					}
 				} else if (entry.type === "message" && entry.message?.role === "toolResult") {
 					const msg = entry.message;
@@ -745,7 +749,7 @@ export async function parseSessionBuffer(buffer: Buffer, signal?: AbortSignal):
 // On-disk cache
 // =============================================================================
 
-const CACHE_VERSION = 5;
+const CACHE_VERSION = 6;
 
 type CachedMessageTuple = [
 	providerIdx: number,
@@ -758,7 +762,7 @@ type CachedMessageTuple = [
 	timestamp: number,
 	thinkingLevelIdx: number,
 	reasoning: number,
-	afterCompaction: 0 | 1,
+	afterContextChange: 0 | 1,
 	auxiliary: 0 | 1,
 	sourceIdIdx: number,
 ];
@@ -860,7 +864,7 @@ export async function loadUsageCache(cachePath: string): Promise<Map<string, Cac
 				cacheWrite: Number(tuple[6]) || 0,
 				timestamp: Number(tuple[7]) || 0,
 				reasoning: Number(tuple[9]) || 0,
-				afterCompaction: tuple[10] === 1,
+				afterContextChange: tuple[10] === 1,
 			});
 		}
 		if (!valid) continue;
@@ -959,7 +963,7 @@ export async function saveUsageCache(cachePath: string, states: Map<string, Cach
 				m.timestamp,
 				intern(m.thinkingLevel),
 				m.reasoning,
-				m.afterCompaction ? 1 : 0,
+				m.afterContextChange ? 1 : 0,
 				m.source === "auxiliary" ? 1 : 0,
 				intern(m.source === "auxiliary" ? m.sourceId : ""),
 			]),
@@ -1036,23 +1040,32 @@ function emptyPeriodRawData(): PeriodRawData {
  */
 export function projectLabelFromCwd(cwd: string): string {
 	if (!cwd) return "(unknown)";
+	// Normalize Windows separators so backslash paths (C:\Users\me\...) match the
+	// forward-slash forms compared below. Path text after the home prefix keeps
+	// its normalized forward slashes, which is what the label displays.
+	const normalized = cwd.replaceAll("\\", "/");
 	// Collapse any home-directory prefix to "~", not just the current user's —
 	// session stores merged from other machines can carry a different username.
-	const home = homedir();
+	const home = homedir().replaceAll("\\", "/");
 	let homePrefix: string | null = null;
-	if (cwd === home || cwd.startsWith(home + "/")) {
+	if (normalized === home || normalized.startsWith(home + "/")) {
 		homePrefix = home;
 	} else {
-		const m = /^(\/Users\/[^/]+|\/home\/[^/]+)(?=\/|$)/.exec(cwd);
+		const m = /^(\/Users\/[^/]+|\/home\/[^/]+|[A-Za-z]:\/Users\/[^/]+)(?=\/|$)/.exec(normalized);
 		if (m) homePrefix = m[1]!;
 	}
-	if (homePrefix !== null && cwd.length <= homePrefix.length) return "~";
-	let rel = homePrefix !== null ? cwd.slice(homePrefix.length + 1) : cwd;
+	if (homePrefix !== null && normalized.length <= homePrefix.length) return "~";
+	let rel = homePrefix !== null ? normalized.slice(homePrefix.length + 1) : normalized;
 	const wt = rel.indexOf("/.worktrees/");
 	if (wt !== -1) rel = rel.slice(0, wt);
 	const parts = rel.split("/").filter(Boolean);
-	const label = parts.slice(0, 2).join("/");
-	return homePrefix !== null ? `~/${label}` : `/${label}`;
+	if (homePrefix !== null) return `~/${parts.slice(0, 2).join("/")}`;
+	// Windows drive paths outside a home (D:/work/repo/sub): drop the drive segment
+	// so the label keeps meaningful segments (work/repo) and stays slash-separated.
+	const segments = /^[A-Za-z]:$/.test(parts[0] ?? "") ? parts.slice(1) : parts;
+	const label = segments.slice(0, 2).join("/");
+	if (/^[A-Za-z]:\//.test(normalized)) return label;
+	return `/${label}`;
 }
 
 function emptyUsageData(bounds: PeriodBounds): UsageData {
@@ -1060,6 +1073,7 @@ function emptyUsageData(bounds: PeriodBounds): UsageData {
 		today: emptyTimeFilteredStats(),
 		thisWeek: emptyTimeFilteredStats(),
 		lastWeek: emptyTimeFilteredStats(),
+		thisMonth: emptyTimeFilteredStats(),
 		last30Days: emptyTimeFilteredStats(),
 		allTime: emptyTimeFilteredStats(),
 		hourly: new Map(),
@@ -1113,6 +1127,7 @@ function getPeriodsForTimestamp(
 	todayMs: number,
 	weekStartMs: number,
 	lastWeekStartMs: number,
+	thisMonthStartMs: number,
 	last30DaysStartMs: number
 ): TabName[] {
 	const periods: TabName[] = ["allTime"];
@@ -1122,6 +1137,7 @@ function getPeriodsForTimestamp(
 	} else if (timestamp >= lastWeekStartMs) {
 		periods.push("lastWeek");
 	}
+	if (timestamp >= thisMonthStartMs) periods.push("thisMonth");
 	if (timestamp >= last30DaysStartMs) periods.push("last30Days");
 	return periods;
 }
@@ -1138,11 +1154,12 @@ function addMessagesToUsageData(
 	todayMs: number,
 	weekStartMs: number,
 	lastWeekStartMs: number,
+	thisMonthStartMs: number,
 	last30DaysStartMs: number,
 	rawByPeriod: Record<TabName, PeriodRawData>,
 	costByDayIdx: Map<number, number>
 ): void {
-	const sessionContributed = { today: false, thisWeek: false, lastWeek: false, last30Days: false, allTime: false };
+	const sessionContributed = { today: false, thisWeek: false, lastWeek: false, thisMonth: false, last30Days: false, allTime: false };
 
 	for (let mi = 0; mi < messages.length; mi++) {
 		const msg = messages[mi]!;
@@ -1159,7 +1176,14 @@ function addMessagesToUsageData(
 
 		addToHourlyBuckets(data.hourly, msg);
 
-		const periods = getPeriodsForTimestamp(msg.timestamp, todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs);
+		const periods = getPeriodsForTimestamp(
+			msg.timestamp,
+			todayMs,
+			weekStartMs,
+			lastWeekStartMs,
+			thisMonthStartMs,
+			last30DaysStartMs
+		);
 		const tokens = {
 			// Count fresh tokens processed this turn.
 			// Include cacheWrite because those prompt tokens were newly written and billed.
@@ -1220,7 +1244,7 @@ function addMessagesToUsageData(
 			}
 			if (mm.isSessionStart) raw.upfrontCost += msg.cost;
 			if (
-				!msg.afterCompaction &&
+				!msg.afterContextChange &&
 				mm.prevCtx >= MISS_MIN_PREV_CONTEXT &&
 				msg.cacheRead < Math.min(MISS_MAX_CACHE_READ, 0.3 * mm.prevCtx)
 			) {
@@ -1238,6 +1262,7 @@ function addMessagesToUsageData(
 	if (sessionContributed.today) data.today.totals.sessions++;
 	if (sessionContributed.thisWeek) data.thisWeek.totals.sessions++;
 	if (sessionContributed.lastWeek) data.lastWeek.totals.sessions++;
+	if (sessionContributed.thisMonth) data.thisMonth.totals.sessions++;
 	if (sessionContributed.last30Days) data.last30Days.totals.sessions++;
 	if (sessionContributed.allTime) data.allTime.totals.sessions++;
 }
@@ -1395,6 +1420,12 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	startOfLastWeek.setDate(startOfLastWeek.getDate() - 7);
 	const lastWeekStartMs = startOfLastWeek.getTime();
 
+	// Calendar month to date, from local midnight on the first.
+	const startOfThisMonth = new Date(now);
+	startOfThisMonth.setDate(1);
+	startOfThisMonth.setHours(0, 0, 0, 0);
+	const thisMonthStartMs = startOfThisMonth.getTime();
+
 	// Rolling 30-day window: the last 30 calendar days including today,
 	// i.e. from midnight 29 days before today. setDate handles DST correctly.
 	const startOfLast30Days = new Date(startOfToday);
@@ -1524,11 +1555,19 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	}
 
 	// 6. Aggregate in sorted path order with cross-file dedupe.
-	const data = emptyUsageData({ todayMs, weekStartMs, lastWeekStartMs, last30DaysStartMs, nowMs: now.getTime() });
+	const data = emptyUsageData({
+		todayMs,
+		weekStartMs,
+		lastWeekStartMs,
+		thisMonthStartMs,
+		last30DaysStartMs,
+		nowMs: now.getTime(),
+	});
 	const rawByPeriod: Record<TabName, PeriodRawData> = {
 		today: emptyPeriodRawData(),
 		thisWeek: emptyPeriodRawData(),
 		lastWeek: emptyPeriodRawData(),
+		thisMonth: emptyPeriodRawData(),
 		last30Days: emptyPeriodRawData(),
 		allTime: emptyPeriodRawData(),
 	};
@@ -1595,6 +1634,7 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 			todayMs,
 			weekStartMs,
 			lastWeekStartMs,
+			thisMonthStartMs,
 			last30DaysStartMs,
 			rawByPeriod,
 			costByDayIdx

package/graph.ts

@@ -118,6 +118,8 @@ function domainFor(period: TabName, bounds: PeriodBounds, hourly: Map<number, Ma
 			return { startMs: bounds.weekStartMs, endMs: bounds.nowMs };
 		case "lastWeek":
 			return { startMs: bounds.lastWeekStartMs, endMs: bounds.weekStartMs };
+		case "thisMonth":
+			return { startMs: bounds.thisMonthStartMs, endMs: bounds.nowMs };
 		case "last30Days":
 			return { startMs: bounds.last30DaysStartMs, endMs: bounds.nowMs };
 		case "allTime": {

package/index.ts

@@ -2,7 +2,7 @@
  * /usage - Usage statistics dashboard
  *
  * Shows an inline view with usage stats grouped by provider.
- * - Tab cycles: Today → This Week → Last Week → All Time
+ * - Tab cycles: Today → This Week → Last Week → This Month → All Time
  * - Arrow keys navigate providers
  * - Enter expands/collapses to show models
  *
@@ -273,6 +273,7 @@ const TAB_LABELS: Record<TabName, string> = {
 	today: "Today",
 	thisWeek: "This Week",
 	lastWeek: "Last Week",
+	thisMonth: "This Month",
 	last30Days: "Last 30 Days",
 	allTime: "All Time",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",
@@ -25,7 +25,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.3",
-    "@earendil-works/pi-tui": "^0.80.3"
+    "@earendil-works/pi-coding-agent": "0.87.0",
+    "@earendil-works/pi-tui": "0.87.0"
   }
 }