@nredd/pi-session-kit 0.0.0-stage → 0.3.0

package/docs/stats-snapshots.md

@@ -0,0 +1,122 @@
+# Offline stats and portable snapshots
+
+Build the committed `dist/pi-stats-export.mjs` with `npm ci && npm run build:stats-export`.
+The exact esbuild version and dependencies are locked; tests assert byte-identical rebuilds.
+Copy only that file. Runtime is Node 22+ with builtins only, no Pi install, extension, private
+repository, package install, auth or network access.
+
+```
+node ARTIFACT export --agent-dir DIR --output OUT [--sessions-dir ROOT]
+node ARTIFACT import --agent-dir DIR --input REPO
+```
+
+`--agent-dir` defaults to `PI_CODING_AGENT_DIR`, then `~/.pi/agent`. The session root defaults to
+`PI_CODING_AGENT_SESSION_DIR`, then `DIR/sessions`; `--sessions-dir` takes precedence. History
+already cached under former roots is retained, even after files disappear. Paths are resolved
+locally and never exported. Run export before fetch/commit/push, then import the updated data
+checkout. Git, locking concurrent sync runs, retrying pushes and network deadlines belong to the
+sync helper, not this data-only artifact.
+
+CLI results:
+
+- Export: `{ "machineId": "<UUID>", "snapshotDir": "<OUT>/machines/<UUID>" }` on stdout.
+- Import: `{ "imported": N, "retained": N, "problems": [], "importedAt": MS }` on stdout.
+- Exactly one JSON object is emitted. Diagnostics go to stderr. Invalid commands, malformed local
+  scans, unwritable caches and publication failures exit nonzero. Partial/corrupt imports emit
+  a JSON result and exit nonzero, retaining every failed machine's last-good snapshot.
+- A failed export never replaces the previous manifest. Its validated immutable shards may remain
+  unpublished. Export writes only its own machine directory; it never edits another machine.
+
+Installation state, never synced:
+
+- `DIR/pi-session-kit/machine.json`: persistent UUID v4 and label, created exclusively and
+  atomically on first use. Default label is `Pi machine`, not the hostname. A corrupt identity
+  fails rather than silently enrolling another machine. Copying an entire agent dir also copies
+  its installation identity: remove `machine.json` on a genuinely new installation before export.
+- `DIR/pi-session-kit/stats-cache.json`: local parser cache v2, including file paths and compact
+  usage tuples. Version 1 entries for deleted files stay intact; existing files reparse even if
+  their mtime/size match. Strong identities are not invented for inaccessible legacy files.
+- `DIR/pi-session-kit/stats-global.json`: one atomically replaced document containing validated
+  last-good machine snapshots, last successful import time and coverage problems. Imports do not
+  mutate local usage or installation identity. A wholly failed import does not advance the sync
+  time; a partial import records valid updates and marks coverage incomplete.
+
+Snapshot version 1:
+
+```
+machines/<UUID>/manifest.json
+machines/<UUID>/<YYYY-MM>-<sha256>.json
+```
+
+Manifest exact keys:
+
+- `version`: `1`.
+- `machineId`: persistent UUID v4, matching its directory.
+- `label`: installation label, maximum 1024 characters. Not a session name.
+- `exportedAt`: positive UTC Unix milliseconds.
+- `shards`: unique month references, each exactly `{month, file, sha256, bytes}`. `file` MUST
+  equal `<month>-<sha256>.json`. No absolute paths, traversal or arbitrary filenames.
+
+Shard exact keys: `{version, machineId, month, events, sessions}`. All shard JSON is canonical
+`JSON.stringify` output (no indentation/newline), bounded to 128 MiB per file. Manifest hashes
+cover exact UTF-8 shard bytes. Immutable content-addressed shards are published first, manifest
+last; unreferenced old shard generations are deliberately retained and ignored. No cleanup races
+with readers. Each manifest references exactly one shard per month.
+
+Event exact keys:
+
+- `id`: SHA-256 event fingerprint.
+- `entryId`: SHA-256 of `entry:<preserved assistant entry ID>`, or `null` for legacy records.
+- `sessionId`: opaque session ID.
+- `ms`: original positive UTC Unix milliseconds, in the shard's UTC month.
+- `provider`, `model`: raw physical attribution, each nonempty and at most 1024 characters.
+- `input`, `output`, `cacheRead`, `cacheWrite`: nonnegative safe integers, not all zero.
+- `cost`: finite nonnegative recorded notional cost.
+
+The identified fingerprint is SHA-256 of the JSON array
+`[entryId, ms, provider, model, input, output, cacheRead, cacheWrite]`.
+Notional price changes do not create new events. Different entry IDs survive equal usage. Copied entries across forks/machines count once. Legacy
+fingerprinting and matching use `[provider, model, ms, input, output, cacheRead, cacheWrite]`,
+intentionally without cost to preserve the old tuple rule; identified counterparts supersede
+legacy duplicates.
+
+Session exact keys: `{id, startMs, endMs, child}`. Header IDs hash as `session:<header ID>`;
+unidentified legacy sessions use a local path hash and therefore cannot always be matched across
+machines. Session metadata is independent of event dedup, lives in the start timestamp's UTC
+month, and merges time bounds by ID through the same helper for local and imported histories.
+Children retain usage but do not contribute to session count.
+Only sessions owning a retained event count. The oldest session owns copied events, independent
+of machine read order. Every exported event references session metadata.
+
+No message content, tool arguments/results, paths, session names, environment, credentials or
+source objects are exported. Explicit projections, not object spreads, enforce the allowlist.
+Raw attribution is retained to avoid display-sanitization collisions. Schema validators reject
+unknown fields, unsupported versions, duplicate IDs, invalid counters/time/months, excluded test
+providers, identity/digest/byte-size mismatches, symlink files and missing session metadata.
+
+Import validates a whole machine before replacement, retaining last-good data for bad, missing
+or older snapshots. Other valid machines still advance. Only the final validated global document
+is atomically renamed, so `/stats` sees either the old or new complete cache, never a mixed import.
+Producer updates are invisible until the producer exports AND the viewer imports. Coverage counts
+known machines, not undiscovered installations; it is not proof that every machine has synced.
+
+`/stats` freshly scans local sessions and combines them with this cache without network access.
+Its UI labels cached coverage, successful import time, local-only/never-synced state and incomplete
+coverage. Future calls are ignored in display totals, not removed from durable history. Statistics
+are not subscription quota measurements or router inputs.
+
+Harness API:
+
+- `src/stats/library.ts` is a Pi-independent barrel for parser, aggregation and snapshot APIs.
+- `parseSession`, `flatten`, `dedupCalls`, `hourlySeries`, `makeSnapshot`, `validateManifest`,
+  `validateShard`, `validateSnapshot`, `exportStats`, `importStats`, `loadCombined`, `coverageLabel`.
+- `hourlySeries(calls, "5h" | "24h", now, keyOf?)` is deterministic, zero-filled, filters exact
+  rolling boundaries and labels partial edges. UTC buckets keep repeated DST hours separate;
+  viewer-local labels carry UTC offsets, including fractional-offset zones.
+
+Limits: legacy no-ID copies can only use tuple dedup, legacy session metadata without header IDs
+cannot reliably match across machines, and concurrent sync workflows must serialize writes to
+one agent directory. The combined global cache is bounded to 128 MiB; a larger import fails
+without replacing last-good data. There is no automatic discovery/network refresh or daemon. Reinitializing
+both the local parser cache and source history permanently loses that machine's local history;
+keep these installation files out of synced snapshots but do not routinely delete them.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "publishConfig": {"access": "public"},
+  "description": "Session-scoped pi tools and commands, offline cross-machine usage stats and a portable privacy-only stats CLI. No daemon.",
+  "author": "nredd",
+  "license": "MIT",
+  "type": "module",
+  "files": ["src", "dist/pi-stats-export.mjs", "docs/stats-snapshots.md", "LICENSE", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nredd/pi-harness.git",
+    "directory": "packages/session-kit"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "lint": "biome check src/ test/",
+    "format": "biome check --write src/ test/",
+    "typecheck": "tsc --noEmit",
+    "build:stats-export": "esbuild src/stats/cli.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/pi-stats-export.mjs",
+    "test": "npm run build:stats-export && vitest run",
+    "check": "npm run lint && npm run typecheck && npm run test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@types/node": "26.6.5",
+    "esbuild": "0.28.2",
+    "typebox": "1.3.36",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/child.ts

@@ -0,0 +1,79 @@
+/**
+ * Subagent child-session detection.
+ *
+ * `pi-subagents` runs children in-process and loads extensions into them, but its own child
+ * marker is a private `AsyncLocalStorage`, unreachable from another package. It names every child
+ * session `<agent type>#<first 8 chars of the agent id>` before `session_start` fires, so that
+ * name bootstraps a session-bound custom entry so renaming and reloading cannot lose identity.
+ * TODO: replace the name heuristic if `pi-subagents` ever exports a shared marker.
+ */
+
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+
+const CHILD_NAME = /#[0-9a-f]{8}$/;
+export const CHILD_ENTRY = "session-kit:child";
+
+const identities = new WeakMap<object, { child: boolean }>();
+
+/**
+ * Register once, at the beginning of a module factory, before its session rebuild hooks.
+ * Runtime APIs are unbound during factory loading; inspect only the active branch on startup.
+ * Include the session id because forks/fresh Plan sessions can inherit a parent's entries.
+ */
+export function registerChildIdentity(pi: ExtensionAPI): void {
+	if (identities.has(pi)) return;
+	const identity = { child: false };
+	identities.set(pi, identity);
+	pi.on("session_start", (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		const marked = ctx.sessionManager.getBranch().some((entry) => {
+			if (entry.type !== "custom" || entry.customType !== CHILD_ENTRY) return false;
+			const data = entry.data as { version?: unknown; sessionId?: unknown } | null;
+			return data?.version === 1 && data.sessionId === sessionId;
+		});
+		identity.child = marked || isChildSessionName(pi.getSessionName());
+		if (identity.child && !marked) pi.appendEntry(CHILD_ENTRY, { version: 1, sessionId });
+	});
+	pi.on("session_shutdown", () => {
+		identity.child = false;
+	});
+}
+
+export function isChildSessionName(name: string | undefined): boolean {
+	return name !== undefined && CHILD_NAME.test(name);
+}
+
+export function isChildSession(pi: Pick<ExtensionAPI, "getSessionName">): boolean {
+	return identities.get(pi)?.child === true || isChildSessionName(pi.getSessionName());
+}
+
+/**
+ * Withdraw a parent-only capability at child binding, not merely from the active set.
+ *
+ * Child scoping reactivates registered tools after `session_start`; deferred promotion can
+ * do so again later. Pi's public `hidden` exposure prevents both schema activation and nested
+ * execution. Keep call-time guards too, including after a child renames its session.
+ */
+export function registerParentTool<TParams extends TSchema, TDetails, TState>(
+	pi: ExtensionAPI,
+	tool: ToolDefinition<TParams, TDetails, TState>,
+): void {
+	registerChildIdentity(pi);
+	const reason = `${tool.name} is not available in subagents`;
+	const guarded: ToolDefinition<TParams, TDetails, TState> = {
+		...tool,
+		async execute(...args) {
+			if (isChildSession(pi)) throw new Error(reason);
+			return tool.execute(...args);
+		},
+	};
+	pi.registerTool(guarded);
+	pi.on("session_start", () => {
+		pi.registerTool(isChildSession(pi) ? { ...guarded, exposure: "hidden" } : guarded);
+	});
+	pi.on("tool_call", (event) => {
+		if (event.toolName === tool.name && isChildSession(pi)) return { block: true, reason };
+		return undefined;
+	});
+}

package/src/config.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-feature switches for pi-session-kit, read from `~/.pi/agent/pi-session-kit.json`.
+ *
+ * Every feature defaults to on. A missing or malformed file yields the defaults; a malformed file
+ * is reported on stderr once so a typo never silently disables the kit.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const FEATURES = ["titles", "rules", "goal", "loop", "monitor", "diff", "stats"] as const;
+export type Feature = (typeof FEATURES)[number];
+
+export interface KitConfig {
+	features: Record<Feature, boolean>;
+	/** Overrides the auto-title model, as `provider/id`. */
+	titleModel?: string;
+}
+
+export function configPath(agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent")): string {
+	return join(agentDir, "pi-session-kit.json");
+}
+
+export function defaultConfig(): KitConfig {
+	return { features: Object.fromEntries(FEATURES.map((f) => [f, true])) as Record<Feature, boolean> };
+}
+
+/** Parse a config document, ignoring unknown keys and wrong-typed values. */
+export function parseConfig(raw: unknown): KitConfig {
+	const config = defaultConfig();
+	if (typeof raw !== "object" || raw === null) return config;
+	const doc = raw as Record<string, unknown>;
+	for (const feature of FEATURES) {
+		const section = doc[feature];
+		if (typeof section === "object" && section !== null) {
+			const enabled = (section as Record<string, unknown>).enabled;
+			if (typeof enabled === "boolean") config.features[feature] = enabled;
+		}
+	}
+	const titles = doc.titles;
+	if (typeof titles === "object" && titles !== null) {
+		const model = (titles as Record<string, unknown>).model;
+		if (typeof model === "string" && model.includes("/")) config.titleModel = model;
+	}
+	return config;
+}
+
+export function loadConfig(path = configPath()): KitConfig {
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return defaultConfig();
+		console.error(`pi-session-kit: cannot read ${path}: ${(error as Error).message}`);
+		return defaultConfig();
+	}
+	try {
+		return parseConfig(JSON.parse(text));
+	} catch (error) {
+		console.error(`pi-session-kit: ${path} is not valid JSON (${(error as Error).message}); using defaults`);
+		return defaultConfig();
+	}
+}

package/src/diff/component.ts

@@ -0,0 +1,214 @@
+/** The `/diff` overlay: file list on the left, scrollable themed patch on the right. Read-only. */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { classifyLines, type DiffFile, type FileStatus, type LineKind } from "./parse.ts";
+import {
+	clamp,
+	clampScroll,
+	fitCols,
+	fitPathLeft,
+	layout,
+	listTop,
+	maxScroll,
+	pageSize,
+	sanitize,
+	window,
+} from "./view.ts";
+
+type ThemeLike = Pick<Theme, "fg" | "bg" | "bold">;
+
+export interface DiffViewOptions {
+	files: DiffFile[];
+	label: string;
+	theme: ThemeLike;
+	/** Current terminal height. */
+	rows: () => number;
+	requestRender: () => void;
+	onClose: () => void;
+	notices?: string[];
+}
+
+const STATUS_LETTER: Record<FileStatus, string> = {
+	modified: "M",
+	added: "A",
+	deleted: "D",
+	renamed: "R",
+	copied: "C",
+	binary: "B",
+	mode: "T",
+	untracked: "?",
+};
+
+const HELP = [
+	" j/k scroll  n/p file  g/G top/bottom  PgUp/PgDn  </> pan  q close",
+	" j/k n/p g/G PgUp/PgDn q",
+	" j/k n/p q",
+	" q",
+];
+
+interface Row {
+	text: string;
+	kind: LineKind | "notice";
+}
+
+export class DiffView implements Component {
+	private selected = 0;
+	private readonly scroll: number[];
+	private hscroll = 0;
+	private listScroll = 0;
+	private bodyHeight = 1;
+	private readonly rowCache = new Map<number, { kinds: LineKind[]; plain: string[] }>();
+
+	constructor(private readonly o: DiffViewOptions) {
+		this.scroll = o.files.map(() => 0);
+	}
+
+	invalidate(): void {
+		// Nothing themed is cached: every render rebuilds colours from the live theme.
+	}
+
+	// --- state -------------------------------------------------------------------------------
+
+	get selectedIndex(): number {
+		return this.selected;
+	}
+
+	get scrollOffset(): number {
+		return this.scroll[this.selected] ?? 0;
+	}
+
+	private rowsFor(index: number): Row[] {
+		const file = this.o.files[index];
+		if (!file) return [];
+		let cached = this.rowCache.get(index);
+		if (!cached) {
+			cached = { kinds: classifyLines(file), plain: file.lines.map((l) => sanitize(l)) };
+			this.rowCache.set(index, cached);
+		}
+		const rows: Row[] = cached.plain.map((text, i) => ({ text, kind: cached?.kinds[i] ?? "context" }));
+		if (file.notice) rows.push({ text: `... ${file.notice}`, kind: "notice" });
+		return rows;
+	}
+
+	private total(): number {
+		const file = this.o.files[this.selected];
+		return file ? file.lines.length + (file.notice ? 1 : 0) : 0;
+	}
+
+	private setScroll(value: number): void {
+		this.scroll[this.selected] = clampScroll(value, this.total(), this.bodyHeight);
+	}
+
+	private selectFile(index: number): void {
+		this.selected = clamp(index, 0, Math.max(0, this.o.files.length - 1));
+		this.hscroll = 0;
+		this.setScroll(this.scrollOffset);
+	}
+
+	// --- input -------------------------------------------------------------------------------
+
+	handleInput(data: string): void {
+		const off = this.scrollOffset;
+		const page = pageSize(this.bodyHeight);
+		if (data === "q" || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.o.onClose();
+			return;
+		}
+		if (data === "j" || matchesKey(data, Key.down)) this.setScroll(off + 1);
+		else if (data === "k" || matchesKey(data, Key.up)) this.setScroll(off - 1);
+		else if (matchesKey(data, Key.pageDown) || data === " ") this.setScroll(off + page);
+		else if (matchesKey(data, Key.pageUp)) this.setScroll(off - page);
+		else if (data === "g" || matchesKey(data, Key.home)) this.setScroll(0);
+		else if (data === "G" || matchesKey(data, Key.shift("g")) || matchesKey(data, Key.end)) {
+			this.setScroll(maxScroll(this.total(), this.bodyHeight));
+		} else if (data === "n") this.selectFile(this.selected + 1);
+		else if (data === "p") this.selectFile(this.selected - 1);
+		else if (data === "l" || matchesKey(data, Key.right)) this.hscroll += 8;
+		else if (data === "h" || matchesKey(data, Key.left)) this.hscroll = Math.max(0, this.hscroll - 8);
+		else return;
+		this.o.requestRender();
+	}
+
+	// --- render ------------------------------------------------------------------------------
+
+	render(width: number): string[] {
+		const w = Math.max(1, Math.floor(width));
+		const rows = Math.max(3, Math.floor(this.o.rows()));
+		this.bodyHeight = Math.max(1, rows - 2);
+		this.setScroll(this.scrollOffset);
+		const lay = layout(w);
+		const out: string[] = [this.title(w)];
+
+		const patch = this.rowsFor(this.selected);
+		const off = this.scrollOffset;
+		this.listScroll = listTop(this.listScroll, this.selected, this.o.files.length, this.bodyHeight);
+		const sep = this.o.theme.fg("borderMuted", "│");
+
+		for (let y = 0; y < this.bodyHeight; y++) {
+			const right = this.patchCell(patch[off + y], lay.right);
+			if (lay.left === 0) {
+				out.push(right);
+				continue;
+			}
+			out.push(this.listCell(this.listScroll + y, lay.left) + sep + right);
+		}
+		out.push(this.help(w, patch.length, off));
+		return out.map((line) => truncateToWidth(line, w, ""));
+	}
+
+	private title(width: number): string {
+		const files = this.o.files;
+		const add = files.reduce((n, f) => n + f.additions, 0);
+		const del = files.reduce((n, f) => n + f.deletions, 0);
+		const t = this.o.theme;
+		const plain = ` /diff ${sanitize(this.o.label)}  ${files.length} file${files.length === 1 ? "" : "s"}  +${add} -${del}`;
+		const extra = this.o.notices?.length ? `  ! ${sanitize(this.o.notices.join("; "))}` : "";
+		return t.bold(t.fg("accent", fitCols(plain + extra, width)));
+	}
+
+	private listCell(index: number, width: number): string {
+		const file = this.o.files[index];
+		if (!file) return " ".repeat(width);
+		const t = this.o.theme;
+		const letter = STATUS_LETTER[file.status];
+		const color =
+			file.status === "added" || file.status === "untracked"
+				? "toolDiffAdded"
+				: file.status === "deleted"
+					? "toolDiffRemoved"
+					: "accent";
+		const path = fitPathLeft(sanitize(file.path), Math.max(0, width - 3));
+		if (index === this.selected) return t.bg("selectedBg", t.bold(fitCols(` ${letter} ${path}`, width)));
+		// colour only the status letter; the path stays plain
+		return fitCols(` ${t.fg(color, letter)} ${path}`, width);
+	}
+
+	private patchCell(row: Row | undefined, width: number): string {
+		if (!row) return " ".repeat(Math.max(0, width));
+		const t = this.o.theme;
+		const text = window(row.text, this.hscroll, width);
+		switch (row.kind) {
+			case "added":
+				return t.fg("toolDiffAdded", text);
+			case "removed":
+				return t.fg("toolDiffRemoved", text);
+			case "hunk":
+				return t.fg("accent", text);
+			case "meta":
+				return t.fg("muted", text);
+			case "notice":
+				return t.fg("warning", text);
+			default:
+				return t.fg("toolDiffContext", text);
+		}
+	}
+
+	private help(width: number, total: number, off: number): string {
+		const t = this.o.theme;
+		const pos = ` ${this.selected + 1}/${this.o.files.length}  ${total === 0 ? 0 : off + 1}-${Math.min(total, off + this.bodyHeight)}/${total} `;
+		const keys = HELP.find((h) => h.length + pos.length <= width) ?? "";
+		const gap = Math.max(0, width - keys.length - pos.length);
+		return t.fg("muted", fitCols(`${keys}${" ".repeat(gap)}${pos}`, width));
+	}
+}