pi-tokenburn 0.5.8 → 0.6.0

package/extensions/features/breakdown/query.ts

@@ -0,0 +1,138 @@
+/** Grouped usage queries: per model, provider, project and session, over a period. */
+import { HOUR_MS, loadSelected, turnTokens } from "../../core/aggregate.ts";
+import type { UsageOptions } from "../../core/select.ts";
+import { bucketStart } from "../../core/time.ts";
+
+export const PERIODS = ["hour", "day", "week", "month", "year", "all"] as const;
+export type Period = (typeof PERIODS)[number];
+/** Words accepted for a period, mapped to it (`today` = day, `total` = all). */
+export const PERIOD_ALIASES: Record<string, Period> = {
+	hour: "hour",
+	day: "day",
+	today: "day",
+	week: "week",
+	month: "month",
+	year: "year",
+	all: "all",
+	total: "all",
+};
+export const PERIOD_TITLE: Record<Period, string> = {
+	hour: "last 60 minutes",
+	day: "today",
+	week: "this week",
+	month: "this month",
+	year: "this year",
+	all: "all time",
+};
+
+/** Start of a period; `hour` is the rolling last 60 minutes, `all` is 0. */
+export function periodStart(now: number, p: Period): number {
+	if (p === "hour") return now - HOUR_MS;
+	if (p === "all") return 0;
+	return bucketStart(now, p);
+}
+
+export const GROUPS = ["model", "provider", "project", "session"] as const;
+export type GroupBy = (typeof GROUPS)[number];
+
+export interface Row {
+	key: string;
+	provider: string;
+	model: string;
+	project: string;
+	session: string;
+	tokens: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+	sessions: number;
+	first: number;
+	last: number;
+	/** What the cached tokens would have cost as plain input, and what they did cost (turns with a known input price). */
+	cacheBase: number;
+	cacheActual: number;
+}
+
+const emptyRow = (key: string): Row => ({
+	key, provider: "", model: "", project: "", session: "",
+	tokens: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0,
+	turns: 0, sessions: 0, first: Infinity, last: 0, cacheBase: 0, cacheActual: 0,
+});
+
+/** Share of prompt tokens served from cache, 0..1. */
+export function cacheHitRatio(r: { input: number; cacheRead: number; cacheWrite: number }): number {
+	const prompt = r.input + r.cacheRead + r.cacheWrite;
+	return prompt > 0 ? r.cacheRead / prompt : 0;
+}
+
+/** Estimated dollars saved by cache reads versus paying the plain input price for them. */
+export const cacheSavings = (r: Row): number => Math.max(0, r.cacheBase - r.cacheActual);
+
+/** Rows for one grouping over a period, biggest cost first (ties: most tokens). */
+export async function collectGroups(
+	root: string,
+	by: GroupBy,
+	period: Period,
+	now: Date = new Date(),
+	includeCache = true,
+	opts?: UsageOptions,
+): Promise<Row[]> {
+	const since = periodStart(now.getTime(), period);
+	const rows = new Map<string, Row>();
+	for (const turns of await loadSelected(root, opts)) {
+		const seen = new Set<string>();
+		for (const t of turns) {
+			if (t.ts < since) continue;
+			const key =
+				by === "model" ? `${t.provider}/${t.model}` : by === "provider" ? t.provider : by === "project" ? t.project : t.session;
+			let r = rows.get(key);
+			if (!r) {
+				r = emptyRow(key);
+				r.provider = t.provider;
+				r.model = t.model;
+				r.project = t.project;
+				r.session = t.session;
+				rows.set(key, r);
+			}
+			r.tokens += turnTokens(t, includeCache);
+			r.input += t.input;
+			r.output += t.output;
+			r.cacheRead += t.cacheRead;
+			r.cacheWrite += t.cacheWrite;
+			r.cost += t.cost;
+			r.turns++;
+			if (t.ts < r.first) r.first = t.ts;
+			if (t.ts > r.last) r.last = t.ts;
+			if (t.input > 0 && t.costInput > 0) {
+				r.cacheBase += (t.cacheRead * t.costInput) / t.input;
+				r.cacheActual += t.costCacheRead;
+			}
+			if (!seen.has(key)) {
+				seen.add(key);
+				r.sessions++;
+			}
+			// Mixed groups (e.g. a provider with many models) keep the label only when unambiguous.
+			if (by === "provider") r.model = "";
+			if (by === "provider" || by === "model") r.project = "";
+			if (by !== "session") r.session = "";
+		}
+	}
+	return [...rows.values()].sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
+}
+
+/** Sum of rows (for a totals line). */
+export function sumRows(rows: Row[]): Row {
+	const t = emptyRow("total");
+	for (const r of rows) {
+		t.tokens += r.tokens; t.input += r.input; t.output += r.output;
+		t.cacheRead += r.cacheRead; t.cacheWrite += r.cacheWrite; t.cost += r.cost;
+		t.turns += r.turns; t.sessions += r.sessions;
+		t.cacheBase += r.cacheBase; t.cacheActual += r.cacheActual;
+		if (r.first < t.first) t.first = r.first;
+		if (r.last > t.last) t.last = r.last;
+	}
+	return t;
+}

package/extensions/features/breakdown/table.ts

@@ -0,0 +1,100 @@
+/** Usage tables (models / providers / projects / sessions) and the current-session summary. */
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import { bar, type Paint } from "../../core/paint.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import { PERIOD_TITLE, cacheHitRatio, cacheSavings, sumRows, type GroupBy, type Period, type Row } from "./query.ts";
+import { pad2 } from "../../core/time.ts";
+
+interface Col {
+	title: string;
+	align: "left" | "right";
+	cell: (r: Row, max: Row) => string;
+	foot?: (t: Row) => string;
+}
+
+const pct = (n: number) => `${Math.round(n * 100)}%`;
+const clip = (s: string, n: number) => (s.length <= n ? s : "…" + s.slice(s.length - n + 1));
+
+/** `~/x/y` for paths under home. */
+export function shortPath(p: string, home = homedir()): string {
+	return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+
+export function stamp(ts: number): string {
+	const d = new Date(ts);
+	return Number.isFinite(ts) ? `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}` : "-";
+}
+
+const tail = (): Col[] => [
+	{ title: "tokens", align: "right", cell: (r) => formatNum(r.tokens), foot: (t) => formatNum(t.tokens) },
+	{ title: "in", align: "right", cell: (r) => formatNum(r.input), foot: (t) => formatNum(t.input) },
+	{ title: "out", align: "right", cell: (r) => formatNum(r.output), foot: (t) => formatNum(t.output) },
+	{ title: "cache hit", align: "right", cell: (r) => (r.cacheRead + r.cacheWrite + r.input > 0 ? pct(cacheHitRatio(r)) : "-"), foot: (t) => pct(cacheHitRatio(t)) },
+	{ title: "cache saved", align: "right", cell: (r) => (cacheSavings(r) > 0 ? "~" + formatCost(cacheSavings(r)) : "-"), foot: (t) => (cacheSavings(t) > 0 ? "~" + formatCost(cacheSavings(t)) : "-") },
+	{ title: "cost", align: "right", cell: (r) => formatCost(r.cost), foot: (t) => formatCost(t.cost) },
+	{ title: "share", align: "left", cell: (r, max) => bar(r.cost > 0 ? r.cost : r.tokens, max.cost > 0 ? max.cost : max.tokens, 10) },
+];
+
+const COLUMNS: Record<GroupBy, () => Col[]> = {
+	model: () => [
+		{ title: "model", align: "left", cell: (r) => clip(r.model, 32), foot: () => "total" },
+		{ title: "provider", align: "left", cell: (r) => r.provider },
+		{ title: "turns", align: "right", cell: (r) => String(r.turns), foot: (t) => String(t.turns) },
+		...tail(),
+	],
+	provider: () => [
+		{ title: "provider", align: "left", cell: (r) => r.provider, foot: () => "total" },
+		{ title: "turns", align: "right", cell: (r) => String(r.turns), foot: (t) => String(t.turns) },
+		...tail(),
+	],
+	project: () => [
+		{ title: "project", align: "left", cell: (r) => clip(shortPath(r.project), 38), foot: () => "total" },
+		{ title: "sessions", align: "right", cell: (r) => String(r.sessions), foot: (t) => String(t.sessions) },
+		{ title: "turns", align: "right", cell: (r) => String(r.turns), foot: (t) => String(t.turns) },
+		...tail(),
+	],
+	session: () => [
+		{ title: "started", align: "left", cell: (r) => stamp(r.first), foot: () => "total" },
+		{ title: "project", align: "left", cell: (r) => clip(shortPath(r.project), 28) },
+		{ title: "turns", align: "right", cell: (r) => String(r.turns), foot: (t) => String(t.turns) },
+		...tail(),
+	],
+};
+
+const NOUN: Record<GroupBy, string> = { model: "Models", provider: "Providers", project: "Projects", session: "Top sessions" };
+
+/** A bordered table with a totals line. `limit` caps the rows (sessions leaderboard). */
+export function renderTable(
+	by: GroupBy,
+	rows: Row[],
+	period: Period,
+	opts: { limit?: number; filterText?: string; paint?: Paint } = {},
+): string[] {
+	const paint = opts.paint ?? ((_k, t) => t);
+	const shown = opts.limit ? rows.slice(0, opts.limit) : rows;
+	const title = `${NOUN[by]} · ${PERIOD_TITLE[period]}${opts.filterText ? ` · ${opts.filterText}` : ""}`;
+	if (rows.length === 0) return [paint("title", title), paint("dim", "no usage in this period")];
+
+	const cols = COLUMNS[by]();
+	const total = sumRows(rows);
+	const max = shown.reduce((m, r) => (r.cost > m.cost || (m.cost === 0 && r.tokens > m.tokens) ? r : m), shown[0]);
+	const body = shown.map((r) => cols.map((c) => c.cell(r, max)));
+	const foot = cols.map((c) => c.foot?.(total) ?? "");
+	const widths = cols.map((c, i) => Math.max(c.title.length, foot[i].length, ...body.map((b) => b[i].length)));
+	const fmt = (cells: string[]) =>
+		cells.map((v, i) => (cols[i].align === "right" ? v.padStart(widths[i]) : v.padEnd(widths[i]))).join("  ");
+	const rule = "─".repeat(widths.reduce((a, w) => a + w, 0) + 2 * (cols.length - 1));
+
+	const lines = [paint("title", title), paint("axis", rule), paint("dim", fmt(cols.map((c) => c.title))), paint("axis", rule), ...body.map(fmt)];
+	if (shown.length < rows.length) lines.push(paint("dim", `… ${rows.length - shown.length} more (total row covers all ${rows.length})`));
+	lines.push(paint("axis", rule), fmt(foot));
+	return lines;
+}
+
+/** Spend of one session file (the current one), against the period totals. */
+export function sessionSummary(file: string, row: Row | undefined, todayCost: number): string {
+	if (!row) return `This session (${basename(file)}): no usage yet`;
+	const share = todayCost > 0 ? `, ${pct(row.cost / todayCost)} of today` : "";
+	return `This session: ${formatNum(row.tokens)} tokens · ${formatCost(row.cost)} · ${row.turns} turns · cache hit ${pct(cacheHitRatio(row))}${share}`;
+}

package/extensions/features/budgets/budgets.ts

@@ -0,0 +1,105 @@
+/** Budgets: projection ("runs out Thu 14:05"), burn rate and threshold warnings (pure). */
+import { budgetsFor, type TokenBurnConfig } from "../../core/config.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import { bucketStart, type Unit } from "../../core/time.ts";
+import type { PeriodStats, Rate, TokenBurnReport, Window } from "../../core/types.ts";
+
+/** Burn rate from the rolling last-60-minutes stats. */
+export const burnRate = (hour: PeriodStats): Rate => ({ tokensPerHour: hour.tokens, costPerHour: hour.cost });
+
+/** Start of the bucket after the one starting at `start`. */
+export function nextBucket(start: number, unit: Exclude<Unit, "year">): number {
+	const d = new Date(start);
+	if (unit === "day") return new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+	if (unit === "week") return new Date(d.getFullYear(), d.getMonth(), d.getDate() + 7).getTime();
+	return new Date(d.getFullYear(), d.getMonth() + 1, 1).getTime();
+}
+
+export interface Projection {
+	/** used / budget, 0..n */
+	ratio: number;
+	/** When the budget runs out at the pace so far, if that is before the period ends. */
+	exhaustAt?: number;
+	/** Projected usage at the end of the period. */
+	projected: number;
+}
+
+/** Linear projection: pace = used / elapsed. Undefined when nothing has been used yet. */
+export function project(used: number, budget: number, start: number, end: number, now: number): Projection | undefined {
+	const elapsed = now - start;
+	if (!(used > 0) || !(elapsed > 0) || !(budget > 0)) return undefined;
+	const pace = used / elapsed;
+	const proj: Projection = { ratio: used / budget, projected: pace * (end - start) };
+	if (used < budget) {
+		const at = now + (budget - used) / pace;
+		if (at < end) proj.exhaustAt = at;
+	}
+	return proj;
+}
+
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** `today 14:05`, `tomorrow 09:00`, or `Thu 14:05`. */
+export function formatWhen(ts: number, now: number): string {
+	const d = new Date(ts);
+	const days = Math.round((bucketStart(ts, "day") - bucketStart(now, "day")) / 86_400_000);
+	const day = days === 0 ? "today" : days === 1 ? "tomorrow" : DAYS[d.getDay()];
+	return `${day} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+const BUDGET_WINDOWS: { w: Window; unit: Exclude<Unit, "year">; name: string }[] = [
+	{ w: "today", unit: "day", name: "daily" },
+	{ w: "week", unit: "week", name: "weekly" },
+	{ w: "month", unit: "month", name: "monthly" },
+];
+
+/** Projection lines for each configured budget, e.g. "at this pace the weekly token budget runs out Thu 14:05". */
+export function forecastLines(report: TokenBurnReport, cfg: TokenBurnConfig, now: number): string[] {
+	const lines: string[] = [];
+	for (const { w, unit, name } of BUDGET_WINDOWS) {
+		const b = budgetsFor(cfg, w);
+		const start = bucketStart(now, unit);
+		const end = nextBucket(start, unit);
+		const stat = report[w];
+		for (const kind of ["tokens", "cost"] as const) {
+			const budget = b[kind];
+			if (budget === undefined) continue;
+			const fmt = kind === "tokens" ? (n: number) => `${formatNum(n)} tokens` : formatCost;
+			const p = project(stat[kind], budget, start, end, now);
+			if (!p) continue;
+			const used = `${Math.round(p.ratio * 100)}% of ${fmt(budget)} used`;
+			if (p.ratio >= 1) lines.push(`${name} ${kind} budget: ${used} (over)`);
+			else if (p.exhaustAt !== undefined) lines.push(`${name} ${kind} budget: ${used}; at this pace it runs out ${formatWhen(p.exhaustAt, now)}`);
+			else lines.push(`${name} ${kind} budget: ${used}; on track (${fmt(p.projected)} projected)`);
+		}
+	}
+	return lines;
+}
+
+export interface Warning {
+	/** Stable id: one notification per id (budget + period bucket + level). */
+	id: string;
+	level: "warn" | "over";
+	message: string;
+}
+
+/** Budgets at or above `warnPct` percent (and those over 100%), each with a once-per-bucket id. */
+export function budgetWarnings(report: TokenBurnReport, cfg: TokenBurnConfig, now: number): Warning[] {
+	const out: Warning[] = [];
+	if (cfg.warnPct <= 0) return out;
+	for (const { w, unit, name } of BUDGET_WINDOWS) {
+		const b = budgetsFor(cfg, w);
+		const bucket = bucketStart(now, unit);
+		for (const kind of ["tokens", "cost"] as const) {
+			const budget = b[kind];
+			if (budget === undefined) continue;
+			const ratio = report[w][kind] / budget;
+			const fmt = kind === "tokens" ? (n: number) => `${formatNum(n)} tokens` : formatCost;
+			const text = `${Math.round(ratio * 100)}% of the ${name} ${kind} budget (${fmt(report[w][kind])} / ${fmt(budget)})`;
+			if (ratio > 1) out.push({ id: `${w}:${kind}:${bucket}:over`, level: "over", message: `tokenburn: over budget, ${text}` });
+			else if (ratio * 100 >= cfg.warnPct) out.push({ id: `${w}:${kind}:${bucket}:warn`, level: "warn", message: `tokenburn: ${text}` });
+		}
+	}
+	return out;
+}

package/extensions/features/budgets/commands.ts

@@ -0,0 +1,20 @@
+/** Commands: set a budget, set the warning threshold. */
+import { formatCost, formatNum } from "../../core/format.ts";
+import type { TokenBurnConfig } from "../../core/config.ts";
+import type { HandlersFor } from "../../command/host.ts";
+
+export const budgetCommands: HandlersFor<"budget" | "warn"> = {
+	async budget(cmd, { config, persist, note }) {
+		const key = `${cmd.period}${cmd.isCost ? "Cost" : "Tokens"}` as keyof TokenBurnConfig["budgets"];
+		config.budgets[key] = cmd.amount;
+		await persist();
+		note(`tokenburn ${cmd.period} budget: ${cmd.isCost ? formatCost(cmd.amount) : formatNum(cmd.amount) + " tokens"}`);
+	},
+
+	async warn(cmd, { config, persist, note, resetWarnings }) {
+		config.warnPct = cmd.pct;
+		resetWarnings();
+		await persist();
+		note(cmd.pct === 0 ? "tokenburn budget warnings: off" : `tokenburn: warning when a budget reaches ${cmd.pct}%`);
+	},
+};

package/extensions/features/export/commands.ts

@@ -0,0 +1,19 @@
+/** Command: write usage to a csv / json file. */
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getSessionsDir } from "../../core/config.ts";
+import type { HandlersFor } from "../../command/host.ts";
+import { collectExport, formatExport } from "./export.ts";
+
+export const exportCommands: HandlersFor<"export"> = {
+	async export(cmd, { usageOpts, ctx }) {
+		const rows = await collectExport(getSessionsDir(), cmd.period, new Date(), usageOpts());
+		const path = resolve(ctx.cwd ?? process.cwd(), cmd.path ?? `tokenburn-${cmd.period}.${cmd.format}`);
+		try {
+			await writeFile(path, formatExport(rows, cmd.format), "utf8");
+			ctx.ui.notify(`tokenburn: exported ${rows.length} rows (${cmd.period}) to ${path}`, "info");
+		} catch (e) {
+			ctx.ui.notify(`tokenburn: export failed: ${(e as Error).message}`, "warning");
+		}
+	},
+};

package/extensions/features/export/export.ts

@@ -0,0 +1,61 @@
+/** Export usage as CSV or JSON: one row per day x provider x model x project. */
+import { loadSelected } from "../../core/aggregate.ts";
+import type { UsageOptions } from "../../core/select.ts";
+import { periodStart, type Period } from "../breakdown/query.ts";
+import { bucketStart, pad2 } from "../../core/time.ts";
+
+export interface ExportRow {
+	date: string;
+	provider: string;
+	model: string;
+	project: string;
+	turns: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+}
+
+export const EXPORT_FORMATS = ["csv", "json"] as const;
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+
+const day = (ts: number) => {
+	const d = new Date(bucketStart(ts, "day"));
+	return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+};
+
+export async function collectExport(root: string, period: Period, now: Date = new Date(), opts?: UsageOptions): Promise<ExportRow[]> {
+	const since = periodStart(now.getTime(), period);
+	const rows = new Map<string, ExportRow>();
+	for (const turns of await loadSelected(root, opts)) {
+		for (const t of turns) {
+			if (t.ts < since) continue;
+			const date = day(t.ts);
+			const key = `${date}\u0000${t.provider}\u0000${t.model}\u0000${t.project}`;
+			let r = rows.get(key);
+			if (!r) rows.set(key, (r = { date, provider: t.provider, model: t.model, project: t.project, turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }));
+			r.turns++;
+			r.input += t.input;
+			r.output += t.output;
+			r.cacheRead += t.cacheRead;
+			r.cacheWrite += t.cacheWrite;
+			r.cost += t.cost;
+		}
+	}
+	return [...rows.values()].sort((a, b) => a.date.localeCompare(b.date) || b.cost - a.cost);
+}
+
+const FIELDS: (keyof ExportRow)[] = ["date", "provider", "model", "project", "turns", "input", "output", "cacheRead", "cacheWrite", "cost"];
+
+/** RFC 4180 quoting; also neutralises spreadsheet formula injection (=, +, -, @ at the start). */
+export function csvCell(v: string | number): string {
+	let s = typeof v === "number" ? (Number.isInteger(v) ? String(v) : v.toFixed(6)) : v;
+	if (typeof v === "string" && /^[=+\-@\t\r]/.test(s)) s = "'" + s;
+	return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+export function formatExport(rows: ExportRow[], format: ExportFormat): string {
+	if (format === "json") return JSON.stringify(rows, null, 2) + "\n";
+	return [FIELDS.join(","), ...rows.map((r) => FIELDS.map((f) => csvCell(r[f])).join(","))].join("\n") + "\n";
+}

package/extensions/features/filter/commands.ts

@@ -0,0 +1,18 @@
+/** Command: limit everything to a provider / model / project. */
+import { describeFilter, hasFilter } from "../../core/select.ts";
+import type { HandlersFor } from "../../command/host.ts";
+
+export const filterCommands: HandlersFor<"filter"> = {
+	async filter(cmd, { config, persist, note, ctx }) {
+		if (cmd.clear) config.filter = {};
+		else if (cmd.key) {
+			if (cmd.value === undefined) delete config.filter[cmd.key];
+			else config.filter[cmd.key] = cmd.value;
+		} else {
+			ctx.ui.notify(hasFilter(config.filter) ? `tokenburn filter: ${describeFilter(config.filter)}` : "tokenburn filter: none (all providers, models and projects)", "info");
+			return;
+		}
+		await persist();
+		note(hasFilter(config.filter) ? `tokenburn filter: ${describeFilter(config.filter)}` : "tokenburn filter cleared: showing everything");
+	},
+};

package/extensions/features/live/coalescer.ts

@@ -0,0 +1,71 @@
+/** Live refresh scheduling. */
+
+export interface Timers {
+	set: (fn: () => void, ms: number) => unknown;
+	clear: (handle: unknown) => void;
+}
+
+const realTimers: Timers = {
+	set: (fn, ms) => setTimeout(fn, ms),
+	clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+};
+
+/**
+ * Runs `run` at most once per `delayMs` window however often `schedule()` is called
+ * (trailing edge), and never two runs at once: a request that arrives mid-run triggers one
+ * more run afterwards. A burst of 50 messages costs one refresh. Failures are swallowed;
+ * the timer never keeps the process alive.
+ */
+export function createCoalescer(
+	run: () => Promise<void>,
+	delayMs: number | (() => number),
+	timers: Timers = realTimers,
+) {
+	let timer: unknown;
+	let running = false;
+	let dirty = false;
+
+	const execute = async () => {
+		if (running) {
+			dirty = true;
+			return;
+		}
+		running = true;
+		try {
+			await run();
+		} catch {
+			/* a failed refresh must never surface */
+		} finally {
+			running = false;
+		}
+		if (dirty) {
+			dirty = false;
+			schedule();
+		}
+	};
+
+	const schedule = () => {
+		if (timer !== undefined) return; // one is already pending: coalesce
+		const ms = typeof delayMs === "function" ? delayMs() : delayMs;
+		timer = timers.set(() => {
+			timer = undefined;
+			void execute();
+		}, ms);
+		(timer as { unref?: () => void } | undefined)?.unref?.();
+	};
+
+	const cancel = () => {
+		if (timer !== undefined) timers.clear(timer);
+		timer = undefined;
+		dirty = false;
+	};
+
+	/** Run now (dropping any pending delayed run). */
+	const flush = () => {
+		if (timer !== undefined) timers.clear(timer);
+		timer = undefined;
+		return execute();
+	};
+
+	return { schedule, cancel, flush, isPending: () => timer !== undefined };
+}

package/extensions/features/pricing/commands.ts

@@ -0,0 +1,30 @@
+/** Commands: where costs come from, and the price table. */
+import { getSessionsDir } from "../../core/config.ts";
+import { sanitizePrices } from "../../core/select.ts";
+import type { HandlersFor } from "../../command/host.ts";
+import { collectPricing, renderPricing } from "./report.ts";
+
+export const pricingCommands: HandlersFor<"pricing" | "price"> = {
+	async pricing(cmd, { config, persist, ctx }) {
+		if (cmd.mode) {
+			config.priceMode = cmd.mode;
+			await persist();
+		}
+		const rep = await collectPricing(getSessionsDir(), config.prices, config.priceMode, config.filter);
+		ctx.ui.notify(renderPricing(rep, config.prices, config.priceMode).join("\n"), "info");
+	},
+
+	async price(cmd, { config, persist, note }) {
+		if (cmd.remove) {
+			const had = cmd.model in config.prices;
+			delete config.prices[cmd.model];
+			await persist();
+			note(had ? `tokenburn: removed price for ${cmd.model}` : `tokenburn: no price for ${cmd.model}`);
+			return;
+		}
+		const next = sanitizePrices({ [cmd.model]: { input: cmd.input, output: cmd.output, cacheRead: cmd.cacheRead, cacheWrite: cmd.cacheWrite } });
+		Object.assign(config.prices, next);
+		await persist();
+		note(`tokenburn: price for ${cmd.model} set ($/M in ${cmd.input}, out ${cmd.output}); mode ${config.priceMode}`);
+	},
+};

package/extensions/features/pricing/report.ts

@@ -0,0 +1,59 @@
+/** Where costs come from: the session logs or the configured price table. */
+import { loadAll } from "../../core/parser.ts";
+import { applyPricing, matchesFilter, type PriceMode, type PriceTable, type UsageFilter } from "../../core/select.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+
+export interface PricingReport {
+	logCost: number;
+	logTurns: number;
+	tableCost: number;
+	tableTurns: number;
+	/** Models with token usage but no cost and no price entry: their cost is counted as $0. */
+	unpriced: { model: string; tokens: number; turns: number }[];
+}
+
+export async function collectPricing(root: string, prices: PriceTable, mode: PriceMode, filter?: UsageFilter): Promise<PricingReport> {
+	const rep: PricingReport = { logCost: 0, logTurns: 0, tableCost: 0, tableTurns: 0, unpriced: [] };
+	const un = new Map<string, { model: string; tokens: number; turns: number }>();
+	for (const turns of await loadAll(root)) {
+		for (const raw of turns) {
+			if (!matchesFilter(raw, filter)) continue;
+			const { turn, source } = applyPricing(raw, prices, mode);
+			if (source === "table") {
+				rep.tableCost += turn.cost;
+				rep.tableTurns++;
+				continue;
+			}
+			rep.logCost += turn.cost;
+			rep.logTurns++;
+			const tokens = turn.input + turn.output + turn.cacheRead + turn.cacheWrite;
+			if (turn.cost === 0 && tokens > 0) {
+				const key = `${turn.provider}/${turn.model}`;
+				const u = un.get(key) ?? { model: key, tokens: 0, turns: 0 };
+				u.tokens += tokens;
+				u.turns++;
+				un.set(key, u);
+			}
+		}
+	}
+	rep.unpriced = [...un.values()].sort((a, b) => b.tokens - a.tokens);
+	return rep;
+}
+
+export function renderPricing(rep: PricingReport, prices: PriceTable, mode: PriceMode): string[] {
+	const entries = Object.entries(prices);
+	const lines = [
+		`Pricing · mode ${mode} (${mode === "fill" ? "price table only fills turns the log has no cost for" : "price table overrides the log cost"})`,
+		`cost from session logs: ${formatCost(rep.logCost)} (${rep.logTurns} turns)`,
+		`cost from price table:  ${formatCost(rep.tableCost)} (${rep.tableTurns} turns)`,
+	];
+	if (entries.length > 0) {
+		lines.push("price table ($ per million tokens: in / out / cache read / cache write):");
+		for (const [name, p] of entries) lines.push(`  ${name}: ${p.input} / ${p.output} / ${p.cacheRead} / ${p.cacheWrite}`);
+	} else lines.push("price table: empty. /tokenburn price <model> <in> <out> [cacheRead] [cacheWrite]");
+	if (rep.unpriced.length > 0) {
+		lines.push("unpriced (tokens but $0, counted as free; add a price):");
+		for (const u of rep.unpriced.slice(0, 8)) lines.push(`  ${u.model}: ${formatNum(u.tokens)} tokens in ${u.turns} turns`);
+	}
+	return lines;
+}