auto-model-router 0.2.32 → 0.3.1

package/test/report-hub.test.ts

@@ -0,0 +1,343 @@
+import { describe, expect, test } from "bun:test";
+
+import { type HubKeys, type HubTheme, ReportHub, WINDOWS } from "../omp-extension/report-hub.ts";
+import type { UsageReport } from "../src/cost/report.ts";
+
+/**
+ * The hub is a pure component: identity styling, ASCII box glyphs and raw
+ * key names stand in for omp's theme, pi-tui and keybindings. These pin the
+ * frame geometry, navigation, window/scope cycling and the async load path.
+ */
+
+const theme: HubTheme = {
+	fg: (_c, t) => t,
+	bg: (_c, t) => t,
+	bold: (t) => t,
+	boxRound: {
+		topLeft: "+",
+		topRight: "+",
+		bottomLeft: "+",
+		bottomRight: "+",
+		horizontal: "-",
+		vertical: "|",
+		teeDown: "T",
+		teeUp: "U",
+		teeLeft: "<",
+		teeRight: ">",
+	},
+	nav: { cursor: ">" },
+};
+
+const text = {
+	visibleWidth: (s: string) => s.length,
+	truncateToWidth: (s: string, w: number) => (s.length <= w ? s : s.slice(0, w)),
+};
+
+const keys: HubKeys = {
+	up: (d) => d === "UP",
+	down: (d) => d === "DOWN",
+	left: (d) => d === "LEFT",
+	right: (d) => d === "RIGHT",
+	pageUp: (d) => d === "PGUP",
+	pageDown: (d) => d === "PGDN",
+	cancel: (d) => d === "ESC",
+	confirm: (d) => d === "ENTER",
+};
+
+function report(over: Partial<UsageReport> = {}): UsageReport {
+	const row = (key: string, spend: number) => ({
+		key,
+		dispatches: 10,
+		spendUsd: spend,
+		share: 0.5,
+		cacheHitRate: 0.8,
+		cacheEstimated: false,
+		avgPromptTokens: 1000,
+		avgTtftMs: 900,
+		tokensPerSec: 120,
+		escalations: 1,
+		errors: 0,
+	});
+	return {
+		generatedAtMs: Date.UTC(2026, 8, 6, 12),
+		windowDays: 7,
+		sinceMs: 0,
+		harnessId: "",
+		totals: {
+			dispatches: 20,
+			conversations: 2,
+			spendUsd: 3,
+			cacheHitRate: 0.8,
+			promptTokens: 20000,
+			completionTokens: 2000,
+			escalations: 2,
+			failovers: 0,
+			errors: 0,
+			aborted: 0,
+			modelSwitches: 1,
+			cacheEstimated: false,
+		},
+		providers: [row("openrouter", 2), row("ollama", 1)],
+		models: [
+			{ ...row("z-ai/glm", 2), provider: "openrouter", tiers: { simple: 6, moderate: 4 } },
+			{ ...row("ollama/kimi", 1), provider: "ollama", tiers: { hard: 10 } },
+		],
+		tiers: [row("simple", 2), row("hard", 1)],
+		days: [
+			{ day: "2026-09-05", dispatches: 10, spendUsd: 1.5, cacheHitRate: 0.8 },
+			{ day: "2026-09-06", dispatches: 10, spendUsd: 1.5, cacheHitRate: 0.8 },
+		],
+		...over,
+	};
+}
+
+interface Harness {
+	hub: ReportHub;
+	renders: number;
+	closed: boolean;
+	requests: { windowDays: number; harnessId: string }[];
+	settle(): Promise<void>;
+}
+
+function mount(opts: { harnessId?: string; initialHarness?: string; fail?: boolean; rows?: number } = {}): Harness {
+	const h: Harness = {
+		hub: undefined as unknown as ReportHub,
+		renders: 0,
+		closed: false,
+		requests: [],
+		settle: async () => {
+			await new Promise((r) => setTimeout(r, 0));
+			await new Promise((r) => setTimeout(r, 0));
+		},
+	};
+	h.hub = new ReportHub({
+		theme,
+		text,
+		keys,
+		source: {
+			report: async (req) => {
+				h.requests.push({ ...req });
+				if (opts.fail === true) throw new Error("boom");
+				return report({ windowDays: req.windowDays, harnessId: req.harnessId });
+			},
+			status: async () => "auto-model-router at http://h: ok\nopenrouter: key configured (omp)",
+		},
+		rows: () => opts.rows ?? 30,
+		requestRender: () => {
+			h.renders++;
+		},
+		close: () => {
+			h.closed = true;
+		},
+		initial: { windowDays: 7, harnessId: opts.initialHarness ?? "" },
+		harnessId: opts.harnessId ?? "",
+	});
+	return h;
+}
+
+describe("ReportHub frame", () => {
+	test("draws a titled two-column frame sized to the terminal", async () => {
+		const h = mount({ rows: 30 });
+		await h.settle();
+		const lines = h.hub.render(100);
+		// 1 top + (rows-4) content + divider + footer + bottom
+		expect(lines).toHaveLength(30);
+		expect(lines[0]).toMatch(/^\+- Router report -+T-+\+$/);
+		expect(lines[lines.length - 1]).toMatch(/^\+-+\+$/);
+		expect(lines[lines.length - 3]).toMatch(/^>-+U-+<$/);
+		for (const l of lines) expect(l.length).toBe(100);
+		// Every content row is | sidebar | body |.
+		expect(lines[1]).toMatch(/^\| .{18} \| .* \|$/);
+	});
+
+	test("overview shows the summary, provider and model tables, and the status row", async () => {
+		const h = mount();
+		await h.settle();
+		const body = h.hub.render(120).join("\n");
+		expect(body).toContain("> ◎ Overview");
+		expect(body).toContain("last 7d");
+		expect(body).toContain("all harnesses");
+		expect(body).toContain("spend $3.00 over 20 dispatches");
+		expect(body).toContain("providers");
+		expect(body).toContain("openrouter");
+		expect(body).toContain("z-ai/glm");
+		expect(body).toContain("window (7d)");
+	});
+
+	test("shows loading before data arrives and the error when the load fails", async () => {
+		const h = mount({ fail: true });
+		expect(h.hub.render(100).join("\n")).toContain("loading…");
+		await h.settle();
+		const out = h.hub.render(100).join("\n");
+		expect(out).toContain("could not load: boom");
+		expect(h.renders).toBeGreaterThanOrEqual(2);
+	});
+});
+
+describe("ReportHub navigation", () => {
+	test("up/down move through views, window entries and status, skipping rules and labels, and wrap", async () => {
+		const h = mount();
+		await h.settle();
+		expect(h.hub.activeView).toBe("overview");
+		h.hub.handleInput("DOWN");
+		expect(h.hub.activeView).toBe("providers");
+		for (let i = 0; i < 3; i++) h.hub.handleInput("DOWN");
+		expect(h.hub.activeView).toBe("days");
+		// Over the rule and the "Window" label onto the first window entry:
+		// the view stays put until Enter picks something.
+		h.hub.handleInput("DOWN");
+		expect(h.hub.cursorEntry).toEqual({ kind: "window", days: 1, label: "24 hours" });
+		expect(h.hub.activeView).toBe("days");
+		for (let i = 0; i < 3; i++) h.hub.handleInput("DOWN");
+		expect(h.hub.cursorEntry).toEqual({ kind: "window", days: 90, label: "90 days" });
+		h.hub.handleInput("DOWN"); // over the rule to Status (no scope entry without a harness id)
+		expect(h.hub.activeView).toBe("status");
+		expect(h.hub.render(100).join("\n")).toContain("openrouter: key configured (omp)");
+		h.hub.handleInput("DOWN"); // wraps
+		expect(h.hub.activeView).toBe("overview");
+		h.hub.handleInput("UP");
+		expect(h.hub.activeView).toBe("status");
+	});
+
+	test("the sidebar shows the window selector with the active window marked", async () => {
+		const h = mount();
+		await h.settle();
+		const side = h.hub.render(100).join("\n");
+		expect(side).toContain("  Window");
+		expect(side).toContain("○ 24 hours");
+		expect(side).toContain("● 7 days");
+		expect(side).toContain("○ 30 days");
+		expect(side).toContain("○ 90 days");
+		expect(side).not.toContain("Scope");
+	});
+
+	test("enter on a window entry applies it and reloads; the view is unchanged", async () => {
+		const h = mount();
+		await h.settle();
+		// Moving down passes every view (each shows as the cursor lands on it)
+		// and stops on the 30-day entry; Enter there changes the window only.
+		for (let i = 0; i < 7; i++) h.hub.handleInput("j");
+		expect(h.hub.cursorEntry).toEqual({ kind: "window", days: 30, label: "30 days" });
+		expect(h.hub.activeView).toBe("days");
+		h.hub.handleInput("ENTER");
+		expect(h.hub.request.windowDays).toBe(30);
+		expect(h.hub.activeView).toBe("days");
+		h.hub.handleInput("ENTER"); // same window again: no reload
+		await h.settle();
+		expect(h.requests.map((r) => r.windowDays)).toEqual([7, 30]);
+		expect(h.hub.render(100).join("\n")).toContain("● 30 days");
+		expect(h.hub.render(100).join("\n")).toContain("enter set window");
+	});
+
+	test("j/k are aliases and a chosen view renders only its table", async () => {
+		const h = mount();
+		await h.settle();
+		h.hub.handleInput("j");
+		h.hub.handleInput("j");
+		expect(h.hub.activeView).toBe("models");
+		const out = h.hub.render(120).join("\n");
+		expect(out).toContain("models (top 2 of 2 by spend)");
+		expect(out).toContain("simple:6 moderate:4");
+		expect(out).not.toContain("spend $3.00 over");
+		h.hub.handleInput("k");
+		expect(h.hub.activeView).toBe("providers");
+	});
+
+	test("left/right cycle the window and reload", async () => {
+		const h = mount();
+		await h.settle();
+		h.hub.handleInput("RIGHT");
+		expect(h.hub.request.windowDays).toBe(30);
+		h.hub.handleInput("RIGHT");
+		expect(h.hub.request.windowDays).toBe(90);
+		h.hub.handleInput("RIGHT");
+		expect(h.hub.request.windowDays).toBe(WINDOWS[0]!);
+		h.hub.handleInput("LEFT");
+		expect(h.hub.request.windowDays).toBe(90);
+		await h.settle();
+		expect(h.requests.map((r) => r.windowDays)).toEqual([7, 30, 90, 1, 90]);
+		expect(h.hub.render(100).join("\n")).toContain("last 90d");
+	});
+
+	test("the scope entry exists only with a harness id; enter (or a) toggles it", async () => {
+		const none = mount();
+		await none.settle();
+		none.hub.handleInput("a");
+		expect(none.hub.request.harnessId).toBe("");
+
+		const h = mount({ harnessId: "omp", initialHarness: "omp" });
+		await h.settle();
+		let side = h.hub.render(100).join("\n");
+		expect(side).toContain("  Scope");
+		expect(side).toContain("◉ this harness");
+		expect(side).toContain("harness omp");
+		// views(5) + window(4) → the scope entry is the 10th selectable.
+		for (let i = 0; i < 9; i++) h.hub.handleInput("DOWN");
+		expect(h.hub.cursorEntry).toEqual({ kind: "scope" });
+		h.hub.handleInput("ENTER");
+		expect(h.hub.request.harnessId).toBe("");
+		side = h.hub.render(100).join("\n");
+		expect(side).toContain("◎ all harnesses");
+		expect(side).toContain("enter toggle scope");
+		h.hub.handleInput("a");
+		expect(h.hub.request.harnessId).toBe("omp");
+		await h.settle();
+		expect(h.requests.map((r) => r.harnessId)).toEqual(["omp", "", "omp"]);
+	});
+
+	test("esc and q close; r reloads", async () => {
+		const h = mount();
+		await h.settle();
+		h.hub.handleInput("r");
+		await h.settle();
+		expect(h.requests).toHaveLength(2);
+		h.hub.handleInput("ESC");
+		expect(h.closed).toBe(true);
+		const h2 = mount();
+		h2.hub.handleInput("q");
+		expect(h2.closed).toBe(true);
+	});
+
+	test("page down scrolls a table longer than the pane and shows the remainder", async () => {
+		const h = mount({ rows: 16 });
+		await h.settle();
+		// 12 body rows; the overview is longer than that.
+		const first = h.hub.render(100).join("\n");
+		expect(first).toContain("more (pgdn)");
+		h.hub.handleInput("PGDN");
+		const second = h.hub.render(100).join("\n");
+		expect(second).not.toBe(first);
+		h.hub.handleInput("PGUP");
+		expect(h.hub.render(100).join("\n")).toBe(first);
+	});
+
+	test("a stale load never overwrites a newer one", async () => {
+		let resolveSlow: ((r: UsageReport) => void) | undefined;
+		const seen: number[] = [];
+		const hub = new ReportHub({
+			theme,
+			text,
+			keys,
+			source: {
+				report: (req) => {
+					seen.push(req.windowDays);
+					if (req.windowDays === 7) return new Promise<UsageReport>((r) => (resolveSlow = r));
+					return Promise.resolve(report({ windowDays: req.windowDays }));
+				},
+				status: async () => "ok",
+			},
+			rows: () => 30,
+			requestRender: () => {},
+			close: () => {},
+			initial: { windowDays: 7, harnessId: "" },
+			harnessId: "",
+		});
+		hub.handleInput("RIGHT"); // 30d, resolves immediately
+		await new Promise((r) => setTimeout(r, 0));
+		resolveSlow?.(report({ windowDays: 7, totals: { ...report().totals, dispatches: 999 } }));
+		await new Promise((r) => setTimeout(r, 0));
+		expect(seen).toEqual([7, 30]);
+		expect(hub.render(100).join("\n")).toContain("last 30d");
+		expect(hub.render(100).join("\n")).not.toContain("999");
+	});
+});

package/test/report-logic.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+
+import { fetchReport, parseReportArgs, renderStatus, type HealthSnapshot } from "../omp-extension/report-logic.ts";
+
+describe("parseReportArgs", () => {
+	test("defaults to 7 days scoped to the harness", () => {
+		expect(parseReportArgs("", "omp")).toEqual({ windowDays: 7, harnessId: "omp" });
+	});
+
+	test("accepts bare numbers and d/h/w suffixes", () => {
+		expect(parseReportArgs("30", "")).toEqual({ windowDays: 30, harnessId: "" });
+		expect(parseReportArgs("14d", "")).toEqual({ windowDays: 14, harnessId: "" });
+		expect(parseReportArgs("24h", "")).toEqual({ windowDays: 1, harnessId: "" });
+		expect(parseReportArgs("36h", "")).toEqual({ windowDays: 2, harnessId: "" });
+		expect(parseReportArgs("2w", "")).toEqual({ windowDays: 14, harnessId: "" });
+	});
+
+	test("--all drops the harness scope and --harness= sets one", () => {
+		expect(parseReportArgs("7d --all", "omp").harnessId).toBe("");
+		expect(parseReportArgs("--harness=hermes", "omp").harnessId).toBe("hermes");
+	});
+
+	test("ignores junk and clamps the window", () => {
+		expect(parseReportArgs("bogus 0 -3", "x")).toEqual({ windowDays: 7, harnessId: "x" });
+		expect(parseReportArgs("9999", "").windowDays).toBe(365);
+	});
+});
+
+describe("fetchReport", () => {
+	test("builds the query and returns the JSON body", async () => {
+		const seen: string[] = [];
+		const fake = async (url: string, init?: RequestInit): Promise<Response> => {
+			seen.push(url);
+			expect((init?.headers as Record<string, string>).authorization).toBe("Bearer k");
+			return new Response(JSON.stringify({ totals: { dispatches: 3 } }), { status: 200 });
+		};
+		const r = await fetchReport("http://127.0.0.1:1", { windowDays: 3, harnessId: "omp" }, { authorization: "Bearer k" }, fake);
+		expect(r.totals.dispatches).toBe(3);
+		expect(seen).toEqual(["http://127.0.0.1:1/v1/router/report?days=3&harness=omp"]);
+	});
+
+	test("omits the harness param when unscoped and throws on a non-2xx", async () => {
+		const seen: string[] = [];
+		const fake = async (url: string): Promise<Response> => {
+			seen.push(url);
+			return new Response("nope", { status: 503 });
+		};
+		await expect(fetchReport("http://h", { windowDays: 7, harnessId: "" }, {}, fake)).rejects.toThrow("503");
+		expect(seen).toEqual(["http://h/v1/router/report?days=7"]);
+	});
+});
+
+describe("renderStatus", () => {
+	test("summarises keys, catalog, ollama and agentdox", () => {
+		const now = 1_000_000_000;
+		const h: HealthSnapshot = {
+			status: "ok",
+			apiKeyConfigured: true,
+			apiKeySource: "omp",
+			agentdox: { url: "http://localhost:3003", defaultScope: "omp-router", recordTurns: true },
+			ollama: {
+				models: 12,
+				available: false,
+				cooldownUntilMs: now + 60_000,
+				apiKeySource: "omp",
+				lastTrip: { kind: "quota", atMs: now - 120_000, message: "402" },
+				usage: { monthlyUsedFraction: 0.42, activityCostUsd: 3.1, fetchedAtMs: now },
+				meter: { usedUsd: 25.2, creditsUsd: 60 },
+				costBias: { configured: 0.1, effective: 0.1, biasUntilUsage: 0.9 },
+			},
+			catalog: { models: 240, ageMs: 5 * 60_000, keyScoped: true, shrink: { fromModels: 300, toModels: 120, atMs: now } },
+		};
+		const text = renderStatus("http://127.0.0.1:8788", h, now);
+		expect(text).toContain("configured (omp)");
+		expect(text).toContain("240 models");
+		expect(text).toContain("refreshed 5m ago");
+		expect(text).toContain("SHRANK 300 -> 120");
+		expect(text).toContain("COOLING DOWN");
+		expect(text).toContain("plan usage 42.0% ($25.20 of $60)");
+		expect(text).toContain("cost bias ×0.1 (until 90%)");
+		expect(text).toContain("last trip quota 2m ago");
+		expect(text).toContain("scope omp-router");
+		expect(text).toContain("recording turns");
+	});
+
+	test("degrades cleanly when sections are absent", () => {
+		const text = renderStatus("http://h", { status: "ok", apiKeyConfigured: false });
+		expect(text).toContain("key MISSING");
+		expect(text).toContain("catalog: not fetched yet");
+		expect(text).toContain("ollama cloud: disabled");
+		expect(text).toContain("agentdox: off");
+	});
+});

package/test/report.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import { createLedger } from "../src/cost/ledger.ts";
+import { buildUsageReport, renderUsageReport } from "../src/cost/report.ts";
+import type { LedgerEntry } from "../src/cost/types.ts";
+import { openDb } from "../src/util/sqlite.ts";
+
+/**
+ * `buildUsageReport` is what `/router report`, the `report` CLI and
+ * `GET /v1/router/report` all render. These pin the aggregation rules:
+ * spend follows the ledger's reported-else-predicted rule, cache hit rate is
+ * cached/prompt tokens, speed comes only from clean streamed rows, the
+ * provider is derived from the served slug, and harness scoping works.
+ */
+
+const HOUR = 3_600_000;
+const NOW = Date.UTC(2026, 8, 6, 12, 0, 0);
+
+function entry(over: Partial<LedgerEntry>): LedgerEntry {
+	return {
+		id: crypto.randomUUID(),
+		createdAtMs: NOW - HOUR,
+		conversationKey: "k",
+		sessionId: "s",
+		turn: 1,
+		requestedModel: "auto",
+		harnessId: "",
+		ompSessionId: "",
+		slug: "vendor/model",
+		servedSlug: "vendor/model",
+		tier: "simple",
+		classificationSource: "heuristic",
+		reasons: [],
+		features: null,
+		score: null,
+		confidence: null,
+		task: null,
+		classifierReasons: null,
+		exploredFrom: null,
+		holdArm: null,
+		predictedUsd: 0.001,
+		reportedUsd: 0.001,
+		usage: { promptTokens: 1000, cachedTokens: 0, cacheWriteTokens: 0, completionTokens: 100, reasoningTokens: 0, images: 0 },
+		attempt: 0,
+		escalationSignal: null,
+		latencyMs: 1_100,
+		ttftMs: 100,
+		finishReason: "stop",
+		wasted: false,
+		upstreamGenerationId: null,
+		error: null,
+		promptTokensSaved: null,
+		...over,
+	} as LedgerEntry;
+}
+
+function seeded() {
+	const cfg = structuredClone(DEFAULT_CONFIG);
+	cfg.ledger.path = ":memory:";
+	const db = openDb(":memory:");
+	const ledger = createLedger(db, cfg);
+	return { db, ledger };
+}
+
+describe("buildUsageReport", () => {
+	test("totals, providers, models and tiers over a mixed window", () => {
+		const { db, ledger } = seeded();
+		// Two OpenRouter turns on one model (one with a warm cache), one Ollama
+		// turn served by a different slug than decided, one escalation, one error.
+		ledger.record(entry({ conversationKey: "a", turn: 1, reportedUsd: 0.01 }));
+		ledger.record(
+			entry({
+				conversationKey: "a",
+				turn: 2,
+				reportedUsd: 0.005,
+				usage: { promptTokens: 1000, cachedTokens: 800, cacheWriteTokens: 0, completionTokens: 100, reasoningTokens: 0, images: 0 },
+			}),
+		);
+		ledger.record(
+			entry({
+				conversationKey: "b",
+				slug: "ollama/glm-5.3-flash",
+				servedSlug: "ollama/glm-5.3-flash",
+				tier: "moderate",
+				predictedUsd: 0.02,
+				reportedUsd: null,
+				latencyMs: 2_100,
+				ttftMs: 100,
+			}),
+		);
+		ledger.record(entry({ conversationKey: "c", tier: "hard", escalationSignal: "refusal", wasted: true, reportedUsd: 0.002 }));
+		ledger.record(entry({ conversationKey: "c", tier: "hard", error: "request aborted", reportedUsd: 0, ttftMs: null }));
+
+		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
+		expect(r.totals.dispatches).toBe(5);
+		expect(r.totals.conversations).toBe(3);
+		// 0.01 + 0.005 + 0.02 (predicted: no reported) + 0.002 + 0
+		expect(r.totals.spendUsd).toBeCloseTo(0.037, 6);
+		expect(r.totals.cacheHitRate).toBeCloseTo(800 / 5000, 6);
+		expect(r.totals.escalations).toBe(1);
+		expect(r.totals.errors).toBe(1);
+		expect(r.totals.aborted).toBe(1);
+
+		// Ordered by spend: the single Ollama turn (0.02 predicted) outspends OpenRouter (0.017).
+		expect(r.providers.map((p) => p.key)).toEqual(["ollama", "openrouter"]);
+		const or = r.providers[1]!;
+		expect(or.dispatches).toBe(4);
+		expect(or.spendUsd).toBeCloseTo(0.017, 6);
+		expect(or.share).toBeCloseTo(0.017 / 0.037, 6);
+		// Speed: 3 clean streamed rows × 100 completion tokens over (1100-100) ms each.
+		expect(or.avgTtftMs).toBe(100);
+		expect(or.tokensPerSec).toBeCloseTo(100, 3);
+
+		const ollama = r.providers[0]!;
+		expect(ollama.dispatches).toBe(1);
+		expect(ollama.tokensPerSec).toBeCloseTo(50, 3);
+
+		expect(r.models.map((m) => m.key)).toEqual(["ollama/glm-5.3-flash", "vendor/model"]);
+		expect(r.models[0]!.provider).toBe("ollama");
+		expect(r.models[1]!.tiers).toEqual({ simple: 2, hard: 2 });
+
+		const tierKeys = r.tiers.map((t) => t.key).sort();
+		expect(tierKeys).toEqual(["hard", "moderate", "simple"]);
+		expect(r.tiers.find((t) => t.key === "hard")!.escalations).toBe(1);
+
+		expect(r.days).toHaveLength(1);
+		expect(r.days[0]!.day).toBe("2026-09-06");
+		db.close();
+	});
+
+	test("counts a model switch only between consecutive kept rows of one conversation", () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ conversationKey: "a", turn: 1, slug: "x/one", createdAtMs: NOW - 3 * HOUR }));
+		ledger.record(entry({ conversationKey: "a", turn: 2, slug: "x/two", createdAtMs: NOW - 2 * HOUR }));
+		ledger.record(entry({ conversationKey: "a", turn: 3, slug: "x/two", createdAtMs: NOW - 1 * HOUR }));
+		// A wasted probe on another slug is not a switch.
+		ledger.record(entry({ conversationKey: "a", turn: 3, slug: "x/three", wasted: true, createdAtMs: NOW - 1 * HOUR + 1 }));
+		// A different conversation starting on another model is not a switch either.
+		ledger.record(entry({ conversationKey: "b", turn: 1, slug: "x/three", createdAtMs: NOW - HOUR }));
+		const r = buildUsageReport(db, { windowDays: 1, nowMs: NOW });
+		expect(r.totals.modelSwitches).toBe(1);
+		db.close();
+	});
+
+	test("window and harness scope exclude rows", () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ harnessId: "omp", createdAtMs: NOW - HOUR }));
+		ledger.record(entry({ harnessId: "hermes", createdAtMs: NOW - HOUR }));
+		ledger.record(entry({ harnessId: "omp", createdAtMs: NOW - 10 * 24 * HOUR }));
+		expect(buildUsageReport(db, { windowDays: 7, nowMs: NOW }).totals.dispatches).toBe(2);
+		expect(buildUsageReport(db, { windowDays: 30, nowMs: NOW }).totals.dispatches).toBe(3);
+		const scoped = buildUsageReport(db, { windowDays: 30, harnessId: "omp", nowMs: NOW });
+		expect(scoped.totals.dispatches).toBe(2);
+		expect(scoped.harnessId).toBe("omp");
+		db.close();
+	});
+
+	test("empty ledger yields zeroed totals and null speeds", () => {
+		const { db } = seeded();
+		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
+		expect(r.totals).toEqual({
+			dispatches: 0,
+			conversations: 0,
+			spendUsd: 0,
+			cacheHitRate: 0,
+			promptTokens: 0,
+			completionTokens: 0,
+			escalations: 0,
+			failovers: 0,
+			errors: 0,
+			aborted: 0,
+			modelSwitches: 0,
+			cacheEstimated: false,
+		});
+		expect(r.providers).toEqual([]);
+		expect(r.models).toEqual([]);
+		db.close();
+	});
+
+	test("speed ignores errored and non-streamed rows", () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ ttftMs: null }));
+		ledger.record(entry({ error: "boom" }));
+		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
+		expect(r.providers[0]!.avgTtftMs).toBeNull();
+		expect(r.providers[0]!.tokensPerSec).toBeNull();
+		db.close();
+	});
+});
+
+describe("renderUsageReport", () => {
+	test("router-estimated cache counts render as an estimate", async () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ slug: "ollama/glm", servedSlug: "ollama/glm", usage: { promptTokens: 1000, cachedTokens: 900, cacheWriteTokens: 0, completionTokens: 10, reasoningTokens: 0, images: 0, cachedEstimated: true } }));
+		ledger.record(entry({ usage: { promptTokens: 1000, cachedTokens: 500, cacheWriteTokens: 0, completionTokens: 10, reasoningTokens: 0, images: 0 } }));
+		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
+		expect(r.totals.cacheEstimated).toBe(true);
+		expect(r.providers.find((p) => p.key === "ollama")!.cacheEstimated).toBe(true);
+		expect(r.providers.find((p) => p.key === "openrouter")!.cacheEstimated).toBe(false);
+		const text = renderUsageReport(r);
+		expect(text).toContain("(cache hit ~70%)");
+		expect(text).toMatch(/ollama\s+1\s+\S+\s+\S+\s+~90%/);
+		expect(text).toMatch(/openrouter\s+1\s+\S+\s+\S+\s+50%/);
+		db.close();
+	});
+
+	test("renders every section as plain fixed-width text", () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ reportedUsd: 1.25, createdAtMs: NOW - HOUR }));
+		ledger.record(entry({ slug: "ollama/kimi", servedSlug: "ollama/kimi", tier: "hard", reportedUsd: 0.5, createdAtMs: NOW - 30 * HOUR }));
+		const text = renderUsageReport(buildUsageReport(db, { windowDays: 7, nowMs: NOW }));
+		expect(text).toContain("last 7d");
+		expect(text).toContain("spend $1.75 over 2 dispatches");
+		expect(text).toContain("providers");
+		expect(text).toContain("openrouter");
+		expect(text).toContain("ollama/kimi");
+		expect(text).toContain("tiers");
+		expect(text).toContain("by day (UTC)");
+		expect(text).toContain("2026-09-05");
+		// No markdown or ANSI: it goes into a code block as-is.
+		expect(text).not.toMatch(/[|*`]/);
+		db.close();
+	});
+
+	test("caps the model table and says so", () => {
+		const { db, ledger } = seeded();
+		for (let i = 0; i < 5; i++) ledger.record(entry({ slug: `v/m${i}`, servedSlug: `v/m${i}` }));
+		const text = renderUsageReport(buildUsageReport(db, { windowDays: 7, nowMs: NOW }), { maxModels: 2 });
+		expect(text).toContain("models (top 2 of 5 by spend)");
+		db.close();
+	});
+});