pi-tokenburn 0.5.8 → 0.7.0

package/README.md

@@ -15,7 +15,10 @@ Totals match the `tokenburn` CLI exactly.
 
 ## Features
 
-- **Status bar:** `🔥 1.20M ($52.79) [today]`, turns red with `OVER BUDGET` past your limit.
+- **Status bar:** `🔥 1.2M ($5.10) [today] · 52k/h · 95% hit · ~$12.40 saved`: tokens, cost, burn rate, cache hit ratio and estimated cache savings for the chosen period (each extra toggleable). Turns red with `OVER BUDGET` past your limit.
+- **Tables:** usage per model, provider, project and session, for any period, with cache hit %, savings, cost and share.
+- **Filter and export:** limit everything to a provider, model or project; write csv or json.
+- **Pricing:** a price table fills in (or overrides) costs the logs don't have.
 - **Report chart:** `/tokenburn` shows the summary plus a vertical column chart (y-axis, budget line, current period marked, over-budget columns in red, peak/avg footer). Daily (14 days), weekly (8 weeks) or monthly (6 months).
 - **Status line:** `/tokenburn day|week|month|year|all` (or `cycle`) changes the period shown at the bottom. Charts live under `/tokenburn chart <view>`.
 - **Window panel (optional):** Today / Week / Month / Total below the editor, with in/out tokens and cost.
@@ -46,6 +49,20 @@ pi install git:github.com/sorinirimies/pi-tokenburn
 | `/tokenburn` | Report + daily chart (same as `/tokenburn chart day`) |
 | `/tokenburn cycle` | Rotate the status line: today → week → month → year → total |
 | `/tokenburn status <today\|week\|month\|year\|total>` | Explicit form of the first row |
+| `/tokenburn models hour|day|week|month|year|all` | **Table** of usage per model (tokens, in/out, cache hit %, cache savings, cost, share). Period (optional): `hour` (last 60 min), `day`, `week`, `month`, `year`, `all` (default `all`) |
+| `/tokenburn providers hour|day|week|month|year|all` | Same table per provider |
+| `/tokenburn projects hour|day|week|month|year|all` | Same table per project (session working directory); all projects by default |
+| `/tokenburn sessions hour|day|week|month|year|all` | Leaderboard of the `n` (default 10) costliest sessions |
+| `/tokenburn session` | Spend of the **current** session, and its share of today |
+| `/tokenburn filter <provider\|model\|project> <value>` | Limit everything (status line, report, tables, export) to matching usage (case-insensitive substring). `filter` shows it, `filter all` clears it |
+| `/tokenburn export csv|json` | Optional `[period]` and `[path]` follow the format. Writes one row per day × provider × model × project (default `tokenburn-<period>.<format>` in the current directory) |
+| `/tokenburn warn <pct>` | Notify once when a budget reaches `pct` percent (default 80) and once when it is exceeded |
+| `/tokenburn rate` | Toggle the burn rate in the status line (`42k/h`: tokens per hour averaged over the status period) |
+| `/tokenburn hit` | Toggle the cache hit ratio (`95% hit`) in the status line |
+| `/tokenburn saved` | Toggle the estimated cache savings (`~$12.40 saved`) in the status line |
+| `/tokenburn hour` | Show the last 60 minutes in the status line (joins `day`, `week`, `month`, `year`, `all`) |
+| `/tokenburn pricing` | Where costs come from (session logs vs your price table) and which models are unpriced |
+| `/tokenburn price <model> <in> <out>` | Set a price in $ per million tokens (key `model` or `provider/model`); `price remove <model>` deletes it. `pricing mode <fill\|override>`: use the table only where the log has no cost (default), or always |
 | `/tokenburn window` | Toggle the panel below the editor |
 | `/tokenburn budget <day\|week\|month> <tokens>` | Token budget, e.g. `budget day 5000000` |
 | `/tokenburn budget <day\|week\|month> $<cost>` | Dollar budget, e.g. `budget week $50` |
@@ -58,9 +75,9 @@ pi install git:github.com/sorinirimies/pi-tokenburn
 
 Recorded from a real pi with only this plugin loaded, on synthetic data.
 
-**Switch what the bottom line shows** (`/tokenburn day|week|month|year|all`, or `cycle`):
+**Switch what the bottom line shows** (`/tokenburn hour|day|week|month|year|all`, or `cycle`):
 
-![Status line: week, month, year, all, day, then cycle](examples/vhs/generated/status.gif)
+![Status line: week, month, year, all, day, then cycle through every period](examples/vhs/generated/status.gif)
 
 **Charts** (`/tokenburn chart day|week|month|year|all`): the current period is green, with a peak and average footer:
 
@@ -78,6 +95,22 @@ Recorded from a real pi with only this plugin loaded, on synthetic data.
 
 ![Disable clears the footer, a chart still works, enable brings it back](examples/vhs/generated/enable-disable.gif)
 
+**Tables** (`/tokenburn models week`, `providers month`, `projects`, `sessions week 5`): who spends what, with cache hit %, estimated savings and share:
+
+![Tables: models, providers, projects and sessions](examples/vhs/generated/tables.gif)
+
+**Filter and export** (`/tokenburn filter model acme-large`, `export csv week usage.csv`): the footer, tables and the file all follow the filter:
+
+![Filter to one model, see it in the table, export csv, clear the filter](examples/vhs/generated/filter-export.gif)
+
+**Footer extras** (`/tokenburn hour`, `rate`, `hit`, `saved`): the burn rate, cache hit ratio and cache savings follow the chosen period, and each can be switched off:
+
+![Footer: hour and week periods, rate, hit and saved toggled off and on](examples/vhs/generated/statusline.gif)
+
+**Pricing** (`/tokenburn pricing`, `price acme-large 3 15 0.3 3.75`): where costs come from, and a price table that can fill in or override them:
+
+![Pricing: cost sources, set a price, switch to override](examples/vhs/generated/pricing.gif)
+
 **Tab-completion** uses pi's own menu, with a description for every option:
 
 ![Autocomplete for /tokenburn and its chart sub-menu](examples/vhs/generated/completion.gif)
@@ -142,7 +175,7 @@ Refreshing is designed to cost nothing you can notice:
 
 ## Demo recordings
 
-The GIFs above live in [`examples/vhs/generated/`](examples/vhs/generated) and are stored with **Git LFS** (`git lfs install` once). They are recorded with [VHS](https://github.com/charmbracelet/vhs) from a **real pi** that loads only this extension, on **synthetic** data (`examples/vhs/fixture.sh`: 900 days of made-up sessions in `/tmp` with deliberately small numbers, and a local mock model for the live-refresh demo), never from real logs, paths or credentials:
+The GIFs above live in [`examples/vhs/generated/`](examples/vhs/generated) and are stored with **Git LFS** (`git lfs install` once). They are recorded with [VHS](https://github.com/charmbracelet/vhs) from a **real pi** that loads only this extension, on **synthetic** data (`examples/vhs/fixture.sh`: 900 days of made-up sessions across fictional projects, providers and models in `/tmp`, with deliberately small numbers, and a local mock model for the live-refresh demo), never from real logs, paths or credentials:
 
 ```sh
 just vhs-all          # every tape (examples/vhs/*.tape): needs vhs, ttyd, ffmpeg, pi, bun, python3
@@ -169,6 +202,28 @@ just push-all       # push main to every configured remote (origin + the Gitea i
 
 **Coverage:** every `bun test` collects coverage (`bunfig.toml`) and **fails below 95% lines / 95% functions**. CI shows the table on the run page and uploads `lcov.info`.
 
+### Code layout
+
+One folder per feature under `extensions/features/`, each with its logic and its `/tokenburn` commands:
+
+```
+extensions/
+  tokenburn.ts            wiring only: pi events + the /tokenburn command
+  core/                   types, config, session-log parser (incremental cache), aggregation, filters + prices, paint
+  command/                parse + completions (pure), handler table, the Host handlers receive
+  features/
+    status-line/          footer text, optional panel, burn rate / cache hit / savings
+    report/               the /tokenburn summary and the column charts
+    budgets/              budgets, projection ("runs out Thu 14:05"), one-time warnings
+    breakdown/            tables per model / provider / project / session, current session
+    filter/               limit everything to a provider / model / project
+    pricing/              cost sources, price table
+    export/               csv / json
+    live/                 refresh scheduling
+```
+
+To add a command: add its kind to `command/parse.ts`, a handler in the owning feature's `commands.ts` (the `Handlers` type makes a missing one a compile error), and a test.
+
 CI scripts are [nushell](https://www.nushell.sh) (`scripts/`), the same ones locally and in GitHub / Gitea Actions.
 `just --list` shows every task.
 

package/extensions/command/completions.ts

@@ -0,0 +1,80 @@
+/** Tab-completion for /tokenburn (pure, unit-tested). */
+import { EXPORT_FORMATS } from "../features/export/export.ts";
+import { FILTER_KEYS_LIST } from "../core/select.ts";
+import { PERIOD_ALIASES } from "../features/breakdown/query.ts";
+import { STATUS_WINDOWS } from "../core/types.ts";
+import { BUDGET_PERIODS, REPORT_VIEWS, type ReportView } from "./parse.ts";
+
+export interface CompletionItem {
+	value: string;
+	/** Required by pi: it calls `label.endsWith(...)` when applying a completion. */
+	label: string;
+	description?: string;
+}
+
+const CHART_SPAN: Record<ReportView, string> = {
+	day: "last 14 days",
+	week: "last 8 weeks",
+	month: "last 6 months",
+	year: "last 5 years",
+	all: "whole history",
+};
+
+const TOP_LEVEL: CompletionItem[] = [
+	{ value: "hour", label: "hour", description: "Status bar: last 60 minutes" },
+	{ value: "day", label: "day", description: "Status bar: today" },
+	{ value: "week", label: "week", description: "Status bar: this week" },
+	{ value: "month", label: "month", description: "Status bar: this month" },
+	{ value: "year", label: "year", description: "Status bar: this year" },
+	{ value: "all", label: "all", description: "Status bar: all-time total" },
+	{ value: "chart ", label: "chart", description: "Report + chart: day, week, month, year or all" },
+	{ value: "status ", label: "status", description: "Set the status-bar period explicitly" },
+	{ value: "models ", label: "models", description: "Table: usage per model (default all time)" },
+	{ value: "providers ", label: "providers", description: "Table: usage per provider" },
+	{ value: "projects ", label: "projects", description: "Table: usage per project (default all projects)" },
+	{ value: "sessions ", label: "sessions", description: "Leaderboard: costliest sessions" },
+	{ value: "session", label: "session", description: "Spend of the current session" },
+	{ value: "filter ", label: "filter", description: "Limit everything to a provider / model / project" },
+	{ value: "export ", label: "export", description: "Write usage to a csv or json file" },
+	{ value: "warn ", label: "warn", description: "Budget warning threshold in percent (or off)" },
+	{ value: "pricing", label: "pricing", description: "Where costs come from; price table status" },
+	{ value: "price ", label: "price", description: "Set a $/M-token price for a model" },
+	{ value: "rate", label: "rate", description: "Toggle the tokens/hour burn rate in the status line" },
+	{ value: "hit", label: "hit", description: "Toggle the cache hit ratio in the status line" },
+	{ value: "saved", label: "saved", description: "Toggle the estimated cache savings in the status line" },
+	{ value: "cycle", label: "cycle", description: "Rotate the status-bar period" },
+	{ value: "window", label: "window", description: "Toggle the panel below the editor" },
+	{ value: "budget ", label: "budget", description: "Set a day/week/month budget" },
+	{ value: "cache", label: "cache", description: "Toggle counting cache tokens" },
+	{ value: "live", label: "live", description: "Toggle refreshing after each message" },
+	{ value: "enable", label: "enable", description: "Turn tokenburn on (status line, panel, refresh)" },
+	{ value: "disable", label: "disable", description: "Turn tokenburn off: nothing runs in the background" },
+];
+
+/** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
+export function completions(prefix: string): CompletionItem[] | null {
+	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
+	// `tail` = " " when the completed text still needs another word (a budget amount).
+	const sub = (head: string, words: readonly string[], desc: (w: string) => string, tail = ""): CompletionItem[] =>
+		words.map((w) => ({ value: `${head} ${w}${tail}`, label: w, description: desc(w) }));
+
+	let pool: CompletionItem[];
+	if (text.startsWith("status ")) pool = sub("status", STATUS_WINDOWS, (w) => `Show ${w} in the status bar`);
+	else if (text.startsWith("budget ") && !/^budget \S+ /.test(text))
+		pool = sub("budget", BUDGET_PERIODS, (w) => `Set the ${w} budget (tokens or $cost)`, " ");
+	else if (/^(models?|providers?|projects?|sessions|top) /.test(text)) {
+		const head = text.split(" ")[0];
+		pool = sub(head, Object.keys(PERIOD_ALIASES).filter((w) => w !== "today" && w !== "total"), (w) => `Usage ${w === "all" ? "over all time" : `for ${w}`}`);
+	} else if (text.startsWith("filter ") && !/^filter \S+ /.test(text)) pool = [
+			...sub("filter", FILTER_KEYS_LIST, (w) => `Only this ${w}`, " "), // still needs a value
+			...sub("filter", ["all"], () => "Clear the filter"), // complete as it is
+		];
+	else if (text.startsWith("export ") && !/^export \S+ /.test(text)) pool = sub("export", EXPORT_FORMATS, (w) => `Export as ${w}`);
+	else if (/^(report|chart) /.test(text)) {
+		const head = text.split(" ")[0];
+		pool = sub(head, REPORT_VIEWS, (w) => `Chart: ${CHART_SPAN[w as ReportView]}`);
+	} else pool = TOP_LEVEL;
+
+	const out = pool.filter((i) => i.value.startsWith(text));
+	return out.length > 0 ? out : null;
+}

package/extensions/command/handlers.ts

@@ -0,0 +1,22 @@
+/** Every command kind mapped to the feature that handles it (compile-time exhaustive). */
+import { budgetCommands } from "../features/budgets/commands.ts";
+import { breakdownCommands } from "../features/breakdown/commands.ts";
+import { exportCommands } from "../features/export/commands.ts";
+import { filterCommands } from "../features/filter/commands.ts";
+import { pricingCommands } from "../features/pricing/commands.ts";
+import { reportCommands } from "../features/report/commands.ts";
+import { statusLineCommands } from "../features/status-line/commands.ts";
+import type { Handlers } from "./host.ts";
+
+export const handlers: Handlers = {
+	...statusLineCommands,
+	...budgetCommands,
+	...breakdownCommands,
+	...filterCommands,
+	...exportCommands,
+	...pricingCommands,
+	...reportCommands,
+	async invalid(cmd, { ctx }) {
+		ctx.ui.notify(cmd.message, "warning");
+	},
+};

package/extensions/command/host.ts

@@ -0,0 +1,25 @@
+/** What a command handler gets, and the shape of a feature's command handlers. */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TokenBurnConfig } from "../core/config.ts";
+import type { UsageFilter, UsageOptions } from "../core/select.ts";
+import type { Command } from "./parse.ts";
+
+export interface Host {
+	ctx: ExtensionContext;
+	/** Live settings: handlers mutate this, then call `persist()`. */
+	config: TokenBurnConfig;
+	/** Config filter + price table, merged with per-command filters. */
+	usageOpts(extra?: UsageFilter): UsageOptions;
+	/** Save the config and refresh the status line / panel. */
+	persist(): Promise<void>;
+	/** Info notification; mentions when tokenburn is disabled (settings still apply). */
+	note(message: string): void;
+	/** Drop a pending live refresh. */
+	cancelRefresh(): void;
+	/** Forget budget warnings already shown (after the threshold changed). */
+	resetWarnings(): void;
+}
+
+/** One handler per command kind; a feature exports the subset it owns. */
+export type Handlers = { [K in Command["kind"]]: (cmd: Extract<Command, { kind: K }>, host: Host) => Promise<void> };
+export type HandlersFor<K extends Command["kind"]> = Pick<Handlers, K>;

package/extensions/command/parse.ts

@@ -0,0 +1,173 @@
+/** Command parsing (pure, unit-tested). Completions live in ./completions.ts. */
+import { EXPORT_FORMATS, type ExportFormat } from "../features/export/export.ts";
+import { FILTER_KEYS_LIST, type FilterKey, type PriceMode, type UsageFilter } from "../core/select.ts";
+import { PERIOD_ALIASES, type GroupBy, type Period } from "../features/breakdown/query.ts";
+import { STATUS_WINDOWS, type Window } from "../core/types.ts";
+
+export const REPORT_VIEWS = ["day", "week", "month", "year", "all"] as const;
+export type ReportView = (typeof REPORT_VIEWS)[number];
+export const BUDGET_PERIODS = ["day", "week", "month"] as const;
+
+export type Command =
+	| { kind: "report"; view: ReportView }
+	| { kind: "status"; window: Window }
+	| { kind: "cycle" }
+	| { kind: "window" }
+	| { kind: "cache" }
+	| { kind: "enable" }
+	| { kind: "disable" }
+	| { kind: "live" }
+	| { kind: "budget"; period: (typeof BUDGET_PERIODS)[number]; amount: number; isCost: boolean }
+	| { kind: "rate" }
+	| { kind: "hit" }
+	| { kind: "saved" }
+	| { kind: "session" }
+	| { kind: "table"; by: GroupBy; period: Period; filter: UsageFilter; limit?: number }
+	| { kind: "filter"; key?: FilterKey; value?: string; clear?: boolean }
+	| { kind: "export"; format: ExportFormat; period: Period; path?: string }
+	| { kind: "warn"; pct: number }
+	| { kind: "pricing"; mode?: PriceMode }
+	| { kind: "price"; model: string; input?: number; output?: number; cacheRead?: number; cacheWrite?: number; remove?: boolean }
+	| { kind: "invalid"; message: string };
+
+export const USAGE =
+	"Usage: /tokenburn [hour|day|week|month|year|all] (status-bar period) · chart [day|week|month|year|all] · status <hour|today|week|month|year|total> · models|providers|projects [hour|day|week|month|year|all] [provider=x model=x project=x] · sessions [period] [n] · session · filter [provider|model|project] <value|all> · export <csv|json> [period] [path] · warn <pct|off> · pricing · price <model> <in> <out> · rate · hit · saved · cycle · window · budget <day|week|month> <tokens|$cost> · cache · live · enable · disable";
+
+/** Words that pick the status-bar period: `day` shows today, `all` shows the all-time total. */
+const WORD_TO_WINDOW: Record<string, Window> = {
+	hour: "hour",
+	day: "today",
+	today: "today",
+	week: "week",
+	month: "month",
+	year: "year",
+	all: "total",
+	total: "total",
+};
+
+/** Views the chart can show. */
+const asView = (w: string | undefined): ReportView | undefined =>
+	w === "today" ? "day" : w === "total" ? "all" : (REPORT_VIEWS as readonly string[]).includes(w ?? "") ? (w as ReportView) : undefined;
+
+const TABLE_WORDS: Record<string, GroupBy> = {
+	model: "model", models: "model", provider: "provider", providers: "provider",
+	project: "project", projects: "project", sessions: "session", top: "session",
+};
+const DEFAULT_TOP = 10;
+
+/** `[period] [n] [key=value ...]` after a table command. */
+function parseTableArgs(by: GroupBy, rest: string[]): Command {
+	let period: Period = "all";
+	let limit: number | undefined = by === "session" ? DEFAULT_TOP : undefined;
+	const filter: UsageFilter = {};
+	for (const raw of rest) {
+		const word = raw.toLowerCase();
+		const eq = raw.indexOf("=");
+		if (eq > 0) {
+			const key = word.slice(0, eq) as FilterKey;
+			const value = raw.slice(eq + 1);
+			if (!FILTER_KEYS_LIST.includes(key) || value === "") return { kind: "invalid", message: `Bad filter "${raw}". Use provider=<x> model=<x> project=<x>` };
+			filter[key] = value;
+		} else if (PERIOD_ALIASES[word]) period = PERIOD_ALIASES[word];
+		else if (/^\d+$/.test(word) && Number(word) > 0) limit = Number(word);
+		else return { kind: "invalid", message: `Unknown argument "${raw}". ${USAGE}` };
+	}
+	return { kind: "table", by, period, filter, limit };
+}
+
+export function parseCommand(args: string | undefined): Command {
+	const rawParts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	const [cmd, p1, p2] = rawParts.map((p) => p.toLowerCase());
+	if (!cmd) return { kind: "report", view: "day" };
+
+	// /tokenburn day|week|month|year|all → what the bottom status line shows
+	const window = WORD_TO_WINDOW[cmd];
+	if (window) return { kind: "status", window };
+
+	switch (cmd) {
+		case "chart":
+		case "report": {
+			if (p1 === undefined) return { kind: "report", view: "day" };
+			const v = asView(p1);
+			return v ? { kind: "report", view: v } : { kind: "invalid", message: `Unknown chart "${p1}". ${USAGE}` };
+		}
+		case "status":
+			return (STATUS_WINDOWS as readonly string[]).includes(p1 ?? "")
+				? { kind: "status", window: p1 as Window }
+				: { kind: "invalid", message: `Usage: /tokenburn status <${STATUS_WINDOWS.join("|")}>` };
+		case "cycle":
+			return { kind: "cycle" };
+		case "window":
+		case "widget":
+			return { kind: "window" };
+		case "cache":
+			return { kind: "cache" };
+		case "enable":
+		case "on":
+			return { kind: "enable" };
+		case "disable":
+		case "off":
+			return { kind: "disable" };
+		case "live":
+			return { kind: "live" };
+		case "rate":
+			return { kind: "rate" };
+		case "hit":
+			return { kind: "hit" };
+		case "saved":
+			return { kind: "saved" };
+		case "session":
+			return { kind: "session" };
+		case "model":
+		case "models":
+		case "provider":
+		case "providers":
+		case "project":
+		case "projects":
+		case "sessions":
+		case "top":
+			return parseTableArgs(TABLE_WORDS[cmd], rawParts.slice(1));
+		case "filter": {
+			if (p1 === undefined) return { kind: "filter" };
+			if (p1 === "clear" || p1 === "all") return { kind: "filter", clear: true };
+			const value = rawParts.slice(2).join(" ");
+			if (!FILTER_KEYS_LIST.includes(p1 as FilterKey)) return { kind: "invalid", message: "Usage: /tokenburn filter [provider|model|project] <value | all>" };
+			if (value === "") return { kind: "invalid", message: `Usage: /tokenburn filter ${p1} <value | all>` };
+			return { kind: "filter", key: p1 as FilterKey, value: value.toLowerCase() === "all" ? undefined : value };
+		}
+		case "export": {
+			if (!(EXPORT_FORMATS as readonly string[]).includes(p1 ?? "")) return { kind: "invalid", message: "Usage: /tokenburn export <csv|json> [hour|day|week|month|year|all] [path]" };
+			const rest = rawParts.slice(2);
+			const period = rest[0] && PERIOD_ALIASES[rest[0].toLowerCase()];
+			return { kind: "export", format: p1 as ExportFormat, period: period || "all", path: (period ? rest.slice(1) : rest).join(" ") || undefined };
+		}
+		case "warn": {
+			const pct = p1 === "off" ? 0 : Number(p1);
+			if (!Number.isFinite(pct) || pct < 0 || pct > 100 || p1 === undefined) return { kind: "invalid", message: "Usage: /tokenburn warn <1-100 | off>" };
+			return { kind: "warn", pct };
+		}
+		case "pricing":
+			if (p1 === undefined) return { kind: "pricing" };
+			if (p1 === "mode" && (p2 === "fill" || p2 === "override")) return { kind: "pricing", mode: p2 };
+			return { kind: "invalid", message: "Usage: /tokenburn pricing [mode <fill|override>]" };
+		case "price": {
+			const model = rawParts[1];
+			if (model === undefined) return { kind: "invalid", message: "Usage: /tokenburn price <model | provider/model> <$in/M> <$out/M> [$cacheRead/M] [$cacheWrite/M] · price remove <model>" };
+			if (model.toLowerCase() === "remove" && rawParts[2]) return { kind: "price", model: rawParts[2], remove: true };
+			const n = rawParts.slice(2, 6).map((v) => Number(v.replace(/^\$/, "")));
+			if (n.length < 2 || n.some((v) => !Number.isFinite(v) || v < 0))
+				return { kind: "invalid", message: "Usage: /tokenburn price <model | provider/model> <$in/M> <$out/M> [$cacheRead/M] [$cacheWrite/M]" };
+			return { kind: "price", model, input: n[0], output: n[1], cacheRead: n[2], cacheWrite: n[3] };
+		}
+		case "budget": {
+			const isCost = (p2 ?? "").startsWith("$");
+			const amount = Number((p2 ?? "").replace(/^\$/, ""));
+			if (!(BUDGET_PERIODS as readonly string[]).includes(p1 ?? "") || !Number.isFinite(amount) || amount <= 0) {
+				return { kind: "invalid", message: "Usage: /tokenburn budget <day|week|month> <tokens | $cost>" };
+			}
+			return { kind: "budget", period: p1 as (typeof BUDGET_PERIODS)[number], amount, isCost };
+		}
+		default:
+			return { kind: "invalid", message: `Unknown option "${cmd}". ${USAGE}` };
+	}
+}

package/extensions/core/aggregate.ts

@@ -0,0 +1,154 @@
+/** Aggregation of parsed turns into period totals and time series. */
+import { loadAll, type Turn } from "./parser.ts";
+import { cacheValue, selectTurns, type UsageOptions } from "./select.ts";
+import { bucketLabel, bucketStart, type Unit } from "./time.ts";
+import type { PeriodStats, TokenBurnReport } from "./types.ts";
+
+const emptyStats = (): PeriodStats => ({
+	tokens: 0,
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+	cost: 0,
+	sessions: 0,
+	cacheBase: 0,
+	cacheActual: 0,
+});
+
+export const HOUR_MS = 3_600_000;
+
+/** Every file's turns with the filter and price table applied (files left empty are dropped). */
+export async function loadSelected(root: string, opts?: UsageOptions): Promise<Turn[][]> {
+	const all = await loadAll(root);
+	if (!opts) return all;
+	return all.map((t) => selectTurns(t, opts)).filter((t) => t.length > 0);
+}
+
+export const turnTokens = (t: Turn, includeCache: boolean) =>
+	t.input + t.output + (includeCache ? t.cacheRead + t.cacheWrite : 0);
+
+export async function collectUsage(
+	sessionsRoot: string,
+	now: Date = new Date(),
+	includeCache = true,
+	opts?: UsageOptions,
+): Promise<TokenBurnReport> {
+	const startOfHour = now.getTime() - HOUR_MS;
+	const startOfDay = bucketStart(now.getTime(), "day");
+	const startOfWeek = bucketStart(now.getTime(), "week");
+	const startOfMonth = bucketStart(now.getTime(), "month");
+	const startOfYear = bucketStart(now.getTime(), "year");
+
+	const report: TokenBurnReport = {
+		hour: emptyStats(),
+		today: emptyStats(),
+		week: emptyStats(),
+		month: emptyStats(),
+		year: emptyStats(),
+		total: emptyStats(),
+	};
+
+	const add = (p: PeriodStats, t: Turn) => {
+		p.tokens += turnTokens(t, includeCache);
+		p.input += t.input;
+		p.output += t.output;
+		p.cacheRead += t.cacheRead;
+		p.cacheWrite += t.cacheWrite;
+		p.cost += t.cost;
+		const cv = cacheValue(t);
+		p.cacheBase += cv.base;
+		p.cacheActual += cv.actual;
+	};
+
+	for (const turns of await loadSelected(sessionsRoot, opts)) {
+		let maxTs = 0;
+		for (const t of turns) {
+			if (t.ts > maxTs) maxTs = t.ts;
+			if (report.firstTs === undefined || t.ts < report.firstTs) report.firstTs = t.ts;
+			add(report.total, t);
+			if (t.ts >= startOfYear) add(report.year, t);
+			if (t.ts >= startOfMonth) add(report.month, t);
+			if (t.ts >= startOfWeek) add(report.week, t);
+			if (t.ts >= startOfDay) add(report.today, t);
+			if (t.ts >= startOfHour) add(report.hour, t);
+		}
+		if (turns.length > 0) report.total.sessions++;
+		if (maxTs >= startOfYear) report.year.sessions++;
+		if (maxTs >= startOfMonth) report.month.sessions++;
+		if (maxTs >= startOfWeek) report.week.sessions++;
+		if (maxTs >= startOfDay) report.today.sessions++;
+		if (maxTs >= startOfHour) report.hour.sessions++;
+	}
+
+	return report;
+}
+
+export interface SeriesPoint {
+	start: number;
+	label: string;
+	tokens: number;
+	cost: number;
+}
+
+export const DEFAULT_COUNT: Record<Unit, number> = { day: 14, week: 8, month: 6, year: 5 };
+
+/** Last `count` buckets ending at `now`, oldest first, empty buckets zero-filled. */
+export async function collectSeries(
+	sessionsRoot: string,
+	unit: Unit,
+	count = DEFAULT_COUNT[unit],
+	now: Date = new Date(),
+	includeCache = true,
+	opts?: UsageOptions,
+): Promise<SeriesPoint[]> {
+	const starts: number[] = [];
+	for (let i = count - 1; i >= 0; i--) {
+		const y = now.getFullYear();
+		const m = now.getMonth();
+		const day = now.getDate();
+		const anchor =
+			unit === "day"
+				? new Date(y, m, day - i)
+				: unit === "week"
+					? new Date(y, m, day - i * 7)
+					: unit === "year"
+						? new Date(y - i, 0, 1)
+						: new Date(y, m - i, 1);
+		starts.push(bucketStart(anchor.getTime(), unit));
+	}
+	const points = new Map<number, SeriesPoint>(
+		starts.map((start) => [start, { start, label: bucketLabel(start, unit), tokens: 0, cost: 0 }]),
+	);
+	for (const turns of await loadSelected(sessionsRoot, opts)) {
+		for (const t of turns) {
+			const pt = points.get(bucketStart(t.ts, unit));
+			if (!pt) continue;
+			pt.tokens += turnTokens(t, includeCache);
+			pt.cost += t.cost;
+		}
+	}
+	return starts.map((s) => points.get(s)!);
+}
+
+/**
+ * Whole history: monthly columns while it spans <= 18 months, yearly after that.
+ * Always at least 2 columns so the chart has a shape.
+ */
+export async function collectAllSeries(
+	sessionsRoot: string,
+	now: Date = new Date(),
+	includeCache = true,
+	opts?: UsageOptions,
+): Promise<{ unit: Unit; series: SeriesPoint[] }> {
+	let first = now.getTime();
+	for (const turns of await loadSelected(sessionsRoot, opts)) for (const t of turns) if (t.ts < first) first = t.ts;
+	const f = new Date(first);
+	const months = (now.getFullYear() - f.getFullYear()) * 12 + (now.getMonth() - f.getMonth()) + 1;
+	if (months <= 18) {
+		const unit: Unit = "month";
+		return { unit, series: await collectSeries(sessionsRoot, unit, Math.max(2, months), now, includeCache, opts) };
+	}
+	const years = now.getFullYear() - f.getFullYear() + 1;
+	return { unit: "year", series: await collectSeries(sessionsRoot, "year", years, now, includeCache, opts) };
+}