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

package/src/stats/aggregate.ts

@@ -0,0 +1,287 @@
+/**
+ * Pure aggregation for `/stats`: date ranges, provider/model filters, per-day series and the
+ * Overview numbers. "Tokens" is all throughput, input + output + cache read + cache write,
+ * everywhere. Anthropic reports almost every prompt token as a cache read or write (its `input` is
+ * single digits per call) while Codex reports them as `input`, so anything less badly undercounts
+ * agentic usage, and cache reads are what rate limits see.
+ */
+
+import { addDays, dayKey, dayRange, daysBetween } from "./days.ts";
+import type { Call, Session } from "./load.ts";
+
+export type Range = "all" | "7d" | "30d" | "5h" | "24h";
+export const RANGES: readonly Range[] = ["all", "7d", "30d", "5h", "24h"];
+export const RANGE_LABEL: Record<Range, string> = { all: "All", "7d": "7d", "30d": "30d", "5h": "5h", "24h": "24h" };
+export const HOUR_MS = 3600000;
+export const isHourly = (range: Range): range is "5h" | "24h" => range === "5h" || range === "24h";
+export const hourlyStart = (range: "5h" | "24h", now: number): number => now - (range === "5h" ? 5 : 24) * HOUR_MS;
+
+/** `{ kind: "all" }`, one provider, or one `provider/model`. */
+export type Filter = { kind: "all" } | { kind: "provider"; provider: string } | { kind: "model"; name: string };
+
+export interface ModelTotals {
+	/** `provider/model` */
+	name: string;
+	provider: string;
+	model: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	calls: number;
+}
+
+export interface DayPoint {
+	day: string;
+	/** Tokens per series key (provider, or `provider/model`). */
+	byKey: Map<string, number>;
+	total: number;
+}
+
+export interface Overview {
+	totalTokens: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	favorite?: string;
+	sessions: number;
+	longestSessionMs: number;
+	activeDays: number;
+	rangeDays: number;
+	mostActiveDay?: string;
+	longestStreak: number;
+	currentStreak: number;
+}
+
+export const tokensOf = (c: Pick<Call, "input" | "output" | "cacheRead" | "cacheWrite">): number =>
+	c.input + c.output + c.cacheRead + c.cacheWrite;
+/** What `tokensOf` counts, shown next to every token total. */
+export const TOKENS_NOTE = "(in + out + cache)";
+export const modelName = (c: Pick<Call, "provider" | "model">): string => `${c.provider}/${c.model}`;
+
+export function matches(filter: Filter, c: Pick<Call, "provider" | "model">): boolean {
+	if (filter.kind === "all") return true;
+	if (filter.kind === "provider") return c.provider === filter.provider;
+	return modelName(c) === filter.name;
+}
+
+export function filterLabel(filter: Filter): string {
+	return filter.kind === "all" ? "All models" : filter.kind === "provider" ? filter.provider : filter.name;
+}
+
+/** First day of the range; `undefined` for all time. */
+export function rangeStart(range: Range, today: string): string | undefined {
+	if (range === "7d") return addDays(today, -6);
+	if (range === "30d") return addDays(today, -29);
+	return undefined;
+}
+
+/** Whether `ms` falls in the range ending today. Days after today (clock skew) are in no range. */
+export function inRange(range: Range, today: string, ms: number, now = Date.now()): boolean {
+	if (ms > now) return false;
+	if (isHourly(range)) return ms >= hourlyStart(range, now);
+	const day = dayKey(ms);
+	const start = rangeStart(range, today);
+	return day <= today && (start === undefined || day >= start);
+}
+
+/** All, then providers by tokens, then every model by tokens. */
+export function filterCycle(calls: readonly Call[]): Filter[] {
+	const byProvider = new Map<string, number>();
+	const byModel = new Map<string, number>();
+	for (const c of calls) {
+		byProvider.set(c.provider, (byProvider.get(c.provider) ?? 0) + tokensOf(c));
+		byModel.set(modelName(c), (byModel.get(modelName(c)) ?? 0) + tokensOf(c));
+	}
+	const desc = (m: Map<string, number>) =>
+		[...m].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([k]) => k);
+	return [
+		{ kind: "all" },
+		...desc(byProvider).map((provider): Filter => ({ kind: "provider", provider })),
+		...desc(byModel).map((name): Filter => ({ kind: "model", name })),
+	];
+}
+
+/** Per-model totals, by tokens descending. */
+export function modelTotals(calls: readonly Call[]): ModelTotals[] {
+	const map = new Map<string, ModelTotals>();
+	for (const c of calls) {
+		const name = modelName(c);
+		let t = map.get(name);
+		if (!t) {
+			t = {
+				name,
+				provider: c.provider,
+				model: c.model,
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				cost: 0,
+				calls: 0,
+			};
+			map.set(name, t);
+		}
+		t.input += c.input;
+		t.output += c.output;
+		t.cacheRead += c.cacheRead;
+		t.cacheWrite += c.cacheWrite;
+		t.cost += c.cost;
+		t.calls++;
+	}
+	return [...map.values()].sort((a, b) => tokensOf(b) - tokensOf(a) || a.name.localeCompare(b.name));
+}
+
+/** One chart line: a provider or a `provider/model`, with its tokens in scope. */
+export interface SeriesKey {
+	key: string;
+	tokens: number;
+}
+
+/**
+ * What the chart splits by: providers under the "all" filter, models otherwise. Largest first,
+ * at most `limit`.
+ */
+export function chartSeries(
+	filter: Filter,
+	calls: readonly Call[],
+	limit: number,
+): { by: "provider" | "model"; keys: SeriesKey[] } {
+	const by = filter.kind === "all" ? "provider" : "model";
+	const keyOf = by === "provider" ? (c: Call) => c.provider : modelName;
+	const sums = new Map<string, number>();
+	for (const c of calls) sums.set(keyOf(c), (sums.get(keyOf(c)) ?? 0) + tokensOf(c));
+	const keys = [...sums]
+		.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+		.slice(0, limit)
+		.map(([key, tokens]) => ({ key, tokens }));
+	return { by, keys };
+}
+
+/** Tokens per local day. */
+export function dailyTotals(calls: readonly Call[]): Map<string, number> {
+	const out = new Map<string, number>();
+	for (const c of calls) {
+		const day = dayKey(c.ms);
+		out.set(day, (out.get(day) ?? 0) + tokensOf(c));
+	}
+	return out;
+}
+
+/** One point per day from `from` to `to` inclusive, zero-filled, split by `keyOf`. */
+export function dailySeries(
+	calls: readonly Call[],
+	from: string,
+	to: string,
+	keyOf: (c: Call) => string = modelName,
+): DayPoint[] {
+	const points = dayRange(from, to).map((day): DayPoint => ({ day, byKey: new Map(), total: 0 }));
+	const index = new Map(points.map((p, i) => [p.day, i]));
+	for (const c of calls) {
+		const p = points[index.get(dayKey(c.ms)) ?? -1];
+		if (!p) continue;
+		const key = keyOf(c);
+		p.byKey.set(key, (p.byKey.get(key) ?? 0) + tokensOf(c));
+		p.total += tokensOf(c);
+	}
+	return points;
+}
+
+/** Viewer-local labels include UTC offset, distinguishing repeated DST hours. */
+export function hourLabel(ms: number): string {
+	const date = new Date(ms);
+	const offset = -date.getTimezoneOffset();
+	const sign = offset >= 0 ? "+" : "-";
+	const abs = Math.abs(offset);
+	return `${date.getMonth() + 1}/${date.getDate()} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")} UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+
+/** One-hour UTC buckets; partial first/last buckets, zero-filled, original timestamps only. */
+export function hourlySeries(
+	calls: readonly Call[],
+	range: "5h" | "24h",
+	now: number,
+	keyOf: (c: Call) => string = modelName,
+): DayPoint[] {
+	const start = hourlyStart(range, now);
+	const from = Math.floor(start / HOUR_MS) * HOUR_MS;
+	const to = Math.floor(now / HOUR_MS) * HOUR_MS;
+	const points: DayPoint[] = [];
+	for (let ms = from; ms <= to; ms += HOUR_MS)
+		points.push({
+			day: `${hourLabel(ms)}${ms < start || ms + HOUR_MS > now ? " (partial)" : ""}`,
+			byKey: new Map(),
+			total: 0,
+		});
+	for (const c of calls) {
+		if (c.ms < start || c.ms > now) continue;
+		const p = points[Math.floor((c.ms - from) / HOUR_MS)];
+		if (!p) continue;
+		const key = keyOf(c);
+		p.byKey.set(key, (p.byKey.get(key) ?? 0) + tokensOf(c));
+		p.total += tokensOf(c);
+	}
+	return points;
+}
+
+/** Longest run of consecutive active days, and the run ending today or yesterday. Future days are ignored. */
+export function streaks(activeDays: Iterable<string>, today: string): { longest: number; current: number } {
+	const days = [...new Set(activeDays)].filter((day) => day <= today).sort();
+	let longest = 0;
+	let run = 0;
+	let prev: string | undefined;
+	for (const day of days) {
+		run = prev !== undefined && daysBetween(prev, day) === 1 ? run + 1 : 1;
+		longest = Math.max(longest, run);
+		prev = day;
+	}
+	const last = days[days.length - 1];
+	const current = last !== undefined && daysBetween(last, today) <= 1 ? run : 0;
+	return { longest, current };
+}
+
+/**
+ * Overview numbers for calls already filtered by model and range. `Sessions` and the longest session
+ * count only sessions owning one of those calls. Streaks come from `allDays` (the all-time active days
+ * under the same model filter), like Claude Code: a streak is not a range stat.
+ */
+export function overview(
+	calls: readonly Call[],
+	sessions: readonly Session[],
+	range: Range,
+	today: string,
+	allDays: Iterable<string>,
+): Overview {
+	const totals = modelTotals(calls);
+	const daily = dailyTotals(calls);
+	let mostActiveDay: string | undefined;
+	let best = -1;
+	for (const [day, tokens] of daily) {
+		if (tokens > best) {
+			best = tokens;
+			mostActiveDay = day;
+		}
+	}
+	const start = rangeStart(range, today);
+	const firstDay = calls.length > 0 ? dayKey(calls[0]?.ms ?? 0) : today;
+	const rangeDays = start === undefined ? daysBetween(firstDay, today) + 1 : daysBetween(start, today) + 1;
+	// A session is in scope when it owns at least one call that survived the model and range filters.
+	const owners = new Set(calls.map((c) => c.session));
+	const inScope = sessions.filter((s) => owners.has(s.path));
+	const { longest, current } = streaks(allDays, today);
+	return {
+		totalTokens: totals.reduce((n, t) => n + tokensOf(t), 0),
+		cacheRead: totals.reduce((n, t) => n + t.cacheRead, 0),
+		cacheWrite: totals.reduce((n, t) => n + t.cacheWrite, 0),
+		cost: totals.reduce((n, t) => n + t.cost, 0),
+		favorite: totals[0]?.name,
+		sessions: inScope.length,
+		longestSessionMs: inScope.reduce((n, s) => Math.max(n, s.endMs - s.startMs), 0),
+		activeDays: daily.size,
+		rangeDays: Math.max(1, rangeDays),
+		mostActiveDay,
+		longestStreak: longest,
+		currentStreak: current,
+	};
+}

package/src/stats/chart.ts

@@ -0,0 +1,247 @@
+/**
+ * The "Tokens per day" line chart: an asciichart-style plot (`╭╮╰╯│─`) with nice y-axis ticks and
+ * date labels. Pure: colours go through a `paint` callback so tests can render plain text.
+ *
+ * Days are bucketed (1, 2, 3, 7, 14 or 30 days) so the whole range fits the width, then sampled
+ * with linear interpolation across every column so a short range draws a smooth curve rather
+ * than a staircase.
+ */
+
+import { addDays, daysBetween, shortDate } from "./days.ts";
+import { axisLabel } from "./format.ts";
+
+export const BUCKET_SIZES = [1, 2, 3, 7, 14, 30] as const;
+const BUCKET_UNIT: Record<number, string> = {
+	1: "day",
+	2: "2 days",
+	3: "3 days",
+	7: "week",
+	14: "2 weeks",
+	30: "30 days",
+};
+/** Fixed y-axis intervals: labels land on every `height / TICKS` rows. */
+export const TICKS = 5;
+
+/** Box-drawing ports: a glyph is the set of sides its line leaves through. */
+const L = 1;
+const R = 2;
+const U = 4;
+const D = 8;
+const GLYPH: Record<number, string> = {
+	[L | R]: "─",
+	[U | D]: "│",
+	[R | D]: "╭",
+	[L | D]: "╮",
+	[U | R]: "╰",
+	[L | U]: "╯",
+	[L | R | U]: "┴",
+	[L | R | D]: "┬",
+	[U | D | R]: "├",
+	[U | D | L]: "┤",
+	[L | R | U | D]: "┼",
+};
+/** Y labels are right-aligned to this many columns, then ` ┤`. */
+export const LABEL_WIDTH = 6;
+export const GUTTER = LABEL_WIDTH + 2;
+const NICE = [1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10] as const;
+
+export interface Bucket {
+	/** First day in the bucket. */
+	start: string;
+	/** Tokens per series. */
+	values: number[];
+}
+
+export interface Bucketed {
+	size: number;
+	unit: string;
+	buckets: Bucket[];
+}
+
+/**
+ * Sum per-day values into buckets of the smallest size that yields at most `maxBuckets` (at least 2).
+ * Buckets end on `to` so the newest bucket is always complete up to today.
+ */
+export function bucketize(
+	from: string,
+	to: string,
+	perDay: (day: string) => number[],
+	seriesCount: number,
+	maxBuckets: number,
+): Bucketed {
+	const days = Math.max(1, daysBetween(from, to) + 1);
+	const most = Math.max(2, maxBuckets);
+	// Calendar-friendly sizes first; past 30-day buckets, whatever size makes it fit.
+	const size = BUCKET_SIZES.find((s) => Math.ceil(days / s) <= most) ?? Math.ceil(days / most);
+	const count = Math.ceil(days / size);
+	const buckets: Bucket[] = [];
+	for (let b = 0; b < count; b++) {
+		const end = addDays(to, -(count - 1 - b) * size);
+		const start = addDays(end, -(size - 1));
+		const values = new Array<number>(seriesCount).fill(0);
+		for (let i = 0; i < size; i++) {
+			const day = addDays(start, i);
+			if (day < from) continue;
+			const v = perDay(day);
+			for (let s = 0; s < seriesCount; s++) values[s] = (values[s] ?? 0) + (v[s] ?? 0);
+		}
+		buckets.push({ start: start < from ? from : start, values });
+	}
+	return { size, unit: BUCKET_UNIT[size] ?? `${size} days`, buckets };
+}
+
+/**
+ * Smallest of 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8 x 10^k that is >= `x`: round labels, little headroom.
+ * Tokens are whole, so the step is a whole number too (never below 1, never 1.5 or 2.5).
+ */
+export function niceStep(x: number): number {
+	if (!(x > 1)) return 1;
+	const exp = 10 ** Math.floor(Math.log10(x));
+	for (const m of NICE) {
+		const step = m * exp;
+		if (Number.isInteger(step) && step >= x - 1e-9 * exp) return step;
+	}
+	return 10 * exp;
+}
+
+/**
+ * Stretch `values` over `columns` points: bucket `k` lands exactly on column `round(k * (columns - 1) /
+ * (n - 1))` with its true value, and columns between two buckets are linearly interpolated. Every
+ * bucket value, so every peak, appears unchanged. Needs `n <= columns`, which `bucketize` guarantees.
+ */
+export function stretch(values: readonly number[], columns: number): number[] {
+	const n = values.length;
+	if (n === 0) return new Array<number>(columns).fill(0);
+	if (n === 1) return new Array<number>(columns).fill(values[0] ?? 0);
+	const out = new Array<number>(columns).fill(0);
+	const at = (k: number) => Math.round((k * (columns - 1)) / (n - 1));
+	for (let k = 0; k < n - 1; k++) {
+		const from = at(k);
+		const to = at(k + 1);
+		const a = values[k] ?? 0;
+		const b = values[k + 1] ?? 0;
+		for (let c = from; c <= to; c++) out[c] = to === from ? b : a + ((b - a) * (c - from)) / (to - from);
+	}
+	return out;
+}
+
+export interface Series<C extends string | number> {
+	values: number[];
+	color: C;
+}
+
+export interface PlotOptions<C extends string | number> {
+	/** Plot columns, axis excluded. */
+	width: number;
+	/** Plot rows above the zero line; a multiple of `TICKS` gives evenly spaced labels. */
+	height: number;
+	paint: (color: C | "axis", text: string) => string;
+}
+
+export interface Plot {
+	lines: string[];
+	/** Columns before the plot area (labels + axis), for aligning the x-axis. */
+	gutter: number;
+	max: number;
+}
+
+/**
+ * Plot `series` stretched over `width` columns. Overlapping series merge into junction glyphs and
+ * the first (largest) series keeps the shared cell's colour.
+ */
+export function plot<C extends string | number>(series: readonly Series<C>[], options: PlotOptions<C>): Plot {
+	const width = Math.max(2, Math.floor(options.width));
+	const height = Math.max(1, Math.floor(options.height));
+	const sampled = series.map((s) => stretch(s.values, width + 1));
+	const raw = Math.max(0, ...series.flatMap((s) => s.values));
+	const step = niceStep(raw / TICKS || 1);
+	const max = step * TICKS;
+	const labels = Array.from({ length: TICKS + 1 }, (_, i) => axisLabel(step * i));
+	const labelWidth = Math.max(LABEL_WIDTH, ...labels.map((l) => l.length));
+	const row = (v: number) => Math.round((v / max) * height);
+
+	// Cells hold box-drawing ports, not glyphs: where series overlap their ports are OR-ed, so a
+	// crossing becomes `┴`/`┬`/`┼` and every line stays connected. The first series keeps the colour.
+	const grid: { ports: number; color?: C }[][] = Array.from({ length: height + 1 }, () =>
+		Array.from({ length: width }, () => ({ ports: 0 })),
+	);
+	const put = (y: number, x: number, ports: number, color: C) => {
+		const cell = grid[height - y]?.[x];
+		if (!cell) return;
+		cell.ports |= ports;
+		cell.color ??= color;
+	};
+	for (let s = 0; s < sampled.length; s++) {
+		const values = sampled[s] ?? [];
+		const color = series[s]?.color as C;
+		for (let x = 0; x < width; x++) {
+			const y0 = row(values[x] ?? 0);
+			const y1 = row(values[x + 1] ?? 0);
+			if (y0 === y1) {
+				put(y0, x, L | R, color);
+				continue;
+			}
+			// enter from the left at y0, leave to the right at y1, vertical in between
+			put(y0, x, L | (y1 > y0 ? U : D), color);
+			put(y1, x, R | (y1 > y0 ? D : U), color);
+			for (let y = Math.min(y0, y1) + 1; y < Math.max(y0, y1); y++) put(y, x, U | D, color);
+		}
+	}
+
+	const perTick = height / TICKS;
+	const lines: string[] = [];
+	for (let r = 0; r <= height; r++) {
+		const y = height - r;
+		const tick = Number.isInteger(y / perTick) ? y / perTick : -1;
+		const label = tick >= 0 ? (labels[tick] ?? "") : "";
+		const axis = y === 0 ? "┼" : tick >= 0 ? "┤" : "│";
+		let body = "";
+		let run = "";
+		let runColor: C | undefined;
+		const flush = () => {
+			if (run) body += runColor !== undefined ? options.paint(runColor, run) : run;
+			run = "";
+		};
+		for (const cell of grid[r] ?? []) {
+			if (cell.color !== runColor) {
+				flush();
+				runColor = cell.color;
+			}
+			run += GLYPH[cell.ports] ?? " ";
+		}
+		flush();
+		lines.push(`${options.paint("axis", `${label.padStart(labelWidth)} ${axis}`)}${body}`);
+	}
+	return { lines, gutter: labelWidth + 2, max };
+}
+
+/**
+ * Two to five date labels under a plot of `width` columns spanning `buckets`: first and last always,
+ * evenly spaced ones between when they fit with two spaces of air. Never past the plot's right edge.
+ */
+export function xAxis(buckets: readonly Bucket[], width: number, gutter: number): string {
+	if (buckets.length === 0 || width <= 0) return "";
+	const last = buckets.length - 1;
+	const at = (col: number) => buckets[Math.round((col * last) / Math.max(1, width))]?.start ?? "";
+	const line = new Array<string>(width).fill(" ");
+	const place = (col: number, text: string): boolean => {
+		const start = Math.max(0, Math.min(width - text.length, col));
+		for (let i = Math.max(0, start - 2); i < Math.min(width, start + text.length + 2); i++) {
+			if (line[i] !== " ") return false;
+		}
+		for (let i = 0; i < text.length && start + i < width; i++) line[start + i] = text[i] ?? " ";
+		return true;
+	};
+	const first = shortDate(buckets[0]?.start ?? "");
+	const end = shortDate(buckets[last]?.start ?? "");
+	// The newest date first: on a plot too narrow for both, today's end of the range wins.
+	if (last > 0) place(width - end.length, end);
+	place(0, first);
+	if (last === 0) return `${" ".repeat(gutter)}${line.join("").trimEnd()}`;
+	const slots = Math.max(1, Math.min(4, Math.floor(width / 14)));
+	for (let i = 1; i < slots; i++) {
+		const col = Math.round((i * width) / slots);
+		place(col - 3, shortDate(at(col)));
+	}
+	return `${" ".repeat(gutter)}${line.join("").trimEnd()}`;
+}

package/src/stats/cli.ts

@@ -0,0 +1,50 @@
+/** Standalone data-only CLI. Bundles the parser; never imports Pi or the private extension entrypoint. */
+import { resolve } from "node:path";
+import { agentDir } from "./load.ts";
+import { exportStats, importStats } from "./snapshot.ts";
+
+async function main(): Promise<void> {
+	const [command, ...args] = process.argv.slice(2);
+	const options = new Map<string, string>();
+	for (let i = 0; i < args.length; i += 2) {
+		const flag = args[i];
+		const value = args[i + 1];
+		if (
+			!flag ||
+			!value ||
+			value.startsWith("--") ||
+			options.has(flag) ||
+			!["--agent-dir", "--output", "--input", "--sessions-dir"].includes(flag)
+		)
+			throw new Error(
+				"usage: export --agent-dir DIR --output OUT [--sessions-dir DIR] | import --agent-dir DIR --input REPO",
+			);
+		options.set(flag, value);
+	}
+	const dir = resolve(options.get("--agent-dir") ?? agentDir());
+	if (command === "export" && options.has("--output") && !options.has("--input")) {
+		const root = options.get("--sessions-dir");
+		console.log(
+			JSON.stringify(await exportStats(dir, resolve(options.get("--output") ?? ""), root ? resolve(root) : undefined)),
+		);
+	} else if (
+		command === "import" &&
+		options.has("--input") &&
+		!options.has("--output") &&
+		!options.has("--sessions-dir")
+	) {
+		const result = await importStats(dir, resolve(options.get("--input") ?? ""));
+		console.log(JSON.stringify(result));
+		if (result.problems.length) {
+			console.error(result.problems.join("\n"));
+			process.exitCode = 1;
+		}
+	} else
+		throw new Error(
+			"usage: export --agent-dir DIR --output OUT [--sessions-dir DIR] | import --agent-dir DIR --input REPO",
+		);
+}
+main().catch((error: unknown) => {
+	console.error(error instanceof Error ? error.message : "Stats operation failed");
+	process.exitCode = 1;
+});