pi-tokenburn 0.5.8 → 0.6.0

package/extensions/features/report/chart.ts

@@ -0,0 +1,96 @@
+/** Terminal chart rendering. */
+import { SPARK, type Paint } from "../../core/paint.ts";
+import { isOverBudget } from "../../core/config.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import { bucketLabel, pad2, type Unit } from "../../core/time.ts";
+import type { SeriesPoint } from "../../core/aggregate.ts";
+import type { PeriodStats } from "../../core/types.ts";
+
+const UNIT_TITLE: Record<Unit, string> = { day: "Daily", week: "Weekly", month: "Monthly", year: "Yearly" };
+const UNIT_NOUN: Record<Unit, string> = { day: "day", week: "week", month: "month", year: "year" };
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+const plain: Paint = (_k, t) => t;
+
+/** Two header rows for a column: [top, bottom]. */
+function columnLabels(p: SeriesPoint, unit: Unit): [string, string] {
+	const d = new Date(p.start);
+	// `?? ""`: an invalid date (NaN) has no weekday or month name.
+	if (unit === "day") return [pad2(d.getDate()), ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"][d.getDay()] ?? ""];
+	if (unit === "week") return [`${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`, "wk"];
+	if (unit === "year") return [String(d.getFullYear()), ""];
+	return [MONTHS[d.getMonth()] ?? "", String(d.getFullYear())];
+}
+
+/**
+ * Vertical column chart: y-axis, 1/8-row precision, optional budget line,
+ * highlighted current bucket and over-budget columns, summary footer.
+ */
+export function renderChart(
+	series: SeriesPoint[],
+	unit: Unit,
+	opts: { height?: number; budget?: { tokens?: number; cost?: number }; paint?: Paint; title?: string } = {},
+): string[] {
+	const paint = opts.paint ?? plain;
+	const height = opts.height ?? 8;
+	const colW = unit === "day" ? 3 : 6; // bar cells + 1 gap
+	const barW = colW - 1;
+
+	const peakPoint = series.reduce((m, p) => (p.tokens > m.tokens ? p : m), series[0]);
+	const dataMax = peakPoint?.tokens ?? 0;
+	const budgetTokens = opts.budget?.tokens;
+	const scaleMax = Math.max(dataMax, budgetTokens ?? 0);
+	const total = series.reduce((a, p) => a + p.tokens, 0);
+	const totalCost = series.reduce((a, p) => a + p.cost, 0);
+
+	const yLabels = [formatNum(scaleMax), formatNum(scaleMax / 2), "0"];
+	const yW = Math.max(...yLabels.map((l) => l.length)) + 1;
+	const labelFor = (row: number) => (row === height ? yLabels[0] : row === Math.ceil(height / 2) ? yLabels[1] : "");
+	const budgetRow = budgetTokens && scaleMax > 0 ? Math.max(1, Math.ceil((budgetTokens / scaleMax) * height)) : 0;
+
+	const isOver = (p: SeriesPoint) =>
+		opts.budget ? isOverBudget({ tokens: p.tokens, cost: p.cost } as PeriodStats, opts.budget) : false;
+	const kindOf = (i: number): "bar" | "now" | "over" =>
+		isOver(series[i]) ? "over" : i === series.length - 1 ? "now" : "bar";
+
+	const lines: string[] = [];
+	lines.push(
+		paint("title", opts.title ?? `${UNIT_TITLE[unit]} tokens`) +
+			paint("dim", ` · ${opts.title ? "" : "last "}${series.length} ${UNIT_NOUN[unit]}${series.length === 1 ? "" : "s"}`) +
+			(budgetTokens ? paint("budget", `  ┄ budget ${formatNum(budgetTokens)}`) : ""),
+	);
+
+	for (let row = height; row >= 1; row--) {
+		let line = paint("axis", `${labelFor(row).padStart(yW)} │`);
+		for (let i = 0; i < series.length; i++) {
+			const h = scaleMax > 0 ? (series[i].tokens / scaleMax) * height : 0;
+			let cell: string;
+			if (h >= row) cell = "█";
+			else if (h > row - 1 && series[i].tokens > 0) cell = SPARK[Math.min(7, Math.max(0, Math.floor((h - (row - 1)) * 8) - 1))];
+			else if (row === 1 && series[i].tokens > 0) cell = "▁";
+			else cell = row === budgetRow ? "┄" : " ";
+			const filled = cell !== " " && cell !== "┄";
+			const body = cell.repeat(barW);
+			line += filled ? paint(kindOf(i), body) : cell === "┄" ? paint("budget", body) : body;
+			line += row === budgetRow ? paint("budget", "┄") : " ";
+		}
+		lines.push(line);
+	}
+
+	lines.push(paint("axis", `${"".padStart(yW)} └${"─".repeat(series.length * colW)}`));
+	const pad = " ".repeat(yW + 2);
+	const cols = series.map((p, i) => ({ l: columnLabels(p, unit), now: i === series.length - 1 }));
+	lines.push(pad + cols.map((c) => c.l[0].padEnd(colW)).join(""));
+	lines.push(paint("dim", pad + cols.map((c) => c.l[1].padEnd(colW)).join("")));
+	lines.push(pad + cols.map((c) => (c.now ? paint("now", "▲".padEnd(colW)) : " ".repeat(colW))).join(""));
+
+	const avg = series.length ? total / series.length : 0;
+	lines.push(
+		paint(
+			"dim",
+			`Σ ${formatNum(total)} (${formatCost(totalCost)}) · avg ${formatNum(avg)}/${UNIT_NOUN[unit]}` +
+				(dataMax > 0 ? ` · peak ${formatNum(dataMax)} (${bucketLabel(peakPoint.start, unit)})` : ""),
+		),
+	);
+	return lines;
+}

package/extensions/features/report/commands.ts

@@ -0,0 +1,33 @@
+/** Command: the summary report with a chart. */
+import { collectAllSeries, collectSeries, collectUsage, DEFAULT_COUNT } from "../../core/aggregate.ts";
+import { budgetsFor, getSessionsDir } from "../../core/config.ts";
+import { themePaint } from "../../core/paint.ts";
+import { describeFilter } from "../../core/select.ts";
+import type { Window } from "../../core/types.ts";
+import type { HandlersFor } from "../../command/host.ts";
+import { collectGroups, sumRows } from "../breakdown/query.ts";
+import { renderChart } from "./chart.ts";
+import { renderReport } from "./report.ts";
+
+export const reportCommands: HandlersFor<"report"> = {
+	async report(cmd, { config, usageOpts, ctx }) {
+		const root = getSessionsDir();
+		const now = new Date();
+		const opts = usageOpts();
+		const report = await collectUsage(root, now, config.includeCache, opts);
+		const paint = config.chartColor ? themePaint(ctx.ui.theme) : undefined;
+
+		let chart: string[];
+		if (cmd.view === "all") {
+			const all = await collectAllSeries(root, now, config.includeCache, opts);
+			chart = renderChart(all.series, all.unit, { paint, title: "All time" });
+		} else {
+			const series = await collectSeries(root, cmd.view, DEFAULT_COUNT[cmd.view], now, config.includeCache, opts);
+			const budgetWindow: Window | undefined = cmd.view === "day" ? "today" : cmd.view === "year" ? undefined : cmd.view;
+			chart = renderChart(series, cmd.view, { paint, budget: budgetWindow ? budgetsFor(config, budgetWindow) : undefined });
+		}
+
+		const models = sumRows(await collectGroups(root, "model", "all", now, config.includeCache, opts));
+		ctx.ui.notify(renderReport({ report, chart, models, config, now: now.getTime(), filterText: describeFilter(opts.filter) }).join("\n"), "info");
+	},
+};

package/extensions/features/report/report.ts

@@ -0,0 +1,47 @@
+/** The text of the `/tokenburn` summary report (pure). */
+import type { TokenBurnConfig } from "../../core/config.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import type { PeriodStats, TokenBurnReport } from "../../core/types.ts";
+import { burnRate, forecastLines } from "../budgets/budgets.ts";
+import { cacheHitRatio, cacheSavings, type Row } from "../breakdown/query.ts";
+
+const row = (name: string, p: PeriodStats) =>
+	`${name.padEnd(10)} ${formatNum(p.tokens).padStart(8)} tokens ${formatCost(p.cost).padStart(9)} · in:${formatNum(p.input)} out:${formatNum(p.output)} cache:${formatNum(p.cacheRead + p.cacheWrite)} · ${p.sessions} sess`;
+
+const FOOTER = "models · providers · projects · sessions · session · filter · export · pricing · chart <view> · <view> sets the status bar · cycle · window · budget · cache · live · on|off";
+
+export function renderReport(input: {
+	report: TokenBurnReport;
+	chart: string[];
+	/** All-time totals over every model (cache efficiency). */
+	models: Row;
+	config: TokenBurnConfig;
+	now: number;
+	filterText: string;
+}): string[] {
+	const { report, chart, models, config, now, filterText } = input;
+	const rule = "─".repeat(60);
+	const rate = burnRate(report.hour);
+	const extra = [
+		`burn rate: ${formatNum(rate.tokensPerHour)} tokens/h · ${formatCost(rate.costPerHour)}/h (last 60 min)`,
+		...(models.cacheRead + models.cacheWrite > 0
+			? [`cache: ${Math.round(cacheHitRatio(models) * 100)}% of prompt tokens read from cache${cacheSavings(models) > 0 ? ` · saved ~${formatCost(cacheSavings(models))}` : ""}`]
+			: []),
+		...forecastLines(report, config, now),
+	];
+	return [
+		`🔥 TokenBurn Report${filterText ? ` · ${filterText}` : ""}`,
+		rule,
+		row("Today", report.today),
+		row("This Week", report.week),
+		row("This Month", report.month),
+		row("This Year", report.year),
+		row("All Time", report.total),
+		rule,
+		...chart,
+		rule,
+		...extra,
+		rule,
+		FOOTER,
+	];
+}

package/extensions/features/status-line/commands.ts

@@ -0,0 +1,78 @@
+/** Commands that change what the status line shows and how tokenburn runs. */
+import { STATUS_WINDOWS } from "../../core/types.ts";
+import type { HandlersFor } from "../../command/host.ts";
+
+const onOff = (v: boolean) => (v ? "on" : "off");
+
+export const statusLineCommands: HandlersFor<"window" | "status" | "cycle" | "cache" | "live" | "enable" | "disable" | "rate" | "hit" | "saved"> = {
+	async window(_cmd, { config, persist, note }) {
+		config.showWidget = !config.showWidget;
+		await persist();
+		note(`tokenburn widget: ${config.showWidget ? "enabled" : "hidden"}`);
+	},
+
+	async status(cmd, { config, persist, note }) {
+		config.statusWindow = cmd.window;
+		await persist();
+		note(`tokenburn status window: ${cmd.window}`);
+	},
+
+	async cycle(_cmd, { config, persist, note }) {
+		const next = STATUS_WINDOWS[(STATUS_WINDOWS.indexOf(config.statusWindow) + 1) % STATUS_WINDOWS.length];
+		config.statusWindow = next;
+		await persist();
+		note(`tokenburn status window: ${next}`);
+	},
+
+	async cache(_cmd, { config, persist, note }) {
+		config.includeCache = !config.includeCache;
+		await persist();
+		note(`tokenburn: cache tokens ${config.includeCache ? "included" : "excluded"}`);
+	},
+
+	async live(_cmd, { config, persist, note, cancelRefresh }) {
+		config.liveRefresh = !config.liveRefresh;
+		if (!config.liveRefresh) cancelRefresh();
+		await persist();
+		note(`tokenburn live refresh ${config.liveRefresh ? "on (after each assistant message)" : "off (only when a turn ends)"}`);
+	},
+
+	async enable(_cmd, { config, persist, ctx }) {
+		if (config.enabled) {
+			ctx.ui.notify("tokenburn is already enabled", "info");
+			return;
+		}
+		config.enabled = true;
+		await persist();
+		ctx.ui.notify("tokenburn enabled", "info");
+	},
+
+	async disable(_cmd, { config, persist, ctx, cancelRefresh }) {
+		if (!config.enabled) {
+			ctx.ui.notify("tokenburn is already disabled", "info");
+			return;
+		}
+		config.enabled = false;
+		cancelRefresh();
+		await persist(); // clears the status line and the panel
+		ctx.ui.notify("tokenburn disabled: nothing runs in the background. /tokenburn enable turns it back on (charts still work on demand)", "info");
+	},
+
+	async rate(_cmd, { config, persist, note }) {
+		config.showRate = !config.showRate;
+		await persist();
+		note(`tokenburn burn rate in the status line: ${onOff(config.showRate)}`);
+	},
+
+	async hit(_cmd, { config, persist, note }) {
+		config.showHit = !config.showHit;
+		await persist();
+		note(`tokenburn cache hit ratio in the status line: ${onOff(config.showHit)}`);
+	},
+
+	async saved(_cmd, { config, persist, note }) {
+		config.showSaved = !config.showSaved;
+		await persist();
+		note(`tokenburn estimated cache savings in the status line: ${onOff(config.showSaved)}`);
+	},
+};

package/extensions/features/status-line/render.ts

@@ -0,0 +1,43 @@
+/** What the status line and the optional panel look like. */
+import { budgetsFor, isOverBudget, type TokenBurnConfig } from "../../core/config.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import { describeFilter } from "../../core/select.ts";
+import type { PeriodStats, TokenBurnReport } from "../../core/types.ts";
+import { statusExtras } from "./status.ts";
+
+type Theme = { fg: (color: any, text: string) => string };
+
+/** `🔥 1.2M ($5.10) [today] · 52k/h · 95% hit · ~$12.40 saved` (red `OVER BUDGET` past a budget). */
+export function renderStatusLine(report: TokenBurnReport, config: TokenBurnConfig, theme: Theme, now: number): string {
+	const stat = report[config.statusWindow];
+	const isOver = isOverBudget(stat, budgetsFor(config, config.statusWindow));
+	const fire = isOver ? theme.fg("error", "🔥 OVER BUDGET") : theme.fg("warning", "🔥");
+	const tokensText = theme.fg(isOver ? "error" : "accent", formatNum(stat.tokens));
+	const costText = theme.fg("dim", `(${formatCost(stat.cost)})`);
+	const filterText = describeFilter(config.filter);
+	const label = theme.fg("dim", `[${config.statusWindow}${filterText ? ` · ${filterText}` : ""}]`);
+	const extras = statusExtras(report, config, now);
+	const tail = extras.length > 0 ? theme.fg("dim", ` · ${extras.join(" · ")}`) : "";
+	return `${fire} ${tokensText} ${costText} ${label}${tail}`;
+}
+
+/** The Today / Week / Month / Year / Total panel below the editor. */
+export function renderWidget(report: TokenBurnReport, config: TokenBurnConfig, theme: Theme): string[] {
+	const header = theme.fg("accent", " 🔥 TokenBurn Dashboard ");
+	const line = (label: string, p: PeriodStats, b: { tokens?: number; cost?: number } = {}) => {
+		const over = isOverBudget(p, b);
+		const tokStr = (over ? theme.fg("error", "!") : " ") + formatNum(p.tokens).padStart(8);
+		const inStr = `(in:${formatNum(p.input)} out:${formatNum(p.output)})`.padEnd(20);
+		const costStr = formatCost(p.cost).padStart(8);
+		return `  ${theme.fg("muted", label.padEnd(8))} ${tokStr}  ${theme.fg("dim", inStr)} ${costStr}`;
+	};
+	return [
+		`┌${header}${"─".repeat(21)}┐`,
+		line("Today", report.today, budgetsFor(config, "today")),
+		line("Week", report.week, budgetsFor(config, "week")),
+		line("Month", report.month, budgetsFor(config, "month")),
+		line("Year", report.year),
+		line("Total", report.total),
+		`└${"─".repeat(46)}┘`,
+	];
+}

package/extensions/features/status-line/status.ts

@@ -0,0 +1,35 @@
+/** Status line: window start, burn rate / cache hit / savings extras for the status window (pure). */
+import type { TokenBurnConfig } from "../../core/config.ts";
+import { formatCost, formatNum } from "../../core/format.ts";
+import { bucketStart } from "../../core/time.ts";
+import type { PeriodStats, Rate, TokenBurnReport, Window } from "../../core/types.ts";
+import { cacheHitRatio } from "../breakdown/query.ts";
+
+const HOUR = 3_600_000;
+
+/** Start of a status window (`hour` = rolling last 60 minutes, `total` = 0). */
+export function windowStart(w: Window, now: number): number {
+	if (w === "hour") return now - HOUR;
+	if (w === "total") return 0;
+	return bucketStart(now, w === "today" ? "day" : w);
+}
+
+/** Tokens/hour and $/hour averaged over the window (counted from the first turn when the window started earlier; at least one hour). */
+export function windowRate(stat: PeriodStats, w: Window, firstTs: number | undefined, now: number): Rate {
+	const from = Math.max(windowStart(w, now), firstTs ?? now);
+	const hours = Math.max((now - from) / HOUR, 1);
+	return { tokensPerHour: stat.tokens / hours, costPerHour: stat.cost / hours };
+}
+
+/** Estimated dollars saved by cache reads in a window. */
+export const statSavings = (s: PeriodStats): number => Math.max(0, s.cacheBase - s.cacheActual);
+
+/** Status-line extras for the window, in order: burn rate, cache hit ratio, cache savings (each only when enabled and meaningful). */
+export function statusExtras(report: TokenBurnReport, cfg: TokenBurnConfig, now: number): string[] {
+	const stat = report[cfg.statusWindow];
+	const out: string[] = [];
+	if (cfg.showRate && stat.tokens > 0) out.push(`${formatNum(windowRate(stat, cfg.statusWindow, report.firstTs, now).tokensPerHour)}/h`);
+	if (cfg.showHit && stat.input + stat.cacheRead + stat.cacheWrite > 0) out.push(`${Math.round(cacheHitRatio(stat) * 100)}% hit`);
+	if (cfg.showSaved && statSavings(stat) >= 0.005) out.push(`~${formatCost(statSavings(stat))} saved`);
+	return out;
+}