@hank-warren/pi-stats 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @hank-warren/pi-stats
 
+## 0.5.0
+
+### Minor Changes
+
+- Count Pi `usage` session entries and de-duplicate them against mirrored extension sidecars (#42).
+
+  Pi 0.86 added `SessionManager.appendUsage()`, which records model calls made outside the conversation, such as cache warming, as `type: "usage"` session entries. `/stats` now counts them in every total and shows them as `provider/model (<kind>)` rows. Unknown kinds are counted like any other usage.
+
+  An extension that also mirrors such a call into a usage sidecar for older pi-stats versions gives the sidecar the id `<sessionId>:<usageEntryId>`. That call is counted once, from the session entry. Sidecars without a matching entry, and entries without a matching sidecar, are still counted. The stats cache version is bumped, so existing caches are rescanned once.
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -39,7 +39,7 @@ Every tab is responsive: as the terminal narrows, lower-priority columns move to
 
 ## What is counted
 
-Pi writes usage to assistant messages, usage-bearing tool results, compactions, and branch summaries. `pi-stats` recursively reads valid Pi session files and counts every recorded model call, including compacted and abandoned branches. Copied fork history is fingerprinted and counted once.
+Pi writes usage to assistant messages, usage-bearing tool results, compactions, branch summaries, and `usage` entries (Pi 0.86+, for model calls outside the conversation such as cache warming). `pi-stats` recursively reads valid Pi session files and counts every recorded model call, including compacted and abandoned branches. Copied fork history is fingerprinted and counted once.
 
 Tool calls are counted separately from tokens, because most of them record no model usage. Every tool result in a session is tallied by name, along with whether it reported an error. Provider tool-call ids are reused verbatim when a session is forked, so they double as the de-duplication key and a forked branch never inflates the counts. Namespaced names such as `functions.bash` are ranked under their base name.
 
@@ -53,7 +53,9 @@ Some extensions call a model outside the agent loop, so their usage never reache
 {"v":1,"id":"3f2b…","ts":"2026-08-11T22:41:03.118Z","source":"auto-permissions","label":"guardian","provider":"anthropic","model":"claude-fable-5","usage":{"input":812,"output":96,"cacheRead":18442,"cacheWrite":0,"reasoning":48,"cost":0.0121}}
 ```
 
-Records are de-duplicated by `id`, counted in every total, and shown as their own `provider/model (label)` row so the overhead stays visible. They never create sessions, so session counts, streaks, and session spans are unaffected. `@hank-warren/pi-auto-permissions` writes one for guardian reviews; set `PI_STATS_DISABLE_USAGE_SIDECARS=1` to ignore all of them.
+Records are de-duplicated by `id`, counted in every total, and shown as their own `provider/model (label)` row so the overhead stays visible. Session `usage` entries appear the same way as `provider/model (kind)`.
+
+An extension that records a call both ways — a session `usage` entry for Pi 0.86+ and a sidecar for older `pi-stats` versions — gives the sidecar the id `<sessionId>:<usageEntryId>` (the session header id and the usage entry id). That call is counted once, from the session entry; sidecars without a matching entry, and entries without a matching sidecar, are each counted normally. They never create sessions, so session counts, streaks, and session spans are unaffected. `@hank-warren/pi-auto-permissions` writes one for guardian reviews; set `PI_STATS_DISABLE_USAGE_SIDECARS=1` to ignore all of them.
 
 The standard Pi session root, the current external session directory, `PI_CODING_AGENT_SESSION_DIR`, and a configured `subagents.defaultSessionDir` are discovered automatically. Add unusual one-off roots with the platform-delimited `PI_STATS_SESSION_DIRS` environment variable.
 

package/cache.ts

@@ -6,7 +6,7 @@ import { makeIndex, parseSessionText, parseUsageSidecar } from "./stats.ts";
 import type { CachedFileRecord, ScanDiagnostics, SessionRecord, StatsCacheFile, StatsIndex, UsageRecord } from "./types.ts";
 
 /** Bumped to 3 when tool-call records were added; older caches lack them and must be reparsed. */
-const CACHE_VERSION = 3 as const;
+const CACHE_VERSION = 4 as const;
 const SKIP_DIRECTORIES = new Set(["subagent-artifacts"]);
 /** Extensions record out-of-transcript model usage in <agentDir>/<extension>/usage.jsonl. */
 const USAGE_SIDECAR_NAMES = new Set(["usage.jsonl", "usage.jsonl.1"]);
@@ -143,7 +143,12 @@ function validUsageRecord(value: unknown): value is UsageRecord {
 		typeof record.fingerprint === "string" &&
 		validNumber(record.timestamp) &&
 		typeof record.model === "string" &&
-		(record.kind === "assistant" || record.kind === "tool" || record.kind === "summary" || record.kind === "sidecar") &&
+		(record.kind === "assistant" ||
+			record.kind === "tool" ||
+			record.kind === "summary" ||
+			record.kind === "usage" ||
+			record.kind === "sidecar") &&
+		(record.sharedId === undefined || typeof record.sharedId === "string") &&
 		Boolean(usage) &&
 		validNumber(usage?.input) &&
 		validNumber(usage?.output) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
   "type": "module",
   "keywords": [

package/stats.ts

@@ -203,6 +203,22 @@ function normalizeEntry(
 			kind: "summary",
 		};
 	}
+
+	// Pi >=0.86 appendUsage(): model usage outside the conversation, such as cache warming.
+	if (entry.type === "usage") {
+		const usage = normalizeUsage(entry.usage);
+		if (!usage) return undefined;
+		const usageKind = typeof entry.kind === "string" && entry.kind.length > 0 ? entry.kind : "usage";
+		const model = `${modelName(entry.provider, entry.model)} (${usageKind})`;
+		return {
+			fingerprint: fingerprint([id, entry.timestamp, "usage", model, usage]),
+			timestamp: entryTimestamp,
+			model,
+			usage,
+			kind: "usage",
+			...(typeof entry.id === "string" && entry.id.length > 0 ? { sharedId: `${sessionId}:${entry.id}` } : {}),
+		};
+	}
 	return undefined;
 }
 
@@ -342,6 +358,7 @@ export function parseUsageSidecar(filePath: string, text: string): { records: Us
 			usage,
 			kind: "sidecar",
 			toolName: source,
+			...(typeof entry.id === "string" && entry.id.length > 0 ? { sharedId: entry.id } : {}),
 		});
 	}
 	return { records, malformedLines };
@@ -391,9 +408,12 @@ function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecor
 export function deduplicateUsage(sessions: readonly SessionRecord[], sidecar: readonly UsageRecord[] = []): UsageRecord[] {
 	const sessionPaths = new Set(sessions.map((session) => resolve(session.path)));
 	const seen = new Set<string>();
+	const sharedIds = new Set<string>();
 	const result: UsageRecord[] = [];
 	for (const session of sessions) {
 		for (const record of session.usage) {
+			// Registered before the fork check so a copied entry still claims the original's sidecar.
+			if (record.sharedId) sharedIds.add(record.sharedId);
 			if (hasPersistedSubagentChild(record, sessionPaths)) continue;
 			if (seen.has(record.fingerprint)) continue;
 			seen.add(record.fingerprint);
@@ -401,6 +421,7 @@ export function deduplicateUsage(sessions: readonly SessionRecord[], sidecar: re
 		}
 	}
 	for (const record of sidecar) {
+		if (record.sharedId && sharedIds.has(record.sharedId)) continue;
 		if (seen.has(record.fingerprint)) continue;
 		seen.add(record.fingerprint);
 		result.push(record);

package/types.ts

@@ -15,8 +15,10 @@ export interface UsageRecord {
 	timestamp: number;
 	model: string;
 	usage: UsageTotals;
-	kind: "assistant" | "tool" | "summary" | "sidecar";
+	kind: "assistant" | "tool" | "summary" | "usage" | "sidecar";
 	toolName?: string;
+	/** `<sessionId>:<usageEntryId>` on usage entries, the record id on sidecars; a match counts the call once. */
+	sharedId?: string;
 	childSessionFiles?: string[];
 }
 
@@ -55,7 +57,7 @@ export interface CachedFileRecord {
 }
 
 export interface StatsCacheFile {
-	version: 3;
+	version: 4;
 	files: Record<string, CachedFileRecord>;
 }