@hank-warren/pi-stats 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @hank-warren/pi-stats
+
+## 0.3.3
+
+### Patch Changes
+
+- cf12677: ship CHANGELOG.md in the published tarball
+- 596888b: keep extension sidecar usage when the current session is not yet on disk
+
+## 0.3.2
+
+### Patch Changes
+
+- 187e12c: Roll usage-free placeholder models into `Tools/summaries` and let the activity heatmap use the full terminal width.
+
+  Pi records placeholder assistant turns whose model is the literal `<synthetic>` (a missing model normalizes to `unknown`). With no tokens and no cost they produced their own empty model row; they are now attributed to the existing unattributed bucket, while a placeholder that did record spend keeps its own row.
+
+  The heatmap previously shrank to the recorded history, leaving most of a wide terminal blank. It now claims the available width up to a full year, drawing weeks before the first recorded session as empty cells that fill in over time.
+
+## 0.3.1
+
+### Patch Changes
+
+- 67abcf5: expand the readme with try-it install, a configuration table, and troubleshooting

package/README.md

@@ -27,7 +27,7 @@ Run `/stats` in interactive mode. The dashboard temporarily replaces the editor
 - `u`: force a full rescan and rebuild the session index
 - `Escape`: close
 
-The Overview compares current-session, selected-range, and all-time usage in one aligned table covering input, output, cache read, cache write, reasoning, cache-hit rate, and recorded cost, followed by a month-labelled activity heatmap and all-time session, streak, and favourite-model highlights. Reasoning is shown as a subset of output and is never added to the total twice.
+The Overview compares current-session, selected-range, and all-time usage in one aligned table covering input, output, cache read, cache write, reasoning, cache-hit rate, and recorded cost, followed by a month-labelled activity heatmap and all-time session, streak, and favourite-model highlights. The heatmap always spans the width the terminal offers, up to a full year; weeks before your first recorded session render as empty cells and fill in as history accumulates. Reasoning is shown as a subset of output and is never added to the total twice.
 
 The Models tab ranks models for the selected range with share bars and a totals row that reconciles with the range total. It attributes assistant usage to the provider response model and keeps otherwise unattributed nested usage in `Tools/summaries`.
 
@@ -70,7 +70,7 @@ Each variable is matched exactly: `PI_STATS_DISABLE_USAGE_SIDECARS=true` does no
 
 **Guardian or other extension usage is missing.** Sidecar reading is skipped entirely when `PI_STATS_DISABLE_USAGE_SIDECARS=1`. Otherwise confirm the writing extension is enabled and that `<agent dir>/<extension>/usage.jsonl` exists; sidecars are only discovered one level below the agent directory.
 
-**A model shows under `Tools/summaries` instead of its own row.** That bucket holds nested usage that carries no attributable response model, such as some compaction and branch-summary records. It is counted in the totals either way.
+**A model shows under `Tools/summaries` instead of its own row.** That bucket holds nested usage that carries no attributable response model, such as some compaction and branch-summary records. It also absorbs Pi's own placeholder turns — assistant messages whose model is `<synthetic>` or missing — but only when they recorded no tokens and no cost; a placeholder that was actually billed keeps its own row so the spend stays visible. Everything in the bucket is counted in the totals either way.
 
 **Costs read `$0.00` or look wrong.** Displayed cost is whatever Pi already recorded in the session; `pi-stats` performs no pricing lookup and contacts no billing API. Providers used through a subscription or proxy commonly record zero cost.
 

package/index.ts

@@ -4,7 +4,8 @@ import { buildSnapshot, makeIndex, usageFromEntries } from "./stats.ts";
 import type { SessionRecord, StatsIndex, StatsRange } from "./types.ts";
 import { StatsWidget } from "./widget.ts";
 
-function includeInMemorySession(index: StatsIndex, ctx: ExtensionCommandContext): StatsIndex {
+/** Exported for tests: the rebuild must keep sidecar usage, which no session record carries. */
+export function includeInMemorySession(index: StatsIndex, ctx: ExtensionCommandContext): StatsIndex {
 	const sessionId = ctx.sessionManager.getSessionId();
 	if (index.sessions.some((session) => session.sessionId === sessionId)) return index;
 	const entries = ctx.sessionManager.getEntries();
@@ -25,7 +26,7 @@ function includeInMemorySession(index: StatsIndex, ctx: ExtensionCommandContext)
 		source: "main",
 		usage,
 	};
-	return makeIndex([...index.sessions, session], index.diagnostics);
+	return makeIndex([...index.sessions, session], index.diagnostics, index.usage.filter((record) => record.kind === "sidecar"));
 }
 
 export default function statsExtension(pi: ExtensionAPI): void {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,8 @@
     "types.ts",
     "widget.ts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/stats.ts

@@ -14,6 +14,9 @@ import {
 	type UsageTotals,
 } from "./types.ts";
 
+/** Bucket for usage that carries no attributable response model. */
+const SUMMARY_MODEL = "Tools/summaries";
+
 interface ParseResult {
 	ignored: boolean;
 	malformedLines: number;
@@ -73,6 +76,29 @@ function detailsModel(details: unknown): string | undefined {
 	return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
 }
 
+/**
+ * Pi records placeholder assistant messages for turns it generates itself; today they
+ * carry the literal model `<synthetic>`, and a missing model normalizes to `unknown`.
+ * Angle brackets are never valid in a provider model id, so they are a safe marker.
+ */
+function placeholderModel(model: string): boolean {
+	const bare = model.slice(model.lastIndexOf("/") + 1);
+	return bare === "unknown" || (bare.startsWith("<") && bare.endsWith(">"));
+}
+
+function unmetered(usage: UsageTotals): boolean {
+	return totalTokens(usage) === 0 && usage.reasoning === 0 && usage.cost === 0;
+}
+
+/**
+ * Placeholder models that recorded no tokens and no cost would otherwise get their own
+ * zero-value model row. Roll them into the unattributed bucket so the call is still
+ * counted without inventing a model that was never billed.
+ */
+function attributedModel(model: string, usage: UsageTotals): string {
+	return placeholderModel(model) && unmetered(usage) ? SUMMARY_MODEL : model;
+}
+
 function nestedSubagentUsage(details: unknown): UsageTotals | undefined {
 	const record = object(details);
 	if (!record) return undefined;
@@ -135,7 +161,7 @@ function normalizeEntry(
 		if (role === "assistant") {
 			const usage = normalizeUsage(message.usage);
 			if (!usage) return undefined;
-			const model = modelName(message.provider, message.responseModel ?? message.model);
+			const model = attributedModel(modelName(message.provider, message.responseModel ?? message.model), usage);
 			return {
 				fingerprint: fingerprint([id, entry.timestamp, "assistant", model, usage]),
 				timestamp: timestamp(message.timestamp, entryTimestamp),
@@ -148,7 +174,7 @@ function normalizeEntry(
 			const toolName = typeof message.toolName === "string" ? message.toolName : "tool";
 			const usage = normalizeUsage(message.usage) ?? (toolName === "subagent" ? nestedSubagentUsage(message.details) : undefined);
 			if (!usage) return undefined;
-			const model = detailsModel(message.details) ?? "Tools/summaries";
+			const model = attributedModel(detailsModel(message.details) ?? SUMMARY_MODEL, usage);
 			const children = toolName === "subagent" ? childSessionFiles(message.details, sessionFile) : [];
 			return {
 				fingerprint: fingerprint([id, entry.timestamp, "tool", toolName, model, usage]),
@@ -167,9 +193,9 @@ function normalizeEntry(
 		const usage = normalizeUsage(entry.usage);
 		if (!usage) return undefined;
 		return {
-			fingerprint: fingerprint([id, entry.timestamp, entry.type, "Tools/summaries", usage]),
+			fingerprint: fingerprint([id, entry.timestamp, entry.type, SUMMARY_MODEL, usage]),
 			timestamp: entryTimestamp,
-			model: "Tools/summaries",
+			model: SUMMARY_MODEL,
 			usage,
 			kind: "summary",
 		};

package/widget.ts

@@ -374,10 +374,10 @@ export class StatsWidget implements Component {
 		today.setHours(12, 0, 0, 0);
 		const end = new Date(today);
 		end.setDate(end.getDate() + (6 - ((end.getDay() + 6) % 7)));
-		const active = snapshot.days.filter((day) => day.total > 0);
-		const first = active[0] ? new Date(`${active[0].day}T12:00:00`) : today;
-		const span = Math.ceil((end.getTime() - first.getTime()) / (7 * 24 * 60 * 60 * 1000)) + 1;
-		const weeks = Math.max(HEATMAP_MIN_WEEKS, Math.min(cells, HEATMAP_MAX_WEEKS, Math.max(span, HEATMAP_MIN_WEEKS)));
+		// Always claim the width the terminal offers, up to a year. Weeks before the first
+		// recorded day render as empty cells so a short history fills the grid in over time
+		// instead of leaving most of a wide row blank.
+		const weeks = Math.max(HEATMAP_MIN_WEEKS, Math.min(cells, HEATMAP_MAX_WEEKS));
 		const start = new Date(end);
 		start.setDate(start.getDate() - weeks * 7 + 1);