mcp-context-cost 0.1.0 → 0.3.0

package/dist/audit/run.js

@@ -0,0 +1,59 @@
+/**
+ * Audit orchestration: discover configs, measure each distinct server once,
+ * hand the results to `buildReport`.
+ *
+ * Kept apart from audit.ts so the arithmetic stays spawn-free and testable.
+ */
+import { homedir } from 'node:os';
+import { measureServer } from '../sweep/run.js';
+import { buildReport, serverKey } from './audit.js';
+import { configCandidates, loadConfigs } from './config.js';
+export function discover(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const candidates = opts.configPaths && opts.configPaths.length
+        ? opts.configPaths.map((path) => ({ client: 'explicit', path }))
+        : configCandidates({ home, cwd, platform: process.platform, appData: process.env.APPDATA });
+    return loadConfigs(candidates, cwd);
+}
+/** Measure every distinct stdio server across the given configs, once each. */
+export async function measureAll(configs, opts = {}) {
+    const unique = new Map();
+    for (const cfg of configs) {
+        for (const s of cfg.servers) {
+            if (s.transport !== 'stdio')
+                continue;
+            // Two clients pointing at the same argv are one measurement, not two.
+            if (!unique.has(serverKey(s)))
+                unique.set(serverKey(s), s);
+        }
+    }
+    const queue = [...unique.entries()];
+    const total = queue.length;
+    const measured = new Map();
+    let done = 0;
+    const worker = async () => {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            const [key, s] = next;
+            const m = await measureServer(s.name, s.command ?? '', {
+                argv: s.argv,
+                env: s.env,
+                timeoutMs: opts.timeoutMs ?? 60_000,
+                docker: opts.docker,
+                persist: false,
+            });
+            measured.set(key, m);
+            opts.onProgress?.(s.name, ++done, total);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(opts.concurrency ?? 3, total || 1)) }, worker));
+    return measured;
+}
+export async function runAudit(opts = {}) {
+    const configs = discover(opts);
+    const measured = await measureAll(configs, opts);
+    return buildReport(configs, measured, {
+        contextWindow: opts.contextWindow,
+        budget: opts.budget,
+    });
+}

package/dist/cli.js

@@ -2,9 +2,14 @@
 /**
  * mcp-context-cost CLI — the dispute drill as a command.
  *
- *   mcp-context-cost verify <measurement.json>   re-derive the number from the
+ *   mcp-context-cost audit [--budget N] [--json]      measure the servers in your own
+ *                                                MCP config; exit 1 if over budget
+ *   mcp-context-cost verify <measurement.json> [--json]   re-derive the number from the
  *                                                published capture; exit 1 on mismatch
+ *   mcp-context-cost verify --remote <url> [--json]   same, fetched from a measurement URL
  *   mcp-context-cost measure --name x --command "npx -y ..."   one-off measurement
+ *
+ * Exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error.
  */
 import { readFileSync } from 'node:fs';
 import { canonicalString, countTokens, sha256Hex } from './core/canonical.js';
@@ -26,14 +31,85 @@ export function verifyMeasurement(m) {
     return { ok: problems.length === 0, rederivedTokens: tokens, rederivedSha: sha, problems };
 }
 const [, , cmd, ...rest] = process.argv;
-if (cmd === 'verify') {
-    const path = rest.find((a) => !a.startsWith('--'));
-    if (!path) {
-        console.error('usage: mcp-context-cost verify <measurement.json>');
+if (cmd === 'audit') {
+    const argOf = (name) => {
+        const i = rest.indexOf(`--${name}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    const all = (name) => rest.flatMap((a, i) => (a === `--${name}` && rest[i + 1] ? [rest[i + 1]] : []));
+    const json = rest.includes('--json');
+    const numeric = (name) => {
+        const raw = argOf(name);
+        if (raw === undefined)
+            return undefined;
+        const v = Number(raw);
+        if (!Number.isFinite(v) || v <= 0) {
+            console.error(`--${name} must be a positive number, got '${raw}'`);
+            process.exit(2);
+        }
+        return v;
+    };
+    const budget = numeric('budget');
+    const { runAudit } = await import('./audit/run.js');
+    const { formatReport } = await import('./audit/audit.js');
+    const report = await runAudit({
+        configPaths: all('config'),
+        budget,
+        contextWindow: numeric('context'),
+        timeoutMs: numeric('timeout'),
+        concurrency: numeric('concurrency'),
+        docker: rest.includes('--docker'),
+        // Progress goes to stderr so `--json` stdout stays a single parseable object.
+        onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
+    });
+    if (report.configs.length === 0) {
+        const where = report.problems.length ? `\n${report.problems.map((p) => `  ${p}`).join('\n')}` : '';
+        if (json)
+            console.log(JSON.stringify(report));
+        else
+            console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf locations.${where}\n` +
+                `Point at one explicitly: mcp-context-cost audit --config <path/to/mcp.json>`);
+        process.exit(1);
+    }
+    console.log(json ? JSON.stringify(report) : formatReport(report));
+    process.exit(report.budget?.over ? 1 : 0);
+}
+else if (cmd === 'verify') {
+    const json = rest.includes('--json');
+    const remoteIdx = rest.indexOf('--remote');
+    const remoteUrl = remoteIdx >= 0 ? rest[remoteIdx + 1] : undefined;
+    const path = rest.find((a) => !a.startsWith('--') && a !== remoteUrl);
+    if (!remoteUrl && !path) {
+        console.error('usage: mcp-context-cost verify <measurement.json> [--json]');
+        console.error('       mcp-context-cost verify --remote <url> [--json]');
         process.exit(2);
     }
-    const m = JSON.parse(readFileSync(path, 'utf8'));
+    let raw;
+    if (remoteUrl) {
+        try {
+            const res = await fetch(remoteUrl, { signal: AbortSignal.timeout(15_000) });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            raw = await res.text();
+        }
+        catch (e) {
+            const problem = `failed to fetch ${remoteUrl}: ${e.message}`;
+            if (json)
+                console.log(JSON.stringify({ ok: false, rederivedTokens: null, rederivedSha: null, problems: [problem] }));
+            else
+                console.error(problem);
+            process.exit(1);
+        }
+    }
+    else {
+        raw = readFileSync(path, 'utf8');
+    }
+    const m = JSON.parse(raw);
     const r = verifyMeasurement(m);
+    if (json) {
+        console.log(JSON.stringify({ serverName: m.serverName, ...r, badge: r.ok ? toBadge(m) : undefined }));
+        process.exit(r.ok ? 0 : 1);
+    }
     if (r.ok) {
         console.log(`OK ${m.serverName}: ${r.rederivedTokens} tokens (${m.encoding}, methodology ${m.methodologyVersion}) — capture, hash, and count all agree`);
         console.log(`badge: ${JSON.stringify(toBadge(m))}`);
@@ -73,6 +149,10 @@ else if (cmd !== undefined && cmd !== '--help' && cmd !== '-h') {
 }
 else {
     console.log('mcp-context-cost — reproducible context-cost measurement for MCP servers');
-    console.log('  verify <measurement.json>    re-derive tokens+sha from the published capture');
+    console.log('  audit [--config <path>] [--budget N]  measure the servers in your own MCP config');
+    console.log('        [--json] [--context N] [--timeout ms] [--concurrency N] [--docker]');
+    console.log('  verify <measurement.json> [--json]    re-derive tokens+sha from the published capture');
+    console.log('  verify --remote <url> [--json]        same, fetched from a measurement URL');
     console.log('  measure --name x --command "npx -y <server>"   run a one-off measurement');
+    console.log('exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error');
 }

package/dist/core/bands.d.ts

@@ -5,3 +5,8 @@
  */
 export declare function bandColor(totalTokens: number): string;
 export declare const UNKNOWN_COLOR = "lightgrey";
+/** Human-readable name + range for each band, shared by every generated view. */
+export declare const BAND_META: Record<string, {
+    label: string;
+    range: string;
+}>;

package/dist/core/bands.js

@@ -15,3 +15,11 @@ export function bandColor(totalTokens) {
     return 'red';
 }
 export const UNKNOWN_COLOR = 'lightgrey';
+/** Human-readable name + range for each band, shared by every generated view. */
+export const BAND_META = {
+    brightgreen: { label: 'lean', range: '< 1K' },
+    green: { label: 'light', range: '1–5K' },
+    yellow: { label: 'moderate', range: '5–15K' },
+    orange: { label: 'heavy', range: '15–30K' },
+    red: { label: 'very heavy', range: '≥ 30K' },
+};

package/dist/core/canonical.js

@@ -44,7 +44,9 @@ export function measureTools(tools, meta) {
         toolCount: tools.length,
         tools: perTool,
         canonicalSha256: sha256Hex(canonical),
-        rawToolsCapture: tools,
+        // Snapshot from the canonical string, not the live `tools` reference — the whole
+        // point of a capture is that it can't change out from under its own hash later.
+        rawToolsCapture: JSON.parse(canonical),
         measuredAt: meta.measuredAt ?? new Date().toISOString(),
         serverName: meta.serverName,
         serverVersion: meta.serverVersion,

package/dist/core/divergence.d.ts

@@ -0,0 +1,71 @@
+/** Method identifier, versioned independently of the o200k methodology. */
+export declare const DIVERGENCE_METHOD = "tools-delta/v1";
+/** The three fields an Anthropic tool definition carries — nothing else. */
+export declare const ANTHROPIC_TOOL_FIELDS: readonly ['name', 'description', 'input_schema'];
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: unknown;
+}
+export interface DivergenceRow {
+    /** o200k count of the full canonical capture — the published headline. */
+    o200kFull: number;
+    /** o200k count of the name/description/input_schema projection. */
+    o200kMapped: number;
+    /**
+     * Claude tokens the projection adds to a request: count_tokens(with tools)
+     * minus count_tokens(same request, no tools). Includes the one-time tool
+     * framework overhead, because attaching any server pays it once.
+     */
+    claudeDelta: number;
+    toolCount: number;
+    /**
+     * canonicalSha256 of the measurement this row was computed from. A re-sweep
+     * changes the hash, which marks the row stale instead of silently mismatched.
+     */
+    capturedSha256: string;
+    /** Set when count_tokens rejected the projection; no numbers are published. */
+    error?: string;
+}
+export interface DivergenceRun {
+    method: string;
+    /** Exact model id the counts are pinned to — Anthropic's tokenizer drifts. */
+    model: string;
+    /** UTC day the counts were taken (YYYY-MM-DD). */
+    measuredAt: string;
+    /** count_tokens for the probe request with no tools at all. */
+    baselineTokens: number;
+    /**
+     * A single minimal tool. Its delta is an upper bound on the fixed framework
+     * overhead included in every `claudeDelta` (the probe tool itself costs > 0,
+     * so the true overhead is strictly less).
+     */
+    probeDelta: number;
+    servers: Record<string, DivergenceRow>;
+}
+/**
+ * Project a `tools/list` capture onto the Anthropic tool shape. Tools without a
+ * usable name are dropped rather than renamed — a fabricated name would change
+ * the token count being compared.
+ */
+export declare function toAnthropicTools(raw: unknown[]): AnthropicTool[];
+/** o200k count of the projection — the same tokenizer as the headline number. */
+export declare function mappedTokens(raw: unknown[]): number;
+/**
+ * Share of the headline number that is MCP-only metadata (cause 1 above).
+ * Returns null when there is nothing to divide by.
+ */
+export declare function fieldSelectionShare(row: DivergenceRow): number | null;
+/**
+ * Claude tokens per o200k token of the headline — the ratio a reader wants when
+ * asking "does the badge over- or under-state what this costs me?".
+ */
+export declare function claudeRatio(row: DivergenceRow): number | null;
+/**
+ * A row is only reportable if it carries numbers and was computed from the
+ * capture currently on disk. Stale rows are hidden rather than shown with a
+ * caveat: a wrong number next to a fresh badge is worse than no number.
+ */
+export declare function isCurrent(row: DivergenceRow | undefined, canonicalSha256: string | null): row is DivergenceRow;
+/** Parse results/divergence.json; anything malformed yields null, never throws. */
+export declare function parseDivergence(text: string): DivergenceRun | null;

package/dist/core/divergence.js

@@ -0,0 +1,103 @@
+/**
+ * Claude divergence — the gap between the published o200k index and what a
+ * server's tools actually cost in an Anthropic request.
+ *
+ * The gap has two independent causes, and reporting them as one number hides
+ * the larger of the two:
+ *
+ * 1. **Field selection.** An Anthropic tool definition carries exactly `name`,
+ *    `description`, and `input_schema`. A `tools/list` result may additionally
+ *    carry `title`, `annotations`, `outputSchema`, `execution`, `icons` — real
+ *    bytes the server ships, counted by the canonical form, but never present
+ *    in the `tools` array a client sends to the API. For some servers this is
+ *    the majority of the payload.
+ * 2. **Tokenizer and framing.** o200k_base vs Anthropic's tokenizer, plus the
+ *    fixed framework overhead the API adds once when any tool is present.
+ *
+ * So the divergence is published as a decomposition: the headline o200k count,
+ * the o200k count of the projection (isolating cause 1), and Claude's own count
+ * of that same projection (isolating cause 2).
+ */
+import { countTokens } from './canonical.js';
+/** Method identifier, versioned independently of the o200k methodology. */
+export const DIVERGENCE_METHOD = 'tools-delta/v1';
+/** The three fields an Anthropic tool definition carries — nothing else. */
+export const ANTHROPIC_TOOL_FIELDS = ['name', 'description', 'input_schema'];
+/**
+ * Project a `tools/list` capture onto the Anthropic tool shape. Tools without a
+ * usable name are dropped rather than renamed — a fabricated name would change
+ * the token count being compared.
+ */
+export function toAnthropicTools(raw) {
+    const out = [];
+    for (const t of raw) {
+        const tool = (t ?? {});
+        if (typeof tool.name !== 'string' || tool.name === '')
+            continue;
+        out.push({
+            name: tool.name,
+            description: typeof tool.description === 'string' ? tool.description : '',
+            // An absent schema is sent as the empty object schema, which is what the
+            // API requires; every tool in the current sweep supplies one.
+            input_schema: tool.inputSchema ?? { type: 'object', properties: {} },
+        });
+    }
+    return out;
+}
+/** o200k count of the projection — the same tokenizer as the headline number. */
+export function mappedTokens(raw) {
+    return countTokens(JSON.stringify(toAnthropicTools(raw)));
+}
+/**
+ * Share of the headline number that is MCP-only metadata (cause 1 above).
+ * Returns null when there is nothing to divide by.
+ */
+export function fieldSelectionShare(row) {
+    if (row.o200kFull <= 0)
+        return null;
+    return (row.o200kFull - row.o200kMapped) / row.o200kFull;
+}
+/**
+ * Claude tokens per o200k token of the headline — the ratio a reader wants when
+ * asking "does the badge over- or under-state what this costs me?".
+ */
+export function claudeRatio(row) {
+    if (row.o200kFull <= 0 || typeof row.claudeDelta !== 'number')
+        return null;
+    return row.claudeDelta / row.o200kFull;
+}
+/**
+ * A row is only reportable if it carries numbers and was computed from the
+ * capture currently on disk. Stale rows are hidden rather than shown with a
+ * caveat: a wrong number next to a fresh badge is worse than no number.
+ */
+export function isCurrent(row, canonicalSha256) {
+    if (!row || row.error)
+        return false;
+    if (typeof row.claudeDelta !== 'number')
+        return false;
+    return !!canonicalSha256 && row.capturedSha256 === canonicalSha256;
+}
+/** Parse results/divergence.json; anything malformed yields null, never throws. */
+export function parseDivergence(text) {
+    let run;
+    try {
+        run = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const r = run;
+    if (!r || typeof r.model !== 'string' || typeof r.measuredAt !== 'string')
+        return null;
+    if (!r.servers || typeof r.servers !== 'object')
+        return null;
+    return {
+        method: typeof r.method === 'string' ? r.method : DIVERGENCE_METHOD,
+        model: r.model,
+        measuredAt: r.measuredAt,
+        baselineTokens: typeof r.baselineTokens === 'number' ? r.baselineTokens : 0,
+        probeDelta: typeof r.probeDelta === 'number' ? r.probeDelta : 0,
+        servers: r.servers,
+    };
+}

package/dist/core/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './canonical.js';
+export * from './divergence.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/index.js

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './canonical.js';
+export * from './divergence.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/sweep/dashboard.js

@@ -6,17 +6,15 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { parse } from 'yaml';
-import { bandColor } from '../core/bands.js';
+import { bandColor, BAND_META } from '../core/bands.js';
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-const BAND_META = {
-    brightgreen: { label: 'lean', range: '< 1K' },
-    green: { label: 'light', range: '1–5K' },
-    yellow: { label: 'moderate', range: '5–15K' },
-    orange: { label: 'heavy', range: '15–30K' },
-    red: { label: 'very heavy', range: '≥ 30K' },
-};
 export function generateDashboard(root = process.cwd()) {
     const doc = parse(readFileSync(join(root, 'servers.yaml'), 'utf8'));
+    const divergencePath = join(root, 'results', 'divergence.json');
+    const divergence = existsSync(divergencePath)
+        ? JSON.parse(readFileSync(divergencePath, 'utf8'))
+        : {};
+    const dSrv = divergence.servers ?? {};
     const rows = doc.servers.map((entry) => {
         const p = join(root, 'results', entry.name, 'measurement.json');
         return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
@@ -39,12 +37,15 @@ export function generateDashboard(root = process.cwd()) {
         const meta = BAND_META[band];
         const largest = [...m.tools].sort((a, b) => b.tokens - a.tokens)[0];
         const pct = Math.max(1.2, (t / max) * 100);
-        return `<div class="row" tabindex="0" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok) · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
+        const div = dSrv[r.entry.name];
+        const claudeTip = div ? ` · in a Claude request: ${fmt(div.claudeDelta)} tok` : '';
+        // The whole row is the link to the server's detail page (docs/servers/).
+        return `<a class="row" href="servers/${encodeURIComponent(r.entry.name)}.html" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok)${claudeTip} · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
   <span class="rank">${i + 1}</span>
   <span class="name">${esc(r.entry.name)}</span>
   <span class="track"><span class="bar" style="width:${pct.toFixed(1)}%"></span></span>
   <span class="val"><span class="dot dot-${band}" aria-hidden="true"></span>${fmt(t)}<span class="bandname">${meta.label}</span></span>
-</div>`;
+</a>`;
     })
         .join('\n');
     const failRows = failed
@@ -57,7 +58,8 @@ export function generateDashboard(root = process.cwd()) {
     const tableRows = measured
         .map((r, i) => {
         const m = r.m;
-        return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</td><td class="num">${esc(m.toolCount)}</td><td>${esc(BAND_META[bandColor(m.totalTokens)].label)}</td><td>${esc(r.entry.category)}</td></tr>`;
+        const div = dSrv[r.entry.name];
+        return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</td><td class="num">${div ? fmt(div.claudeDelta) : '—'}</td><td class="num">${esc(m.toolCount)}</td><td>${esc(BAND_META[bandColor(m.totalTokens)].label)}</td><td>${esc(r.entry.category)}</td></tr>`;
     })
         .join('\n');
     const specimens = [measured[measured.length - 1], measured[0]]
@@ -115,8 +117,9 @@ export function generateDashboard(root = process.cwd()) {
   .stat .l { font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
 
   .board { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; }
-  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; }
+  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; color: inherit; text-decoration: none; }
   .row:hover, .row:focus-visible { background: var(--accent-soft); }
+  .row:hover .name, .row:focus-visible .name { text-decoration: underline; }
   .rank { font-family: ui-monospace, Menlo, monospace; font-size: 11px; color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
   .name { font-size: 0.86rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .track { background: var(--track); border-radius: 3px; height: 12px; overflow: hidden; }
@@ -169,7 +172,7 @@ export function generateDashboard(root = process.cwd()) {
   </div>
 
   <h2>Leaderboard</h2>
-  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes. Hover or focus a row for detail.</p>
+  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes — the wire payload. What a <em>Claude request</em> actually carries can differ sharply (github: 54,422 on the wire, ${dSrv['github'] ? fmt(dSrv['github'].claudeDelta) : '…'} in a request — 80% of its schema bytes are fields no Anthropic request sends). Hover a row for both numbers; <a href="METHODOLOGY.html#claude-divergence">method</a>.</p>
   <div class="board">
 ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.</p>'}
   </div>
@@ -195,7 +198,7 @@ ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.
 
   <details><summary>Full data table</summary>
   <div class="tablewrap" style="margin-top:10px"><table>
-    <thead><tr><th>#</th><th>server</th><th>tokens</th><th>tools</th><th>band</th><th>category</th></tr></thead>
+    <thead><tr><th>#</th><th>server</th><th>tokens (o200k)</th><th>claude req</th><th>tools</th><th>band</th><th>category</th></tr></thead>
     <tbody>${tableRows}</tbody>
   </table></div>
   </details>

package/dist/sweep/history.d.ts

@@ -0,0 +1,30 @@
+import type { Measurement } from '../core/types.js';
+export interface HistoryRow {
+    /** UTC calendar day of the measurement (YYYY-MM-DD). */
+    date: string;
+    server: string;
+    tokens: number;
+    toolCount: number;
+    /** 'measured' or 'dynamic' — dynamic means the tool set moved between captures. */
+    status: string;
+}
+export declare const HISTORY_HEADER = "date,server,tokens,toolCount,status";
+/** Parse history.csv text; malformed or non-numeric rows are dropped, not thrown. */
+export declare function parseHistory(text: string): HistoryRow[];
+export declare function formatHistory(rows: HistoryRow[]): string;
+/** Upsert one row by (date, server) — the newest write for a day wins. */
+export declare function upsert(rows: HistoryRow[], row: HistoryRow): HistoryRow[];
+/**
+ * A measurement contributes a row only if it produced a number: failures and
+ * auth walls are recorded in the leaderboard's "not measured" section, and
+ * writing them here as zeros would fabricate a drop to zero in the series.
+ */
+export declare function rowFor(server: string, m: Measurement): HistoryRow | null;
+/**
+ * Fold every results/<server>/measurement.json into results/history.csv.
+ * Idempotent: running twice over the same results is a no-op.
+ */
+export declare function appendHistory(root?: string): {
+    rows: number;
+    added: number;
+};

package/dist/sweep/history.js

@@ -0,0 +1,120 @@
+/**
+ * results/history.csv — the time series behind the leaderboard snapshot.
+ *
+ * One row per (date, server): a server's tokens on the day it was measured.
+ * Every sweep upserts by (date, server), so re-running a sweep on the same day
+ * corrects that day's row instead of appending a duplicate. Rows for earlier
+ * dates are never rewritten — history is append-only in practice.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const HISTORY_HEADER = 'date,server,tokens,toolCount,status';
+function csvCell(s) {
+    const v = String(s ?? '');
+    return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}
+/** Split one CSV line, honouring double-quoted fields. */
+function splitCsvLine(line) {
+    const out = [];
+    let cur = '';
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (quoted) {
+            if (c === '"' && line[i + 1] === '"') {
+                cur += '"';
+                i++;
+            }
+            else if (c === '"')
+                quoted = false;
+            else
+                cur += c;
+        }
+        else if (c === '"')
+            quoted = true;
+        else if (c === ',') {
+            out.push(cur);
+            cur = '';
+        }
+        else
+            cur += c;
+    }
+    out.push(cur);
+    return out;
+}
+/** Parse history.csv text; malformed or non-numeric rows are dropped, not thrown. */
+export function parseHistory(text) {
+    const rows = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim() || line.startsWith('date,'))
+            continue;
+        const [date, server, tokens, toolCount, status] = splitCsvLine(line);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date ?? '') || !server)
+            continue;
+        if (!/^\d+$/.test(tokens ?? '') || !/^\d+$/.test(toolCount ?? ''))
+            continue;
+        rows.push({ date, server, tokens: Number(tokens), toolCount: Number(toolCount), status: status ?? '' });
+    }
+    return rows;
+}
+export function formatHistory(rows) {
+    const sorted = [...rows].sort((a, b) => a.date.localeCompare(b.date) || a.server.localeCompare(b.server));
+    const lines = sorted.map((r) => [csvCell(r.date), csvCell(r.server), r.tokens, r.toolCount, csvCell(r.status)].join(','));
+    return [HISTORY_HEADER, ...lines].join('\n') + '\n';
+}
+/** Upsert one row by (date, server) — the newest write for a day wins. */
+export function upsert(rows, row) {
+    const i = rows.findIndex((r) => r.date === row.date && r.server === row.server);
+    if (i < 0)
+        return [...rows, row];
+    const next = [...rows];
+    next[i] = row;
+    return next;
+}
+/**
+ * A measurement contributes a row only if it produced a number: failures and
+ * auth walls are recorded in the leaderboard's "not measured" section, and
+ * writing them here as zeros would fabricate a drop to zero in the series.
+ */
+export function rowFor(server, m) {
+    if (m.status !== 'measured' && m.status !== 'dynamic')
+        return null;
+    if (typeof m.totalTokens !== 'number' || typeof m.toolCount !== 'number')
+        return null;
+    const date = String(m.measuredAt ?? '').slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+        return null;
+    return { date, server, tokens: m.totalTokens, toolCount: m.toolCount, status: m.status };
+}
+/**
+ * Fold every results/<server>/measurement.json into results/history.csv.
+ * Idempotent: running twice over the same results is a no-op.
+ */
+export function appendHistory(root = process.cwd()) {
+    const resultsDir = join(root, 'results');
+    const path = join(resultsDir, 'history.csv');
+    const existing = existsSync(path) ? parseHistory(readFileSync(path, 'utf8')) : [];
+    let rows = existing;
+    if (!existsSync(resultsDir))
+        return { rows: 0, added: 0 };
+    for (const server of readdirSync(resultsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort()) {
+        const file = join(resultsDir, server, 'measurement.json');
+        if (!existsSync(file))
+            continue;
+        let m;
+        try {
+            m = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            continue; // a half-written measurement should not abort the whole fold
+        }
+        const row = rowFor(server, m);
+        if (row)
+            rows = upsert(rows, row);
+    }
+    writeFileSync(path, formatHistory(rows));
+    return { rows: rows.length, added: rows.length - existing.length };
+}

package/dist/sweep/regen.js

@@ -1,7 +1,14 @@
-/** Regenerate leaderboard + dashboard from existing results/: npx tsx src/sweep/regen.ts */
+/** Regenerate leaderboard + history + server pages from results/: npx tsx src/sweep/regen.ts */
 import { readFileSync } from 'node:fs';
 import { parse } from 'yaml';
 import { writeLeaderboard, percentiles } from './report.js';
+import { appendHistory } from './history.js';
+import { writeServerPages } from './server-pages.js';
 const doc = parse(readFileSync('servers.yaml', 'utf8'));
 writeLeaderboard(doc.servers);
+// History first: the server pages read history.csv for their over-time table.
+const h = appendHistory();
+const p = writeServerPages(doc.servers);
 console.log('leaderboard:', JSON.stringify(percentiles(doc.servers)));
+console.log(`history: ${h.rows} rows (${h.added >= 0 ? '+' : ''}${h.added})`);
+console.log(`server pages: ${p.pages}`);