@vimoxshah/tokenflow 1.1.0

package/src/analytics/token-usage.js

@@ -0,0 +1,267 @@
+/**
+ * Core token-usage analytics: the time series, its moving averages, the
+ * composition split, the hour/day profiles, and the trend.
+ */
+import {
+  groupRows, sumRows, zeroMeasures, finalize, addInto, dateRange, weekStart,
+  monthKey, percentile, mean, daysBetween, addDays,
+} from './aggregate.js';
+
+/**
+ * Daily (or weekly / monthly) token series.
+ *
+ * Empty calendar days inside the range are emitted with zeros and
+ * `active: false`, because a gap in a time series is information — but they are
+ * excluded from "average per active day", which is the number people actually
+ * mean when they ask how much they use per day.
+ *
+ * @param {any[][]} rows filtered cube rows
+ * @param {object} ix index from indexCube
+ * @param {{granularity?:'day'|'week'|'month', from?:string, to?:string, fill?:boolean}} opt
+ */
+export function calculateDailyUsage(rows, ix, opt = {}) {
+  const gran = opt.granularity || 'day';
+  const keyOf = gran === 'week' ? weekStart : gran === 'month' ? monthKey : (d) => d;
+  const groups = groupRows(rows, ix, (r, d) => keyOf(r[d.d]));
+
+  let keys = [...groups.keys()].sort();
+  if (opt.fill !== false && gran === 'day') {
+    const from = opt.from || keys[0];
+    const to = opt.to || keys[keys.length - 1];
+    if (from && to) keys = dateRange(from, to);
+  }
+  return keys.map((k) => {
+    const g = groups.get(k);
+    const m = g ? g.m : finalize(zeroMeasures());
+    return {
+      key: k,
+      date: k,
+      // `active` = any AI activity that day (including sources that report no
+      // tokens). `tokenActive` = tokens were actually measured. Averaging over
+      // the wrong one is how a dashboard ends up claiming a median of ~0.
+      active: !!g && m.req > 0,
+      tokenActive: !!g && m.total > 0,
+      ...m,
+    };
+  });
+}
+
+/** Trailing simple moving average over a series field. Nulls until the window fills. */
+export function movingAverage(series, window, field = 'total') {
+  const out = new Array(series.length).fill(null);
+  let sum = 0;
+  for (let i = 0; i < series.length; i++) {
+    sum += series[i][field] || 0;
+    if (i >= window) sum -= series[i - window][field] || 0;
+    if (i >= window - 1) out[i] = sum / window;
+  }
+  return out;
+}
+
+/**
+ * Average usage. `perActiveDay` is the headline; `perCalendarDay` is offered
+ * beside it so the difference between "how hard I work when I work" and "how
+ * much I use overall" stays visible instead of being silently chosen for you.
+ */
+export function calculateAverageUsage(series) {
+  const active = series.filter((d) => d.tokenActive);
+  const anyActivity = series.filter((d) => d.active);
+  const sum = (f, arr) => arr.reduce((a, b) => a + (b[f] || 0), 0);
+  return {
+    activeDays: active.length,
+    activityDays: anyActivity.length,
+    activityOnlyDays: anyActivity.length - active.length,
+    calendarDays: series.length,
+    perActiveDay: active.length ? sum('total', active) / active.length : null,
+    perCalendarDay: series.length ? sum('total', series) / series.length : null,
+    outputPerActiveDay: active.length ? sum('out', active) / active.length : null,
+    requestsPerActiveDay: active.length ? sum('req', active) / active.length : null,
+    medianActiveDay: active.length
+      ? percentile(active.map((d) => d.total).sort((a, b) => a - b), 0.5)
+      : null,
+  };
+}
+
+/** Input / output / cache composition, with the two ratios the spec asks for. */
+export function calculateComposition(totals) {
+  const t = totals.total || 0;
+  return {
+    total: t,
+    input: totals.in,
+    output: totals.out,
+    cacheRead: totals.cr,
+    cacheWrite: totals.cw,
+    cacheRefresh: totals.cf,
+    reasoning: totals.rs,
+    cache: totals.cr + totals.cw,
+    shares: t
+      ? {
+        input: totals.in / t,
+        output: totals.out / t,
+        cacheRead: totals.cr / t,
+        cacheWrite: totals.cw / t,
+        cache: (totals.cr + totals.cw) / t,
+      }
+      : { input: null, output: null, cacheRead: null, cacheWrite: null, cache: null },
+    outputPerInput: totals.in ? totals.out / totals.in : null,
+    // Output against ALL prompt-side tokens (fresh + cache read + cache write).
+    // With a cache-heavy agent, fresh input is a sliver of what was actually
+    // sent, so out/in alone would badly misdescribe the workload.
+    outputPerPromptToken: (totals.in + totals.cr + totals.cw)
+      ? totals.out / (totals.in + totals.cr + totals.cw) : null,
+    promptTokens: totals.in + totals.cr + totals.cw,
+    cacheRatio: t ? (totals.cr + totals.cw) / t : null,
+    // Of all prompt-side tokens, how many were served from cache rather than
+    // re-sent fresh. This is the number that actually reflects cache benefit.
+    cacheHitRate: totals.in + totals.cr ? totals.cr / (totals.in + totals.cr) : null,
+    reasoningShareOfOutput: totals.out ? totals.rs / totals.out : null,
+    refreshShareOfCacheWrite: totals.cw ? totals.cf / totals.cw : null,
+  };
+}
+
+export function calculateCacheRatio(totals) {
+  return calculateComposition(totals).cacheRatio;
+}
+
+/**
+ * Trend: compare the last `window` active-or-not calendar days against the
+ * equally long window before it. Returns null rather than a made-up number
+ * when there isn't enough history for a fair comparison.
+ */
+export function calculateUsageTrend(series, window = 30) {
+  if (series.length < 4) return { window: null, change: null, reason: 'not enough history' };
+  const w = Math.min(window, Math.floor(series.length / 2));
+  const recent = series.slice(-w);
+  const prior = series.slice(-2 * w, -w);
+  const sum = (a) => a.reduce((x, d) => x + (d.total || 0), 0);
+  const a = sum(prior);
+  const b = sum(recent);
+  return {
+    window: w,
+    recentTotal: b,
+    priorTotal: a,
+    change: a > 0 ? (b - a) / a : null,
+    direction: a > 0 ? (b > a * 1.05 ? 'increasing' : b < a * 0.95 ? 'decreasing' : 'flat') : 'unknown',
+    reason: a > 0 ? null : 'no usage in the comparison window',
+  };
+}
+
+/** 24-bucket hour-of-day profile. */
+export function calculateHourlyUsage(rows, ix) {
+  const buckets = Array.from({ length: 24 }, (_, h) => ({ hour: h, ...finalize(zeroMeasures()) }));
+  for (const r of rows) {
+    const b = buckets[r[ix.d.h]];
+    if (!b) continue;
+    addInto(b, r, ix);
+  }
+  for (const b of buckets) finalize(b);
+  const totals = buckets.map((b) => b.total);
+  return { buckets, peakWindow: bestWindow(totals, 3), secondaryWindow: secondBestWindow(totals, 3) };
+}
+
+/** Monday-first day-of-week profile, with a per-active-day average. */
+export function calculateDowUsage(rows, ix, series = null) {
+  const buckets = Array.from({ length: 7 }, (_, w) => ({ dow: w, days: 0, ...finalize(zeroMeasures()) }));
+  for (const r of rows) {
+    const b = buckets[r[ix.d.w]];
+    if (!b) continue;
+    addInto(b, r, ix);
+  }
+  if (series) {
+    for (const d of series) {
+      if (!d.tokenActive) continue;
+      const w = dowOf(d.date);
+      buckets[w].days++;
+    }
+  }
+  for (const b of buckets) {
+    finalize(b);
+    b.perActiveDay = b.days ? b.total / b.days : null;
+  }
+  return buckets;
+}
+
+/** 7x24 matrix for the hour x weekday heatmap. */
+export function calculateHourDow(rows, ix) {
+  const cells = [];
+  const grid = Array.from({ length: 7 }, () => Array.from({ length: 24 }, () => zeroMeasures()));
+  for (const r of rows) {
+    const w = r[ix.d.w];
+    const h = r[ix.d.h];
+    if (grid[w] && grid[w][h]) addInto(grid[w][h], r, ix);
+  }
+  let max = 0;
+  for (let w = 0; w < 7; w++) {
+    for (let h = 0; h < 24; h++) {
+      const m = finalize(grid[w][h]);
+      if (m.total > max) max = m.total;
+      cells.push({ dow: w, hour: h, ...m });
+    }
+  }
+  return { cells, max };
+}
+
+/**
+ * Calendar-heatmap levels from the *distribution* of the data, not from fixed
+ * thresholds — so the heatmap still reads correctly whether your daily usage is
+ * measured in thousands or in billions.
+ */
+export function calendarLevels(series, levels = 4) {
+  const active = series.filter((d) => d.tokenActive).map((d) => d.total).sort((a, b) => a - b);
+  if (!active.length) return { thresholds: [], levelOf: () => 0, max: 0 };
+  const thresholds = [];
+  for (let i = 1; i <= levels; i++) thresholds.push(percentile(active, i / (levels + 1)));
+  return {
+    thresholds,
+    max: active[active.length - 1],
+    median: percentile(active, 0.5),
+    levelOf(total, isActive) {
+      if (!isActive || !total) return 0;
+      let l = 1;
+      for (const t of thresholds) if (total > t) l++;
+      return Math.min(l, levels + 1);
+    },
+  };
+}
+
+export function dowOf(iso) {
+  const [y, m, d] = iso.split('-').map(Number);
+  return (new Date(Date.UTC(y, m - 1, d)).getUTCDay() + 6) % 7;
+}
+
+/** Contiguous window of `size` buckets with the largest sum (wraps midnight). */
+export function bestWindow(values, size) {
+  const n = values.length;
+  if (!n) return null;
+  let best = -1;
+  let at = 0;
+  for (let i = 0; i < n; i++) {
+    let s = 0;
+    for (let k = 0; k < size; k++) s += values[(i + k) % n];
+    if (s > best) { best = s; at = i; }
+  }
+  if (best <= 0) return null;
+  return { from: at, to: (at + size - 1) % n, total: best, share: best / values.reduce((a, b) => a + b, 0) };
+}
+
+function secondBestWindow(values, size) {
+  const first = bestWindow(values, size);
+  if (!first) return null;
+  const masked = values.slice();
+  for (let k = 0; k < size; k++) masked[(first.from + k) % masked.length] = 0;
+  const second = bestWindow(masked, size);
+  if (!second || !second.total) return null;
+  return { ...second, share: second.total / values.reduce((a, b) => a + b, 0) };
+}
+
+/** Longest run of consecutive active days, and the current run. */
+export function calculateStreaks(series) {
+  let best = 0, cur = 0, bestEnd = null;
+  for (const d of series) {
+    if (d.tokenActive) {
+      cur++;
+      if (cur > best) { best = cur; bestEnd = d.date; }
+    } else cur = 0;
+  }
+  return { longest: best, longestEndedOn: bestEnd, current: cur };
+}

package/src/commands/diagnostics.js

@@ -0,0 +1,88 @@
+/**
+ * `tokenflow diagnostics` — local observability without telemetry.
+ *
+ * Everything a support request or a debugging session needs, printed from
+ * local state only. Nothing is transmitted; `--out <file>` writes the same
+ * content to a file the user can choose to share voluntarily.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig, paths } from '../core/config.js';
+
+/**
+ * @param {{includePaths?: boolean}} opt
+ * @returns {object} diagnostics snapshot (plain JSON-able)
+ */
+export function collect(opt = {}) {
+  const cfg = loadConfig();
+  const p = paths();
+  const showPaths = !!opt.includePaths;
+
+  const dataDir = p.data;
+  const fileStat = (f) => {
+    try { const s = fs.statSync(f); return { exists: true, sizeBytes: s.size, modified: s.mtime.toISOString() }; }
+    catch { return { exists: false }; }
+  };
+
+  return {
+    version: process.env.npm_package_version || '1.1.0',
+    node: process.version,
+    platform: `${os.platform()} ${os.arch()} ${os.release()}`,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    providers: {
+      enabled: cfg.providers.length ? cfg.providers : 'all detected',
+      configuredSources: Object.keys(cfg.sources || {}),
+    },
+    store: {
+      records: fileStat(`${dataDir}/cube.json`),
+      sessions: fileStat(`${dataDir}/sessions.json`),
+      status: fileStat(`${dataDir}/status.json`),
+    },
+    freshness: (() => {
+      try {
+        const s = JSON.parse(fs.readFileSync(`${dataDir}/status.json`, 'utf8'));
+        return { lastRefresh: s.freshness?.lastRefresh ?? null, stale: s.freshness?.stale ?? null };
+      } catch { return { lastRefresh: null, stale: 'unknown' }; }
+    })(),
+    features: {
+      budgetConfigured: !!(cfg.budget?.monthly),
+      digestScheduleInstalled: fs.existsSync(path.join(os.homedir(), 'Library', 'LaunchAgents', 'app.tokenflow.digest.plist')),
+      promptAnalyticsEnabled: !!cfg.promptAnalytics?.enabled,
+      rawPromptCaptureEnabled: !!cfg.promptAnalytics?.storeRaw,
+      syncEnabled: !!cfg.sync?.enabled,
+      syncDir: cfg.sync?.enabled ? (showPaths ? cfg.sync.dir : '<configured>') : null,
+      deliveryChannels: Object.entries(cfg.delivery || {})
+        .filter(([, v]) => v && Object.values(v).some(Boolean))
+        .map(([k]) => k),
+    },
+    paths: showPaths
+      ? { home: p.root, data: dataDir, config: p.config }
+      : undefined,
+  };
+}
+
+export function renderText(d) {
+  const L = [];
+  L.push('TokenFlow diagnostics');
+  L.push(`  version:   ${d.version}   node: ${d.node}`);
+  L.push(`  platform:  ${d.platform}   tz: ${d.timezone}`);
+  L.push('');
+  L.push('Providers');
+  L.push(`  enabled: ${Array.isArray(d.providers.enabled) ? d.providers.enabled.join(', ') : d.providers.enabled}`);
+  L.push('');
+  L.push('Store');
+  for (const [k, v] of Object.entries(d.store)) {
+    L.push(`  ${k}: ${v.exists ? `${v.sizeBytes} bytes, modified ${v.modified}` : 'MISSING'}`);
+  }
+  L.push(`  last refresh: ${d.freshness.lastRefresh || 'never'}${d.freshness.stale === true ? ' (STALE)' : ''}`);
+  L.push('');
+  L.push('Features');
+  L.push(`  budget alerts:     ${d.features.budgetConfigured ? 'configured' : 'not configured'}`);
+  L.push(`  digest schedule:   ${d.features.digestScheduleInstalled ? 'installed' : 'not installed'}`);
+  L.push(`  prompt analytics:  ${d.features.promptAnalyticsEnabled ? `ON${d.features.rawPromptCaptureEnabled ? ' (+RAW)' : ''}` : 'off'}`);
+  L.push(`  sync:              ${d.features.syncEnabled ? `ON → ${d.features.syncDir}` : 'off'}`);
+  L.push(`  delivery channels: ${d.features.deliveryChannels.length ? d.features.deliveryChannels.join(', ') : 'none'}`);
+  if (d.paths) L.push('', 'Paths', `  home: ${d.paths.home}`, `  data: ${d.paths.data}`, `  config: ${d.paths.config}`);
+  return L.join('\n');
+}

package/src/commands/digest.js

@@ -0,0 +1,155 @@
+/**
+ * `tokenflow digest` — a shareable weekly summary.
+ *
+ * The missing "show someone else" surface: the dashboard is interactive, the
+ * offline HTML export carries the whole dataset, but neither fits in a Slack
+ * message or a stand-up note. The digest renders the current view (or an
+ * arbitrary --from/--to window) as compact Markdown or plain text: headline
+ * numbers, top providers/models/sources, week-over-week delta, and any active
+ * alerts — every number from the same cube the dashboard uses, so nothing can
+ * disagree. Zero dependencies, no network, no new data collection.
+ *
+ *   tokenflow digest                     # last 7 days, markdown to stdout
+ *   tokenflow digest --format text       # plain text
+ *   tokenflow digest --out digest.md     # write to a file
+ *   tokenflow digest --from 2026-08-01 --to 2026-08-07
+ */
+import { buildBundle } from '../core/bundle.js';
+import { computeView } from '../analytics/index.js';
+import { filterCube, indexCube, finalize, sumRows, addDays } from '../analytics/aggregate.js';
+import { compact, usd } from '../core/units.js';
+import fs from 'node:fs';
+
+const money = (n) => (n == null || !(n > 0) ? null : usd(n));
+const tokens = (n) => (n > 0 ? compact(n) : '0');
+
+function rankBy(rows, ix, dim, n = 5) {
+  const by = new Map();
+  for (const r of rows) {
+    if (!(r[ix.m.totalKey] ?? true)) { /* noop; totals computed below */ }
+    const k = r[dim];
+    by.set(k, (by.get(k) || 0) + r[ix.m.in] + r[ix.m.out] + r[ix.m.cr] + r[ix.m.cw]);
+  }
+  return [...by.entries()].filter(([, v]) => v > 0).sort((a, b) => b[1] - a[1]).slice(0, n);
+}
+
+export function renderDigest({ status, from, to, format = 'markdown' }) {
+  const u = status.usage;
+  const today = u.today;
+  const lines = [];
+
+  const title = `TokenFlow digest — ${from} → ${to}`;
+  if (format === 'text') {
+    lines.push(title, '='.repeat(title.length), '');
+  } else {
+    lines.push(`## ${title}`, '');
+  }
+  const bullet = (s) => (format === 'text' ? ` • ${s}` : `- ${s}`);
+
+  // headline
+  const cost = today.cost != null ? money(today.cost) : today.costMeasured != null ? `${money(today.costMeasured)} (measured)` : null;
+  lines.push(bullet(`Tokens: **${tokens(today.tokens.total)}** (${tokens(today.tokens.input)} in / ${tokens(today.tokens.output)} out / ${tokens(today.tokens.cacheRead)} cache-read)`));
+  if (cost) lines.push(bullet(`Estimated spend: **${cost}**`));
+  if (today.requests != null) lines.push(bullet(`Requests: ${today.requests} across ${today.sessions ?? '?'} sessions`));
+
+  // period totals when it's not just today
+  if (u.weekToDate && from !== to) {
+    lines.push(bullet(`Week-to-date: ${tokens(u.weekToDate.tokens.total)}${money(u.weekToDate.cost) ? ` · ${money(u.weekToDate.cost)}` : ''}`));
+  }
+
+  // breakdowns
+  const sec = (name, items, fmt) => {
+    if (!items.length) return;
+    lines.push('', format === 'text' ? name : `### ${name}`);
+    for (const [k, v] of items) lines.push(bullet(`${k}: ${fmt(v)}`));
+  };
+  sec('By source', status.sourcesToday.map((s) => [s.key, s.tokens]), (v) => tokens(v));
+  sec('By provider', status.providersToday.map((p) => [p.key, p.tokens]), (v) => tokens(v));
+  sec('Top models', status.modelsToday.map((m) => [m.key, m.tokens]), (v) => tokens(v));
+
+  // velocity + capacity
+  if (status.velocity?.ratio != null) {
+    const r = status.velocity.ratio;
+    const dir = r >= 1 ? 'above' : 'below';
+    lines.push('', bullet(`Pace: ${r.toFixed(2)}× your trailing 14-day average (${dir})`));
+  }
+  const worst = status.capacity?.summary?.worst;
+  if (worst && worst.pctUsed != null) {
+    lines.push(bullet(`Nearest limit: ${worst.label} at ${Math.round(worst.pctUsed * 100)}%${worst.resetsInMs ? `, resets in ${Math.round(worst.resetsInMs / 3600000)}h` : ''}`));
+  }
+
+  // alerts
+  const alerts = (status.anomalies || []).filter((a) => a.severity === 'high');
+  if (alerts.length) {
+    lines.push('', format === 'text' ? 'Alerts' : '### Alerts');
+    for (const a of alerts.slice(0, 3)) lines.push(bullet(a.detail));
+  }
+
+  lines.push('', format === 'text'
+    ? 'local-first · numbers from the same cube as the dashboard'
+    : `<sub>local-first · same cube as the dashboard</sub>`);
+  return lines.join('\n');
+}
+
+/** Build the status snapshot for an arbitrary window without mutating config. */
+export async function run(opts = {}) {
+  const b = buildBundle();
+  const v = computeView(b, {});
+  const ix = indexCube(b.cube);
+  const to = opts.to || b.meta.today;
+  const from = opts.from || addDays(to, -6);
+
+  const rows = filterCube(ix, { from, to, includeOverlay: !!b.meta.includeOverlayDefault });
+  const m = finalize(sumRows(rows, ix));
+  const topSources = rankBy(rows, ix, ix.d.c);
+  const topProviders = rankBy(rows, ix, ix.d.p);
+  const topModels = rankBy(rows, ix, ix.d.m);
+
+  const status = {
+    usage: {
+      today: {
+        tokens: { total: m.total, input: m.in, output: m.out, cacheRead: m.cr },
+        requests: m.req,
+        cost: m.costReq > 0 ? m.cost : null,
+        costMeasured: m.costMeasured > 0 ? m.costMeasured : null,
+        sessions: filterSessionsCount(b, from, to),
+      },
+      weekToDate: null,
+    },
+    sourcesToday: topSources.map(([key, tk]) => ({ key, tokens: tk })),
+    providersToday: topProviders.map(([key, tk]) => ({ key, tokens: tk })),
+    modelsToday: topModels.map(([key, tk]) => ({ key, tokens: tk })),
+    velocity: v.velocity,
+    capacity: v.capacity,
+    anomalies: v.anomalies,
+  };
+  return renderDigest({ status, from, to, format: opts.format || 'markdown' });
+}
+
+function filterSessionsCount(b, from, to) {
+  try {
+    return b.sessions.filter((s) => s.date >= from && s.date <= to).length;
+  } catch { return null; }
+}
+
+/** CLI entry point. */
+export function register(program, ctx) {
+  program
+    .command('digest')
+    .description('shareable weekly/daily summary (markdown or text)')
+    .option('--from <date>', 'window start (YYYY-MM-DD)')
+    .option('--to <date>', 'window end (YYYY-MM-DD)')
+    .option('--format <fmt>', 'markdown | text', 'markdown')
+    .option('--out <file>', 'write to file instead of stdout')
+    .action(async (flags) => {
+      const md = await run({
+        from: flags.from, to: flags.to, format: flags.format,
+      });
+      if (flags.out) {
+        fs.writeFileSync(flags.out, md + '\n');
+        console.log(`wrote ${flags.out}`);
+      } else {
+        console.log(md);
+      }
+    });
+}

package/src/commands/models-compare.js

@@ -0,0 +1,96 @@
+/**
+ * `tokenflow models-compare` — "which model is actually costing me what?"
+ *
+ * Uses ONLY the user's own measured data from the same cube as every other
+ * surface. Metrics are factual arithmetic over the window; the only judgement
+ * offered is cost-efficiency per request/token, clearly derived, never a
+ * claim about model quality. No useful-output signal exists in local logs,
+ * so "cost per useful output" is explicitly reported as unavailable rather
+ * than fabricated.
+ */
+import { buildBundle } from '../core/bundle.js';
+import { filterCube, indexCube, finalize, sumRows } from '../analytics/aggregate.js';
+import { compact, usd } from '../core/units.js';
+
+/**
+ * @param {{from?:string, to?:string}} opt
+ */
+export function compare({ from, to } = {}) {
+  const b = buildBundle();
+  const ix = indexCube(b.cube);
+  const toD = to || b.meta.today;
+  const fromD = from || addDays(toD, -29);
+
+  const rows = filterCube(ix, { from: fromD, to: toD, includeOverlay: false })
+    .filter((r) => r[ix.d.m] !== 'unknown');
+  if (!rows.length) return null;
+
+  const byModel = new Map();
+  for (const r of rows) {
+    const k = r[ix.d.m];
+    let m = byModel.get(k);
+    if (!m) {
+      m = { key: k, requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, pricedReq: 0 };
+      byModel.set(k, m);
+    }
+    m.requests += r[ix.m.req];
+    m.input += r[ix.m.in];
+    m.output += r[ix.m.out];
+    m.cacheRead += r[ix.m.cr];
+    m.cacheWrite += r[ix.m.cw];
+    m.cost += r[ix.m.cost] || 0;
+    if (r[ix.m.costReq] > 0) m.pricedReq += r[ix.m.costReq];
+  }
+
+  return {
+    from: fromD, to: toD,
+    models: [...byModel.values()]
+      .filter((m) => m.requests > 0)
+      .sort((a, b) => b.cost - a.cost)
+      .map((m) => {
+        const tokens = m.input + m.output + m.cacheRead + m.cacheWrite;
+        return {
+          ...m,
+          tokens,
+          cacheHitPct: (m.cacheRead + m.cacheWrite) > 0
+            ? Math.round((m.cacheRead / (m.cacheRead + m.input + m.cacheWrite)) * 1000) / 10
+            : null,
+          avgCostPerRequest: m.pricedReq > 0 ? m.cost / m.pricedReq : null,
+          avgTokensPerRequest: m.requests > 0 ? Math.round(tokens / m.requests) : null,
+        };
+      }),
+  };
+}
+
+function addDays(date, n) {
+  const d = new Date(`${date}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + n);
+  return d.toISOString().slice(0, 10);
+}
+
+/** Render the comparison as aligned plain text. */
+export function renderText(cmp) {
+  if (!cmp) return 'No model usage in this window.';
+  const L = [];
+  L.push(`Model comparison — ${cmp.from} → ${cmp.to}`);
+  L.push('');
+  L.push('Model                          Requests   Tokens      Cost        $/req     tok/req   cache-hit');
+  L.push('-'.repeat(100));
+  for (const m of cmp.models.slice(0, 15)) {
+    const perReq = m.avgCostPerRequest != null ? usd(m.avgCostPerRequest) : 'n/a';
+    const cache = m.cacheHitPct != null ? `${m.cacheHitPct}%` : 'n/a';
+    L.push(
+      m.key.padEnd(30).slice(0, 30)
+      + String(m.requests.toLocaleString('en-US')).padStart(9)
+      + compact(m.tokens).padStart(10)
+      + (m.cost > 0 ? usd(m.cost).padStart(12) : 'n/a'.padStart(12))
+      + perReq.padStart(11)
+      + String(m.avgTokensPerRequest ?? 'n/a').padStart(10)
+      + cache.padStart(10),
+    );
+  }
+  L.push('');
+  L.push('Costs are estimates from the versioned price table where rates exist; "n/a" means unpriced — never $0.');
+  L.push('"cost per useful output" is not computable from local logs and is deliberately not shown.');
+  return L.join('\n');
+}