@hank-warren/pi-stats 0.2.0 → 0.3.0

package/README.md

@@ -33,6 +33,16 @@ Pi writes usage to assistant messages, usage-bearing tool results, compactions,
 
 Persisted subagent files in the conventional `run-*/session.jsonl` layout are included. `pi-processes` does not create model sessions; model usage around its tool calls already belongs to the parent Pi session and therefore needs no separate integration.
 
+### Extension usage sidecars
+
+Some extensions call a model outside the agent loop, so their usage never reaches a session transcript. `pi-stats` also reads content-free usage sidecars at `<agent dir>/<extension>/usage.jsonl` (plus one rotated `usage.jsonl.1`). Each line is one call:
+
+```json
+{"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.
+
 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.
 
 ## Cache and privacy

package/cache.ts

@@ -2,11 +2,13 @@ import { randomUUID } from "node:crypto";
 import { readFile, readdir, realpath, rename, stat, writeFile, mkdir, chmod, unlink } from "node:fs/promises";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { makeIndex, parseSessionText } from "./stats.ts";
+import { makeIndex, parseSessionText, parseUsageSidecar } from "./stats.ts";
 import type { CachedFileRecord, ScanDiagnostics, SessionRecord, StatsCacheFile, StatsIndex, UsageRecord } from "./types.ts";
 
-const CACHE_VERSION = 1 as const;
+const CACHE_VERSION = 2 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"]);
 
 export interface ScanOptions {
 	agentDir: string;
@@ -93,6 +95,37 @@ async function discoverJsonlFiles(roots: readonly string[], signal?: AbortSignal
 	return [...found].sort();
 }
 
+/** One level below the agent directory only; sidecars are a flat, documented convention. */
+async function discoverUsageSidecars(agentDir: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string[]> {
+	if (env.PI_STATS_DISABLE_USAGE_SIDECARS === "1") return [];
+	const found = new Set<string>();
+	let directories;
+	try {
+		directories = await readdir(agentDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	for (const directory of directories) {
+		signal?.throwIfAborted();
+		if (!directory.isDirectory() || directory.isSymbolicLink()) continue;
+		let entries;
+		try {
+			entries = await readdir(join(agentDir, directory.name), { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isFile() || entry.isSymbolicLink() || !USAGE_SIDECAR_NAMES.has(entry.name)) continue;
+			try {
+				found.add(await realpath(join(agentDir, directory.name, entry.name)));
+			} catch {
+				// File disappeared between listing and resolution.
+			}
+		}
+	}
+	return [...found].sort();
+}
+
 function emptyCache(): StatsCacheFile {
 	return { version: CACHE_VERSION, files: {} };
 }
@@ -109,7 +142,7 @@ 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 === "assistant" || record.kind === "tool" || record.kind === "summary" || record.kind === "sidecar") &&
 		Boolean(usage) &&
 		validNumber(usage?.input) &&
 		validNumber(usage?.output) &&
@@ -149,7 +182,8 @@ function validCache(value: unknown): value is StatsCacheFile {
 			validNumber(record.mtimeMs) &&
 			validNumber(record.malformedLines) &&
 			(record.ignored === undefined || record.ignored === true) &&
-			(record.session === undefined || validSessionRecord(record.session))
+			(record.session === undefined || validSessionRecord(record.session)) &&
+			(record.sidecar === undefined || (Array.isArray(record.sidecar) && record.sidecar.every(validUsageRecord)))
 		);
 	});
 }
@@ -207,7 +241,10 @@ export function statsCachePath(agentDir: string): string {
 
 export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 	const roots = await resolveSessionRoots(options);
-	const files = await discoverJsonlFiles(roots, options.signal);
+	const sessionFiles = await discoverJsonlFiles(roots, options.signal);
+	const sidecarFiles = await discoverUsageSidecars(options.agentDir, options.env ?? process.env, options.signal);
+	const sidecars = new Set(sidecarFiles);
+	const files = [...sessionFiles.filter((file) => !sidecars.has(file)), ...sidecarFiles];
 	const cachePath = statsCachePath(options.agentDir);
 	await cleanupStaleTemporaryFiles(cachePath);
 	const loaded = options.force ? { cache: emptyCache(), valid: false } : await loadCache(cachePath);
@@ -231,6 +268,16 @@ export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 			if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
 				next.files[file] = previous!;
 				diagnostics.reusedFiles++;
+			} else if (sidecars.has(file)) {
+				const parsed = parseUsageSidecar(file, await readFile(file, "utf8"));
+				next.files[file] = {
+					size: metadata.size,
+					mtimeMs: metadata.mtimeMs,
+					sidecar: parsed.records,
+					malformedLines: parsed.malformedLines,
+				};
+				diagnostics.parsedFiles++;
+				changed = true;
 			} else {
 				const parsed = parseSessionText(file, await readFile(file, "utf8"));
 				next.files[file] = {
@@ -260,7 +307,8 @@ export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 		});
 	}
 	const sessions = Object.values(next.files).flatMap((record) => (record.session ? [record.session] : []));
-	return makeIndex(sessions, diagnostics);
+	const sidecarUsage = Object.values(next.files).flatMap((record) => record.sidecar ?? []);
+	return makeIndex(sessions, diagnostics, sidecarUsage);
 }
 
 export function isExternalSessionDirectory(activeSessionDir: string, agentDir: string): boolean {

package/package.json

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

package/stats.ts

@@ -238,6 +238,49 @@ export function parseSessionText(filePath: string, text: string): ParseResult {
 	};
 }
 
+/**
+ * Parse a usage sidecar: one content-free JSON record per model call made outside a Pi
+ * session transcript, such as pi-auto-permissions guardian reviews.
+ */
+export function parseUsageSidecar(filePath: string, text: string): { records: UsageRecord[]; malformedLines: number } {
+	const records: UsageRecord[] = [];
+	let malformedLines = 0;
+	const lines = text.split("\n");
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index]?.trim();
+		if (!line) continue;
+		let entry: Record<string, unknown> | undefined;
+		try {
+			entry = object(JSON.parse(line));
+		} catch {
+			malformedLines++;
+			continue;
+		}
+		if (!entry || entry.v !== 1) {
+			malformedLines++;
+			continue;
+		}
+		const usage = normalizeUsage(entry.usage);
+		if (!usage) {
+			malformedLines++;
+			continue;
+		}
+		const label = typeof entry.label === "string" && entry.label.length > 0 ? entry.label : undefined;
+		const source = typeof entry.source === "string" && entry.source.length > 0 ? entry.source : "sidecar";
+		const model = `${modelName(entry.provider, entry.model)} (${label ?? source})`;
+		const identity = typeof entry.id === "string" && entry.id.length > 0 ? entry.id : `${resolve(filePath)}:${index}`;
+		records.push({
+			fingerprint: fingerprint([identity, entry.ts, source, model, usage]),
+			timestamp: timestamp(entry.ts, 0),
+			model,
+			usage,
+			kind: "sidecar",
+			toolName: source,
+		});
+	}
+	return { records, malformedLines };
+}
+
 export function usageFromEntries(
 	sessionId: string,
 	entries: readonly unknown[],
@@ -254,7 +297,7 @@ function hasPersistedSubagentChild(record: UsageRecord, sessionPaths: ReadonlySe
 	return record.toolName === "subagent" && Boolean(record.childSessionFiles?.some((file) => sessionPaths.has(resolve(file))));
 }
 
-export function deduplicateUsage(sessions: readonly SessionRecord[]): UsageRecord[] {
+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 result: UsageRecord[] = [];
@@ -266,6 +309,11 @@ export function deduplicateUsage(sessions: readonly SessionRecord[]): UsageRecor
 			result.push(record);
 		}
 	}
+	for (const record of sidecar) {
+		if (seen.has(record.fingerprint)) continue;
+		seen.add(record.fingerprint);
+		result.push(record);
+	}
 	return result;
 }
 
@@ -400,6 +448,10 @@ export function buildSnapshot(
 	};
 }
 
-export function makeIndex(sessions: SessionRecord[], diagnostics: StatsIndex["diagnostics"]): StatsIndex {
-	return { sessions, usage: deduplicateUsage(sessions), diagnostics };
+export function makeIndex(
+	sessions: SessionRecord[],
+	diagnostics: StatsIndex["diagnostics"],
+	sidecar: UsageRecord[] = [],
+): StatsIndex {
+	return { sessions, usage: deduplicateUsage(sessions, sidecar), diagnostics };
 }

package/types.ts

@@ -15,7 +15,7 @@ export interface UsageRecord {
 	timestamp: number;
 	model: string;
 	usage: UsageTotals;
-	kind: "assistant" | "tool" | "summary";
+	kind: "assistant" | "tool" | "summary" | "sidecar";
 	toolName?: string;
 	childSessionFiles?: string[];
 }
@@ -35,11 +35,13 @@ export interface CachedFileRecord {
 	mtimeMs: number;
 	ignored?: true;
 	session?: SessionRecord;
+	/** Usage recorded by extensions whose model calls never reach a session transcript. */
+	sidecar?: UsageRecord[];
 	malformedLines: number;
 }
 
 export interface StatsCacheFile {
-	version: 1;
+	version: 2;
 	files: Record<string, CachedFileRecord>;
 }