@timo972/cc-router 0.13.0-rc.3 → 0.13.0-rc.4

package/CHANGELOG.md

@@ -8,6 +8,24 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- `cc-router usage` charts and its daily grid switch between tokens and
+  estimated API spend (`s`) and narrow to input or output (`i`); every bucket,
+  model series and day in the report now carries frozen-rate USD per token
+  category. The model view (`l`) lists input, output, cache and spend per
+  model. Input, output and cache figures share one colour each across the
+  header, the cost line and the model view.
+- The usage view fills the terminal like `cc-router status`, is indented one
+  column, and quits on `Esc`. Chart columns scale to the available width and
+  the chart shares the daily grid's right edge; the axis names its unit
+  instead of running day numbers together. Warnings sit below the grid.
+- Subscription cost and net savings are no longer displayed in the usage
+  dashboard or the plain-text summary; the API-equivalent value stands alone,
+  broken down by input, output and cache. Both remain in `--json` output and
+  `usage subscription` still records costs. A client talking to an older
+  router shows the per-category spend as unavailable rather than zero.
+
 ### ⚠️ Breaking
 
 - `cc-router accounts add-openai`, `login-openai`, `add-grok` and `login-grok`

package/README.md

@@ -109,12 +109,14 @@ it later. Adding more accounts is `cc-router accounts login`, re-signing one in
 Per-platform token extraction, Codex CLI, Docker and everything else lives in
 [the docs](docs/).
 
-## Usage history and savings
+## Usage history and API-equivalent cost
 
 Run `cc-router usage` for persistent token history, provider/model stacked bars,
-and a daily activity grid. Switch between day, week, month and year; history
-survives service restarts. Configure your monthly subscription costs to compare
-them with the estimated standard API token value:
+and a daily activity grid, each switchable between tokens and what the recorded
+tokens would have cost at standard API rates, and narrowable to input or output.
+Switch between day, week, month and year; history survives service restarts.
+Monthly subscription costs can be recorded for comparison in the `--json`
+report:
 
 ```bash
 cc-router usage subscription set personal --monthly-usd 100 --from 2026-09-01

package/dist/cli/cmd-usage.js

@@ -46,15 +46,16 @@ export function formatUsageText(report) {
     const money = (n) => n === null ? "unavailable" : `${n < 0 ? "-" : ""}$${Math.abs(n).toFixed(2)}`;
     return [
         `Usage ${report.period}: ${report.start.slice(0, 10)} — ${report.end.slice(0, 10)} (UTC, end exclusive)`,
+        // Same four categories the dashboard shows, so the two surfaces read alike.
         `Tokens: ${totalTokens(t).toLocaleString("en-US")} | input ${t.input} | output ${t.output} | cache read ${t.cacheRead} | cache write ${t.cacheWrite}`,
+        // Subscription cost and net savings are hidden for now; the API-equivalent
+        // value is the figure that stands on its own. Both remain in --json.
         `API equivalent: ${money(c.pricedApiUsd)}${c.coverage.pricingComplete ? "" : " (partial; unpriced tokens excluded)"}`,
-        `Subscription: ${money(c.subscriptionUsd)}${c.coverage.subscriptionComplete ? "" : " (partial; configure missing costs)"}`,
-        `Net savings: ${money(c.savingsUsd)}${c.savingsPercent === null ? "" : ` (${c.savingsPercent.toFixed(1)}%)`}`,
         ...report.warnings.map(w => `Warning: ${w}`),
     ].join("\n");
 }
 export function registerUsage(program) {
-    const usage = program.command("usage").description("Persistent token usage and API-equivalent subscription savings")
+    const usage = program.command("usage").description("Persistent token usage and its API-equivalent cost")
         .option("--period <period>", "day, week, month or year", "month")
         .option("--date <date>", "Date within the selected period (YYYY-MM-DD, UTC)")
         .option("--provider <provider>", "Filter Claude, OpenAI or Grok (repeatable)", (value, previous = []) => [...previous, value])

package/dist/cli/index.js

@@ -31,7 +31,7 @@ Examples:
   $ cc-router start --reconfigure# Re-ask run preferences
   $ cc-router stop               # Stop proxy (offers to remove auto-start / config)
   $ cc-router status             # Live dashboard with account stats
-  $ cc-router usage              # Persistent token usage and subscription savings
+  $ cc-router usage              # Persistent token usage and its API-equivalent cost
   $ cc-router models list        # List dynamically discovered provider models
   $ cc-router logs               # View proxy logs (background mode)
   $ cc-router accounts list      # Show Claude, ChatGPT, and Grok accounts

package/dist/ui/UsageDashboard.js

@@ -1,11 +1,23 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { Box, Text, useApp, useInput, useStdout } from "ink";
-import { USAGE_PROVIDERS, totalTokens } from "../usage/types.js";
+import { USAGE_PROVIDERS, addSpend, addTokens, totalSpend, totalTokens, zeroSpend, zeroTokens } from "../usage/types.js";
 import { activityLevel, chartColumns, formatTokens, heatmapWeeks, legendColor, legendGlyph, PROVIDER_COLORS, PROVIDER_LABELS } from "./usage-chart.js";
 const PERIODS = ["day", "week", "month", "year"];
 const HEAT = ["#42474e", "#466c50", "#5b9565", "#82c489", "#b7efba"];
+const FACETS = ["sum", "input", "output"];
+const FACET_LABELS = { sum: "All", input: "Input", output: "Output" };
+/** One colour per token category, shared by the totals, the cost line, the mode indicator and the inspector. */
+const CATEGORY_COLORS = { input: "#8dcc9a", output: "#db9bac", cache: "#e1ce8a" };
+const MAX_COLUMN_WIDTH = 12;
 const money = (n) => n === null ? "unavailable" : `${n < 0 ? "-" : ""}$${Math.abs(n).toFixed(2)}`;
+/** Axis-sized money: two decimals until the scale suffixes read better. */
+const compactMoney = (n) => n >= 1000 ? `$${formatTokens(n)}` : money(n);
+export function measureUsage(tokens, usd, spend, facet) {
+    if (spend)
+        return facet === "sum" ? totalSpend(usd) : usd[facet];
+    return facet === "sum" ? totalTokens(tokens) : tokens[facet];
+}
 export function shiftUsageDate(query, direction) {
     const d = new Date(`${query.date ?? new Date().toISOString().slice(0, 10)}T00:00:00Z`);
     if (query.period === "month") {
@@ -29,6 +41,8 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
     const [error, setError] = useState();
     const [loading, setLoading] = useState(true);
     const [models, setModels] = useState(false);
+    const [spend, setSpend] = useState(false);
+    const [facet, setFacet] = useState("sum");
     const [gridFocus, setGridFocus] = useState(false);
     const [helpOpen, setHelpOpen] = useState(false);
     const [modelInspector, setModelInspector] = useState(false);
@@ -68,13 +82,35 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
         void poll();
         return () => { cancelled = true; clearTimeout(timer); };
     }, [load, query]);
-    const fullModels = [...new Map(report?.buckets.flatMap(bucket => Object.values(bucket.series).map(series => [`${series.provider}:${series.model}`, series])) ?? []).values()].sort((a, b) => `${a.provider}:${a.model}`.localeCompare(`${b.provider}:${b.model}`));
+    // Period totals per model: the inspector shows input/output/cache/spend, not a single bucket.
+    const fullModels = [...(report?.buckets ?? []).reduce((acc, bucket) => {
+            for (const series of Object.values(bucket.series)) {
+                const key = `${series.provider}:${series.model}`;
+                const entry = acc.get(key) ?? { provider: series.provider, model: series.model, tokens: zeroTokens(), usd: zeroSpend() };
+                addTokens(entry.tokens, series.tokens);
+                addSpend(entry.usd, series.usd);
+                acc.set(key, entry);
+            }
+            return acc;
+        }, new Map()).values()].sort((a, b) => `${a.provider}:${a.model}`.localeCompare(`${b.provider}:${b.model}`));
     useInput((input, key) => {
         if (input === "q" || (key.ctrl && input === "c")) {
             onExit?.();
             exit();
             return;
         }
+        // Escape mirrors status: it leaves an overlay first and only quits from the main view.
+        if (key.escape) {
+            if (helpOpen)
+                setHelpOpen(false);
+            else if (modelInspector)
+                setModelInspector(false);
+            else {
+                onExit?.();
+                exit();
+            }
+            return;
+        }
         if (input === "?") {
             setHelpOpen(value => !value);
             return;
@@ -94,6 +130,10 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
             setQuery(q => ({ ...q, period: PERIODS[(PERIODS.indexOf(q.period) + (key.shift ? 3 : 1)) % 4] }));
         if (input === "m")
             setModels(value => !value);
+        if (input === "s")
+            setSpend(value => !value);
+        if (input === "i")
+            setFacet(value => FACETS[(FACETS.indexOf(value) + 1) % FACETS.length]);
         if (input === "g")
             setGridFocus(value => !value);
         if (input === "t") {
@@ -119,58 +159,97 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
     const width = Math.max(12, size.width - 2);
     const height = Math.max(4, size.height - 1);
     const line = (content, key) => _jsx(Text, { wrap: "truncate-end", children: content }, key);
+    const measure = (tokens, usd) => measureUsage(tokens, usd, spend, facet);
+    const formatMeasure = (value) => spend ? compactMoney(value) : formatTokens(value);
+    const unit = `${facet === "sum" ? "" : `${facet} `}${spend ? "spend" : "tokens"}`;
+    const describe = (value) => `${spend ? money(value) : value.toLocaleString("en-US")} ${unit}`;
+    // A fixed frame height, as the status dashboard uses, so the view always fills the terminal
+    // and whatever was on screen before scrolls away instead of sitting above a short report.
+    // One column of left padding, like the status dashboard; `width` already leaves room for it.
     if (helpOpen)
-        return _jsx(Box, { width: width, flexDirection: "column", children: [
-                "Usage controls (UTC)", "Tab / Shift+Tab  Period tab", "← →  Previous / next period", "t  Current period", "1/2/3  Claude/OpenAI/Grok", "m  Model stacks", "l  Full model names", "g  Day focus / chart", "↑ ↓  Inspect day (grid)", "← →  Inspect week (grid)", "?  Return to usage", "q quit",
+        return _jsx(Box, { width: width, height: height, paddingLeft: 1, flexDirection: "column", children: [
+                "Usage controls (UTC)", "Esc  Back / quit", "Tab / Shift+Tab  Period tab", "← →  Previous / next period", "t  Current period", "1/2/3  Claude/OpenAI/Grok", "m  Model stacks", "s  Tokens / spend", "i  All / input / output", "l  Full model names", "g  Day focus / chart", "↑ ↓  Inspect day (grid)", "← →  Inspect week (grid)", "?  Return to usage", "q quit",
             ].slice(0, height).map((text, i) => line(text, `help${i}`)) });
     if (modelInspector) {
         const selected = fullModels[modelIndex % Math.max(1, fullModels.length)];
         const name = selected?.model ?? "No model usage in this period";
         const chunks = Array.from({ length: Math.ceil(name.length / width) }, (_, i) => name.slice(i * width, (i + 1) * width));
-        return _jsxs(Box, { width: width, flexDirection: "column", children: [line(`Model ${fullModels.length ? modelIndex % fullModels.length + 1 : 0}/${fullModels.length} · ${selected ? PROVIDER_LABELS[selected.provider] : ""}`, "model-title"), chunks.slice(0, Math.max(1, height - 3)).map((text, i) => line(text, `model-name${i}`)), line("↑↓ browse · l back · q quit", "model-help")] });
+        const detail = selected ? [
+            line(_jsxs(_Fragment, { children: [_jsxs(Text, { color: CATEGORY_COLORS.input, children: ["Input ", formatTokens(selected.tokens.input)] }), " \u00B7 ", _jsxs(Text, { color: CATEGORY_COLORS.output, children: ["Output ", formatTokens(selected.tokens.output)] }), " \u00B7 ", _jsxs(Text, { color: CATEGORY_COLORS.cache, children: ["Cache ", formatTokens(selected.tokens.cacheRead), " read / ", formatTokens(selected.tokens.cacheWrite), " write"] })] }), "model-tokens"),
+            report?.spendAvailable === false
+                ? line(_jsx(Text, { dimColor: true, children: "Spend unavailable until the router restarts" }), "model-spend")
+                : line(_jsxs(_Fragment, { children: [_jsxs(Text, { bold: true, children: ["Spend ", money(totalSpend(selected.usd))] }), " \u00B7 ", _jsxs(Text, { color: CATEGORY_COLORS.input, children: ["Input ", money(selected.usd.input)] }), " \u00B7 ", _jsxs(Text, { color: CATEGORY_COLORS.output, children: ["Output ", money(selected.usd.output)] }), " \u00B7 ", _jsxs(Text, { color: CATEGORY_COLORS.cache, children: ["Cache ", money(selected.usd.cacheRead + selected.usd.cacheWrite)] })] }), "model-spend"),
+        ] : [];
+        return _jsxs(Box, { width: width, height: height, paddingLeft: 1, flexDirection: "column", children: [line(`Model ${fullModels.length ? modelIndex % fullModels.length + 1 : 0}/${fullModels.length} · ${selected ? PROVIDER_LABELS[selected.provider] : ""}`, "model-title"), chunks.slice(0, Math.max(1, height - 3 - detail.length)).map((text, i) => line(text, `model-name${i}`)), detail, line("↑↓ browse · l back · q quit", "model-help")] });
     }
+    // Spacer lines between sections whenever the viewport can afford them.
+    const roomy = height >= 30;
     const lines = [];
+    const gap = (key) => { if (roomy)
+        lines.push(line(" ", key)); };
     lines.push(line(_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, color: "cyan", children: "cc-router usage" }), "  ", report?.start.slice(0, 10) ?? query.date ?? "Current", " \u00B7 UTC", loading ? " · loading" : ""] }), "title"));
     lines.push(line(_jsx(_Fragment, { children: PERIODS.map(period => _jsxs(Text, { bold: period === query.period, inverse: period === query.period, children: [" ", period[0].toUpperCase() + period.slice(1), " "] }, period)) }), "tabs"));
+    gap("gap-tabs");
     if (report) {
         const { totals, costs } = report;
-        lines.push(line(_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: formatTokens(totalTokens(totals)) }), " tokens  Input ", formatTokens(totals.input), "  Output ", formatTokens(totals.output), "  Cache ", formatTokens(totals.cacheRead), " read / ", formatTokens(totals.cacheWrite), " write"] }), "tokens"));
-        const saved = _jsxs(_Fragment, { children: [_jsx(Text, { color: costs.savingsUsd !== null && costs.savingsUsd < 0 ? "red" : "green", children: money(costs.savingsUsd) }), costs.savingsPercent === null ? "" : ` (${costs.savingsPercent.toFixed(1)}%)`] });
-        lines.push(line(_jsxs(_Fragment, { children: [width < 68 ? "API" : "API equivalent", " ", money(costs.pricedApiUsd), costs.coverage.pricingComplete ? "" : " (partial)", "  Sub ", money(costs.subscriptionUsd), costs.coverage.subscriptionComplete ? "" : " (partial)", width >= 68 ? _jsxs(_Fragment, { children: ["  Savings ", saved] }) : null] }), "costs"));
+        const spendTotals = report.buckets.reduce((acc, bucket) => { addSpend(acc, bucket.usd); return acc; }, zeroSpend());
+        const spendKnown = report.spendAvailable !== false;
+        const cacheTokens = _jsxs(Text, { color: CATEGORY_COLORS.cache, children: ["Cache ", _jsx(Text, { bold: true, children: formatTokens(totals.cacheRead) }), " read / ", _jsx(Text, { bold: true, children: formatTokens(totals.cacheWrite) }), " write"] });
+        lines.push(line(_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: formatTokens(totalTokens(totals)) }), " tokens  ", _jsxs(Text, { color: CATEGORY_COLORS.input, children: ["Input ", _jsx(Text, { bold: true, children: formatTokens(totals.input) })] }), "  ", _jsxs(Text, { color: CATEGORY_COLORS.output, children: ["Output ", _jsx(Text, { bold: true, children: formatTokens(totals.output) })] }), width >= 68 ? _jsxs(_Fragment, { children: ["  ", cacheTokens] }) : null] }), "tokens"));
+        // Narrow terminals truncated the cache figures off the end of the line; give them their own.
         if (width < 68)
-            lines.push(line(_jsxs(_Fragment, { children: ["Savings ", saved] }), "savings"));
+            lines.push(line(cacheTokens, "cache-tokens"));
+        lines.push(line(_jsxs(_Fragment, { children: [_jsxs(Text, { bold: true, children: ["API cost ", money(costs.pricedApiUsd)] }), costs.coverage.pricingComplete ? "" : _jsx(Text, { color: "yellow", children: " (partial)" }), width < 68 ? null : spendKnown
+                    ? _jsxs(_Fragment, { children: ["  ", _jsxs(Text, { color: CATEGORY_COLORS.input, children: ["Input ", _jsx(Text, { bold: true, children: money(spendTotals.input) })] }), "  ", _jsxs(Text, { color: CATEGORY_COLORS.output, children: ["Output ", _jsx(Text, { bold: true, children: money(spendTotals.output) })] }), "  ", _jsxs(Text, { color: CATEGORY_COLORS.cache, children: ["Cache ", _jsx(Text, { bold: true, children: money(spendTotals.cacheRead + spendTotals.cacheWrite) })] })] })
+                    : _jsx(Text, { dimColor: true, children: "  Input / output / cache unavailable until the router restarts" })] }), "costs"));
+        gap("gap-totals");
     }
-    lines.push(line(_jsxs(_Fragment, { children: [USAGE_PROVIDERS.map((provider, i) => _jsxs(Text, { color: PROVIDER_COLORS[provider], dimColor: query.providers !== undefined && !query.providers.includes(provider), children: [i + 1, " ", query.providers === undefined || query.providers.includes(provider) ? "■" : "□", " ", PROVIDER_LABELS[provider], "  "] }, provider)), _jsx(Text, { dimColor: true, children: models ? "Models" : "Providers" })] }), "providers"));
+    lines.push(line(_jsxs(_Fragment, { children: [USAGE_PROVIDERS.map((provider, i) => _jsxs(Text, { color: PROVIDER_COLORS[provider], dimColor: query.providers !== undefined && !query.providers.includes(provider), children: [i + 1, " ", query.providers === undefined || query.providers.includes(provider) ? "■" : "□", " ", PROVIDER_LABELS[provider], "  "] }, provider)), _jsxs(Text, { dimColor: true, children: [models ? "Models" : "Providers", " \u00B7 "] }), _jsx(Text, { color: spend ? "yellow" : "cyan", children: spend ? "Spend" : "Tokens" }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), _jsx(Text, { color: facet === "sum" ? undefined : CATEGORY_COLORS[facet], dimColor: facet === "sum", children: FACET_LABELS[facet] })] }), "providers"));
     const warning = error ?? report?.warnings[0];
-    if (warning)
-        lines.push(line(_jsxs(Text, { color: "yellow", children: [error ? "Error" : "Partial", ": ", warning, report && report.warnings.length > 1 ? ` (+${report.warnings.length - 1})` : ""] }), "warning"));
-    else if (report && totalTokens(report.totals) === 0)
-        lines.push(line(_jsx(Text, { dimColor: true, children: query.providers?.length === 0 ? "No providers selected. Press 1–3 to include one." : "No tokens recorded in this period. History begins with tracking." }), "empty"));
+    const notice = warning
+        ? line(_jsxs(Text, { color: "yellow", children: [error ? "Error" : "Partial", ": ", warning, report && report.warnings.length > 1 ? ` (+${report.warnings.length - 1})` : ""] }), "warning")
+        : report && totalTokens(report.totals) === 0
+            ? line(_jsx(Text, { dimColor: true, children: query.providers?.length === 0 ? "No providers selected. Press 1–3 to include one." : "No tokens recorded in this period. History begins with tracking." }), "empty")
+            : undefined;
     if (report) {
         const showBoth = height >= 25;
         const showGrid = showBoth || gridFocus;
-        const chartHeight = showBoth ? Math.max(2, Math.min(8, height - lines.length - 13)) : Math.max(2, Math.min(8, height - lines.length - 4));
+        const gapLines = roomy ? 1 : 0;
+        // Everything that must still fit under the chart: axis, legend, grid, notice, help and the spacers between them.
+        const reserved = 2 + (showGrid ? 9 + gapLines : 0) + gapLines + (notice ? 1 : 0) + 1;
+        const chartHeight = Math.max(2, Math.min(8, height - lines.length - gapLines - reserved));
+        // The grid is at most a year of weeks wide; the chart shares that right edge so the two read as one block.
+        const weeks = heatmapWeeks(report.days.map(day => day.date));
+        const span = Math.max(1, Math.min(weeks.length, Math.floor((width - 4) / 2)));
+        const gridWidth = 4 + span * 2;
         if (showBoth || !gridFocus) {
+            gap("gap-chart");
+            // Few buckets (a week has seven) get wide columns so the bars fill the row and every label has room.
+            const plotWidth = Math.max(2, Math.min(width, gridWidth) - 8);
+            const columnWidth = Math.max(2, Math.min(MAX_COLUMN_WIDTH, Math.floor(plotWidth / Math.max(1, report.buckets.length))));
             const chart = chartColumns(report.buckets.map(b => ({
                 label: query.period === "day" ? b.start.slice(11, 13) : query.period === "year" ? b.start.slice(5, 7) : b.start.slice(8, 10),
-                series: Object.values(b.series).map(s => ({ ...s, tokens: totalTokens(s.tokens) })),
-            })), Math.max(1, Math.floor((width - 7) / 2)), chartHeight, models, models ? Math.max(2, Math.floor(width / 24)) : 3);
+                series: Object.values(b.series).map(s => ({ ...s, tokens: measure(s.tokens, s.usd) })),
+            })), Math.max(1, Math.floor(plotWidth / columnWidth)), chartHeight, models, models ? Math.max(2, Math.floor(width / 24)) : 3);
             const colors = new Map(chart.legend.map((s, i) => [s.key, legendColor(s, i, models)]));
             const glyphs = new Map(chart.legend.map((s, i) => [s.key, legendGlyph(s, i, models)]));
+            // Wide columns keep one blank cell between bars; two-cell columns stay flush as before.
+            const fill = columnWidth >= 3 ? columnWidth - 1 : columnWidth;
             for (let row = 0; row < chartHeight; row++)
-                lines.push(line(_jsxs(_Fragment, { children: [_jsxs(Text, { dimColor: true, children: [(row === 0 ? formatTokens(chart.max) : row === chartHeight - 1 ? "0" : "").padStart(5), " \u2502"] }), chart.columns.map((col, i) => _jsx(Text, { color: col.cells[row] ? colors.get(col.cells[row]) : undefined, children: col.cells[row] ? glyphs.get(col.cells[row]).repeat(2) : "  " }, i))] }), `bar${row}`));
-            lines.push(line(_jsxs(Text, { dimColor: true, children: ["      └", chart.columns.map((col, i) => i % Math.max(1, Math.ceil(chart.columns.length / 8)) === 0 ? col.label.padStart(2).slice(-2) : "  ").join("")] }), "axis"));
+                lines.push(line(_jsxs(_Fragment, { children: [_jsxs(Text, { dimColor: true, children: [(row === 0 ? formatMeasure(chart.max) : row === chartHeight - 1 ? "0" : "").padStart(6), " \u2502"] }), chart.columns.map((col, i) => _jsx(Text, { color: col.cells[row] ? colors.get(col.cells[row]) : undefined, children: (col.cells[row] ? glyphs.get(col.cells[row]).repeat(fill) : " ".repeat(fill)).padEnd(columnWidth) }, i))] }), `bar${row}`));
+            const labelStride = columnWidth >= 3 ? 1 : Math.max(1, Math.ceil(chart.columns.length / 8));
+            const axisUnit = query.period === "day" ? "hour" : query.period === "year" ? "month" : "day";
+            lines.push(line(_jsxs(Text, { dimColor: true, children: ["       └", chart.columns.map((col, i) => i % labelStride === 0 ? col.label.padStart(2).slice(-2).padEnd(columnWidth) : " ".repeat(columnWidth)).join("").trimEnd(), "  ", axisUnit] }), "axis"));
             const labelWidth = Math.max(5, Math.floor(width / Math.max(1, chart.legend.length)) - 4);
             lines.push(line(_jsx(_Fragment, { children: chart.legend.map(s => _jsxs(Text, { color: colors.get(s.key), children: [glyphs.get(s.key), " ", s.label.length > labelWidth ? `${s.label.slice(0, Math.ceil((labelWidth - 1) / 2))}…${s.label.slice(-Math.floor((labelWidth - 1) / 2))}` : s.label, "  "] }, s.key)) }), "legend"));
         }
-        if (showGrid && height - lines.length >= 10) {
+        if (showGrid && height - lines.length >= 10 + gapLines) {
+            gap("gap-grid");
             const byDate = new Map(report.days.map(day => [day.date, day]));
-            const weeks = heatmapWeeks(report.days.map(day => day.date));
-            const span = Math.max(1, Math.floor((width - 4) / 2));
             const focusedWeek = weeks.findIndex(week => week.includes(focused));
             const firstWeek = Math.max(0, Math.min(weeks.length - span, focusedWeek - Math.floor(span / 2)));
             const visible = weeks.slice(firstWeek, firstWeek + span);
-            const max = Math.max(0, ...report.days.map(day => totalTokens(day.tokens)));
+            const max = Math.max(0, ...report.days.map(day => measure(day.tokens, day.usd)));
             let lastMonth = "";
             const months = visible.map(week => {
                 const date = week.find(Boolean) ?? "";
@@ -179,7 +258,7 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
                 lastMonth = month;
                 return label;
             }).join("");
-            lines.push(line(_jsxs(Text, { dimColor: true, children: ["    ", months, "  ", gridFocus ? "[day focus]" : "[daily tokens]"] }), "months"));
+            lines.push(line(_jsxs(Text, { dimColor: true, children: ["    ", months, "  ", gridFocus ? "[day focus]" : `[daily ${spend ? "spend" : "tokens"}${facet === "sum" ? "" : ` · ${facet}`}]`] }), "months"));
             for (let row = 0; row < 7; row++)
                 lines.push(line(_jsxs(_Fragment, { children: [_jsxs(Text, { dimColor: true, children: [["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"][row], "  "] }), visible.map((week, i) => {
                             const date = week[row];
@@ -187,22 +266,26 @@ export function UsageDashboard({ load, initialQuery = { period: "month" }, onExi
                             if (!day)
                                 return _jsx(Text, { children: "  " }, i);
                             const unknown = day.coverage === "future" || day.coverage === "untracked";
-                            return _jsx(Text, { inverse: gridFocus && date === focused, bold: day.selected, color: unknown ? "gray" : HEAT[activityLevel(totalTokens(day.tokens), max)], children: day.coverage === "future" ? "· " : day.coverage === "untracked" ? "? " : day.coverage === "partial" ? "▧ " : "■ " }, i);
+                            return _jsx(Text, { inverse: gridFocus && date === focused, bold: day.selected, color: unknown ? "gray" : HEAT[activityLevel(measure(day.tokens, day.usd), max)], children: day.coverage === "future" ? "· " : day.coverage === "untracked" ? "? " : day.coverage === "partial" ? "▧ " : "■ " }, i);
                         })] }), `heat${row}`));
             const selected = byDate.get(focused);
-            lines.push(line(_jsxs(Text, { dimColor: true, children: [selected ? `${focused}  ${totalTokens(selected.tokens).toLocaleString("en-US")} tokens · ${selected.coverage}` : "Daily tokens", "  Less \u2591\u2592\u2593\u2588 More"] }), "day"));
+            lines.push(line(_jsxs(Text, { dimColor: true, children: [selected ? `${focused}  ${describe(measure(selected.tokens, selected.usd))} · ${selected.coverage}` : `Daily ${unit}`, "  Less \u2591\u2592\u2593\u2588 More"] }), "day"));
         }
         else if (showGrid) {
             const selected = report.days.find(day => day.date === focused);
             lines.push(line(_jsx(Text, { bold: true, children: "Compact day focus \u00B7 arrows inspect" }), "compact-grid"));
             if (selected)
-                lines.push(line(`${focused}  ${totalTokens(selected.tokens).toLocaleString("en-US")} tokens`, "compact-inspector"));
+                lines.push(line(`${focused}  ${describe(measure(selected.tokens, selected.usd))}`, "compact-inspector"));
             lines.push(line(`${selected?.coverage ?? "unavailable"} · ? untracked · · future`, "compact-coverage"));
         }
     }
+    if (notice) {
+        gap("gap-notice");
+        lines.push(notice);
+    }
     if (!report && !loading && !error)
         lines.push(line("No usage history available.", "nohistory"));
-    const help = width >= 76 ? "q quit · ? help · Tab period · ←→ move · t today · 1–3 · m models · g grid · l names" : width >= 38 ? "q quit · ? help · Tab ←→ t 1–3 m g l" : "q quit · ? help";
+    const help = width >= 96 ? "q quit · ? help · Tab period · ←→ move · t today · 1–3 · m models · s spend · i in/out · g grid · l names" : width >= 38 ? "q quit · ? help · Tab ←→ t 1–3 m s i g l" : "q quit · ? help";
     // Explicit viewport budget prevents Ink from scrolling controls offscreen on resize.
-    return _jsxs(Box, { width: width, flexDirection: "column", children: [lines.slice(0, height - 1), line(_jsx(Text, { dimColor: true, children: help }), "help")] });
+    return _jsxs(Box, { width: width, height: height, paddingLeft: 1, flexDirection: "column", children: [lines.slice(0, height - 1), line(_jsx(Text, { dimColor: true, children: help }), "help")] });
 }

package/dist/usage/client.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { UsageStore } from "./store.js";
 import { queryRuntimeUsage } from "./runtime.js";
-import { utcTimestamp, usageProvider, validateAccount, validateTokens } from "./types.js";
+import { utcTimestamp, usageProvider, validateAccount, validateSpend, validateTokens, zeroSpend } from "./types.js";
 const clean = (value, max = 256) => {
     if (typeof value !== "string" || value.length > max || /[\p{Cc}\p{Cf}]/u.test(value))
         throw new Error("Invalid usage text from server");
@@ -21,16 +21,25 @@ export function validateUsageReport(value) {
     if (!Array.isArray(r.buckets) || r.buckets.length > 366 || !Array.isArray(r.days) || r.days.length > 366
         || !Array.isArray(r.accounts) || r.accounts.length > 10_000 || !Array.isArray(r.warnings) || r.warnings.length > 100)
         throw new Error("Invalid usage report size");
+    // A router from before per-bucket spend omits `usd`; treat that as zero rather than refusing its history,
+    // but flag it so the dashboard shows "unavailable" instead of a false $0.00 split.
+    let spendMissing = false;
+    const spend = (value) => { if (value === undefined) {
+        spendMissing = true;
+        return zeroSpend();
+    } return validateSpend(value); };
     for (const b of [...r.buckets, ...r.days]) {
         utcTimestamp(b.start);
         utcTimestamp(b.end);
         validateTokens(b.tokens);
+        b.usd = spend(b.usd);
         if (!b.series || typeof b.series !== "object" || Object.keys(b.series).length > 100)
             throw new Error("Invalid usage series");
         for (const s of Object.values(b.series)) {
             usageProvider(s.provider);
             clean(s.model);
             validateTokens(s.tokens);
+            s.usd = spend(s.usd);
         }
     }
     for (const d of r.days) {
@@ -52,6 +61,10 @@ export function validateUsageReport(value) {
     for (const key of ["pricingComplete", "subscriptionComplete", "trackingComplete", "persistenceHealthy"])
         if (typeof r.costs.coverage[key] !== "boolean")
             throw new Error("Invalid coverage");
+    if (spendMissing) {
+        r.spendAvailable = false;
+        r.warnings.push("This router predates per-category spend; restart it (cc-router start) to see input, output and cache costs.");
+    }
     return r;
 }
 function transportFailure(error) {

package/dist/usage/query.js

@@ -1,32 +1,34 @@
-import { addTokens, object, USAGE_PROVIDERS, utcTimestamp, usageProvider, zeroTokens } from "./types.js";
+import { addSpend, addTokens, object, totalSpend, USAGE_PROVIDERS, utcTimestamp, usageProvider, zeroSpend, zeroTokens } from "./types.js";
 import { prorateSubscriptions } from "./subscriptions.js";
 const DAY = 86_400_000;
 const HOUR = 3_600_000;
 const MODEL_LIMIT = 16; // Per provider, including Other. Bounds all chart/heatmap series.
 function iso(ms) { return new Date(ms).toISOString(); }
-function newBucket(start, end) { return { start: iso(start), end: iso(end), tokens: zeroTokens(), series: {} }; }
-function addToBucket(bucket, entry, model) {
+function newBucket(start, end) { return { start: iso(start), end: iso(end), tokens: zeroTokens(), usd: zeroSpend(), series: {} }; }
+function addToBucket(bucket, entry, model, usd) {
     addTokens(bucket.tokens, entry.tokens);
+    addSpend(bucket.usd, usd);
     const key = JSON.stringify([entry.provider, model]);
-    const series = bucket.series[key] ??= { provider: entry.provider, model, tokens: zeroTokens() };
+    const series = bucket.series[key] ??= { provider: entry.provider, model, tokens: zeroTokens(), usd: zeroSpend() };
     addTokens(series.tokens, entry.tokens);
+    addSpend(series.usd, usd);
 }
 function price(entry) {
     const { tokens, rates } = entry;
     const categories = [
-        [tokens.input, rates?.input], [tokens.output, rates?.output], [tokens.cacheRead, rates?.cacheRead],
-        [tokens.cacheWrite - tokens.cacheWrite5m - tokens.cacheWrite1h, rates?.cacheWrite],
-        [tokens.cacheWrite5m, rates?.cacheWrite5m], [tokens.cacheWrite1h, rates?.cacheWrite1h],
+        ["input", tokens.input, rates?.input], ["output", tokens.output, rates?.output], ["cacheRead", tokens.cacheRead, rates?.cacheRead],
+        ["cacheWrite", tokens.cacheWrite - tokens.cacheWrite5m - tokens.cacheWrite1h, rates?.cacheWrite],
+        ["cacheWrite", tokens.cacheWrite5m, rates?.cacheWrite5m], ["cacheWrite", tokens.cacheWrite1h, rates?.cacheWrite1h],
     ];
-    let usd = 0;
+    const usd = zeroSpend();
     let priced = 0;
     let unpriced = 0;
-    for (const [count, rate] of categories) {
+    for (const [category, count, rate] of categories) {
         if (rate === undefined)
             unpriced += count;
         else {
             priced += count;
-            usd += count * rate / 1e6;
+            usd[category] += count * rate / 1e6;
         }
     }
     return { usd, priced, unpriced };
@@ -131,9 +133,10 @@ export function queryUsage(snapshot, query, now) {
             }
         }
         const incomplete = "attemptId" in entry && incompleteAttempts.has(entry.attemptId);
+        const cost = price(entry);
         if (ts >= yearStart && ts < yearEnd) {
             const day = days[Math.floor((ts - yearStart) / DAY)];
-            addToBucket(day, entry, model);
+            addToBucket(day, entry, model, cost.usd);
             if (incomplete && day.coverage === "complete")
                 day.coverage = "partial";
         }
@@ -143,13 +146,12 @@ export function queryUsage(snapshot, query, now) {
             incompleteInPeriod = true;
         observedAccounts.add(entry.accountKey);
         addTokens(totals, entry.tokens);
-        const cost = price(entry);
-        pricedApiUsd += cost.usd;
+        pricedApiUsd += totalSpend(cost.usd);
         pricedTokens += cost.priced;
         unpricedTokens += cost.unpriced;
         const bucket = buckets.find(candidate => candidate.start <= iso(ts) && candidate.end > iso(ts));
         if (bucket)
-            addToBucket(bucket, entry, model);
+            addToBucket(bucket, entry, model, cost.usd);
     }
     const subscriptions = snapshot.subscriptions.filter(entry => providers.has(entry.provider));
     const overlappingSubscriptions = subscriptions.filter(entry => Date.parse(entry.from) < elapsedEnd && (!entry.to || Date.parse(entry.to) > start));

package/dist/usage/types.js

@@ -1,5 +1,21 @@
 export const USAGE_PROVIDERS = ["anthropic_subscription", "openai_subscription", "xai_subscription"];
 export const TOKEN_KEYS = ["input", "output", "cacheRead", "cacheWrite", "cacheWrite5m", "cacheWrite1h"];
+export const SPEND_KEYS = ["input", "output", "cacheRead", "cacheWrite"];
+export function zeroSpend() { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }; }
+export function totalSpend(usd) { return usd.input + usd.output + usd.cacheRead + usd.cacheWrite; }
+export function addSpend(target, usd) { for (const key of SPEND_KEYS)
+    target[key] += usd[key]; }
+export function validateSpend(value) {
+    const input = object(value, SPEND_KEYS);
+    const result = zeroSpend();
+    for (const key of SPEND_KEYS) {
+        const amount = input[key] ?? 0;
+        if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0)
+            throw new Error(`Invalid ${key} spend`);
+        result[key] = amount;
+    }
+    return result;
+}
 export function zeroTokens() { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cacheWrite5m: 0, cacheWrite1h: 0 }; }
 export function totalTokens(tokens) { return tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite; }
 export function addTokens(target, tokens) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timo972/cc-router",
-  "version": "0.13.0-rc.3",
+  "version": "0.13.0-rc.4",
   "description": "Cache-aware session router for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {