pi-tokenburn 0.5.7 → 0.6.0

package/extensions/core/config.ts

@@ -0,0 +1,157 @@
+/** Config file (tokenburn.json), path resolution, budgets. */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { sanitizeFilter, sanitizePrices, type PriceMode, type PriceTable, type UsageFilter } from "./select.ts";
+import { STATUS_WINDOWS, type PeriodStats, type Window } from "./types.ts";
+
+export interface TokenBurnConfig {
+	/** Master switch. When false nothing runs in the background and the status line / panel are cleared. */
+	enabled: boolean;
+	/** Refresh after each assistant message (coalesced), not only when a turn ends. */
+	liveRefresh: boolean;
+	/** Trailing delay for live refreshes, in ms (250 to 60000). */
+	refreshMs: number;
+	/** Count cache read/write tokens in totals (matches the tokenburn CLI). */
+	includeCache: boolean;
+	/** Color the report chart (set false if your terminal garbles ANSI in notifications). */
+	chartColor: boolean;
+	showStatus: boolean;
+	showWidget: boolean;
+	statusWindow: Window;
+	/** Show the burn rate (tokens/hour averaged over the status window) in the status line. */
+	showRate: boolean;
+	/** Show the cache hit ratio of the status window in the status line. */
+	showHit: boolean;
+	/** Show the estimated cache savings of the status window in the status line. */
+	showSaved: boolean;
+	/** Notify once when a budget reaches this percentage (1 to 100); 0 turns warnings off. */
+	warnPct: number;
+	/** Only count usage matching these (case-insensitive substrings). Empty = everything. */
+	filter: UsageFilter;
+	/** Price table in $ per million tokens, keyed by `model` or `provider/model`. */
+	prices: PriceTable;
+	/** `fill`: use the table only where the log has no cost. `override`: table wins over the log. */
+	priceMode: PriceMode;
+	budgets: {
+		dayTokens?: number;
+		weekTokens?: number;
+		monthTokens?: number;
+		dayCost?: number;
+		weekCost?: number;
+		monthCost?: number;
+	};
+}
+
+export const DEFAULT_CONFIG: TokenBurnConfig = {
+	enabled: true,
+	liveRefresh: true,
+	refreshMs: 750,
+	includeCache: true,
+	chartColor: true,
+	showStatus: true,
+	showWidget: false,
+	statusWindow: "today",
+	showRate: true,
+	showHit: true,
+	showSaved: true,
+	warnPct: 80,
+	filter: {},
+	prices: {},
+	priceMode: "fill",
+	budgets: {},
+};
+
+/** Where pi keeps its config: PI_CODING_AGENT_DIR, then $XDG_CONFIG_HOME/pi/agent, then ~/.pi/agent. */
+export function resolveAgentDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.PI_CODING_AGENT_DIR) return env.PI_CODING_AGENT_DIR;
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi", "agent");
+	return join(home, ".pi", "agent");
+}
+
+/** Pi session logs: TOKENBURN_PI_SESSIONS, PI_CODING_AGENT_SESSION_DIR, then <agent dir>/sessions. */
+export function resolveSessionsDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.TOKENBURN_PI_SESSIONS) return env.TOKENBURN_PI_SESSIONS;
+	if (env.PI_CODING_AGENT_SESSION_DIR) return env.PI_CODING_AGENT_SESSION_DIR;
+	return join(resolveAgentDir(env, home), "sessions");
+}
+
+export const getConfigDir = () => resolveAgentDir(process.env, homedir());
+
+export const getSessionsDir = () => resolveSessionsDir(process.env, homedir());
+
+export async function loadConfig(): Promise<TokenBurnConfig> {
+	try {
+		const raw = await readFile(join(getConfigDir(), "tokenburn.json"), "utf8");
+		const parsed = JSON.parse(raw);
+		return {
+			enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
+			liveRefresh: typeof parsed.liveRefresh === "boolean" ? parsed.liveRefresh : DEFAULT_CONFIG.liveRefresh,
+			refreshMs: sanitizeRefreshMs(parsed.refreshMs),
+			includeCache: typeof parsed.includeCache === "boolean" ? parsed.includeCache : DEFAULT_CONFIG.includeCache,
+			chartColor: typeof parsed.chartColor === "boolean" ? parsed.chartColor : DEFAULT_CONFIG.chartColor,
+			showStatus: typeof parsed.showStatus === "boolean" ? parsed.showStatus : DEFAULT_CONFIG.showStatus,
+			showWidget: typeof parsed.showWidget === "boolean" ? parsed.showWidget : DEFAULT_CONFIG.showWidget,
+			statusWindow: (STATUS_WINDOWS as readonly string[]).includes(parsed.statusWindow)
+				? parsed.statusWindow
+				: DEFAULT_CONFIG.statusWindow,
+			showRate: typeof parsed.showRate === "boolean" ? parsed.showRate : DEFAULT_CONFIG.showRate,
+			showHit: typeof parsed.showHit === "boolean" ? parsed.showHit : DEFAULT_CONFIG.showHit,
+			showSaved: typeof parsed.showSaved === "boolean" ? parsed.showSaved : DEFAULT_CONFIG.showSaved,
+			warnPct: sanitizeWarnPct(parsed.warnPct),
+			filter: sanitizeFilter(parsed.filter),
+			prices: sanitizePrices(parsed.prices),
+			priceMode: parsed.priceMode === "override" ? "override" : "fill",
+			budgets: sanitizeBudgets(parsed.budgets),
+		};
+	} catch {
+		return freshConfig();
+	}
+}
+
+/** Live-refresh delay: a finite number clamped to 250..60000 ms, else the default. */
+export function sanitizeRefreshMs(value: unknown): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_CONFIG.refreshMs;
+	return Math.min(60_000, Math.max(250, Math.round(value)));
+}
+
+/** Warn threshold: a finite number 1..100, 0 = off, anything else the default. */
+export function sanitizeWarnPct(value: unknown): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_CONFIG.warnPct;
+	return value <= 0 ? 0 : Math.min(100, Math.round(value));
+}
+
+const BUDGET_KEYS = ["dayTokens", "weekTokens", "monthTokens", "dayCost", "weekCost", "monthCost"] as const;
+
+/** Keep only known budget keys holding positive, finite numbers (the file is hand-editable). */
+export function sanitizeBudgets(value: unknown): TokenBurnConfig["budgets"] {
+	const out: TokenBurnConfig["budgets"] = {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return out;
+	for (const key of BUDGET_KEYS) {
+		const n = (value as Record<string, unknown>)[key];
+		if (typeof n === "number" && Number.isFinite(n) && n > 0) out[key] = n;
+	}
+	return out;
+}
+
+/** A config that shares no mutable state with DEFAULT_CONFIG. */
+export function freshConfig(): TokenBurnConfig {
+	return { ...DEFAULT_CONFIG, budgets: {}, filter: {}, prices: {} };
+}
+
+export async function saveConfig(cfg: TokenBurnConfig): Promise<void> {
+	await mkdir(getConfigDir(), { recursive: true });
+	await writeFile(join(getConfigDir(), "tokenburn.json"), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+export function budgetsFor(cfg: TokenBurnConfig, w: Window): { tokens?: number; cost?: number } {
+	const b = cfg.budgets;
+	if (w === "today") return { tokens: b.dayTokens, cost: b.dayCost };
+	if (w === "week") return { tokens: b.weekTokens, cost: b.weekCost };
+	if (w === "month") return { tokens: b.monthTokens, cost: b.monthCost };
+	return {};
+}
+
+export function isOverBudget(p: PeriodStats, b: { tokens?: number; cost?: number }): boolean {
+	return (b.tokens !== undefined && p.tokens > b.tokens) || (b.cost !== undefined && p.cost > b.cost);
+}

package/extensions/core/format.ts

@@ -0,0 +1,12 @@
+/** Number and cost formatting. */
+
+export function formatNum(n: number): string {
+	if (n >= 1_000_000_000) return (n / 1_000_000_000).toFixed(2) + "B";
+	if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + "M";
+	if (n >= 1_000) return (n / 1_000).toFixed(1) + "k";
+	return n.toString();
+}
+
+export function formatCost(c: number): string {
+	return `$${c.toFixed(2)}`;
+}

package/extensions/core/paint.ts

@@ -0,0 +1,35 @@
+/** Terminal paint helpers shared by charts and tables: bars, sparklines, theme colors. */
+
+const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
+export const SPARK = "▁▂▃▄▅▆▇█";
+
+/** Horizontal bar of `value/max` over `width` cells, with 1/8-cell precision. */
+export function bar(value: number, max: number, width: number): string {
+	if (!(max > 0) || !(value > 0) || !(width > 0)) return "";
+	// Capped at the full width: a value above `max` (or Infinity) must not build a giant string.
+	const eighths = Math.min(Math.floor(width) * 8, Math.max(1, Math.round((value / max) * width * 8)));
+	const full = Math.floor(eighths / 8);
+	return "█".repeat(full) + EIGHTHS[eighths % 8];
+}
+
+export function sparkline(values: number[]): string {
+	const max = Math.max(...values, 0);
+	if (max <= 0) return SPARK[0].repeat(values.length);
+	return values.map((v) => SPARK[Math.min(7, Math.round((v / max) * 7))]).join("");
+}
+
+export type Paint = (kind: "bar" | "now" | "over" | "axis" | "budget" | "dim" | "title", text: string) => string;
+
+/** Map chart roles to pi theme colors. */
+export function themePaint(theme: { fg: (c: any, t: string) => string }): Paint {
+	const color: Record<string, string> = {
+		bar: "accent",
+		now: "success",
+		over: "error",
+		axis: "dim",
+		budget: "warning",
+		dim: "dim",
+		title: "accent",
+	};
+	return (kind, text) => theme.fg(color[kind], text);
+}

package/extensions/core/parser.ts

@@ -0,0 +1,261 @@
+/**
+ * Session-log parser with a per-file incremental cache. Pi session logs are append-only
+ * JSONL, so after the first parse only the appended bytes are read.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { open, type FileHandle } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export interface Turn {
+	ts: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	/** Cost split, used to estimate what prompt caching saved. */
+	costInput: number;
+	costCacheRead: number;
+	provider: string;
+	model: string;
+	/** Working directory of the session (falls back to the session directory name). */
+	project: string;
+	/** Session file path. */
+	session: string;
+}
+
+/** Per-file context for a parse: where the file is and the cwd from its header line. */
+interface Meta {
+	file: string;
+	cwd?: string;
+}
+
+/** What was read from disk, for tests and tuning: refreshes must cost O(new bytes). */
+export const stats = { bytesRead: 0, fullParses: 0, incrementalParses: 0 };
+
+export function resetStats(): void {
+	stats.bytesRead = 0;
+	stats.fullParses = 0;
+	stats.incrementalParses = 0;
+}
+
+/**
+ * Per-session-file parse state. Pi session logs are append-only JSONL, so after the first
+ * parse only the bytes added since then are read. The state is dropped (full reparse) when
+ * the file shrank, was rewritten in place, or its head / last-parsed bytes no longer match.
+ */
+interface FileEntry {
+	size: number;
+	mtimeMs: number;
+	/** End of the last COMPLETE (newline-terminated) line that was parsed. */
+	offset: number;
+	turns: Turn[];
+	/** Turn from an unterminated final line; counted now, re-parsed once the line completes. */
+	tail: Turn[];
+	cwd?: string;
+	/** First bytes of the file, to notice a rewrite. */
+	head: Buffer;
+	/** The bytes just before `offset`, same purpose. */
+	guard: Buffer;
+}
+
+const FILE_CACHE = new Map<string, FileEntry>();
+const GUARD_BYTES = 64;
+const HEAD_BYTES = 256;
+export const CHUNK_BYTES = 1 << 20;
+
+/** A Turn from one JSONL line, or undefined when it carries no usage. */
+/** A finite number, else 0 (logs can hold 1e999, strings, junk). */
+const finite = (v: unknown): number => {
+	const n = Number(v);
+	return Number.isFinite(n) ? n : 0;
+};
+
+function turnFromLine(line: Buffer, meta: Meta): Turn | undefined {
+	if (meta.cwd === undefined && line.includes('"type":"session"')) {
+		try {
+			const h = JSON.parse(line.toString("utf8"));
+			if (h.type === "session" && typeof h.cwd === "string") meta.cwd = h.cwd;
+		} catch {
+			/* not a header */
+		}
+		return undefined;
+	}
+	if (!line.includes('"usage"')) return undefined; // most lines: skip without a JSON parse
+	try {
+		const obj = JSON.parse(line.toString("utf8"));
+		const usage = obj.message?.usage;
+		if (!obj.timestamp || !usage) return undefined;
+		const ts = new Date(obj.timestamp).getTime();
+		if (!Number.isFinite(ts)) return undefined;
+		return {
+			ts,
+			input: finite(usage.input),
+			output: finite(usage.output),
+			cacheRead: finite(usage.cacheRead),
+			cacheWrite: finite(usage.cacheWrite),
+			cost: finite(usage.cost?.total),
+			costInput: finite(usage.cost?.input),
+			costCacheRead: finite(usage.cost?.cacheRead),
+			provider: String(obj.message?.provider ?? "unknown"),
+			model: String(obj.message?.model ?? "unknown"),
+			project: meta.cwd ?? basename(dirname(meta.file)),
+			session: meta.file,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+async function readAt(fd: FileHandle, buf: Buffer, position: number): Promise<number> {
+	const { bytesRead } = await fd.read(buf, 0, buf.length, position);
+	stats.bytesRead += bytesRead;
+	return bytesRead;
+}
+
+/** Parse complete lines in [start, end). Returns their turns, where they stop, and the unterminated rest. */
+async function scan(
+	fd: FileHandle,
+	start: number,
+	end: number,
+	chunkSize: number,
+	meta: Meta,
+): Promise<{ turns: Turn[]; consumed: number; rest: Buffer }> {
+	const turns: Turn[] = [];
+	const buf = Buffer.allocUnsafe(Math.min(chunkSize, Math.max(1, end - start)));
+	let pos = start;
+	let consumed = start;
+	let carry: Buffer = Buffer.alloc(0);
+	while (pos < end) {
+		const want = Math.min(buf.length, end - pos);
+		const n = await readAt(fd, want === buf.length ? buf : buf.subarray(0, want), pos);
+		if (n === 0) break;
+		const base = pos - carry.length;
+		const data = carry.length > 0 ? Buffer.concat([carry, buf.subarray(0, n)]) : buf.subarray(0, n);
+		let lineStart = 0;
+		for (let nl = data.indexOf(10, lineStart); nl !== -1; nl = data.indexOf(10, lineStart)) {
+			const t = turnFromLine(data.subarray(lineStart, nl), meta);
+			if (t) turns.push(t);
+			lineStart = nl + 1;
+		}
+		if (lineStart > 0) consumed = base + lineStart;
+		carry = Buffer.from(data.subarray(lineStart)); // copy: `buf` is reused
+		pos += n;
+	}
+	return { turns, consumed, rest: carry };
+}
+
+async function bytesAt(fd: FileHandle, position: number, length: number): Promise<Buffer> {
+	if (length <= 0) return Buffer.alloc(0);
+	const buf = Buffer.alloc(length);
+	const n = await readAt(fd, buf, position);
+	return buf.subarray(0, n);
+}
+
+/** Is the prefix we parsed earlier still what is on disk? */
+async function stillAppendOnly(fd: FileHandle, prev: FileEntry): Promise<boolean> {
+	const head = await bytesAt(fd, 0, prev.head.length);
+	if (!head.equals(prev.head)) return false;
+	const guard = await bytesAt(fd, prev.offset - prev.guard.length, prev.guard.length);
+	return guard.equals(prev.guard);
+}
+
+async function refreshEntry(
+	file: string,
+	st: { size: number; mtimeMs: number },
+	prev: FileEntry | undefined,
+	chunkSize: number,
+): Promise<FileEntry | undefined> {
+	let fd: FileHandle;
+	try {
+		fd = await open(file, "r");
+	} catch {
+		return undefined;
+	}
+	try {
+		const grew = prev !== undefined && st.size > prev.size;
+		const incremental = grew && (await stillAppendOnly(fd, prev!));
+		const start = incremental ? prev!.offset : 0;
+		const turns = incremental ? prev!.turns : [];
+		if (incremental) stats.incrementalParses++;
+		else stats.fullParses++;
+
+		const meta: Meta = { file, cwd: incremental ? prev!.cwd : undefined };
+		const r = await scan(fd, start, st.size, chunkSize, meta);
+		for (const t of r.turns) turns.push(t);
+		const tailTurn = r.rest.length > 0 ? turnFromLine(r.rest, meta) : undefined;
+		return {
+			size: st.size,
+			mtimeMs: st.mtimeMs,
+			offset: r.consumed,
+			turns,
+			tail: tailTurn ? [tailTurn] : [],
+			cwd: meta.cwd,
+			head: incremental ? prev!.head : await bytesAt(fd, 0, Math.min(HEAD_BYTES, st.size)),
+			guard: await bytesAt(fd, Math.max(0, r.consumed - GUARD_BYTES), Math.min(GUARD_BYTES, r.consumed)),
+		};
+	} catch {
+		return undefined;
+	} finally {
+		await fd.close();
+	}
+}
+
+/** Size and mtime of a file, or undefined when it cannot be stat'ed. */
+export function fileStat(file: string): { size: number; mtimeMs: number } | undefined {
+	try {
+		const st = statSync(file);
+		return { size: st.size, mtimeMs: st.mtimeMs };
+	} catch {
+		return undefined;
+	}
+}
+
+function listSessionFiles(root: string): string[] {
+	const files: string[] = [];
+	const walk = (dir: string) => {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const e of entries) {
+			const full = join(dir, e.name);
+			if (e.isDirectory()) walk(full);
+			else if (e.isFile() && e.name.endsWith(".jsonl")) files.push(full);
+		}
+	};
+	walk(root);
+	return files;
+}
+
+/** Bring the per-file cache up to date (reading only what changed) and return every file's turns. */
+export async function loadAll(sessionsRoot: string, chunkSize = CHUNK_BYTES): Promise<Turn[][]> {
+	const files = listSessionFiles(sessionsRoot);
+	const live = new Set(files);
+	for (const key of FILE_CACHE.keys()) if (!live.has(key)) FILE_CACHE.delete(key);
+
+	const out: Turn[][] = [];
+	for (const file of files) {
+		const st = fileStat(file);
+		if (st === undefined) continue; // vanished between listing and stat
+		let entry = FILE_CACHE.get(file);
+		if (!entry || entry.size !== st.size || entry.mtimeMs !== st.mtimeMs) {
+			const fresh = await refreshEntry(file, st, entry, chunkSize);
+			if (fresh) FILE_CACHE.set(file, fresh);
+			else FILE_CACHE.delete(file);
+			entry = fresh;
+		}
+		if (entry) out.push(entry.tail.length > 0 ? entry.turns.concat(entry.tail) : entry.turns);
+	}
+	return out;
+}
+
+/** Test hooks: parse with a tiny chunk size (chunk boundaries) / refresh one file directly. */
+export const __loadAllForTests = loadAll;
+export const __refreshEntryForTests = refreshEntry;
+
+export function clearCache(): void {
+	FILE_CACHE.clear();
+}

package/extensions/core/select.ts

@@ -0,0 +1,105 @@
+/**
+ * Usage filter + price table. Costs normally come straight from the session logs (pi computes
+ * them from its own model prices). The price table lets you fill in models pi had no price for
+ * (`fill`) or correct stale prices (`override`).
+ */
+import type { Turn } from "./parser.ts";
+
+export interface UsageFilter {
+	provider?: string;
+	model?: string;
+	project?: string;
+}
+
+/** $ per million tokens. */
+export interface Price {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+export type PriceTable = Record<string, Price>;
+export type PriceMode = "fill" | "override";
+
+/** Options every collector accepts. */
+export interface UsageOptions {
+	filter?: UsageFilter;
+	prices?: PriceTable;
+	priceMode?: PriceMode;
+}
+
+const FILTER_KEYS = ["provider", "model", "project"] as const;
+export type FilterKey = (typeof FILTER_KEYS)[number];
+export const FILTER_KEYS_LIST: readonly FilterKey[] = FILTER_KEYS;
+
+/** Keep only known keys holding non-empty strings (the file is hand-editable). */
+export function sanitizeFilter(value: unknown): UsageFilter {
+	const out: UsageFilter = {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return out;
+	for (const k of FILTER_KEYS) {
+		const v = (value as Record<string, unknown>)[k];
+		if (typeof v === "string" && v.trim() !== "") out[k] = v.trim();
+	}
+	return out;
+}
+
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined);
+
+/** Keep only entries with a finite, non-negative input and output price. */
+export function sanitizePrices(value: unknown): PriceTable {
+	const out: PriceTable = {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return out;
+	for (const [name, p] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof p !== "object" || p === null) continue;
+		const r = p as Record<string, unknown>;
+		const input = num(r.input);
+		const output = num(r.output);
+		if (input === undefined || output === undefined) continue;
+		out[name] = { input, output, cacheRead: num(r.cacheRead) ?? input, cacheWrite: num(r.cacheWrite) ?? input };
+	}
+	return out;
+}
+
+export const hasFilter = (f: UsageFilter | undefined) => !!f && (!!f.provider || !!f.model || !!f.project);
+
+/** Human text for an active filter, e.g. `provider=anthropic model=opus`. */
+export function describeFilter(f: UsageFilter | undefined): string {
+	return FILTER_KEYS.filter((k) => f?.[k]).map((k) => `${k}=${f![k]}`).join(" ");
+}
+
+export function matchesFilter(t: Turn, f: UsageFilter | undefined): boolean {
+	if (!f) return true;
+	const has = (hay: string, needle: string | undefined) => !needle || hay.toLowerCase().includes(needle.toLowerCase());
+	return has(t.provider, f.provider) && has(t.model, f.model) && has(t.project, f.project);
+}
+
+export function priceFor(t: Turn, prices: PriceTable): Price | undefined {
+	return prices[`${t.provider}/${t.model}`] ?? prices[t.model];
+}
+
+export type CostSource = "log" | "table";
+
+/** The turn with the price table applied (same object when it does not apply). */
+export function applyPricing(t: Turn, prices: PriceTable | undefined, mode: PriceMode = "fill"): { turn: Turn; source: CostSource } {
+	if (!prices) return { turn: t, source: "log" };
+	const p = priceFor(t, prices);
+	if (!p || (mode === "fill" && t.cost > 0)) return { turn: t, source: "log" };
+	const costInput = (t.input * p.input) / 1e6;
+	const costCacheRead = (t.cacheRead * p.cacheRead) / 1e6;
+	const cost = costInput + costCacheRead + (t.output * p.output) / 1e6 + (t.cacheWrite * p.cacheWrite) / 1e6;
+	return { turn: { ...t, cost, costInput, costCacheRead }, source: "table" };
+}
+
+/** Filter then price every turn. Returns the input array untouched when there is nothing to do. */
+export function selectTurns(turns: Turn[], opts: UsageOptions | undefined): Turn[] {
+	if (!opts) return turns;
+	const filter = hasFilter(opts.filter) ? opts.filter : undefined;
+	const prices = opts.prices && Object.keys(opts.prices).length > 0 ? opts.prices : undefined;
+	if (!filter && !prices) return turns;
+	const out: Turn[] = [];
+	for (const t of turns) {
+		if (!matchesFilter(t, filter)) continue;
+		out.push(prices ? applyPricing(t, prices, opts.priceMode).turn : t);
+	}
+	return out;
+}

package/extensions/core/time.ts

@@ -0,0 +1,25 @@
+/** Local-time buckets (hour / day / Monday-week / month / year). */
+
+export type Unit = "day" | "week" | "month" | "year";
+
+/** Local-time start of the day / Monday-week / month containing `ts`. */
+export function bucketStart(ts: number, unit: Unit): number {
+	const d = new Date(ts);
+	if (unit === "day") return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+	if (unit === "week") {
+		const dow = (d.getDay() + 6) % 7; // Monday = 0
+		return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+	}
+	if (unit === "year") return new Date(d.getFullYear(), 0, 1).getTime();
+	return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+}
+
+export const pad2 = (n: number) => String(n).padStart(2, "0");
+
+export function bucketLabel(start: number, unit: Unit): string {
+	const d = new Date(start);
+	if (unit === "year") return String(d.getFullYear());
+	if (unit === "month") return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}`;
+	const base = `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+	return unit === "day" ? `${base} ${["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][d.getDay()]}` : `${base} wk`;
+}

package/extensions/core/types.ts

@@ -0,0 +1,43 @@
+/** Shared types. */
+
+export interface TokenUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+}
+
+export interface PeriodStats {
+	/** input + output (+ cache read/write when includeCache). */
+	tokens: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	sessions: number;
+	/** What cache reads would have cost as plain input vs what they cost (turns with a known input price). */
+	cacheBase: number;
+	cacheActual: number;
+}
+
+export interface TokenBurnReport {
+	/** Rolling last 60 minutes (burn rate). */
+	hour: PeriodStats;
+	today: PeriodStats;
+	week: PeriodStats;
+	month: PeriodStats;
+	year: PeriodStats;
+	total: PeriodStats;
+	/** Timestamp of the earliest turn counted (undefined when there is none). */
+	firstTs?: number;
+}
+
+export const STATUS_WINDOWS = ["hour", "today", "week", "month", "year", "total"] as const;
+export type Window = (typeof STATUS_WINDOWS)[number];
+
+export interface Rate {
+	tokensPerHour: number;
+	costPerHour: number;
+}

package/extensions/features/breakdown/commands.ts

@@ -0,0 +1,32 @@
+/** Commands: usage tables (models / providers / projects / sessions) and the current session. */
+import { collectUsage } from "../../core/aggregate.ts";
+import { getSessionsDir } from "../../core/config.ts";
+import { themePaint } from "../../core/paint.ts";
+import { describeFilter } from "../../core/select.ts";
+import type { HandlersFor } from "../../command/host.ts";
+import { collectGroups } from "./query.ts";
+import { renderTable, sessionSummary } from "./table.ts";
+
+export const breakdownCommands: HandlersFor<"table" | "session"> = {
+	async table(cmd, { config, usageOpts, ctx }) {
+		const opts = usageOpts(cmd.filter);
+		const rows = await collectGroups(getSessionsDir(), cmd.by, cmd.period, new Date(), config.includeCache, opts);
+		const paint = config.chartColor ? themePaint(ctx.ui.theme) : undefined;
+		ctx.ui.notify(renderTable(cmd.by, rows, cmd.period, { limit: cmd.limit, filterText: describeFilter(opts.filter), paint }).join("\n"), "info");
+	},
+
+	async session(_cmd, { config, usageOpts, ctx }) {
+		const file = ctx.sessionManager?.getSessionFile?.();
+		if (!file) {
+			ctx.ui.notify("tokenburn: this session has no log file yet (in-memory session)", "info");
+			return;
+		}
+		const root = getSessionsDir();
+		const now = new Date();
+		const [rows, report] = await Promise.all([
+			collectGroups(root, "session", "all", now, config.includeCache, usageOpts()),
+			collectUsage(root, now, config.includeCache, usageOpts()),
+		]);
+		ctx.ui.notify(sessionSummary(file, rows.find((r) => r.key === file), report.today.cost), "info");
+	},
+};