Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Add admin spend dashboard and time-series breakdowns (#1614)

Joshua France19bb8eb643d3
diff --git a/plugins/admin/public/admin-components.css b/plugins/admin/public/admin-components.css
index b9e86dfe4..c01ed7259 100644
--- a/plugins/admin/public/admin-components.css
+++ b/plugins/admin/public/admin-components.css
@@ -1902,3 +1902,199 @@ dialog.credential-dialog {
text-align: left;
}
}
+
+.spend-chart {
+ --spend-live: var(--text);
+ --spend-cron: var(--trigger);
+ --spend-background: var(--muted);
+ padding-top: 4px;
+}
+.spend-chart-summary {
+ display: flex;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 18px 32px;
+ margin-bottom: 24px;
+}
+.spend-chart-summary > div:not(.spend-chart-legend) {
+ display: grid;
+ gap: 4px;
+}
+.spend-chart-summary strong {
+ font-size: 24px;
+ font-weight: 500;
+ letter-spacing: -0.025em;
+ font-variant-numeric: tabular-nums;
+}
+.spend-chart-summary span {
+ color: var(--muted);
+ font-size: 12px;
+}
+.spend-chart-legend {
+ display: flex;
+ gap: 16px;
+ margin-left: auto;
+ flex-wrap: wrap;
+}
+.spend-chart-legend span {
+ display: inline-flex;
+ gap: 6px;
+ align-items: center;
+}
+.spend-chart-legend i {
+ width: 8px;
+ height: 8px;
+ border-radius: 2px;
+}
+.spend-live {
+ background: var(--spend-live);
+}
+.spend-cron {
+ background: var(--spend-cron);
+}
+.spend-background {
+ background: var(--spend-background);
+}
+.spend-chart-plot {
+ display: grid;
+ grid-template-columns: max-content minmax(0, 1fr);
+ grid-template-rows: 240px 24px;
+ gap: 8px 12px;
+}
+.spend-chart-axis {
+ display: flex;
+ flex-direction: column;
+ justify-content: space-between;
+ font-size: 11px;
+ color: var(--muted);
+ text-align: right;
+ font-variant-numeric: tabular-nums;
+}
+.spend-chart-axis span {
+ line-height: 1;
+ transform: translateY(-50%);
+}
+.spend-chart-axis span:last-child {
+ transform: translateY(50%);
+}
+.spend-chart-bars {
+ position: relative;
+ display: flex;
+ gap: 3px;
+ min-width: 0;
+}
+.spend-chart-grid {
+ position: absolute;
+ inset: 0;
+ display: flex;
+ flex-direction: column;
+ justify-content: space-between;
+ pointer-events: none;
+}
+.spend-chart-grid span {
+ border-top: 1px solid var(--border);
+ width: 100%;
+}
+.spend-column {
+ position: relative;
+ flex: 1;
+ min-width: 0;
+ display: flex;
+ flex-direction: column-reverse;
+ align-items: center;
+ outline-offset: 2px;
+ cursor: crosshair;
+}
+.spend-column:hover,
+.spend-column.inspected {
+ background: color-mix(in srgb, var(--text) 5%, transparent);
+}
+.spend-column:focus-visible {
+ outline: 2px solid var(--trigger);
+}
+.spend-segment {
+ width: 80%;
+ max-width: 64px;
+ flex-shrink: 0;
+}
+.spend-chart-dates {
+ grid-column: 2;
+ display: flex;
+ color: var(--muted);
+ font-size: 11px;
+ gap: 3px;
+}
+.spend-chart-dates span {
+ flex: 1;
+ min-width: 0;
+ white-space: nowrap;
+ text-align: center;
+}
+.spend-chart-dates span:first-child {
+ text-align: left;
+}
+.spend-chart-dates span:last-child {
+ text-align: right;
+ direction: rtl;
+}
+.spend-chart-detail {
+ min-height: 36px;
+ padding-top: 8px;
+ font-size: 12px;
+ color: var(--muted);
+ font-variant-numeric: tabular-nums;
+}
+@media (max-width: 600px) {
+ .spend-chart-legend {
+ margin-left: 0;
+ width: 100%;
+ }
+ .spend-chart-bars,
+ .spend-chart-dates {
+ gap: 1px;
+ }
+ .spend-chart-summary {
+ gap: 14px 24px;
+ }
+ .spend-chart-detail {
+ min-height: 56px;
+ }
+}
+
+.spend-models td:first-child {
+ overflow-wrap: anywhere;
+ white-space: normal;
+ min-width: 140px;
+}
+
+.spend-chart-switch {
+ display: flex;
+ gap: 4px;
+}
+.spend-chart-switch button[aria-pressed="true"],
+#app-view #main .spend-chart-switch button[aria-pressed="true"]:hover,
+#app-view #main .spend-chart-switch button[aria-pressed="true"] {
+ color: var(--bg);
+ background: var(--text);
+ border-color: var(--text);
+}
+.spend-chart-switch button:focus-visible {
+ outline: 2px solid var(--trigger);
+ outline-offset: 2px;
+}
+.spend-chart-legend span {
+ overflow-wrap: anywhere;
+ min-width: 0;
+}
+.spend-chart-legend i {
+ flex-shrink: 0;
+}
+.spend-chart-detail {
+ overflow-wrap: anywhere;
+}
+
+.spend-chart-detail span {
+ display: inline-block;
+ max-width: 100%;
+ margin-right: 12px;
+}
diff --git a/plugins/admin/public/index.html b/plugins/admin/public/index.html
index 9b3e931cd..658e8ce0e 100644
--- a/plugins/admin/public/index.html
+++ b/plugins/admin/public/index.html
@@ -6623,7 +6623,7 @@
const EFFECT_LABELS = { allow: "Allow", deny: "Deny", require_approval: "Require approval" };
const SECTIONS = [
{
- views: ["governance", "models", "credentials", "connectors", "slack-settings", "customize", "users"],
+ views: ["governance", "models", "credentials", "connectors", "slack-settings", "customize", "users", "spend"],
},
{
label: "Logs",
@@ -6780,6 +6780,7 @@
keychain: "Keychain",
user: "User",
metrics: "Metrics",
+ spend: "Spend",
egress: "Egress",
history: "Sessions",
files: "Files",
@@ -6814,6 +6815,7 @@
const ORG_WIDE = new Set([
"retention",
"users",
+ "spend",
"keychain",
"connectors",
"judgments",
@@ -7329,6 +7331,7 @@
if (st.own && SCOPED.has(st.view)) p.set("own", st.own);
if (st.view === "memory" && st.mem) p.set("mem", st.mem);
if (st.view === "metrics" && st.phase) p.set("phase", st.phase);
+ if (st.view === "spend" && st.range) p.set("range", st.range);
if (st.view === "slack" && st.container) p.set("container", st.container);
if (st.view === "slack" && st.container && st.ts) p.set("ts", st.ts);
if (st.view === "judgments" && st.container) p.set("container", st.container);
@@ -7393,6 +7396,7 @@
own: p.get("own") || null,
mem: p.get("mem") || null,
phase: p.get("phase") || null,
+ range: p.get("range") || null,
historyKind: normalizedHistoryKind,
page: Math.max(1, parseInt(p.get("page"), 10) || 1),
container: p.get("container") || null,
@@ -7443,6 +7447,7 @@
"customize",
"slack-settings",
"users",
+ "spend",
"design-system",
].includes(view)
? "true"
@@ -9262,6 +9267,7 @@
root.textContent = "";
({
metrics: renderMetrics,
+ spend: renderSpend,
egress: renderEgress,
history: renderHistory,
files: renderFiles,
@@ -9295,6 +9301,7 @@
if (historyKind === "background") path += "&origin=other_background";
}
if (view === "errors") path += `&limit=${ERRORS_PAGE_SIZE}&offset=${(page - 1) * ERRORS_PAGE_SIZE}`;
+ if (view === "spend") path += `?${spendQuery(urlToState())}`;
const cacheable = view !== "memory";
const cached = cacheable ? dataCache.get(path) : undefined;
if (cached !== undefined) {
@@ -9376,10 +9383,10 @@
if (s.provisioned === false) return "no machine";
return "";
}
- function sparkline(daily) {
+ function sparkline(daily, valueOf = (r) => r.p50) {
const vals = (daily || [])
.slice(-14)
- .map((r) => r.p50)
+ .map(valueOf)
.filter((v) => v != null);
if (vals.length < 2) {
const s = document.createElement("span");
@@ -9425,6 +9432,44 @@
sparkline,
});
}
+ const SPEND_RANGES = { "7d": 7, "30d": 30, "90d": 90 };
+ function spendQuery(st) {
+ const DAY = 86400000;
+ const range = SPEND_RANGES[st.range] ? st.range : "30d";
+ const to = Math.floor(Date.now() / DAY) * DAY + DAY;
+ const iso = (t) => new Date(t).toISOString().slice(0, 10);
+ const params = new URLSearchParams({
+ from: iso(to - SPEND_RANGES[range] * DAY),
+ to: iso(to),
+ bucket: range === "90d" ? "week" : "day",
+ });
+ return params.toString();
+ }
+ function renderSpend(root, d) {
+ governanceUI.spend.spend(root, d, {
+ defaultShell,
+ fmtPct,
+ fmtTokens,
+ shortName,
+ plural,
+ range: urlToState().range || "30d",
+ openUser: (principal) => go({ view: "user", scope, session: null, principal }),
+ setRange: (range) => go({ ...urlToState(), view: "spend", range }),
+ downloadCsv: (breakdown = "entity") => {
+ const a = document.createElement("a");
+ a.href =
+ API_BASE +
+ "/api/spend?format=csv&breakdown=" +
+ encodeURIComponent(breakdown) +
+ "&" +
+ spendQuery(urlToState());
+ a.rel = "noreferrer";
+ document.body.appendChild(a);
+ a.click();
+ a.remove();
+ },
+ });
+ }
function renderErrors(root, d) {
governanceUI.activity.errors(root, d, {
all: orgWideView(),
diff --git a/plugins/admin/src/index.ts b/plugins/admin/src/index.ts
index c95da8cac..274790745 100644
--- a/plugins/admin/src/index.ts
+++ b/plugins/admin/src/index.ts
@@ -313,6 +313,7 @@ const WRITES = new Map<string, string[]>([
const READS = [
"metrics",
+ "spend",
"egress",
"errors",
"audit",
@@ -482,6 +483,11 @@ async function handle(req: IncomingMessage, res: ServerResponse): Promise<void>
return forwardDownload(res, principal, `/v1/admin/files/download${url.search}`);
}
+ if (method === "GET" && pathname === "/api/spend" && url.searchParams.get("format") === "csv") {
+ if (!principal) return json(res, 401, { error: "signed_out" });
+ return forwardDownload(res, principal, `/v1/admin/spend${url.search}`);
+ }
+
if (method === "POST" && pathname === "/api/files/upload") {
if (!principal) {
req.resume();
diff --git a/plugins/admin/test/default-view.test.ts b/plugins/admin/test/default-view.test.ts
index 89d27957f..42f924d4d 100644
--- a/plugins/admin/test/default-view.test.ts
+++ b/plugins/admin/test/default-view.test.ts
@@ -54,7 +54,7 @@ test("admin shell groups control, logs, and artifacts like the reorganization",
assert.ok(sections);
const actual = JSON.parse(JSON.stringify(vm.runInNewContext(sections)));
assert.deepEqual(actual, [
- { views: ["governance", "models", "credentials", "connectors", "slack-settings", "customize", "users"] },
+ { views: ["governance", "models", "credentials", "connectors", "slack-settings", "customize", "users", "spend"] },
{ label: "Logs", views: ["history", "slack", "judgments", "errors", "audit", "egress"] },
{ label: "Artifacts", views: ["files", "skills", "memory", "deployments", "crons"] },
{ views: ["design-system"] },
diff --git a/plugins/admin/test/history-urls.test.ts b/plugins/admin/test/history-urls.test.ts
index b555bc450..13882befd 100644
--- a/plugins/admin/test/history-urls.test.ts
+++ b/plugins/admin/test/history-urls.test.ts
@@ -44,6 +44,7 @@ function routerAt(pathname: string, search = "", base = "/admin") {
"slack",
"judgments",
"user",
+ "spend",
],
"history",
(scopeId: string) => String(scopeId || "").split(":")[0] || "scope",
@@ -60,6 +61,7 @@ function routerAt(pathname: string, search = "", base = "/admin") {
historyKind: string;
cron: string | null;
turn: string | null;
+ range: string | null;
page: number;
};
};
@@ -91,6 +93,18 @@ test("scoped history addresses the scope as a path segment; kind stays a query p
assert.equal(stateToUrl({ view: "history", scope: "org:acme", session: null }), "/admin/history");
});
+test("the spend window round-trips through the URL so Back restores the prior range", () => {
+ const { stateToUrl } = routerAt("/admin/spend");
+ assert.equal(stateToUrl({ view: "spend", scope: "org:acme", range: "7d" }), "/admin/spend?range=7d");
+ assert.equal(stateToUrl({ view: "spend", scope: "org:acme", range: null }), "/admin/spend");
+ const router = routerAt("/admin/spend", "?range=90d");
+ const st = router.urlToState();
+ assert.equal(st.view, "spend");
+ assert.equal(st.range, "90d");
+ assert.equal(router.stateToUrl(st), "/admin/spend?range=90d");
+ assert.equal(routerAt("/admin/spend").urlToState().range, null);
+});
+
test("non-history views keep their query-param scope", () => {
const { stateToUrl } = routerAt("/admin/files");
assert.equal(stateToUrl({ view: "files", scope: SCOPE }), `/admin/files?scope=${SCOPE_ENC}`);
diff --git a/plugins/admin/test/spend-download.test.ts b/plugins/admin/test/spend-download.test.ts
new file mode 100644
index 000000000..a7f395357
--- /dev/null
+++ b/plugins/admin/test/spend-download.test.ts
@@ -0,0 +1,88 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createServer, type IncomingMessage } from "node:http";
+import type { AddressInfo } from "node:net";
+
+const CSV_HEADER =
+ "principal_id,scope_id,kind,display_name,live_usd,cron_usd,background_usd,total_usd,calls,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cache_hit_ratio";
+const CSV_BODY =
+ CSV_HEADER +
+ "\r\n" +
+ Array.from(
+ { length: 40 },
+ (_, i) => `person-${i},personal:person-${i},person,Person ${i},1,2,3,6,4,5,6,7,8,0.5`,
+ ).join("\r\n") +
+ "\r\n";
+
+const calls: { url: string; actor: string | null }[] = [];
+const core = createServer((req: IncomingMessage, res) => {
+ calls.push({ url: req.url ?? "", actor: (req.headers["x-admin-actor"] as string) ?? null });
+ if (req.method === "GET" && (req.url ?? "").startsWith("/v1/admin/spend") && (req.url ?? "").includes("format=csv")) {
+ res.writeHead(200, {
+ "content-type": "text/csv; charset=utf-8",
+ "content-length": String(Buffer.byteLength(CSV_BODY)),
+ "content-disposition": 'attachment; filename="qm-spend-2026-08-26-2026-09-25.csv"',
+ "x-content-type-options": "nosniff",
+ });
+ return void res.end(CSV_BODY);
+ }
+ if (req.method === "GET" && (req.url ?? "").startsWith("/v1/admin/spend")) {
+ res.writeHead(200, { "content-type": "application/json" });
+ return void res.end(JSON.stringify({ org: { costUsd: 0 }, people: [], scopes: [], series: [] }));
+ }
+ res.writeHead(404, { "content-type": "application/json" });
+ res.end(JSON.stringify({ error: "not_found" }));
+});
+await new Promise<void>((r) => core.listen(0, r));
+
+process.env.CORE_API_URL = `http://localhost:${(core.address() as AddressInfo).port}`;
+process.env.CORE_SIGNING_SECRET = "admin-spend-download-proxy-secret";
+
+const { server } = await import("../src/index.ts");
+await new Promise<void>((r) => server.listen(0, r));
+const base = `http://localhost:${(server.address() as AddressInfo).port}`;
+test.after(() => {
+ server.close();
+ if (core.listening) core.close();
+});
+
+const ADMIN = "admin=U-admin";
+
+test("GET /api/spend?format=csv keeps the core's CSV headers and full body", async () => {
+ assert.ok(Buffer.byteLength(CSV_BODY) > 1024, "the fixture must exceed the gzip threshold to be a real proof");
+ const r = await fetch(`${base}/api/spend?from=2026-08-26&to=2026-09-25&format=csv`, { headers: { cookie: ADMIN } });
+ assert.equal(r.status, 200);
+ assert.equal(r.headers.get("content-type"), "text/csv; charset=utf-8");
+ assert.equal(r.headers.get("content-disposition"), 'attachment; filename="qm-spend-2026-08-26-2026-09-25.csv"');
+ assert.equal(r.headers.get("x-content-type-options"), "nosniff");
+ const body = await r.text();
+ assert.equal(body, CSV_BODY);
+ assert.equal(Number(r.headers.get("content-length")), Buffer.byteLength(body));
+ assert.equal(calls.at(-1)!.url, "/v1/admin/spend?from=2026-08-26&to=2026-09-25&format=csv");
+ assert.equal(calls.at(-1)!.actor, "U-admin@acme");
+});
+
+test("GET /api/spend without format still takes the JSON read path", async () => {
+ const r = await fetch(`${base}/api/spend?from=2026-08-26&to=2026-09-25`, { headers: { cookie: ADMIN } });
+ assert.equal(r.status, 200);
+ assert.equal(r.headers.get("content-type"), "application/json");
+ assert.deepEqual(await r.json(), { org: { costUsd: 0 }, people: [], scopes: [], series: [] });
+ assert.equal(calls.at(-1)!.url, "/v1/admin/spend?from=2026-08-26&to=2026-09-25");
+});
+
+test("GET /api/spend?format=csv requires a signed-in cookie before proxying", async () => {
+ const before = calls.length;
+ const r = await fetch(`${base}/api/spend?format=csv`);
+ assert.equal(r.status, 401);
+ assert.equal(calls.length, before, "a signed-out CSV request never reaches core");
+});
+
+test("GET /api/spend forwards the model CSV dimension without losing auth", async () => {
+ const r = await fetch(`${base}/api/spend?format=csv&breakdown=model&from=2026-08-26&to=2026-09-25`, {
+ headers: { cookie: ADMIN },
+ });
+ assert.equal(r.status, 200);
+ assert.equal(await r.text(), CSV_BODY);
+ assert.equal(calls.at(-1)!.url, "/v1/admin/spend?format=csv&breakdown=model&from=2026-08-26&to=2026-09-25");
+ assert.equal(calls.at(-1)!.actor, "U-admin@acme");
+});
diff --git a/plugins/admin/test/spend-lit.test.ts b/plugins/admin/test/spend-lit.test.ts
new file mode 100644
index 000000000..c8e4e94bc
--- /dev/null
+++ b/plugins/admin/test/spend-lit.test.ts
@@ -0,0 +1,375 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { litFixture } from "./lit-fixture.ts";
+
+const person = (principalId: string, costUsd: number, over: Record<string, any> = {}) => ({
+ principalId,
+ scopeId: `personal:${principalId}`,
+ kind: "person",
+ displayName: "",
+ costUsd,
+ calls: 2,
+ tokens: 1000,
+ input: 100,
+ output: 100,
+ cacheRead: 700,
+ cacheWrite: 100,
+ cacheHitRatio: 0.7,
+ live: { costUsd, calls: 2, tokens: 1000 },
+ cron: { costUsd: 0, calls: 0, tokens: 0 },
+ background: { costUsd: 0, calls: 0, tokens: 0 },
+ ...over,
+});
+
+const DATA = {
+ window: { from: "2026-08-26", to: "2026-09-25", bucket: "day" },
+ org: {
+ costUsd: 16,
+ calls: 8,
+ tokens: 4000,
+ input: 400,
+ output: 400,
+ cacheRead: 2800,
+ cacheWrite: 400,
+ cacheHitRatio: 0.7,
+ live: { costUsd: 16, calls: 8, tokens: 4000 },
+ cron: { costUsd: 0, calls: 0, tokens: 0 },
+ background: { costUsd: 0, calls: 0, tokens: 0 },
+ },
+ series: [
+ { day: "2026-09-23", costUsd: 6, calls: 4, live: { costUsd: 6 }, cron: { costUsd: 0 }, background: { costUsd: 0 } },
+ {
+ day: "2026-09-24",
+ costUsd: 10,
+ calls: 4,
+ live: { costUsd: 10 },
+ cron: { costUsd: 0 },
+ background: { costUsd: 0 },
+ },
+ ],
+ people: [person("alice", 5), person("bob", 10), person("carol", 1)],
+ scopes: [person("", 0, { principalId: null, scopeId: "channel:C1", kind: "channel", displayName: "#general" })],
+};
+
+const EMPTY = {
+ window: { from: "2026-08-26", to: "2026-09-25", bucket: "day" },
+ org: {
+ costUsd: 0,
+ calls: 0,
+ tokens: 0,
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ cacheHitRatio: null,
+ live: { costUsd: 0, calls: 0, tokens: 0 },
+ cron: { costUsd: 0, calls: 0, tokens: 0 },
+ background: { costUsd: 0, calls: 0, tokens: 0 },
+ },
+ series: [],
+ people: [],
+ scopes: [],
+};
+
+function render(data: any) {
+ const f = litFixture();
+ const calls: any = { shell: null, ranges: [], opened: [], downloads: 0, modelDownloads: 0, api: 0 };
+ const view = f.ui.spend.spend(f.root, data, {
+ range: "30d",
+ defaultShell: (opts: any) => {
+ calls.shell = opts;
+ },
+ api: () => {
+ calls.api += 1;
+ return Promise.resolve({ ok: true, data: {} });
+ },
+ fmtPct: (n: number) => (n * 100).toFixed(1) + "%",
+ fmtTokens: (n: number) => `${n} tokens`,
+ shortName: String,
+ plural: (n: number, one: string) => `${n} ${one}`,
+ openUser: (principal: string) => calls.opened.push(principal),
+ setRange: (range: string) => calls.ranges.push(range),
+ downloadCsv: (breakdown?: string) => {
+ if (breakdown === "model") calls.modelDownloads += 1;
+ else calls.downloads += 1;
+ },
+ });
+ const peopleRows = () =>
+ [...f.root.querySelectorAll(".tablewrap")[0]!.querySelectorAll("tbody tr")].map((r) =>
+ r.querySelector("td")!.textContent!.trim(),
+ );
+ return { f, calls, view, peopleRows };
+}
+
+test("spend view: KPI stats, stacked chart and range tabs describe the whole org", () => {
+ const { f, calls } = render(DATA);
+ assert.deepEqual(JSON.parse(JSON.stringify(calls.shell.stats)), [
+ ["$16.00", "Total spend"],
+ ["$16.00", "Live"],
+ ["$0.00", "Crons"],
+ ["70.0%", "Cache hit rate"],
+ ]);
+ assert.deepEqual(JSON.parse(JSON.stringify(calls.shell.tabs.map((t: any) => [t.label, t.active]))), [
+ ["7d", false],
+ ["30d", true],
+ ["90d", false],
+ ]);
+ assert.equal(f.root.querySelectorAll(".spend-column").length, 30, "zero-spend dates retain their space");
+ assert.ok(f.root.textContent!.includes("$0.53"), "daily average includes zero-spend days");
+ const bar = f.root.querySelectorAll<HTMLElement>(".spend-column")[29]!;
+ bar.dispatchEvent(new f.window.Event("pointerenter"));
+ assert.match(f.root.querySelector(".spend-chart-detail")!.textContent!, /Sep 24.*\$10.00 total.*Live \$10.00/);
+ assert.equal(bar.querySelector<HTMLElement>(".spend-live")!.style.height, "100%");
+ calls.shell.tabs[0].onClick();
+ assert.deepEqual(calls.ranges, ["7d"]);
+ f.window.close();
+});
+
+test("spend view: search narrows the per-person table without touching the org stats", () => {
+ const { f, calls, peopleRows } = render(DATA);
+ const before = calls.shell.stats;
+ assert.deepEqual(peopleRows(), ["bob", "alice", "carol"]);
+ calls.shell.search.onInput("ali");
+ assert.deepEqual(peopleRows(), ["alice"]);
+ assert.equal(calls.shell.stats, before, "the shellbar is not rebuilt and the totals stay org-wide");
+ calls.shell.search.onInput("");
+ assert.deepEqual(peopleRows(), ["bob", "alice", "carol"]);
+ f.window.close();
+});
+
+test("spend view: a Total header click sorts ascending, a second click descending, with no refetch", () => {
+ const { f, calls, peopleRows } = render(DATA);
+ const totalHeader = () =>
+ [...f.root.querySelectorAll(".tablewrap")[0]!.querySelectorAll("thead th button")].find((b) =>
+ b.textContent!.includes("Total"),
+ ) as HTMLElement;
+ totalHeader().click();
+ assert.deepEqual(peopleRows(), ["carol", "alice", "bob"]);
+ totalHeader().click();
+ assert.deepEqual(peopleRows(), ["bob", "alice", "carol"]);
+ assert.equal(calls.api, 0, "sorting is client-side");
+ f.window.close();
+});
+
+test("spend view: a row click opens the sorted row's principal, and Export CSV downloads", () => {
+ const { f, calls } = render(DATA);
+ const rows = f.root.querySelectorAll(".tablewrap")[0]!.querySelectorAll<HTMLTableRowElement>("tbody tr");
+ rows[1]!.click();
+ assert.deepEqual(calls.opened, ["alice"], "the click indexes the sorted rows on screen");
+ calls.shell.actions[0].click();
+ assert.equal(calls.downloads, 1);
+ f.window.close();
+});
+
+test("spend view: shared-scope rows are labelled and never open a user page", () => {
+ const { f } = render(DATA);
+ const shared = f.root.querySelectorAll(".tablewrap")[1]!;
+ assert.equal(shared.querySelector("tbody td")!.textContent!.trim(), "#general");
+ assert.equal(shared.querySelectorAll("tr.openable").length, 0);
+ f.window.close();
+});
+
+test("spend view: an empty window renders empty-state copy and n/a, not a confident 0.0%", () => {
+ const { f, calls } = render(EMPTY);
+ assert.deepEqual(JSON.parse(JSON.stringify(calls.shell.stats[3])), ["n/a", "Cache hit rate"]);
+ assert.equal(f.root.querySelectorAll(".tablewrap").length, 0);
+ const text = f.root.textContent!;
+ assert.ok(text.includes("No spend recorded in this window."), text);
+ assert.ok(text.includes("No model calls recorded in this window."), text);
+ f.window.close();
+});
+
+test("spend view: a null per-row cache ratio reads n/a", () => {
+ const { f } = render({ ...DATA, people: [person("alice", 0, { cacheHitRatio: null })], scopes: [] });
+ const cells = [...f.root.querySelectorAll(".tablewrap")[0]!.querySelectorAll("tbody td")].map((c) =>
+ c.textContent!.trim(),
+ );
+ assert.equal(cells.at(-1), "n/a");
+ f.window.close();
+});
+
+test("spend chart: category stacks and keyboard details use exact amounts", () => {
+ const { f } = render({
+ ...DATA,
+ series: [{ day: "2026-09-24", live: { costUsd: 3 }, cron: { costUsd: 2 }, background: { costUsd: 1 } }],
+ });
+ const bar = f.root.querySelectorAll<HTMLElement>(".spend-column")[29]!;
+ bar.dispatchEvent(new f.window.Event("focus"));
+ assert.match(
+ f.root.querySelector(".spend-chart-detail")!.textContent!,
+ /Live \$3.00.*Crons \$2.00.*Background \$1.00/,
+ );
+ assert.equal(bar.querySelectorAll(".spend-segment").length, 3);
+ assert.ok(!f.root.innerHTML.includes("NaN"));
+ f.window.close();
+});
+test("spend chart: weekly bins preserve partial boundaries and zero spend is finite", () => {
+ const { f } = render({
+ ...DATA,
+ window: { ...DATA.window, bucket: "week" },
+ series: [{ day: "2026-08-24", live: { costUsd: 0 } }],
+ });
+ assert.equal(f.root.querySelectorAll(".spend-column").length, 5);
+ assert.match(f.root.querySelector(".spend-column")!.getAttribute("aria-label")!, /Aug 26.*Aug 30/);
+ assert.ok(!/NaN|Infinity/.test(f.root.innerHTML));
+ f.window.close();
+});
+
+test("spend models: category breakdown, sorting, filtering and export", () => {
+ const { f, calls } = render({
+ ...DATA,
+ models: [
+ { ...person("", 10), model: "model-a", live: { costUsd: 3 }, cron: { costUsd: 6 }, background: { costUsd: 1 } },
+ { ...person("", 6), model: null, live: { costUsd: 5 }, cron: { costUsd: 0 }, background: { costUsd: 1 } },
+ ],
+ });
+ const names = () =>
+ [...f.root.querySelectorAll(".spend-models tbody tr")].map((row) => row.querySelector("td")!.textContent!.trim());
+ assert.deepEqual(names(), ["model-a", "Unknown model"]);
+ const cells = [...f.root.querySelectorAll(".spend-models tbody tr:first-child td")].map((c) => c.textContent!.trim());
+ assert.deepEqual(cells.slice(0, 5), ["model-a", "$10.00", "$3.00", "$6.00", "$1.00"]);
+ const cron = [...f.root.querySelectorAll<HTMLElement>(".spend-models thead button")].find((b) =>
+ b.textContent!.includes("Crons"),
+ )!;
+ cron.click();
+ assert.deepEqual(names(), ["Unknown model", "model-a"]);
+ calls.shell.search.onInput("model-a");
+ assert.deepEqual(names(), ["model-a"]);
+ calls.shell.search.onInput("unmatched");
+ assert.match(f.root.querySelector(".spend-models")!.textContent!, /No models match/);
+ [...f.root.querySelectorAll<HTMLElement>("button")].find((b) => b.textContent === "Export model CSV")!.click();
+ assert.equal(calls.modelDownloads, 1);
+ assert.equal(calls.downloads, 0);
+ assert.deepEqual(calls.opened, []);
+ f.window.close();
+});
+
+test("spend chart: model stacks use each bucket, retain gaps, and switch back to categories", () => {
+ const data = {
+ ...DATA,
+ series: DATA.series.map((p, i) => ({
+ ...p,
+ models:
+ i === 0
+ ? [
+ { model: "model-a", costUsd: 2 },
+ { model: "model-b", costUsd: 4 },
+ ]
+ : [
+ { model: "model-a", costUsd: 7 },
+ { model: null, costUsd: 3 },
+ ],
+ })),
+ };
+ const { f, calls } = render(data);
+ const bars = () => f.root.querySelectorAll<HTMLElement>(".spend-column");
+ assert.match(f.root.querySelector(".spend-chart-plot")!.getAttribute("aria-label")!, /by model/);
+ assert.match(bars()[28]!.getAttribute("aria-label")!, /model-a \$2.00.*model-b \$4.00.*Unknown model \$0.00/);
+ assert.match(bars()[29]!.getAttribute("aria-label")!, /model-a \$7.00.*model-b \$0.00.*Unknown model \$3.00/);
+ assert.deepEqual(
+ [...bars()[29]!.querySelectorAll<HTMLElement>(".spend-segment")].map((s) => s.style.height),
+ ["70%", "0%", "30%"],
+ );
+ assert.match(bars()[0]!.getAttribute("aria-label")!, /\$0.00 total/);
+ bars()[29]!.dispatchEvent(new f.window.Event("focus"));
+ assert.match(f.root.querySelector(".spend-chart-detail")!.textContent!, /model-a \$7.00/);
+ calls.shell.search.onInput("alice");
+ assert.match(f.root.querySelector(".spend-chart-plot")!.getAttribute("aria-label")!, /by model/);
+ const toggle = (label: string) =>
+ [...f.root.querySelectorAll<HTMLElement>(".spend-chart-switch button")].find(
+ (b) => b.textContent!.trim() === label,
+ )!;
+ toggle("Category").click();
+ assert.equal(toggle("Category").getAttribute("aria-pressed"), "true");
+ assert.equal(bars()[29]!.querySelectorAll(".spend-live").length, 1);
+ assert.match(bars()[29]!.getAttribute("aria-label")!, /Live \$10.00/);
+ assert.doesNotMatch(f.root.querySelector(".spend-chart-detail")!.textContent!, /model-a/);
+ toggle("Model").click();
+ assert.equal(toggle("Model").getAttribute("aria-pressed"), "true");
+ assert.equal(bars()[29]!.querySelectorAll(".spend-model").length, 3);
+ assert.equal(calls.api, 0);
+ f.window.close();
+});
+
+test("spend chart: weekly model stacks and zero totals remain finite", () => {
+ const { f } = render({
+ ...DATA,
+ window: { ...DATA.window, bucket: "week" },
+ series: [{ day: "2026-08-24", models: [{ model: null, costUsd: 0 }] }],
+ });
+ assert.equal(f.root.querySelectorAll(".spend-column").length, 5);
+ assert.match(
+ f.root.querySelector(".spend-column")!.getAttribute("aria-label")!,
+ /Aug 26.*Aug 30.*Unknown model \$0.00/,
+ );
+ assert.ok(!/NaN|Infinity/.test(f.root.innerHTML));
+ f.window.close();
+});
+
+for (const bucket of ["day", "week"]) {
+ test(`spend chart: ${bucket} person toggle shows names, shared scopes and zero bins`, () => {
+ const { f, calls, view } = render({
+ ...DATA,
+ window: { ...DATA.window, bucket },
+ people: [person("alice", 3, { displayName: "Alice" }), person("bob", 2)],
+ series: [
+ {
+ day: bucket === "day" ? "2026-09-24" : "2026-09-21",
+ live: { costUsd: 10 },
+ models: [{ model: "model-a", costUsd: 10 }],
+ people: [
+ { principalId: "alice", costUsd: 3 },
+ { principalId: "bob", costUsd: 2 },
+ { principalId: null, costUsd: 5 },
+ ],
+ },
+ ],
+ });
+ const toggle = (label: string) =>
+ [...f.root.querySelectorAll<HTMLButtonElement>(".spend-chart-switch button")].find(
+ (b) => b.textContent!.trim() === label,
+ )!;
+ toggle("Person").click();
+ assert.equal(toggle("Person").getAttribute("aria-pressed"), "true");
+ const bars = () => f.root.querySelectorAll<HTMLElement>(".spend-column");
+ assert.equal(bars().length, bucket === "day" ? 30 : 5);
+ assert.match(
+ bars()[0]!.getAttribute("aria-label")!,
+ /\$0.00 total.*Alice \$0.00.*bob \$0.00.*Shared scopes \$0.00/,
+ );
+ const last = () => bars()[bars().length - 1]!;
+ last().dispatchEvent(new f.window.Event("focus"));
+ assert.match(
+ f.root.querySelector(".spend-chart-detail")!.textContent!,
+ /\$10.00 total.*Alice \$3.00.*bob \$2.00.*Shared scopes \$5.00/,
+ );
+ const colors = () => [...last().querySelectorAll<HTMLElement>(".spend-person")].map((s) => s.style.background);
+ const before = colors();
+ view.data.people[0].displayName = "Renamed Alice";
+ calls.shell.search.onInput("unmatched");
+ assert.deepEqual(colors(), before, "colors are stable across display-name changes and filtering");
+ assert.deepEqual(
+ [...last().querySelectorAll<HTMLElement>(".spend-segment")].map((s) => s.style.height),
+ ["30%", "20%", "50%"],
+ );
+ for (const label of ["Category", "Model", "Person"]) {
+ toggle(label).click();
+ assert.equal(toggle(label).getAttribute("aria-pressed"), "true");
+ assert.match(last().getAttribute("aria-label")!, /\$10.00 total/);
+ }
+ assert.ok(!/NaN|Infinity/.test(f.root.innerHTML));
+ assert.equal(calls.api, 0);
+ f.window.close();
+ });
+}
+
+test("spend chart: person toggle is disabled for reports without person buckets", () => {
+ const { f } = render(DATA);
+ assert.equal(
+ [...f.root.querySelectorAll<HTMLButtonElement>(".spend-chart-switch button")].find(
+ (b) => b.textContent!.trim() === "Person",
+ )!.disabled,
+ true,
+ );
+ f.window.close();
+});
diff --git a/plugins/admin/ui/admin.ts b/plugins/admin/ui/admin.ts
index 5f6fe925e..f2b08bab5 100644
--- a/plugins/admin/ui/admin.ts
+++ b/plugins/admin/ui/admin.ts
@@ -11,6 +11,7 @@ export * as users from "./users.ts";
export * as userDetail from "./user-detail.ts";
export * as keychain from "./keychain.ts";
export * as metrics from "./metrics.ts";
+export * as spend from "./spend.ts";
export * as transcript from "./transcript.ts";
export * as design from "./design.ts";
export * as activity from "./activity.ts";
diff --git a/plugins/admin/ui/spend-chart.ts b/plugins/admin/ui/spend-chart.ts
new file mode 100644
index 000000000..f9841f854
--- /dev/null
+++ b/plugins/admin/ui/spend-chart.ts
@@ -0,0 +1,126 @@
+import { html } from "lit";
+
+const DAY = 86400000;
+const PARTS = [
+ ["live", "Live"],
+ ["cron", "Crons"],
+ ["background", "Background"],
+] as const;
+const usd = (n: number) => "$" + n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+const date = (ms: number) =>
+ new Date(ms).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+
+export function spendChart(data: any, breakdown: "category" | "model" | "person" = "category") {
+ const field = breakdown === "person" ? "people" : "models";
+ const id = breakdown === "person" ? "principalId" : "model";
+ const unknown = breakdown === "person" ? "Shared scopes" : "Unknown model";
+ const names = new Map(
+ (breakdown === "person" ? data.people || [] : []).map((p: any) => [p.principalId, p.displayName || p.principalId]),
+ );
+ const keys = [
+ ...new Set<string | null>((data.series || []).flatMap((p: any) => (p[field] || []).map((item: any) => item[id]))),
+ ].sort((a, b) => {
+ if (a === b) return 0;
+ if (a === null) return 1;
+ if (b === null) return -1;
+ return a < b ? -1 : 1;
+ });
+ const parts =
+ breakdown !== "category"
+ ? keys.map((key) => {
+ let hash = 0;
+ for (const ch of key ?? "unknown") hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
+ return {
+ key,
+ label: key === null ? unknown : names.get(key) || key,
+ color: key === null ? "var(--muted)" : `hsl(${hash % 360} 55% 48%)`,
+ cls: `spend-${breakdown}`,
+ };
+ })
+ : PARTS.map(([key, label]) => ({ key, label, color: `var(--spend-${key})`, cls: `spend-${key}` }));
+ const from = Date.parse(data.window.from),
+ to = Date.parse(data.window.to);
+ const weekly = data.window.bucket === "week";
+ const step = (weekly ? 7 : 1) * DAY;
+ const start = weekly ? from - ((new Date(from).getUTCDay() + 6) % 7) * DAY : from;
+ const recorded = new Map((data.series || []).map((p: any) => [Date.parse(p.day), p]));
+ const points: any[] = [];
+ for (let t = start; t < to; t += step) {
+ const p: any = recorded.get(t);
+ const costs = new Map((p?.[field] || []).map((item: any) => [item[id], item.costUsd]));
+ points.push({
+ t,
+ values: parts.map(({ key }) =>
+ Math.max(0, Number(breakdown !== "category" ? costs.get(key) : p?.[key!]?.costUsd) || 0),
+ ),
+ });
+ }
+ const peak = Math.max(0, ...points.map((p) => p.values.reduce((a: number, b: number) => a + b, 0)));
+ const magnitude = 10 ** Math.floor(Math.log10(peak || 1));
+ const ceiling = peak ? [1, 2, 2.5, 5, 10].find((n) => n * magnitude >= peak)! * magnitude : 1;
+ const labelIndices = new Set([0, Math.floor((points.length - 1) / 2), points.length - 1]);
+ const total = Number(data.org?.costUsd) || 0;
+ const detailParts = (i: number) => {
+ const p = points[i];
+ const first = Math.max(p.t, from),
+ last = Math.min(p.t + step, to) - DAY;
+ return [
+ `${date(first)}${weekly && first !== last ? " – " + date(last) : ""}`,
+ `${usd(p.values.reduce((a: number, b: number) => a + b, 0))} total`,
+ ...parts.map(({ label }, k) => `${label} ${usd(p.values[k])}`),
+ ];
+ };
+ const detail = (i: number) => detailParts(i).join(" · ");
+ const inspect = (event: Event, i: number) => {
+ const chart = (event.currentTarget as HTMLElement).closest(".spend-chart")!;
+ chart.querySelector<HTMLElement>(".spend-chart-detail")!.replaceChildren(
+ ...detailParts(i).map((text) => {
+ const span = chart.ownerDocument.createElement("span");
+ span.textContent = text;
+ return span;
+ }),
+ );
+ chart.querySelectorAll(".spend-column").forEach((el, k) => el.classList.toggle("inspected", i === k));
+ };
+ return html`<div class="spend-chart">
+ <div class="spend-chart-summary">
+ <div><strong>${usd(total)}</strong><span>Total spend</span></div>
+ <div><strong>${usd(total / Math.max(1, (to - from) / DAY))}</strong><span>Average / day</span></div>
+ <div class="spend-chart-legend">
+ ${parts.map(({ label, color }) => html`<span><i style=${"background:" + color}></i>${label}</span>`)}
+ </div>
+ </div>
+ <div
+ class="spend-chart-plot"
+ role="group"
+ aria-label=${`Spend over time by ${breakdown} in US dollars. Focus a bar for its breakdown.`}
+ >
+ <div class="spend-chart-axis" aria-hidden="true">
+ ${[4, 3, 2, 1, 0].map((n) => html`<span>${usd((ceiling * n) / 4)}</span>`)}
+ </div>
+ <div class="spend-chart-bars">
+ <div class="spend-chart-grid" aria-hidden="true">${[0, 1, 2, 3, 4].map(() => html`<span></span>`)}</div>
+ ${points.map(
+ (p, i) =>
+ html`<div
+ class="spend-column"
+ tabindex="0"
+ role="img"
+ aria-label=${detail(i)}
+ @pointerenter=${(e: Event) => inspect(e, i)}
+ @focus=${(e: Event) => inspect(e, i)}
+ @click=${(e: Event) => inspect(e, i)}
+ >
+ ${parts.map(({ cls, color }, k) => html`<span class=${"spend-segment " + cls} style=${"height:" + (100 * p.values[k]) / ceiling + "%;background:" + color}></span>`)}
+ </div>`,
+ )}
+ </div>
+ <div class="spend-chart-dates" aria-hidden="true">
+ ${points.map((p, i) => html`<span>${labelIndices.has(i) ? date(Math.max(p.t, from)) : ""}</span>`)}
+ </div>
+ </div>
+ <div class="spend-chart-detail" aria-live="polite">
+ Hover or focus a bar for the ${weekly ? "weekly" : "daily"} breakdown. USD · UTC.
+ </div>
+ </div>`;
+}
diff --git a/plugins/admin/ui/spend.ts b/plugins/admin/ui/spend.ts
new file mode 100644
index 000000000..a559b590b
--- /dev/null
+++ b/plugins/admin/ui/spend.ts
@@ -0,0 +1,207 @@
+import { html } from "lit";
+import { keyed } from "lit/directives/keyed.js";
+import { spendChart } from "./spend-chart.ts";
+import { table, card, renderer } from "./shared.ts";
+
+type Services = Record<string, any>;
+
+const RANGES = ["7d", "30d", "90d"];
+const COLUMNS: Array<[string, string]> = [
+ ["person", "Person"],
+ ["costUsd", "Total"],
+ ["live", "Live"],
+ ["cron", "Crons"],
+ ["background", "Background"],
+ ["tokens", "Tokens"],
+ ["cacheHitRatio", "Cache hit"],
+];
+
+const rowName = (row: any) =>
+ "model" in row ? row.model || "Unknown model" : row.displayName || row.principalId || row.scopeId || "";
+
+const fmtUsd = (n: any) => "$" + (Number(n) || 0).toFixed(2);
+
+function sortValue(row: any, key: string): number | string {
+ if (key === "person") return String(rowName(row)).toLowerCase();
+ if (key === "live" || key === "cron" || key === "background") return Number(row[key]?.costUsd || 0);
+ if (key === "cacheHitRatio") return row.cacheHitRatio === null ? -1 : Number(row.cacheHitRatio);
+ return Number(row[key] || 0);
+}
+
+export class SpendView {
+ root: HTMLElement;
+ data: any;
+ services: Services;
+ paint: (template: unknown) => void;
+ filter = "";
+ chartBreakdown: "category" | "model" | "person";
+ sortKey = "costUsd";
+ sortDir: "asc" | "desc" = "desc";
+ search: HTMLElement | null = null;
+ constructor(root: HTMLElement, data: any, services: Services) {
+ this.root = root;
+ this.data = data;
+ this.chartBreakdown =
+ data.series?.length && data.series.every((p: any) => Array.isArray(p.models)) ? "model" : "category";
+ this.services = services;
+ this.paint = renderer(root);
+ this.renderShell();
+ this.draw();
+ }
+ renderShell() {
+ const s = this.services;
+ const org = this.data.org || {};
+ const document = this.root.ownerDocument;
+ const previous = this.search;
+ if (previous && !previous.isConnected) return;
+ const active = document.activeElement as HTMLElement | null;
+ const focused = !!active && !!previous?.contains(active);
+ const exportCsv = document.createElement("button");
+ exportCsv.type = "button";
+ exportCsv.textContent = "Export CSV";
+ exportCsv.onclick = () => s.downloadCsv();
+ s.defaultShell({
+ stats: [
+ [fmtUsd(org.costUsd), "Total spend"],
+ [fmtUsd(org.live?.costUsd), "Live"],
+ [fmtUsd(org.cron?.costUsd), "Crons"],
+ [org.cacheHitRatio == null ? "n/a" : s.fmtPct(org.cacheHitRatio), "Cache hit rate"],
+ ],
+ tabs: RANGES.map((range) => ({
+ label: range,
+ active: (s.range || "30d") === range,
+ onClick: () => s.setRange(range),
+ })),
+ search: {
+ value: this.filter,
+ placeholder: "person, scope or model",
+ onInput: (value: string) => {
+ this.filter = value;
+ this.draw();
+ },
+ },
+ actions: [exportCsv],
+ });
+ const search = document.querySelector<HTMLElement>("#shellbar .shell-search");
+ if (previous && search) {
+ search.replaceWith(previous);
+ if (focused) active?.focus({ preventScroll: true });
+ } else this.search = search;
+ }
+ sortBy(key: string) {
+ if (this.sortKey === key) this.sortDir = this.sortDir === "asc" ? "desc" : "asc";
+ else {
+ this.sortKey = key;
+ this.sortDir = "asc";
+ }
+ this.draw();
+ }
+ arrow(key: string) {
+ if (this.sortKey !== key) return "";
+ return this.sortDir === "asc" ? " ↑" : " ↓";
+ }
+ header(models = false) {
+ return COLUMNS.map(
+ ([key, label]) =>
+ html`<button type="button" class="rowbtn" @click=${() => this.sortBy(key)}>
+ ${models && key === "person" ? "Model" : label}${this.arrow(key)}
+ </button>`,
+ );
+ }
+ rowCells(row: any) {
+ const s = this.services;
+ const name = "model" in row ? rowName(row) : row.displayName || (row.principalId ?? s.shortName(row.scopeId));
+ return [
+ { text: name, cls: "mono" },
+ { text: fmtUsd(row.costUsd), cls: "num" },
+ { text: fmtUsd(row.live?.costUsd), cls: "num" },
+ { text: fmtUsd(row.cron?.costUsd), cls: "num" },
+ { text: fmtUsd(row.background?.costUsd), cls: "num" },
+ { text: s.fmtTokens(row.tokens || 0), cls: "num" },
+ { text: row.cacheHitRatio == null ? "n/a" : s.fmtPct(row.cacheHitRatio), cls: "num" },
+ ];
+ }
+ draw() {
+ const s = this.services;
+ const needle = this.filter.trim().toLowerCase();
+ const matches = (row: any) =>
+ [row.principalId || "", row.scopeId || "", row.displayName || ""].join(" ").toLowerCase().includes(needle);
+ const sorted = (rows: any[]) =>
+ rows.slice().sort((a, b) => {
+ const left = sortValue(a, this.sortKey);
+ const right = sortValue(b, this.sortKey);
+ if (left === right) return 0;
+ const order = left < right ? -1 : 1;
+ return this.sortDir === "asc" ? order : -order;
+ });
+ const people = sorted((this.data.people || []).filter(matches));
+ const scopes = sorted((this.data.scopes || []).filter(matches));
+ const models = sorted((this.data.models || []).filter((row: any) => rowName(row).toLowerCase().includes(needle)));
+ const series = this.data.series || [];
+ const org = this.data.org || {};
+ this.paint(
+ html`${card(
+ "Spend over time",
+ series.length
+ ? `${this.data.window?.from ?? ""} to ${this.data.window?.to ?? ""} (UTC, ${this.data.window?.bucket ?? "day"} buckets) · ${s.plural(org.calls || 0, "model call")}`
+ : "No model calls recorded in this window.",
+ series.length
+ ? keyed(this.chartBreakdown, spendChart(this.data, this.chartBreakdown))
+ : html`<p class="empty">Nothing to chart yet.</p>`,
+ series.length
+ ? html`<div class="spend-chart-switch" role="group" aria-label="Chart breakdown">
+ ${(["category", "model", "person"] as const).map(
+ (mode) =>
+ html`<button
+ type="button"
+ aria-pressed=${this.chartBreakdown === mode}
+ ?disabled=${mode !== "category" && !series.every((p: any) => Array.isArray(p[mode === "person" ? "people" : "models"]))}
+ @click=${() => {
+ this.chartBreakdown = mode;
+ this.draw();
+ }}
+ >
+ ${{ category: "Category", model: "Model", person: "Person" }[mode]}
+ </button>`,
+ )}
+ </div>`
+ : null,
+ )}${card(
+ "Spend per person",
+ "Live is interactive conversation; Crons are scheduled runs; Background covers webhook and monitor runs.",
+ table(
+ this.header(),
+ people.map((row: any) => this.rowCells(row)),
+ this.data.people?.length ? "No people match." : "No spend recorded in this window.",
+ (i) => {
+ const principalId = people[i]?.principalId;
+ if (principalId) s.openUser(principalId);
+ },
+ ),
+ )}${card(
+ "Shared scopes",
+ "Channels, groups and teams are billed to the scope, not to a speaker. These rows plus the people above make up the org total.",
+ table(
+ this.header(),
+ scopes.map((row: any) => this.rowCells(row)),
+ this.data.scopes?.length ? "No scopes match." : "No shared-scope spend in this window.",
+ ),
+ )}${card(
+ "Spend by model",
+ "Same org spend, split by the model recorded on each call. Unknown model covers calls without a model ID.",
+ html`<div class="spend-models">
+ ${table(
+ this.header(true),
+ models.map((row: any) => this.rowCells(row)),
+ this.data.models?.length ? "No models match." : "No model breakdown available in this window.",
+ )}
+ </div>`,
+ html`<button type="button" @click=${() => s.downloadCsv("model")}>Export model CSV</button>`,
+ )}`,
+ );
+ }
+}
+
+export function spend(root: HTMLElement, data: any, services: Services) {
+ return new SpendView(root, data, services);
+}
diff --git a/src/api/routes/admin.ts b/src/api/routes/admin.ts
index 37c850c2a..da8d407e2 100644
--- a/src/api/routes/admin.ts
+++ b/src/api/routes/admin.ts
@@ -55,6 +55,7 @@ import { deleteModelProvider, getModelProviders, putModelProvider } from "./admi
import { deleteCustomProvider, getCustomProviders, putCustomProvider } from "./admin/custom-providers.ts";
import { deleteMcpServer, getMcpServers, putMcpServer } from "./admin/mcp-servers.ts";
import { listSecurityFlags, releaseSecurityTaint } from "./admin/security.ts";
+import { spend } from "./admin/spend.ts";
import { createPrincipalLink, deletePrincipalLink, listPrincipalLinks } from "./admin/principal-links.ts";
const timed =
@@ -116,6 +117,7 @@ const routes: ReadonlyArray<Route<ApiCtx>> = [
{ method: "GET", path: "/v1/admin/resources", auth: "either", handle: getAdminResources },
{ method: "GET", path: "/v1/admin/retention", auth: "either", handle: retention },
{ method: "GET", path: "/v1/admin/metrics", auth: "either", handle: metrics },
+ { method: "GET", path: "/v1/admin/spend", auth: "either", handle: spend },
{ method: "GET", path: "/v1/admin/egress", auth: "either", handle: egress },
{ method: "GET", path: "/v1/admin/sessions", auth: "either", handle: listAdminSessions },
{ method: "GET", path: "/v1/admin/sessions/:id/llm", auth: "either", handle: getAdminSessionLlm },
diff --git a/src/api/routes/admin/spend.ts b/src/api/routes/admin/spend.ts
new file mode 100644
index 000000000..0e8fba5b8
--- /dev/null
+++ b/src/api/routes/admin/spend.ts
@@ -0,0 +1,386 @@
+import { cacheHitRatio } from "../../../admin/metrics-sink.ts";
+import { canonicalPerson } from "../../../directory/person.ts";
+import { parseScopeId, personalScope, type ScopeId } from "../../../types.ts";
+import type { SessionOrigin, SpendRow } from "../../../sessions/session-store.ts";
+import { contentDispositionAttachment, contentTypeWithUtf8Charset, sendJson } from "../../http.ts";
+import { audit, authorizeAdmin, orgScope } from "../shared.ts";
+import { discoverScopes } from "./common.ts";
+import { type ApiCtx } from "../route.ts";
+
+const DAY_MS = 86_400_000;
+const DEFAULT_WINDOW_DAYS = 30;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const EPOCH_MS = /^\d+$/;
+const CSV_FORMULA_LEAD = /^[=+\-@\t\r]/;
+const CSV_NEEDS_QUOTES = /["\r\n,]/;
+const CSV_TOTALS_HEADER = [
+ "live_usd",
+ "cron_usd",
+ "background_usd",
+ "total_usd",
+ "calls",
+ "input_tokens",
+ "output_tokens",
+ "cache_read_tokens",
+ "cache_write_tokens",
+ "cache_hit_ratio",
+];
+
+type SpendBreakdown = "entity" | "model";
+type SpendBucket = "day" | "week";
+type OriginBucket = "live" | "cron" | "background";
+const ORIGIN_BUCKETS: readonly OriginBucket[] = ["live", "cron", "background"];
+
+interface SpendBucketTotals {
+ costUsd: number;
+ calls: number;
+ tokens: number;
+}
+
+interface SpendTotals {
+ costUsd: number;
+ calls: number;
+ tokens: number;
+ input: number;
+ output: number;
+ cacheRead: number;
+ cacheWrite: number;
+ cacheHitRatio: number | null;
+ live: SpendBucketTotals;
+ cron: SpendBucketTotals;
+ background: SpendBucketTotals;
+}
+
+interface SpendEntity extends SpendTotals {
+ principalId: string | null;
+ scopeId: ScopeId;
+ kind: string;
+ displayName: string;
+}
+
+interface SpendSeriesPoint {
+ day: string;
+ costUsd: number;
+ calls: number;
+ models: { model: string | null; costUsd: number }[];
+ people: { principalId: string | null; costUsd: number }[];
+ live: { costUsd: number };
+ cron: { costUsd: number };
+ background: { costUsd: number };
+}
+
+export interface SpendReport {
+ window: { from: string; to: string; bucket: SpendBucket };
+ org: SpendTotals;
+ series: SpendSeriesPoint[];
+ people: SpendEntity[];
+ scopes: SpendEntity[];
+ models: ({ model: string | null } & SpendTotals)[];
+}
+
+export interface SpendSummaryOptions {
+ from: number;
+ to: number;
+ bucket: SpendBucket;
+ label: (scopeId: ScopeId) => string;
+}
+
+interface Tally {
+ costUsd: number;
+ calls: number;
+ input: number;
+ output: number;
+ cacheRead: number;
+ cacheWrite: number;
+}
+
+interface EntityAccumulator {
+ principalId: string | null;
+ scopeId: ScopeId;
+ kind: string;
+ sources: ScopeId[];
+ byOrigin: Record<OriginBucket, Tally>;
+}
+
+function emptyTally(): Tally {
+ return { costUsd: 0, calls: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+function emptyOrigins(): Record<OriginBucket, Tally> {
+ return { live: emptyTally(), cron: emptyTally(), background: emptyTally() };
+}
+
+function addRow(t: Tally, r: SpendRow): void {
+ t.costUsd += r.costUsd;
+ t.calls += r.calls;
+ t.input += r.input;
+ t.output += r.output;
+ t.cacheRead += r.cacheRead;
+ t.cacheWrite += r.cacheWrite;
+}
+
+function addTally(t: Tally, other: Tally): void {
+ t.costUsd += other.costUsd;
+ t.calls += other.calls;
+ t.input += other.input;
+ t.output += other.output;
+ t.cacheRead += other.cacheRead;
+ t.cacheWrite += other.cacheWrite;
+}
+
+function tokensOf(t: Tally): number {
+ return t.input + t.output + t.cacheRead + t.cacheWrite;
+}
+
+function bucketTotals(t: Tally): SpendBucketTotals {
+ return { costUsd: t.costUsd, calls: t.calls, tokens: tokensOf(t) };
+}
+
+function originBucket(origin: SessionOrigin): OriginBucket {
+ if (origin === "conversation") return "live";
+ if (origin === "cron") return "cron";
+ return "background";
+}
+
+function isoDay(day: number): string {
+ return new Date(day * DAY_MS).toISOString().slice(0, 10);
+}
+
+function weekStart(day: number): number {
+ return day - ((day + 3) % 7);
+}
+
+function totalsOf(byOrigin: Record<OriginBucket, Tally>): SpendTotals {
+ const total = emptyTally();
+ for (const bucket of ORIGIN_BUCKETS) addTally(total, byOrigin[bucket]);
+ return {
+ costUsd: total.costUsd,
+ calls: total.calls,
+ tokens: tokensOf(total),
+ input: total.input,
+ output: total.output,
+ cacheRead: total.cacheRead,
+ cacheWrite: total.cacheWrite,
+ cacheHitRatio: cacheHitRatio({
+ cacheRead: total.cacheRead,
+ cacheWrite: total.cacheWrite,
+ uncachedInput: total.input,
+ }),
+ live: bucketTotals(byOrigin.live),
+ cron: bucketTotals(byOrigin.cron),
+ background: bucketTotals(byOrigin.background),
+ };
+}
+
+function entityOf(acc: EntityAccumulator, label: (scopeId: ScopeId) => string): SpendEntity {
+ return {
+ principalId: acc.principalId,
+ scopeId: acc.scopeId,
+ kind: acc.kind,
+ displayName: acc.sources.map(label).find((name) => name) ?? "",
+ ...totalsOf(acc.byOrigin),
+ };
+}
+
+function byCostThenId(a: SpendEntity, b: SpendEntity): number {
+ if (a.costUsd !== b.costUsd) return b.costUsd - a.costUsd;
+ if (a.scopeId === b.scopeId) return 0;
+ return a.scopeId < b.scopeId ? -1 : 1;
+}
+
+function byCostThenModel(
+ a: { model: string | null; costUsd: number },
+ b: { model: string | null; costUsd: number },
+): number {
+ if (a.costUsd !== b.costUsd) return b.costUsd - a.costUsd;
+ if (a.model === b.model) return 0;
+ if (a.model === null) return 1;
+ if (b.model === null) return -1;
+ return a.model < b.model ? -1 : 1;
+}
+
+export function summarizeSpend(rows: readonly SpendRow[], opts: SpendSummaryOptions): SpendReport {
+ const accumulators = new Map<string, EntityAccumulator>();
+ const buckets = new Map<
+ number,
+ { byOrigin: Record<OriginBucket, Tally>; models: Map<string | null, number>; people: Map<string | null, number> }
+ >();
+ const modelBuckets = new Map<string | null, Record<OriginBucket, Tally>>();
+ const orgOrigins = emptyOrigins();
+ for (const row of rows) {
+ const parsed = parseScopeId(row.scopeId);
+ const person = parsed.kind === "personal" && parsed.ref ? canonicalPerson(parsed.ref) : null;
+ const key = person === null ? row.scopeId : personalScope(person);
+ let acc = accumulators.get(key);
+ if (!acc) {
+ acc = {
+ principalId: person,
+ scopeId: key,
+ kind: person === null ? (parsed.kind ?? "unknown") : "person",
+ sources: [],
+ byOrigin: emptyOrigins(),
+ };
+ accumulators.set(key, acc);
+ }
+ if (!acc.sources.includes(row.scopeId)) acc.sources.push(row.scopeId);
+ const origin = originBucket(row.origin);
+ addRow(acc.byOrigin[origin], row);
+ addRow(orgOrigins[origin], row);
+ let model = modelBuckets.get(row.model);
+ if (!model) {
+ model = emptyOrigins();
+ modelBuckets.set(row.model, model);
+ }
+ addRow(model[origin], row);
+
+ const bucketKey = opts.bucket === "week" ? weekStart(row.day) : row.day;
+ let bucket = buckets.get(bucketKey);
+ if (!bucket) {
+ bucket = { byOrigin: emptyOrigins(), models: new Map(), people: new Map() };
+ buckets.set(bucketKey, bucket);
+ }
+ addRow(bucket.byOrigin[origin], row);
+ bucket.models.set(row.model, (bucket.models.get(row.model) ?? 0) + row.costUsd);
+ bucket.people.set(person, (bucket.people.get(person) ?? 0) + row.costUsd);
+ }
+
+ const entities = [...accumulators.values()].map((acc) => entityOf(acc, opts.label));
+ const people = entities.filter((e) => e.principalId !== null).sort(byCostThenId);
+ const scopes = entities.filter((e) => e.principalId === null).sort(byCostThenId);
+
+ const models = [...modelBuckets.entries()]
+ .map(([model, byOrigin]) => ({ model, ...totalsOf(byOrigin) }))
+ .sort(byCostThenModel);
+
+ const series = [...buckets.entries()]
+ .sort(([a], [b]) => a - b)
+ .map(([day, { byOrigin, models, people }]) => {
+ const total = emptyTally();
+ for (const bucket of ORIGIN_BUCKETS) addTally(total, byOrigin[bucket]);
+ return {
+ day: isoDay(day),
+ costUsd: total.costUsd,
+ calls: total.calls,
+ models: [...models].map(([model, costUsd]) => ({ model, costUsd })).sort(byCostThenModel),
+ people: [...people]
+ .sort(([a], [b]) => {
+ if (a === b) return 0;
+ if (a === null) return 1;
+ if (b === null) return -1;
+ return a < b ? -1 : 1;
+ })
+ .map(([principalId, costUsd]) => ({ principalId, costUsd })),
+ live: { costUsd: byOrigin.live.costUsd },
+ cron: { costUsd: byOrigin.cron.costUsd },
+ background: { costUsd: byOrigin.background.costUsd },
+ };
+ });
+
+ return {
+ window: {
+ from: isoDay(Math.floor(opts.from / DAY_MS)),
+ to: isoDay(Math.floor(opts.to / DAY_MS)),
+ bucket: opts.bucket,
+ },
+ org: totalsOf(orgOrigins),
+ series,
+ people,
+ scopes,
+ models,
+ };
+}
+
+function csvCell(value: string | number | null): string {
+ if (value === null) return "";
+ if (typeof value === "number") return String(value);
+ const defanged = CSV_FORMULA_LEAD.test(value) ? `'${value}` : value;
+ return CSV_NEEDS_QUOTES.test(defanged) ? `"${defanged.replaceAll('"', '""')}"` : defanged;
+}
+
+export function spendCsv(report: SpendReport, breakdown: SpendBreakdown = "entity"): string {
+ const modelBreakdown = breakdown === "model";
+ const header = modelBreakdown ? ["model"] : ["principal_id", "scope_id", "kind", "display_name"];
+ const rows = modelBreakdown
+ ? report.models.map((row) => ({ labels: [row.model ?? "Unknown model"], totals: row }))
+ : [...report.people, ...report.scopes].map((row) => ({
+ labels: [row.principalId, row.scopeId, row.kind, row.displayName],
+ totals: row,
+ }));
+ const lines = [[...header, ...CSV_TOTALS_HEADER].join(",")];
+ for (const { labels, totals: row } of rows) {
+ lines.push(
+ [
+ ...labels,
+ row.live.costUsd,
+ row.cron.costUsd,
+ row.background.costUsd,
+ row.costUsd,
+ row.calls,
+ row.input,
+ row.output,
+ row.cacheRead,
+ row.cacheWrite,
+ row.cacheHitRatio,
+ ]
+ .map(csvCell)
+ .join(","),
+ );
+ }
+ return lines.join("\r\n") + "\r\n";
+}
+
+function parseBound(raw: string): number | null {
+ const value = raw.trim();
+ let parsed = NaN;
+ if (DATE_ONLY.test(value)) {
+ parsed = Date.parse(`${value}T00:00:00.000Z`);
+ if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== value) return null;
+ } else if (EPOCH_MS.test(value)) parsed = Number(value);
+ return Number.isSafeInteger(parsed) && Number.isFinite(new Date(parsed).getTime()) ? parsed : null;
+}
+
+export async function spend(ctx: ApiCtx): Promise<void> {
+ const { res, app, deps, url } = ctx;
+ const scope = orgScope(deps);
+ const actor = await authorizeAdmin(ctx, scope);
+ if (!actor) return;
+ audit(deps, { principalId: actor.id, action: "spend.read", resource: "spend", scopeLabel: scope });
+
+ const bad = (message: string) => sendJson(res, 400, { error: "bad_request", message });
+ const bucket = url.searchParams.get("bucket") ?? "day";
+ if (bucket !== "day" && bucket !== "week") return bad('bucket must be "day" or "week"');
+ const format = url.searchParams.get("format") ?? "json";
+ if (format !== "json" && format !== "csv") return bad('format must be "json" or "csv"');
+
+ const breakdown = url.searchParams.get("breakdown") ?? "entity";
+ if (breakdown !== "entity" && breakdown !== "model") return bad('breakdown must be "entity" or "model"');
+
+ const toRaw = url.searchParams.get("to");
+ const to = toRaw === null ? Math.floor(Date.now() / DAY_MS) * DAY_MS + DAY_MS : parseBound(toRaw);
+ if (to === null) return bad("to must be a YYYY-MM-DD date (UTC) or epoch milliseconds");
+ const fromRaw = url.searchParams.get("from");
+ const from = fromRaw === null ? to - DEFAULT_WINDOW_DAYS * DAY_MS : parseBound(fromRaw);
+ if (from === null) return bad("from must be a YYYY-MM-DD date (UTC) or epoch milliseconds");
+ if (to <= from) return bad("to must be later than from");
+
+ const rows = (await deps.sessions?.spendRollup({ from, to })) ?? [];
+ const labels = await discoverScopes(
+ app,
+ deps,
+ rows.map((r) => r.scopeId),
+ );
+ const report = summarizeSpend(rows, { from, to, bucket, label: (id) => labels.get(id) ?? "" });
+ if (format === "json") return sendJson(res, 200, { scopeId: scope, ...report });
+
+ const body = spendCsv(report, breakdown);
+ res.writeHead(200, {
+ "content-type": contentTypeWithUtf8Charset("text/csv"),
+ "content-length": String(Buffer.byteLength(body)),
+ "content-disposition": contentDispositionAttachment(
+ `qm-spend-${breakdown === "model" ? "models-" : ""}${report.window.from}-${report.window.to}.csv`,
+ ),
+ "x-content-type-options": "nosniff",
+ });
+ res.end(body);
+ return;
+}
diff --git a/src/sessions/memory-session-store.ts b/src/sessions/memory-session-store.ts
index 704b3c370..fc1f3d6a6 100644
--- a/src/sessions/memory-session-store.ts
+++ b/src/sessions/memory-session-store.ts
@@ -22,6 +22,7 @@ import type {
SessionStore,
SessionSummary,
SessionPin,
+ SpendRow,
StoreOptions,
TapeRecord,
} from "./session-store.ts";
@@ -881,6 +882,55 @@ export function createMemorySessionStore(opts: StoreOptions = {}): SessionStore
return out;
},
+ async spendRollup(range): Promise<SpendRow[]> {
+ const DAY = 86_400_000;
+ const buckets = new Map<string, SpendRow>();
+ for (const [sessionId, records] of llmRequests) {
+ const session = sessions.get(sessionId);
+ if (!session) continue;
+ let origin = sessionOrigin(session.threadRef);
+ let ancestor = session;
+ const visited = new Set([sessionId]);
+ while (origin === "conversation" && ancestor.parentSessionId && visited.size < 64) {
+ const parent = sessions.get(ancestor.parentSessionId);
+ if (!parent || visited.has(parent.id)) break;
+ visited.add(parent.id);
+ ancestor = parent;
+ origin = sessionOrigin(parent.threadRef);
+ }
+ for (const r of records) {
+ if (!r.usage) continue;
+ if (r.createdAt < range.from || r.createdAt >= range.to) continue;
+ const day = Math.floor(r.createdAt / DAY);
+ const model = r.model ?? null;
+ const key = JSON.stringify([day, session.scopeId, origin, model]);
+ let row = buckets.get(key);
+ if (!row) {
+ row = {
+ day,
+ model,
+ scopeId: session.scopeId,
+ origin,
+ calls: 0,
+ costUsd: 0,
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ };
+ buckets.set(key, row);
+ }
+ row.calls += 1;
+ row.costUsd += r.usage.costUsd;
+ row.input += r.usage.input;
+ row.output += r.usage.output;
+ row.cacheRead += r.usage.cacheRead;
+ row.cacheWrite += r.usage.cacheWrite;
+ }
+ }
+ return [...buckets.values()];
+ },
+
async listParticipants() {
const out: ParticipantWindow[] = [];
for (const [sessionId, byPrincipal] of windows) {
diff --git a/src/sessions/postgres-session-store.ts b/src/sessions/postgres-session-store.ts
index e28b94ffc..f25f2456e 100644
--- a/src/sessions/postgres-session-store.ts
+++ b/src/sessions/postgres-session-store.ts
@@ -29,6 +29,7 @@ import type {
SessionRef,
SessionStore,
SessionSummary,
+ SpendRow,
StoreOptions,
TapeRecord,
} from "./session-store.ts";
@@ -172,6 +173,21 @@ export function rowToEntry(r: Record<string, unknown>): SessionEntry {
};
}
+function rowToSpendRow(r: Record<string, unknown>): SpendRow {
+ return {
+ day: Number(r.day),
+ model: (r.model as string | null) ?? null,
+ scopeId: r.scope_id as ScopeId,
+ origin: r.origin as SessionOrigin,
+ calls: Number(r.calls),
+ costUsd: Number(r.cost_usd),
+ input: Number(r.input),
+ output: Number(r.output),
+ cacheRead: Number(r.cache_read),
+ cacheWrite: Number(r.cache_write),
+ };
+}
+
const LAST_ACTIVITY_DEBOUNCE_MS = 60_000;
const SEARCH_TIMEOUT_MS = 10_000;
@@ -571,6 +587,14 @@ export function createPostgresSessionStore(connectionString: string, opts: Store
id: "sessions/store/0016-status",
statements: ["ALTER TABLE sessions ADD COLUMN IF NOT EXISTS status JSONB"],
},
+ {
+ id: "sessions/store/0018-llm-requests-created-at",
+ statements: [
+ `SET LOCAL lock_timeout = '3s'`,
+ `CREATE INDEX IF NOT EXISTS session_llm_requests_created_at
+ ON session_llm_requests(created_at)`,
+ ],
+ },
],
[
{
@@ -1606,6 +1630,50 @@ export function createPostgresSessionStore(connectionString: string, opts: Store
}));
},
+ async spendRollup(range): Promise<SpendRow[]> {
+ const rows = await q(
+ `WITH RECURSIVE spending AS (
+ SELECT DISTINCT session_id FROM session_llm_requests
+ WHERE created_at >= $1 AND created_at < $2 AND usage_json IS NOT NULL
+ ), ancestry AS (
+ SELECT s.id AS session_id, s.parent_session_id, ${originExpr("s")} AS origin, ARRAY[s.id] AS path
+ FROM sessions s JOIN spending r ON r.session_id = s.id
+ UNION ALL
+ SELECT a.session_id, p.parent_session_id, ${originExpr("p")}, a.path || p.id
+ FROM ancestry a JOIN sessions p ON p.id = a.parent_session_id
+ WHERE a.origin = 'conversation' AND NOT p.id = ANY(a.path) AND cardinality(a.path) < 64
+ ), origins AS (
+ SELECT DISTINCT ON (session_id) session_id, origin
+ FROM ancestry ORDER BY session_id, cardinality(path) DESC
+ )
+ SELECT day, scope_id, origin, model,
+ COUNT(*) AS calls,
+ COALESCE(SUM(cost_usd), 0) AS cost_usd,
+ COALESCE(SUM(input), 0) AS input,
+ COALESCE(SUM(output), 0) AS output,
+ COALESCE(SUM(cache_read), 0) AS cache_read,
+ COALESCE(SUM(cache_write), 0) AS cache_write
+ FROM (SELECT (r.created_at / 86400000)::bigint AS day,
+ s.scope_id,
+ r.model,
+ o.origin,
+ (u.j ->> 'costUsd')::double precision AS cost_usd,
+ (u.j ->> 'input')::bigint AS input,
+ (u.j ->> 'output')::bigint AS output,
+ (u.j ->> 'cacheRead')::bigint AS cache_read,
+ (u.j ->> 'cacheWrite')::bigint AS cache_write
+ FROM session_llm_requests r
+ JOIN sessions s ON s.id = r.session_id
+ JOIN origins o ON o.session_id = s.id
+ CROSS JOIN LATERAL (SELECT r.usage_json::jsonb AS j) u
+ WHERE r.created_at >= $1 AND r.created_at < $2
+ AND r.usage_json IS NOT NULL) t
+ GROUP BY day, scope_id, origin, model`,
+ [range.from, range.to],
+ );
+ return rows.map(rowToSpendRow);
+ },
+
async listParticipants(): Promise<ParticipantWindow[]> {
const rows = await q(
"SELECT session_id, principal_id, valid_from, valid_to, valid_from_seq, valid_to_seq FROM participants",
diff --git a/src/sessions/session-store.ts b/src/sessions/session-store.ts
index 8878d8393..f2676a671 100644
--- a/src/sessions/session-store.ts
+++ b/src/sessions/session-store.ts
@@ -336,6 +336,19 @@ export interface ScopeSessionStats {
crons: number;
}
+export interface SpendRow {
+ day: number;
+ model: string | null;
+ scopeId: ScopeId;
+ origin: SessionOrigin;
+ calls: number;
+ costUsd: number;
+ input: number;
+ output: number;
+ cacheRead: number;
+ cacheWrite: number;
+}
+
export interface LlmCallUsage {
input: number;
output: number;
@@ -789,6 +802,8 @@ export interface SessionStore {
attributedTurns(): Promise<AttributedTurn[]>;
+ spendRollup(range: { from: number; to: number }): Promise<SpendRow[]>;
+
listParticipants(): Promise<ParticipantWindow[]>;
distinctParticipants(): Promise<string[]>;
diff --git a/test/admin-spend.test.ts b/test/admin-spend.test.ts
new file mode 100644
index 000000000..771a4a47d
--- /dev/null
+++ b/test/admin-spend.test.ts
@@ -0,0 +1,360 @@
+import "./support/auto-fake-sprites.ts";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AddressInfo } from "node:net";
+import { createInsecureTestServer } from "../src/api/server.ts";
+import { createMemorySessionStore } from "../src/sessions/memory-session-store.ts";
+import { cacheHitRatio } from "../src/admin/metrics-sink.ts";
+import { buildApp } from "../src/wiring.ts";
+import { scopeId, type SessionType, type TurnRequest } from "../src/types.ts";
+import type { LlmCallUsage, SessionStore } from "../src/sessions/session-store.ts";
+import { testConfig } from "./support/test-config.ts";
+
+const DAY = 86_400_000;
+const ALICE = { "x-admin-actor": "admin-alice@default-org" };
+const RANDO = { "x-admin-actor": "rando@default-org" };
+const ORG = "org:default-org";
+
+function start(sessions?: SessionStore) {
+ const built = buildApp(testConfig({ dataDir: mkdtempSync(join(tmpdir(), "admin-spend-")) }));
+ const server = createInsecureTestServer(built.app, {
+ admin: built.admin,
+ sessions: sessions ?? built.sessions,
+ auditLog: built.auditLog,
+ metrics: built.metrics,
+ runs: built.runs,
+ });
+ server.listen(0);
+ const base = `http://localhost:${(server.address() as AddressInfo).port}`;
+ return { base, built, close: () => new Promise<void>((r) => server.close(() => r())) };
+}
+
+const get = (base: string, path: string, headers: Record<string, string> = ALICE) => fetch(base + path, { headers });
+const getJson = async (base: string, path: string, headers: Record<string, string> = ALICE): Promise<any> =>
+ (await get(base, path, headers)).json();
+
+const dm = (principal: string, text: string): TurnRequest => ({
+ surface: "test",
+ actor: { externalId: principal },
+ conversation: { kind: "dm", threadRef: `dm:${principal}:t1` },
+ text,
+});
+
+const usage = (over: Partial<LlmCallUsage>): LlmCallUsage => ({
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ totalTokens: 560,
+ costUsd: 0,
+ ...over,
+});
+
+async function bill(
+ sessions: SessionStore,
+ threadRef: string,
+ type: SessionType,
+ scope: string,
+ over: Partial<LlmCallUsage>,
+ model = "mock",
+): Promise<void> {
+ const session = await sessions.getOrCreateByThread(threadRef, type, scope);
+ await sessions.recordLlmRequest(session.id, {
+ turnSeq: null,
+ step: 0,
+ model,
+ scopeLabel: scope,
+ usage: usage(over),
+ });
+}
+
+async function seedPricedFixture(sessions: SessionStore): Promise<void> {
+ await bill(sessions, "dm:alice:priced", "dm", scopeId("personal", "alice"), { costUsd: 2 });
+ await bill(sessions, "cron:nightly:fire:abc123", "dm", scopeId("personal", "alice"), { costUsd: 0.5 });
+ await bill(sessions, "dm:bob:priced", "dm", scopeId("personal", "bob"), { costUsd: 1.25 });
+ await bill(sessions, "ch:C1:priced", "channel", scopeId("channel", "C1"), { costUsd: 3 });
+}
+
+const conserved = (report: any, column: string): number =>
+ [...report.people, ...report.scopes].reduce((sum: number, e: any) => sum + e[column], 0);
+
+test("spend: live and cron dollars land on the owning person, shared scopes on their own rows", async () => {
+ const s = start();
+ try {
+ assert.equal((await s.built.app.turn(dm("alice", "hello there"))).status, "ok");
+ assert.equal((await s.built.app.turn(dm("bob", "hello there"))).status, "ok");
+ await seedPricedFixture(s.built.sessions);
+
+ const body = await getJson(s.base, "/v1/admin/spend");
+ assert.equal(body.scopeId, ORG);
+ assert.equal(body.window.bucket, "day");
+
+ const alice = body.people.find((p: any) => p.principalId === "alice");
+ const bob = body.people.find((p: any) => p.principalId === "bob");
+ assert.ok(alice && bob, "both principals appear with the ids the Users page shows");
+ assert.ok(alice.live.costUsd > 0 && alice.cron.costUsd > 0, "alice carries both live and cron dollars");
+ assert.equal(bob.cron.costUsd, 0, "bob never ran a cron");
+ assert.equal(alice.cron.costUsd, 0.5, "the cron is billed to its scope owner, not to a speaker");
+
+ assert.deepEqual(
+ body.scopes.map((e: any) => [e.principalId, e.scopeId, e.kind, e.costUsd]),
+ [[null, "channel:C1", "channel", 3]],
+ );
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: people plus shared scopes reconcile to the org totals", async () => {
+ const s = start();
+ try {
+ assert.equal((await s.built.app.turn(dm("alice", "hello there"))).status, "ok");
+ await seedPricedFixture(s.built.sessions);
+
+ const body = await getJson(s.base, "/v1/admin/spend");
+ assert.ok(Math.abs(conserved(body, "costUsd") - body.org.costUsd) <= 1e-9);
+ for (const column of ["calls", "tokens", "input", "output", "cacheRead", "cacheWrite"]) {
+ assert.equal(conserved(body, column), body.org[column], column);
+ }
+ assert.equal(
+ body.org.cacheHitRatio,
+ cacheHitRatio({ cacheRead: body.org.cacheRead, cacheWrite: body.org.cacheWrite, uncachedInput: body.org.input }),
+ );
+ for (const person of body.people) {
+ assert.ok(
+ person.cacheHitRatio === null || (person.cacheHitRatio >= 0 && person.cacheHitRatio <= 1),
+ "a per-person ratio is a real fraction or null",
+ );
+ }
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: a mock-harness turn shows zero dollars with its tokens intact", async () => {
+ const s = start();
+ try {
+ assert.equal((await s.built.app.turn(dm("codexlike", "hello there"))).status, "ok");
+ const body = await getJson(s.base, "/v1/admin/spend");
+ const row = body.people.find((p: any) => p.principalId === "codexlike");
+ assert.ok(row, "a scope whose harness books no dollars is still listed");
+ assert.equal(row.costUsd, 0);
+ assert.ok(row.tokens > 0, "tokens are a separate column, so $0 turns stay visible");
+ assert.ok(row.cacheHitRatio !== null && row.cacheHitRatio >= 0 && row.cacheHitRatio <= 1);
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: a window in the past excludes today's rows entirely", async () => {
+ const s = start();
+ try {
+ assert.equal((await s.built.app.turn(dm("alice", "hello there"))).status, "ok");
+ await seedPricedFixture(s.built.sessions);
+
+ const now = await getJson(s.base, "/v1/admin/spend");
+ assert.ok(now.org.costUsd > 0);
+ const past = await getJson(s.base, "/v1/admin/spend?from=2020-01-01&to=2020-02-01");
+ assert.deepEqual(past.window, { from: "2020-01-01", to: "2020-02-01", bucket: "day" });
+ assert.equal(past.org.costUsd, 0);
+ assert.equal(past.org.calls, 0);
+ assert.deepEqual(past.people, []);
+ assert.deepEqual(past.scopes, []);
+ assert.deepEqual(past.series, []);
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: from/to and bucket=week reshape the series over backdated rows", async () => {
+ const clock = { at: Date.UTC(2026, 0, 5, 12) };
+ const store = createMemorySessionStore({ now: () => clock.at });
+ const s = start(store);
+ try {
+ await bill(store, "dm:alice:d1", "dm", scopeId("personal", "alice"), { costUsd: 2 });
+ await bill(store, "ch:C1:d1", "channel", scopeId("channel", "C1"), { costUsd: 1 });
+ clock.at += DAY;
+ await bill(store, "dm:alice:d2", "dm", scopeId("personal", "alice"), { costUsd: 4 });
+ await bill(store, "cron:nightly:fire:abc123", "dm", scopeId("personal", "alice"), { costUsd: 0.5 });
+
+ const both = await getJson(s.base, "/v1/admin/spend?from=2026-01-05&to=2026-01-07");
+ assert.deepEqual(
+ both.series.map((p: any) => p.day),
+ ["2026-01-05", "2026-01-06"],
+ );
+ for (const point of both.series) assert.match(point.day, /^\d{4}-\d{2}-\d{2}$/);
+ assert.equal(both.org.costUsd, 7.5);
+
+ const dayTwo = await getJson(s.base, "/v1/admin/spend?from=2026-01-06&to=2026-01-07");
+ assert.deepEqual(
+ dayTwo.series.map((p: any) => p.day),
+ ["2026-01-06"],
+ );
+ assert.equal(dayTwo.org.costUsd, 4.5);
+ assert.ok(dayTwo.org.costUsd < both.org.costUsd, "a narrower window cannot report more spend");
+ assert.deepEqual(
+ dayTwo.people.map((p: any) => p.principalId),
+ ["alice"],
+ "day one's channel row falls outside [from, to)",
+ );
+ assert.deepEqual(dayTwo.scopes, []);
+
+ const weekly = await getJson(s.base, "/v1/admin/spend?from=2026-01-05&to=2026-01-07&bucket=week");
+ assert.deepEqual(
+ weekly.series.map((p: any) => [p.day, p.costUsd]),
+ [["2026-01-05", 7.5]],
+ "both UTC days collapse into the Monday-aligned week that contains them",
+ );
+ assert.equal(weekly.window.bucket, "week");
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: ?format=csv exports the same numbers for the same window", async () => {
+ const clock = { at: Date.UTC(2026, 0, 5, 12) };
+ const store = createMemorySessionStore({ now: () => clock.at });
+ const s = start(store);
+ try {
+ await seedPricedFixture(store);
+ const query = "from=2026-01-05&to=2026-01-06";
+ const json = await getJson(s.base, `/v1/admin/spend?${query}`);
+ const r = await get(s.base, `/v1/admin/spend?${query}&format=csv`);
+ assert.equal(r.status, 200);
+ assert.equal(r.headers.get("content-type"), "text/csv; charset=utf-8");
+ assert.equal(r.headers.get("x-content-type-options"), "nosniff");
+ assert.match(r.headers.get("content-disposition")!, /^attachment; filename="qm-spend-2026-01-05-2026-01-06\.csv"/);
+ const body = await r.text();
+ assert.equal(Number(r.headers.get("content-length")), Buffer.byteLength(body));
+
+ const lines = body.trimEnd().split("\r\n");
+ assert.equal(
+ lines[0],
+ "principal_id,scope_id,kind,display_name,live_usd,cron_usd,background_usd,total_usd,calls,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cache_hit_ratio",
+ );
+ assert.equal(lines.length, json.people.length + json.scopes.length + 1);
+ const alice = lines.find((l) => l.startsWith("alice,"))!.split(",");
+ assert.equal(Number(alice[7]), json.people.find((p: any) => p.principalId === "alice").costUsd);
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: a caller with no admin grant gets 403 and writes no audit event, JSON or CSV", async () => {
+ const s = start();
+ try {
+ for (const path of [
+ "/v1/admin/spend",
+ "/v1/admin/spend?format=csv",
+ "/v1/admin/spend?format=csv&breakdown=model",
+ ]) {
+ const r = await get(s.base, path, RANDO);
+ assert.equal(r.status, 403);
+ assert.equal(r.headers.get("content-type"), "application/json");
+ const body = (await r.json()) as Record<string, unknown>;
+ assert.deepEqual(Object.keys(body).sort(), ["error", "message"]);
+ }
+ assert.equal(
+ (await s.built.auditLog.events()).filter((e) => e.action === "spend.read").length,
+ 0,
+ "a rejected read leaves no spend.read trail",
+ );
+
+ assert.equal((await get(s.base, "/v1/admin/spend")).status, 200);
+ assert.equal((await get(s.base, "/v1/admin/spend?format=csv")).status, 200);
+ const audited = (await s.built.auditLog.events()).filter((e) => e.action === "spend.read");
+ assert.equal(audited.length, 2, "both formats audit under the same action");
+ for (const event of audited) assert.equal(event.resource, "spend");
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: malformed windows are rejected instead of silently defaulted", async () => {
+ const s = start();
+ try {
+ for (const query of [
+ "from=not-a-date",
+ "from=9007199254740991",
+ "to=9007199254740991",
+ "from=2026-02-30",
+ "to=2026-13-01",
+ "to=yesterday",
+ "from=2026-01-05&to=2026-01-05",
+ "from=2026-01-06&to=2026-01-05",
+ "bucket=fortnight",
+ "format=xlsx",
+ "breakdown=provider",
+ "breakdown=",
+ "format=csv&breakdown=provider",
+ "to=99999999999999999999",
+ ]) {
+ const r = await get(s.base, `/v1/admin/spend?${query}`);
+ assert.equal(r.status, 400, query);
+ assert.equal(((await r.json()) as { error: string }).error, "bad_request", query);
+ }
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: an empty deployment answers 200 with zeroed totals", async () => {
+ const s = start();
+ try {
+ const body = await getJson(s.base, "/v1/admin/spend");
+ assert.equal(body.org.costUsd, 0);
+ assert.equal(body.org.calls, 0);
+ assert.equal(body.org.cacheHitRatio, null);
+ assert.deepEqual(body.people, []);
+ assert.deepEqual(body.scopes, []);
+ assert.deepEqual(body.series, []);
+ assert.deepEqual(body.models, []);
+ } finally {
+ await s.close();
+ }
+});
+
+test("spend: model CSV selects the model breakdown with its own filename", async () => {
+ const clock = { at: Date.UTC(2026, 0, 5, 12) };
+ const store = createMemorySessionStore({ now: () => clock.at });
+ const s = start(store);
+ try {
+ await seedPricedFixture(store);
+ await bill(store, "dm:alice:priced", "dm", scopeId("personal", "alice"), { costUsd: 4 }, "other-model");
+ const query = "from=2026-01-05&to=2026-01-06&breakdown=model";
+ const json = await getJson(s.base, `/v1/admin/spend?${query}`);
+ assert.deepEqual(
+ json.models.map((m: any) => [m.model, m.costUsd]),
+ [
+ ["mock", 6.75],
+ ["other-model", 4],
+ ],
+ );
+ const r = await get(s.base, `/v1/admin/spend?${query}&format=csv`);
+ assert.equal(r.status, 200);
+ assert.match(
+ r.headers.get("content-disposition")!,
+ /^attachment; filename="qm-spend-models-2026-01-05-2026-01-06\.csv"/,
+ );
+ const body = await r.text();
+ assert.equal(Number(r.headers.get("content-length")), Buffer.byteLength(body));
+ const lines = body.trimEnd().split("\r\n");
+ assert.equal(lines.length, json.models.length + 1);
+ for (const [i, model] of json.models.entries()) {
+ const cells = lines[i + 1]!.split(",");
+ assert.equal(cells[0], model.model);
+ assert.equal(Number(cells[4]), model.costUsd);
+ assert.equal(Number(cells[5]), model.calls);
+ }
+ assert.equal(
+ json.models.reduce((sum: number, m: any) => sum + m.costUsd, 0),
+ json.org.costUsd,
+ );
+ } finally {
+ await s.close();
+ }
+});
diff --git a/test/postgres-store.test.ts b/test/postgres-store.test.ts
index 0752af44b..b6b70fd16 100644
--- a/test/postgres-store.test.ts
+++ b/test/postgres-store.test.ts
@@ -17,6 +17,7 @@ import { createPostgresRunSignalStore } from "../src/runs/postgres-run-signal-st
import { scopeId, type Principal, type TurnRequest, type TurnResult } from "../src/types.ts";
import type { OrchestratorInput } from "../src/core/orchestrator.ts";
import { assertParticipantSessionParity } from "./support/participant-session-parity.ts";
+import { assertSpendRollupParity } from "./support/spend-rollup-parity.ts";
import { byScopeId, rollupsFromSummaries } from "./support/scope-rollup-oracle.ts";
const URL = process.env.DATABASE_URL;
@@ -72,6 +73,10 @@ test("pg session store: getForParticipant returns exactly the row listByParticip
await assertParticipantSessionParity(createPostgresSessionStore(URL!), `pg-parity-${randomUUID()}`);
});
+test("pg session store: spendRollup matches the memory rollup row for row", { skip }, async () => {
+ await assertSpendRollupParity((now) => createPostgresSessionStore(URL!, { now }), `pg-spend-${randomUUID()}`);
+});
+
test("pg session store: a bare failed acquire means the session is gone, not a lease race", { skip }, async () => {
const s = createPostgresSessionStore(URL!);
const scope = scopeId("personal", "U1");
diff --git a/test/session-store.test.ts b/test/session-store.test.ts
index 4bccd76e9..e552a72f0 100644
--- a/test/session-store.test.ts
+++ b/test/session-store.test.ts
@@ -7,6 +7,7 @@ import { acquireLeaseWithin, cronIdOf, sessionCategory, sessionOrigin } from "..
import { parseSessionWakeRef } from "../src/api/routes/admin/origins.ts";
import { scopeId } from "../src/types.ts";
import { assertParticipantSessionParity } from "./support/participant-session-parity.ts";
+import { assertSpendRollupParity } from "./support/spend-rollup-parity.ts";
import { byScopeId, rollupsFromSummaries } from "./support/scope-rollup-oracle.ts";
test("sessionOrigin classifies trigger threads by prefix", () => {
@@ -733,6 +734,10 @@ for (const [name, make] of backends) {
await assertParticipantSessionParity(store, `parity-${name}-b`);
});
+ test(`${name}: spendRollup groups model-call cost by UTC day, scope, origin and model`, async () => {
+ await assertSpendRollupParity((now) => createMemorySessionStore({ now }), `spend-${name}`);
+ });
+
test(`${name}: countSessions and distinctParticipants aggregate without loading rows`, async () => {
const store = make();
const scope = scopeId("channel", "CAGG");
diff --git a/test/spend-summary.test.ts b/test/spend-summary.test.ts
new file mode 100644
index 000000000..20db89a25
--- /dev/null
+++ b/test/spend-summary.test.ts
@@ -0,0 +1,411 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { installPrincipalLinks } from "../src/directory/person.ts";
+import { cacheHitRatio } from "../src/admin/metrics-sink.ts";
+import type { SpendRow } from "../src/sessions/session-store.ts";
+import { spendCsv, summarizeSpend, type SpendReport } from "../src/api/routes/admin/spend.ts";
+
+const DAY = 86_400_000;
+const MON = 20353;
+const TUE = 20354;
+const WED = 20355;
+
+const row = (over: Partial<SpendRow> & Pick<SpendRow, "day" | "scopeId" | "origin">): SpendRow => ({
+ model: null,
+ calls: 1,
+ costUsd: 0,
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ ...over,
+});
+
+const ROWS: SpendRow[] = [
+ row({
+ day: MON,
+ scopeId: "personal:alice",
+ origin: "conversation",
+ costUsd: 1.5,
+ input: 100,
+ output: 10,
+ cacheRead: 300,
+ cacheWrite: 50,
+ }),
+ row({
+ day: TUE,
+ scopeId: "personal:alice",
+ origin: "conversation",
+ costUsd: 0.25,
+ input: 20,
+ output: 4,
+ cacheRead: 60,
+ cacheWrite: 0,
+ }),
+ row({
+ day: TUE,
+ scopeId: "personal:alice",
+ origin: "cron",
+ costUsd: 0.75,
+ calls: 3,
+ input: 40,
+ output: 8,
+ cacheRead: 120,
+ cacheWrite: 10,
+ }),
+ row({
+ day: TUE,
+ scopeId: "personal:bob",
+ origin: "conversation",
+ costUsd: 0.5,
+ input: 10,
+ output: 2,
+ cacheRead: 0,
+ cacheWrite: 0,
+ }),
+ row({
+ day: TUE,
+ scopeId: "channel:C1",
+ origin: "webhook",
+ costUsd: 2,
+ calls: 2,
+ input: 5,
+ output: 1,
+ cacheRead: 0,
+ cacheWrite: 0,
+ }),
+ row({
+ day: WED,
+ scopeId: "personal:bob",
+ origin: "monitor",
+ costUsd: 4,
+ input: 7,
+ output: 3,
+ cacheRead: 0,
+ cacheWrite: 0,
+ }),
+];
+
+const summarize = (rows: SpendRow[], over: Partial<Parameters<typeof summarizeSpend>[1]> = {}): SpendReport =>
+ summarizeSpend(rows, {
+ from: MON * DAY,
+ to: (WED + 1) * DAY,
+ bucket: "day",
+ label: () => "",
+ ...over,
+ });
+
+const conserved = (report: SpendReport, pick: (e: SpendReport["people"][number]) => number): number =>
+ [...report.people, ...report.scopes].reduce((sum, e) => sum + pick(e), 0);
+
+test("summarizeSpend: people plus non-person scopes conserve the org totals", () => {
+ const report = summarize(ROWS);
+ assert.deepEqual(
+ report.people.map((p) => p.principalId),
+ ["bob", "alice"],
+ "people are ranked by total cost",
+ );
+ assert.deepEqual(
+ report.people.map((p) => p.scopeId),
+ ["personal:bob", "personal:alice"],
+ );
+ assert.deepEqual(
+ report.scopes.map((s) => [s.principalId, s.scopeId, s.kind]),
+ [[null, "channel:C1", "channel"]],
+ );
+ assert.ok(Math.abs(conserved(report, (e) => e.costUsd) - report.org.costUsd) <= 1e-9);
+ for (const column of ["calls", "tokens", "input", "output", "cacheRead", "cacheWrite"] as const) {
+ assert.equal(
+ conserved(report, (e) => e[column]),
+ report.org[column],
+ column,
+ );
+ }
+ const alice = report.people.find((p) => p.principalId === "alice")!;
+ assert.equal(alice.live.costUsd, 1.75);
+ assert.equal(alice.cron.costUsd, 0.75);
+ assert.equal(alice.cron.calls, 3);
+ assert.equal(alice.background.costUsd, 0);
+ const bob = report.people.find((p) => p.principalId === "bob")!;
+ assert.equal(bob.cron.costUsd, 0, "no cron rows means a zero cron bucket, not a missing one");
+ assert.equal(bob.background.costUsd, 4, "monitor origin rolls up as background");
+ assert.equal(report.scopes[0]!.background.costUsd, 2, "webhook origin rolls up as background");
+});
+
+test("summarizeSpend: cache hit ratio comes from the shared helper and is null without cache data", () => {
+ const report = summarize(ROWS);
+ assert.equal(
+ report.org.cacheHitRatio,
+ cacheHitRatio({
+ cacheRead: report.org.cacheRead,
+ cacheWrite: report.org.cacheWrite,
+ uncachedInput: report.org.input,
+ }),
+ );
+ for (const person of report.people) {
+ assert.ok(person.cacheHitRatio === null || (person.cacheHitRatio >= 0 && person.cacheHitRatio <= 1));
+ }
+ const noCache = summarize([row({ day: MON, scopeId: "personal:zoe", origin: "conversation", costUsd: 0, input: 0 })]);
+ assert.equal(noCache.people[0]!.cacheHitRatio, null, "a zero denominator reports null, never 0%");
+});
+
+test("summarizeSpend: zero-dollar calls keep their tokens instead of disappearing", () => {
+ const report = summarize([
+ row({
+ day: MON,
+ scopeId: "personal:codex",
+ origin: "conversation",
+ costUsd: 0,
+ input: 900,
+ output: 30,
+ cacheRead: 70,
+ }),
+ ]);
+ const codex = report.people[0]!;
+ assert.equal(codex.costUsd, 0);
+ assert.equal(codex.tokens, 1000);
+ assert.ok(codex.cacheHitRatio !== null && codex.cacheHitRatio > 0);
+});
+
+test("summarizeSpend: the series is sparse, UTC-keyed, and restricted to [from, to)", () => {
+ const report = summarize(ROWS);
+ assert.deepEqual(
+ report.series.map((p) => p.day),
+ ["2025-09-22", "2025-09-23", "2025-09-24"],
+ );
+ for (const point of report.series) assert.match(point.day, /^\d{4}-\d{2}-\d{2}$/);
+ assert.equal(report.series[0]!.costUsd, 1.5);
+ assert.equal(report.series[2]!.background.costUsd, 4);
+ assert.deepEqual(summarize([]).series, [], "an empty deployment gets no zero-filled calendar");
+
+ const narrowed = summarizeSpend(
+ ROWS.filter((r) => r.day >= TUE && r.day < WED),
+ { from: TUE * DAY, to: WED * DAY, bucket: "day", label: () => "" },
+ );
+ assert.deepEqual(narrowed.window, { from: "2025-09-23", to: "2025-09-24", bucket: "day" });
+ assert.deepEqual(
+ narrowed.series.map((p) => p.day),
+ ["2025-09-23"],
+ );
+ assert.ok(narrowed.org.costUsd < report.org.costUsd);
+});
+
+test("summarizeSpend: week buckets collapse to the Monday that starts them", () => {
+ const report = summarize(ROWS, { bucket: "week" });
+ assert.deepEqual(
+ report.series.map((p) => p.day),
+ ["2025-09-22"],
+ "Wednesday 2025-09-24 belongs to the week starting Monday 2025-09-22",
+ );
+ const daily = summarize(ROWS);
+ assert.ok(Math.abs(report.series[0]!.costUsd - daily.series.reduce((n, p) => n + p.costUsd, 0)) <= 1e-9);
+ assert.equal(report.window.bucket, "week");
+ assert.ok(Math.abs(conserved(report, (e) => e.costUsd) - report.org.costUsd) <= 1e-9);
+});
+
+test("spendCsv: one row per entity, people first, matching the report's numbers", () => {
+ const report = summarize(ROWS);
+ const lines = spendCsv(report).trimEnd().split("\r\n");
+ assert.equal(
+ lines[0],
+ "principal_id,scope_id,kind,display_name,live_usd,cron_usd,background_usd,total_usd,calls,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cache_hit_ratio",
+ );
+ assert.equal(lines.length, report.people.length + report.scopes.length + 1);
+ const bob = lines.find((l) => l.startsWith("bob,"))!.split(",");
+ const bobRow = report.people.find((p) => p.principalId === "bob")!;
+ assert.equal(Number(bob[7]), bobRow.costUsd);
+ assert.equal(Number(bob[4]), bobRow.live.costUsd);
+ assert.equal(Number(bob[6]), bobRow.background.costUsd);
+ assert.equal(lines.at(-1)!.split(",")[1], "channel:C1", "non-person rows come last");
+});
+
+test("spendCsv: hostile display names are RFC 4180 quoted and de-fanged", () => {
+ const labels = new Map([
+ ["personal:alice", 'Alice "The, Closer"'],
+ ["channel:C1", "=cmd|' /c calc'!A1"],
+ ["personal:bob", "line one\r\nline two"],
+ ]);
+ const report = summarize(ROWS, { label: (id) => labels.get(id) ?? "" });
+ const csv = spendCsv(report);
+ assert.ok(csv.includes('"Alice ""The, Closer"""'), csv);
+ assert.ok(csv.includes(`,'=cmd|' /c calc'!A1,`), csv);
+ assert.ok(csv.includes('"line one\r\nline two"'), csv);
+});
+
+test("summarizeSpend: models conserve org totals and category totals across scopes and days", () => {
+ const report = summarize(ROWS.map((r, i) => ({ ...r, model: ["alpha", "beta", null][i % 3]! })));
+ assert.deepEqual(
+ report.models.map((m) => m.model),
+ [null, "beta", "alpha"],
+ );
+ for (const column of ["costUsd", "calls", "tokens", "input", "output", "cacheRead", "cacheWrite"] as const) {
+ assert.equal(
+ report.models.reduce((sum, m) => sum + m[column], 0),
+ report.org[column],
+ column,
+ );
+ }
+ for (const origin of ["live", "cron", "background"] as const) {
+ for (const column of ["costUsd", "calls", "tokens"] as const) {
+ assert.equal(
+ report.models.reduce((sum, m) => sum + m[origin][column], 0),
+ report.org[origin][column],
+ );
+ }
+ }
+ for (const model of report.models) {
+ assert.equal(
+ model.cacheHitRatio,
+ cacheHitRatio({
+ cacheRead: model.cacheRead,
+ cacheWrite: model.cacheWrite,
+ uncachedInput: model.input,
+ }),
+ );
+ }
+ assert.equal(report.models.find((m) => m.model === null)!.cron.costUsd, 0.75);
+ assert.deepEqual(summarize([]).models, []);
+});
+
+test("summarizeSpend: model ties sort by identifier with unknown last, independent of input order", () => {
+ const rows = [null, "zeta", "alpha", ""].map((model) =>
+ row({
+ day: MON,
+ scopeId: "personal:alice",
+ origin: "conversation",
+ model,
+ costUsd: 1,
+ }),
+ );
+ const report = summarize(rows);
+ assert.deepEqual(
+ report.models.map((m) => m.model),
+ ["", "alpha", "zeta", null],
+ );
+ assert.deepEqual(summarize(rows.toReversed()).models, report.models);
+});
+
+test("spendCsv: model export retains totals, unknown models, and safe escaping", () => {
+ const models = [null, 'Model "quoted", name', "line one\r\nline two", "=formula", "+formula", "-formula", "@formula"];
+ const report = summarize(
+ models.map((model) =>
+ row({
+ day: MON,
+ scopeId: "personal:alice",
+ origin: "cron",
+ model,
+ costUsd: 1,
+ input: 100,
+ cacheRead: 100,
+ }),
+ ),
+ );
+ const csv = spendCsv(report, "model");
+ assert.ok(
+ csv.startsWith(
+ "model,live_usd,cron_usd,background_usd,total_usd,calls,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cache_hit_ratio\r\n",
+ ),
+ );
+ assert.ok(csv.includes('"Model ""quoted"", name",0,1,0,1,1,100,0,100,0,0.5\r\n'));
+ assert.ok(csv.includes('"line one\r\nline two"'));
+ for (const model of ["=formula", "+formula", "-formula", "@formula"]) assert.ok(csv.includes(`'${model},`));
+ assert.ok(csv.includes("Unknown model,0,1,0,1,1,100,0,100,0,0.5\r\n"));
+ assert.equal(spendCsv(report), spendCsv(report, "entity"));
+});
+
+for (const bucket of ["day", "week"] as const) {
+ test(`summarizeSpend: ${bucket} model series conserves each point and window model totals`, () => {
+ const rows = [
+ row({ day: MON, scopeId: "personal:alice", origin: "conversation", model: "alpha", costUsd: 1 }),
+ row({ day: MON, scopeId: "personal:alice", origin: "cron", model: "alpha", costUsd: 2 }),
+ row({ day: MON, scopeId: "channel:C1", origin: "webhook", model: "beta", costUsd: 4 }),
+ row({ day: MON, scopeId: "personal:bob", origin: "monitor", model: null, costUsd: 8 }),
+ row({ day: TUE, scopeId: "personal:alice", origin: "conversation", model: "alpha", costUsd: 16 }),
+ row({ day: MON + 6, scopeId: "personal:bob", origin: "cron", model: null, costUsd: 32 }),
+ row({ day: MON + 7, scopeId: "personal:bob", origin: "conversation", model: "beta", costUsd: 64 }),
+ row({ day: MON + 7, scopeId: "personal:bob", origin: "conversation", model: "free", costUsd: 0 }),
+ ];
+ const report = summarize(rows, { bucket, to: (MON + 8) * DAY });
+ assert.deepEqual(
+ report.series[0]!.models,
+ bucket === "day"
+ ? [
+ { model: null, costUsd: 8 },
+ { model: "beta", costUsd: 4 },
+ { model: "alpha", costUsd: 3 },
+ ]
+ : [
+ { model: null, costUsd: 40 },
+ { model: "alpha", costUsd: 19 },
+ { model: "beta", costUsd: 4 },
+ ],
+ );
+ assert.deepEqual(report.series.at(-1)!.models, [
+ { model: "beta", costUsd: 64 },
+ { model: "free", costUsd: 0 },
+ ]);
+ assert.equal(report.series.at(-1)!.day, "2025-09-29");
+ const modelTotals = new Map<string | null, number>();
+ for (const point of report.series) {
+ assert.equal(
+ point.models.reduce((sum, m) => sum + m.costUsd, 0),
+ point.costUsd,
+ );
+ for (const model of point.models) {
+ modelTotals.set(model.model, (modelTotals.get(model.model) ?? 0) + model.costUsd);
+ }
+ }
+ assert.equal(modelTotals.size, report.models.length);
+ for (const model of report.models) assert.equal(modelTotals.get(model.model), model.costUsd);
+ assert.deepEqual(summarize(rows.toReversed(), { bucket, to: (MON + 8) * DAY }).series, report.series);
+ });
+}
+
+for (const bucket of ["day", "week"] as const) {
+ test(`summarizeSpend: ${bucket} person series merges aliases and conserves shared spend`, (t) => {
+ installPrincipalLinks({ canonical: (id) => (id === "slack-alice" ? "alice" : undefined), aliases: () => [] });
+ t.after(() => installPrincipalLinks(null));
+ const rows = [
+ row({ day: MON, scopeId: "personal:alice", origin: "conversation", costUsd: 1 }),
+ row({ day: MON, scopeId: "personal:slack-alice", origin: "cron", costUsd: 2 }),
+ row({ day: TUE, scopeId: "personal:slack-alice", origin: "monitor", costUsd: 4 }),
+ row({ day: MON, scopeId: "channel:C1", origin: "conversation", costUsd: 8 }),
+ row({ day: TUE, scopeId: "team:T1", origin: "cron", costUsd: 16 }),
+ row({ day: MON + 7, scopeId: "personal:bob", origin: "conversation", costUsd: 32 }),
+ row({ day: MON + 7, scopeId: "org:default", origin: "webhook", costUsd: 64 }),
+ row({ day: MON + 7, scopeId: "personal:free", origin: "conversation", costUsd: 0 }),
+ ];
+ const report = summarize(rows, { bucket, to: (MON + 8) * DAY });
+ assert.deepEqual(report.series[0]!.people, [
+ { principalId: "alice", costUsd: bucket === "day" ? 3 : 7 },
+ { principalId: null, costUsd: bucket === "day" ? 8 : 24 },
+ ]);
+ const totals = new Map<string | null, number>();
+ for (const point of report.series) {
+ assert.equal(
+ point.people.reduce((sum, p) => sum + p.costUsd, 0),
+ point.costUsd,
+ );
+ for (const p of point.people) totals.set(p.principalId, (totals.get(p.principalId) ?? 0) + p.costUsd);
+ }
+ assert.deepEqual(
+ [...totals],
+ [
+ ["alice", 7],
+ [null, 88],
+ ["bob", 32],
+ ["free", 0],
+ ],
+ );
+ for (const p of report.people) assert.equal(totals.get(p.principalId), p.costUsd);
+ assert.equal(
+ totals.get(null),
+ report.scopes.reduce((sum, p) => sum + p.costUsd, 0),
+ );
+ assert.equal(
+ [...totals.values()].reduce((sum, cost) => sum + cost, 0),
+ report.org.costUsd,
+ );
+ assert.deepEqual(summarize(rows.toReversed(), { bucket, to: (MON + 8) * DAY }).series, report.series);
+ });
+}
diff --git a/test/support/spend-rollup-parity.ts b/test/support/spend-rollup-parity.ts
new file mode 100644
index 000000000..152311923
--- /dev/null
+++ b/test/support/spend-rollup-parity.ts
@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import { scopeId, type SessionType } from "../../src/types.ts";
+import type { SessionStore, SpendRow } from "../../src/sessions/session-store.ts";
+
+const DAY = 86_400_000;
+const BASE = Date.UTC(2021, 0, 1);
+
+export async function assertSpendRollupParity(
+ makeStore: (now: () => number) => SessionStore,
+ prefix: string,
+): Promise<void> {
+ const clock = { at: BASE + 6 * 3_600_000 };
+ const store = makeStore(() => clock.at);
+ const alice = scopeId("personal", `${prefix}-alice`);
+ const bob = scopeId("personal", `${prefix}-bob`);
+ const channel = scopeId("channel", `${prefix}-C1`);
+ const mine = new Set<string>([alice, bob, channel]);
+
+ const record = async (
+ threadRef: string,
+ type: SessionType,
+ scope: string,
+ costUsd: number | null,
+ model = "mock",
+ ) => {
+ const session = await store.getOrCreateByThread(threadRef, type, scope);
+ await store.recordLlmRequest(session.id, {
+ turnSeq: null,
+ step: 0,
+ model,
+ scopeLabel: scope,
+ usage:
+ costUsd === null ? null : { input: 100, output: 20, cacheRead: 400, cacheWrite: 40, totalTokens: 560, costUsd },
+ });
+ return session;
+ };
+
+ await record(`${prefix}:alice-live-a`, "dm", alice, 1.5);
+ await record(`${prefix}:alice-live-b`, "dm", alice, 0.25);
+ await record(`${prefix}:alice-live-a`, "dm", alice, 0.75, "other-model");
+ await record(`${prefix}:channel-live`, "channel", channel, 2);
+ await record(`cron:${prefix}-nightly:fire:aaa`, "dm", alice, 0.5);
+ clock.at += DAY;
+ await record(`${prefix}:alice-live-c`, "dm", alice, 0.125);
+ await record(`${prefix}:bob-live`, "dm", bob, 4);
+ await record(`${prefix}:bob-unpriced`, "dm", bob, null);
+ clock.at += DAY;
+ await record(`${prefix}:alice-out-of-window`, "dm", alice, 8);
+
+ await store.recordLlmRequest(`${prefix}-orphan-session`, {
+ turnSeq: null,
+ step: 0,
+ model: "mock",
+ scopeLabel: alice,
+ usage: { input: 1, output: 1, cacheRead: 1, cacheWrite: 1, totalTokens: 4, costUsd: 99 },
+ });
+
+ const day = Math.floor(BASE / DAY);
+ const rollup = (await store.spendRollup({ from: BASE, to: BASE + 2 * DAY })).filter((r) => mine.has(r.scopeId));
+ const key = (r: SpendRow) => JSON.stringify([r.day, r.scopeId, r.origin, r.model]);
+ const byKey = (a: SpendRow, b: SpendRow) => {
+ if (key(a) === key(b)) return 0;
+ return key(a) < key(b) ? -1 : 1;
+ };
+ const sorted = [...rollup].sort(byKey);
+
+ const expected: SpendRow[] = (
+ [
+ {
+ day,
+ scopeId: alice,
+ model: "other-model",
+ origin: "conversation",
+ calls: 1,
+ costUsd: 0.75,
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ },
+ {
+ day,
+ scopeId: alice,
+ model: "mock",
+ origin: "conversation",
+ calls: 2,
+ costUsd: 1.75,
+ input: 200,
+ output: 40,
+ cacheRead: 800,
+ cacheWrite: 80,
+ },
+ {
+ day,
+ scopeId: alice,
+ model: "mock",
+ origin: "cron",
+ calls: 1,
+ costUsd: 0.5,
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ },
+ {
+ day,
+ scopeId: channel,
+ model: "mock",
+ origin: "conversation",
+ calls: 1,
+ costUsd: 2,
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ },
+ {
+ day: day + 1,
+ scopeId: alice,
+ model: "mock",
+ origin: "conversation",
+ calls: 1,
+ costUsd: 0.125,
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ },
+ {
+ day: day + 1,
+ scopeId: bob,
+ model: "mock",
+ origin: "conversation",
+ calls: 1,
+ costUsd: 4,
+ input: 100,
+ output: 20,
+ cacheRead: 400,
+ cacheWrite: 40,
+ },
+ ] satisfies SpendRow[]
+ ).sort(byKey);
+
+ assert.deepEqual(sorted, expected);
+
+ clock.at = BASE;
+ const child = async (name: string, parentId: string) => {
+ const session = await record(`agent:main:subagent:${prefix}-${name}`, "dm", alice, 0.01, `${prefix}-${name}`);
+ await store.setParentSession(session.id, parentId);
+ return session;
+ };
+ for (const origin of ["cron", "webhook", "monitor", "conversation"] as const) {
+ const parent = await store.getOrCreateByThread(`agent:main:${origin}:${prefix}-parent`, "dm", bob);
+ const first = await child(`${origin}-child`, parent.id);
+ await child(`${origin}-grandchild`, first.id);
+ }
+ await child("missing-parent", `${prefix}-missing`);
+ const deleted = await store.getOrCreateByThread(`cron:${prefix}-deleted`, "dm", bob);
+ await child("deleted-parent", deleted.id);
+ await store.deleteSession(deleted.id);
+ const cycleA = await child("cycle-a", `${prefix}-missing`);
+ const cycleB = await child("cycle-b", cycleA.id);
+ await store.setParentSession(cycleA.id, cycleB.id);
+ const self = await child("self-cycle", `${prefix}-missing`);
+ await store.setParentSession(self.id, self.id);
+
+ const inherited = (await store.spendRollup({ from: BASE, to: BASE + DAY })).filter((r) =>
+ r.model?.startsWith(`${prefix}-`),
+ );
+ const origins = new Map<string, string>([
+ ...["cron", "webhook", "monitor", "conversation"].flatMap((origin) =>
+ ["child", "grandchild"].map((kind) => [`${prefix}-${origin}-${kind}`, origin] as const),
+ ),
+ ...["missing-parent", "deleted-parent", "cycle-a", "cycle-b", "self-cycle"].map(
+ (name) => [`${prefix}-${name}`, "conversation"] as const,
+ ),
+ ]);
+ assert.equal(inherited.length, origins.size);
+ for (const row of inherited) {
+ assert.equal(row.origin, origins.get(row.model!), row.model!);
+ assert.equal(row.scopeId, alice, "inherit origin, not the parent's scope");
+ assert.equal(row.calls, 1);
+ assert.equal(row.costUsd, 0.01);
+ }
+}