@hank-warren/pi-stats 0.3.0 → 0.3.2

package/README.md

@@ -8,6 +8,12 @@ A compact, theme-aware `/stats` dashboard for [Pi](https://pi.dev). It totals th
 pi install npm:@hank-warren/pi-stats
 ```
 
+Try it for a single run without installing:
+
+```bash
+pi -e npm:@hank-warren/pi-stats
+```
+
 Do not install this standalone package on a host that also installs the aggregate `hank-warren/pi-extensions` Git package; that would load the extension twice.
 
 ## Use
@@ -21,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`.
 
@@ -45,6 +51,33 @@ Records are de-duplicated by `id`, counted in every total, and shown as their ow
 
 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.
 
+## Configuration
+
+There is no config file; behavior is controlled entirely by environment variables.
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `PI_STATS_DISABLE_USAGE_SIDECARS` | unset | Set to `1` to ignore all extension usage sidecars and count only session transcripts. |
+| `PI_STATS_SESSION_DIRS` | unset | Extra session roots to scan, joined by the platform path delimiter (`:` on Unix, `;` on Windows). Added to the automatically discovered roots. |
+| `PI_CODING_AGENT_SESSION_DIR` | unset | Standard Pi variable; the directory it names is picked up as a session root. |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Standard Pi variable; determines where the cache and sidecars are read from. |
+
+Each variable is matched exactly: `PI_STATS_DISABLE_USAGE_SIDECARS=true` does nothing, only `=1` disables sidecars.
+
+## Troubleshooting
+
+**Totals look too low, or a session is missing.** Press `u` in the dashboard to force a full rescan and rebuild the index; the cache keys off file stat identity, so a session restored from backup with older timestamps can otherwise be skipped. If the sessions live outside the standard root, add their directory to `PI_STATS_SESSION_DIRS`.
+
+**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 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.
+
+**The dashboard looks cramped.** Columns collapse onto a labelled continuation line as the terminal narrows. Widen the terminal to restore the single-line layout, or press `e` to switch to compact totals.
+
+**Reset everything.** Delete `~/.pi/agent/pi-stats/cache.json` (path follows `PI_CODING_AGENT_DIR`). It is a disposable index and the next `/stats` run rebuilds it from the sessions.
+
 ## Cache and privacy
 
 Sessions remain authoritative. For fast repeat opens, the extension stores one disposable index:

package/package.json

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

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