@zenithfoundry/slm-gate 1.2.1

package/dist/config.js

@@ -0,0 +1,255 @@
+import { config } from 'dotenv';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { z } from 'zod';
+import { ramPresets } from './hardware.js';
+import { resolveHomeDir } from './home-dir.js';
+import { getSubscriptionPlan, getValidPlanKeys, isValidPlanKey } from './pricing/plans.js';
+import { isEntryPoint } from './utils/entry-point.js';
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+const ROOT_DIR = path.resolve(dirname, '..');
+// Settings and data (.env, output/): the checkout for a git clone, ~/.slm-gate for an npm install,
+// or SLM_GATE_HOME (src/home-dir.ts).
+const HOME_DIR = resolveHomeDir({ installDir: ROOT_DIR, env: process.env, userHome: os.homedir() });
+const OUTPUT_DIR = path.join(HOME_DIR, 'output');
+// Load THIS INSTALL'S .env, from HOME_DIR. Deliberately not cwd-relative:
+// MCP hosts spawn the gate with cwd set to whatever workspace the user has open, so a
+// bare dotenv.config() silently found nothing and left LANGFUSE_*/PROVIDER undefined
+// while LEDGER_PATH's module-relative default still resolved — a gate that looked
+// healthy and shipped no telemetry.
+//
+// The caller's cwd .env is deliberately NOT loaded as a fallback: it would pull an
+// unrelated project's PROVIDER, CLOUD_API_KEY and CLOUD_MODEL into this process.
+// Host-supplied process.env still wins, because dotenv never overrides an existing var.
+const envFile = config({ path: path.join(HOME_DIR, '.env') });
+// Zod pre-processors for env strings
+const parseInteger = (fallback) => z.string().optional().transform(v => v ? parseInt(v, 10) : fallback);
+const parseFloatNumber = (fallback) => z.string().optional().transform(v => v ? parseFloat(v) : fallback);
+const parseBoolean = (fallback) => z.string().optional().transform(v => {
+    if (!v)
+        return fallback;
+    return v.toLowerCase() === 'on' || v.toLowerCase() === 'true' || v === '1';
+});
+const parseNumberArray = (fallback) => z.string().optional().transform(v => v ? v.split(',').map(n => parseInt(n.trim(), 10)) : fallback);
+const parseDownstreamMcp = () => z.string().optional().transform(v => {
+    if (!v)
+        return null;
+    try {
+        const parsed = JSON.parse(v);
+        if (parsed.command) {
+            return { command: parsed.command, args: parsed.args, env: parsed.env };
+        }
+        if (parsed.url) {
+            return { url: parsed.url, headers: parsed.headers };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+});
+const envSchema = z.object({
+    // STEP 1
+    SLM_PROVIDER: z.enum(['ollama', 'openai']).default('ollama'),
+    OLLAMA_HOST: z.string().default('http://localhost:11434'),
+    OLLAMA_KEEP_ALIVE: z.string().default('12h'),
+    SLM_BRAIN_MODEL: z.string().optional(), // resolved below
+    SLM_GATE_MODEL: z.string().optional(), // resolved below
+    SLM_GATE_TESTING_MODEL: z.string().optional(), // resolved below, used for benchmark harness & test runs
+    NUM_CTX: parseInteger(8192),
+    TEMPERATURE: parseFloatNumber(0),
+    SLM_TIMEOUT_MS: parseInteger(120000),
+    SELF_CONSISTENCY_K: parseInteger(3),
+    SELF_CONSISTENCY_TEMP: parseFloatNumber(0.7),
+    // STEP 2
+    STRICTNESS_LEVELS: parseNumberArray([0, 1, 2, 3, 4, 5]),
+    HEADLINE_STRICTNESS: parseInteger(4),
+    // STEP 3
+    CLOUD_API_STYLE: z.enum(['openai', 'anthropic']).default('openai'),
+    CLOUD_BASE_URL: z.string().optional(),
+    CLOUD_API_KEY: z.string().optional(),
+    CLOUD_MODEL: z.string().optional(),
+    // Semantic CACHE
+    SEMCACHE: parseBoolean(false),
+    SEMCACHE_THRESHOLD: parseFloatNumber(0.95),
+    EMBED_MODEL: z.string().default('nomic-embed-text'),
+    // STEP 4
+    LLM_GATE_PORT: parseInteger(8787),
+    // When a coding tool starts slm-gate's MCP server, also start the model gate (in the background) if it
+    // is not running, and keep it running while tools are open. Off = you start it yourself (`slm-gate start`).
+    LLM_GATE_AUTOSTART: parseBoolean(true),
+    // Distil large command, search and listing tool results before requests leave the machine. Off makes
+    // the gate a plain pass-through; ongoing conversations then resend their distilled history in full
+    // once (one prompt-cache miss, and Claude drops its earlier thinking once).
+    LLM_GATE_DISTILL: parseBoolean(true),
+    // Offer the first request of a conversation to the local model (Step A). Off sends every request on.
+    LLM_GATE_LOCAL_FIRST: parseBoolean(true),
+    // How long a first request may wait for a local answer before it goes on; the attempt is then cancelled.
+    // A warm local answer (3 samples) measured 3.8 s; deciding a coding task is not eligible takes ~0.25 s.
+    LOCAL_ATTEMPT_BUDGET_MS: parseInteger(6000),
+    // Where the model gate forwards each wire format. Built in; override only when your requests
+    // must already go through a company gateway. The tool's own login is forwarded either way.
+    UPSTREAM_ANTHROPIC_URL: z.string().url().default('https://api.anthropic.com'),
+    UPSTREAM_OPENAI_URL: z.string().url().default('https://api.openai.com/v1'),
+    UPSTREAM_CHATGPT_URL: z.string().url().default('https://chatgpt.com/backend-api/codex'),
+    UPSTREAM_GEMINI_URL: z.string().url().default('https://generativelanguage.googleapis.com'),
+    DOWNSTREAM_MCP: parseDownstreamMcp(),
+    MCP_GATE_TRANSPORT: z.enum(['stdio', 'http']).default('stdio'),
+    MCP_GATE_PORT: parseInteger(8788),
+    // STEP 5
+    PROVIDER: z.enum(['gemini', 'claude', 'chatgpt']).optional(),
+    LEDGER_PATH: z.string().default(path.join(OUTPUT_DIR, 'ledger.sqlite')),
+    LANGFUSE_PUBLIC_KEY: z.string().optional(),
+    LANGFUSE_SECRET_KEY: z.string().optional(),
+    LANGFUSE_HOST: z.string().optional(),
+    // Langfuse environment dimension. Keeps benchmark/harness runs out of the real
+    // traffic view — the dashboard's Env selector filters on this. Langfuse requires
+    // lowercase alphanumeric plus - and _, and forbids the 'langfuse' prefix.
+    // Not 'default': that is where any other writer to the same Langfuse project lands
+    // when it sets no environment, so the gate's traffic would be mixed with theirs.
+    LANGFUSE_ENVIRONMENT: z.string()
+        .regex(/^(?!langfuse)[a-z0-9_-]+$/, "LANGFUSE_ENVIRONMENT must be lowercase alphanumeric (- and _ allowed) and must not start with 'langfuse'")
+        .default('slm-gate'),
+    SUBSCRIPTION_PLAN: z.string().optional(),
+    PLAN_CLAUDE: z.string().optional(),
+    PLAN_CHATGPT: z.string().optional(),
+    PLAN_GEMINI: z.string().optional(),
+    // STEP 6
+    RESOLVER_CLOUD_TIER: parseBoolean(false),
+    RESOLVER_CLOUD_BUDGET_USD: parseFloatNumber(0),
+    PROMPT_VERSION: z.string().default('v1'),
+    // The presets in src/hardware.ts ramPresets. Every value recommendPreset() can print must be accepted
+    // here, or following doctor's advice stops slm-gate from starting. slm-gate needs 16 GB of RAM or more.
+    RAM_PRESET: z.enum(['ram-16', 'ram-24', 'ram-32', 'ram-48', 'ram-64', 'ram-128', 'custom']).default('custom'),
+    TLS_ADAPTER: parseBoolean(false),
+    DISTILL_PRESERVE_PATH: z.string().optional().transform(v => v?.trim() || null),
+    DISTILL_PRESERVE_MODE: z.enum(['extend', 'replace']).default('extend'),
+    DISTILL_SKILLS: parseBoolean(false),
+    DISTILL_ADAPTIVE: parseBoolean(false),
+    DISTILL_ADAPTIVE_THRESHOLD: parseFloatNumber(0.86),
+    DISTILL_ADAPTIVE_EXPLORE_RATE: parseFloatNumber(0.15),
+    DISTILL_FEEDBACK_RETENTION_DAYS: parseInteger(180),
+    DISTILL_FEEDBACK_MAX_ROWS: parseInteger(5000),
+    DISTILL_MAX_TOKENS: parseInteger(2000),
+    DISTILL_MIN_TOKENS: parseInteger(500),
+    // How long the model gate may hold one request to distil its new tool results. Past it, a result is
+    // sent (and kept, forever) as the original. Warm local-model runs take ~0.5 s per ~600 words.
+    DISTILL_BUDGET_MS: parseInteger(3000),
+    KEEP_RECENT_TOOL_TURNS: parseInteger(2),
+    ELISION_MAX_ENTRIES: parseInteger(5000),
+    ELISION_RETENTION_DAYS: parseInteger(180),
+    ELISION_MAX_MB: parseInteger(500),
+    // How many days of data your Langfuse plan keeps (Hobby: 30). Only the dashboard text reads it: the
+    // cards cover this rolling window, while the local ledger keeps everything.
+    LANGFUSE_RETENTION_DAYS: parseInteger(30),
+    // ROUTING TUNE
+    ROUTING_TUNE: parseBoolean(false),
+    ROUTING_TUNE_WINDOW: parseInteger(20),
+    ROUTING_TUNE_MIN_SAMPLES: parseInteger(8),
+    ROUTING_TUNE_THRESHOLD: parseFloatNumber(0.5),
+    ROUTING_TUNE_EXPLORE_RATE: parseFloatNumber(0.15),
+});
+// A variable that is present but blank means "unset". dotenv and MCP-host env blocks both
+// deliver `LEDGER_PATH=` (as shipped in every .env template) as '', and zod's .default() only
+// fires on undefined — so a blank value used to defeat the absolute default and leave a
+// cwd-relative './output/ledger.sqlite', which ENOENTs when the host's cwd does not exist
+// (Claude Desktop). Dropping empties here fixes that for every variable in one place.
+const envInput = Object.fromEntries(Object.entries(process.env).filter(([, value]) => value !== ''));
+/**
+ * Every environment variable slm-gate's configuration reads. The automatically started model gate is
+ * launched without these, so it takes its settings only from slm-gate's own .env — never from the MCP env
+ * block of whichever coding tool happened to start it (src/setup/model-gate.ts).
+ */
+export const CONFIG_ENV_KEYS = Object.keys(envSchema.shape);
+const parsedEnv = envSchema.parse(envInput);
+const preset = ramPresets[parsedEnv.RAM_PRESET] || ramPresets['custom'];
+const resolvePlan = (provider) => {
+    // 1. PLAN_<P>
+    const planProviderKey = `PLAN_${provider.toUpperCase()}`;
+    let planKey = parsedEnv[planProviderKey];
+    // 2. SUBSCRIPTION_PLAN
+    if (!planKey && parsedEnv.SUBSCRIPTION_PLAN) {
+        if (parsedEnv.SUBSCRIPTION_PLAN.startsWith(provider)) {
+            planKey = parsedEnv.SUBSCRIPTION_PLAN;
+        }
+    }
+    // 3. Default
+    if (!planKey) {
+        if (provider === 'claude')
+            planKey = 'claude-pro';
+        else if (provider === 'chatgpt')
+            planKey = 'chatgpt-plus';
+        else if (provider === 'gemini')
+            planKey = 'gemini-pro';
+    }
+    if (planKey && !isValidPlanKey(planKey)) {
+        throw new Error(`Invalid plan key '${planKey}' for ${provider}. Valid keys: ${getValidPlanKeys().join(', ')}`);
+    }
+    const resolved = getSubscriptionPlan(planKey);
+    return {
+        windowMinutes: resolved.windowMinutes,
+        source: resolved.source,
+        plan: planKey
+    };
+};
+const claudePlan = resolvePlan('claude');
+const chatgptPlan = resolvePlan('chatgpt');
+const geminiPlan = resolvePlan('gemini');
+console.error(`[config] claude plan: ${claudePlan.plan} (windowMinutes: ${claudePlan.windowMinutes})`);
+console.error(`[config] chatgpt plan: ${chatgptPlan.plan} (windowMinutes: ${chatgptPlan.windowMinutes})`);
+console.error(`[config] gemini plan: ${geminiPlan.plan} (windowMinutes: ${geminiPlan.windowMinutes})`);
+export const CONFIG = Object.freeze({
+    ...parsedEnv,
+    ROOT_DIR,
+    HOME_DIR,
+    OUTPUT_DIR,
+    SLM_BRAIN_MODEL: parsedEnv.SLM_BRAIN_MODEL || preset.brain,
+    SLM_GATE_MODEL: parsedEnv.SLM_GATE_MODEL || preset.gate,
+    SLM_GATE_TESTING_MODEL: parsedEnv.SLM_GATE_TESTING_MODEL || parsedEnv.SLM_GATE_MODEL || preset.gate,
+    // Where every session looks for, and starts, the one shared model gate: LLM_GATE_PORT as slm-gate's own
+    // .env sets it. LLM_GATE_PORT above prefers the process environment, so a value in one coding tool's MCP
+    // env block (or the shell) would send that session to another port, where it would start a second gate.
+    MODEL_GATE_PORT: envSchema.shape.LLM_GATE_PORT.parse(envFile.parsed?.LLM_GATE_PORT || undefined),
+    RESOLVED_PLAN_CLAUDE: claudePlan,
+    RESOLVED_PLAN_CHATGPT: chatgptPlan,
+    RESOLVED_PLAN_GEMINI: geminiPlan,
+});
+/**
+ * Validates that specific keys exist and are non-empty. Throws actionable errors if missing.
+ * Called right before an operation that requires them, NOT on module boot.
+ */
+export function requireKeys(keys) {
+    const missing = keys.filter(k => !CONFIG[k]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required configuration for this operation: ${missing.join(', ')}. Please update your .env file.`);
+    }
+}
+// Config test script executed via `pnpm run config`
+if (isEntryPoint(import.meta.url)) {
+    console.log('=== SMALL-LANGUAGE-MODEL-GATE CONFIGURATION ===');
+    const redactedConfig = { ...CONFIG };
+    if (redactedConfig.CLOUD_API_KEY)
+        redactedConfig.CLOUD_API_KEY = '<SET>';
+    else
+        redactedConfig.CLOUD_API_KEY = '<UNSET>';
+    if (redactedConfig.LANGFUSE_SECRET_KEY)
+        redactedConfig.LANGFUSE_SECRET_KEY = '<SET>';
+    else
+        redactedConfig.LANGFUSE_SECRET_KEY = '<UNSET>';
+    if (redactedConfig.LANGFUSE_PUBLIC_KEY)
+        redactedConfig.LANGFUSE_PUBLIC_KEY = '<SET>';
+    else
+        redactedConfig.LANGFUSE_PUBLIC_KEY = '<UNSET>';
+    console.log(JSON.stringify(redactedConfig, null, 2));
+    console.log('\n--- Summary ---');
+    console.log(`brain: ${CONFIG.SLM_BRAIN_MODEL} | gate: ${CONFIG.SLM_GATE_MODEL} | test: ${CONFIG.SLM_GATE_TESTING_MODEL}`);
+    const downstream = CONFIG.DOWNSTREAM_MCP ? (CONFIG.DOWNSTREAM_MCP.command ? `command: ${CONFIG.DOWNSTREAM_MCP.command}` : `url: ${CONFIG.DOWNSTREAM_MCP.url}`) : 'standalone';
+    console.log(`downstream: ${downstream}`);
+    const sinks = ['sqlite'];
+    if (CONFIG.LANGFUSE_PUBLIC_KEY && CONFIG.LANGFUSE_SECRET_KEY && CONFIG.LANGFUSE_HOST) {
+        sinks.push('langfuse');
+    }
+    console.log(`sinks: [${sinks.join(', ')}]`);
+}

package/dist/dashboard/data.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview The dashboard's numbers, computed from the local ledger.
+ *
+ * One JSON document drives both servings of the dashboard page: `slm-gate dashboard`
+ * computes it fresh per request, and `dashboard:export` bakes it into a static site.
+ * Everything here is aggregate — counts, token sums, minutes, dates. No prompt text,
+ * tool names or skill names leave the machine, so an export is safe to publish.
+ *
+ * The per-cycle view is the reason this exists locally: a provider window is a rolling
+ * span opened by the first request (Claude: 5 h), so cycles can only be reconstructed
+ * by clustering events by time — which Langfuse widgets cannot do.
+ *
+ * Benchmark runs (environment 'bench') are excluded from every savings figure and from
+ * routing: they are synthetic. They appear only in the accuracy split, labelled as such.
+ */
+import Database from 'better-sqlite3';
+import { CONFIG } from '../config.js';
+import { formatEventForLangfuse, perEventBaselineTokens, perEventCycleMinutes, perEventTokensSaved, resolveProvider, routingOutcome, } from '../ledger/index.js';
+import { getProviderRegistry } from '../pricing/providers.js';
+const PROVIDERS = [
+    { id: 'claude', label: 'Claude' },
+    { id: 'chatgpt', label: 'ChatGPT' },
+    { id: 'gemini', label: 'Gemini' },
+];
+function resolvedPlan(id) {
+    const plans = {
+        claude: CONFIG.RESOLVED_PLAN_CLAUDE,
+        chatgpt: CONFIG.RESOLVED_PLAN_CHATGPT,
+        gemini: CONFIG.RESOLVED_PLAN_GEMINI,
+    };
+    const resolved = plans[id];
+    return { windowMinutes: resolved.windowMinutes, plan: resolved.plan ?? id };
+}
+/** Monday of the event's week, UTC. */
+function weekStartOf(ts) {
+    const date = new Date(ts);
+    date.setUTCDate(date.getUTCDate() - ((date.getUTCDay() + 6) % 7));
+    return date.toISOString().slice(0, 10);
+}
+/** The event's accuracy score (0–100) exactly as the Langfuse mirror would emit it, or null. */
+function accuracyOf(e) {
+    const score = formatEventForLangfuse(e).scores?.find(s => s.name === 'accuracy_rate_pct');
+    return typeof score?.value === 'number' ? score.value : null;
+}
+/**
+ * Clusters one provider's events into window instances: a cycle opens at its first event
+ * and spans windowMinutes; the next event past that boundary opens the next cycle. This
+ * mirrors how the providers meter — the window starts on first use, not on the clock hour.
+ */
+export function clusterCycles(params) {
+    const hasBudget = getProviderRegistry()[params.providerId]?.windowBudget != null;
+    const cycles = [];
+    let windowEndMs = -Infinity;
+    for (const e of params.events) {
+        const t = Date.parse(e.ts);
+        if (t >= windowEndMs) {
+            windowEndMs = t + params.windowMinutes * 60_000;
+            cycles.push({ start: new Date(t).toISOString(), events: 0, tokensSaved: 0, minutes: hasBudget ? 0 : null });
+        }
+        const cycle = cycles[cycles.length - 1];
+        cycle.events += 1;
+        cycle.tokensSaved += perEventTokensSaved(e);
+        if (cycle.minutes !== null)
+            cycle.minutes += perEventCycleMinutes(e, params.providerId) ?? 0;
+    }
+    return cycles.map(c => ({ ...c, minutes: c.minutes === null ? null : Number(c.minutes.toFixed(3)) }));
+}
+/** Pure aggregation over ledger events, so it is testable without a database. */
+export function computeDashboardData(events) {
+    const sorted = [...events].sort((a, b) => a.ts.localeCompare(b.ts));
+    const real = sorted.filter(e => e.environment !== 'bench');
+    const bench = sorted.filter(e => e.environment === 'bench');
+    const routing = { resolvedLocal: 0, distilledForwarded: 0, escalatedCloud: 0 };
+    const days = new Map();
+    for (const e of real) {
+        const day = new Date(e.ts).toISOString().slice(0, 10);
+        const row = days.get(day) ?? { day, events: 0, tokensSaved: 0, baselineTokens: 0, resolvedLocal: 0, distilledForwarded: 0, escalatedCloud: 0 };
+        row.events += 1;
+        row.tokensSaved += perEventTokensSaved(e);
+        row.baselineTokens += perEventBaselineTokens(e);
+        if (e.route !== 'feedback') {
+            const outcome = routingOutcome(e) === 'resolved_local' ? 'resolvedLocal'
+                : routingOutcome(e) === 'distilled_forwarded' ? 'distilledForwarded' : 'escalatedCloud';
+            row[outcome] += 1;
+            routing[outcome] += 1;
+        }
+        days.set(day, row);
+    }
+    const accuracySlice = (slice) => {
+        const scores = slice.map(accuracyOf).filter((v) => v !== null);
+        if (scores.length === 0)
+            return { avgPct: null, n: 0 };
+        return { avgPct: Number((scores.reduce((s, v) => s + v, 0) / scores.length).toFixed(2)), n: scores.length };
+    };
+    const registry = getProviderRegistry();
+    const providers = PROVIDERS.map(({ id, label }) => {
+        const plan = resolvedPlan(id);
+        const mine = real.filter(e => resolveProvider(e) === id);
+        const cycles = clusterCycles({ events: mine, windowMinutes: plan.windowMinutes, providerId: id });
+        const budget = registry[id]?.windowBudget ?? null;
+        const weeks = new Map();
+        for (const e of mine) {
+            const weekStart = weekStartOf(e.ts);
+            const row = weeks.get(weekStart) ?? { weekStart, events: 0, tokensSaved: 0, minutes: budget === null ? null : 0 };
+            row.events += 1;
+            row.tokensSaved += perEventTokensSaved(e);
+            if (row.minutes !== null)
+                row.minutes = Number((row.minutes + (perEventCycleMinutes(e, id) ?? 0)).toFixed(3));
+            weeks.set(weekStart, row);
+        }
+        const minuteValues = cycles.map(c => c.minutes).filter((m) => m !== null).sort((a, b) => a - b);
+        const round = (n) => Number(n.toFixed(3));
+        return {
+            id,
+            label,
+            plan: plan.plan,
+            windowMinutes: plan.windowMinutes,
+            windowBudgetTokens: budget,
+            events: mine.length,
+            tokensSaved: mine.reduce((s, e) => s + perEventTokensSaved(e), 0),
+            minutesTotal: budget === null ? null : round(minuteValues.reduce((s, m) => s + m, 0)),
+            avgMinutesPerCycle: minuteValues.length === 0 ? null : round(minuteValues.reduce((s, m) => s + m, 0) / minuteValues.length),
+            medianMinutesPerCycle: minuteValues.length === 0 ? null : round(minuteValues[Math.floor(minuteValues.length / 2)]),
+            cycles,
+            weeks: [...weeks.values()].sort((a, b) => a.weekStart.localeCompare(b.weekStart)),
+        };
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        firstEventTs: sorted[0]?.ts ?? null,
+        lastEventTs: sorted[sorted.length - 1]?.ts ?? null,
+        realEvents: real.length,
+        benchEvents: bench.length,
+        routing,
+        accuracy: { real: accuracySlice(real), bench: accuracySlice(bench) },
+        days: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)),
+        providers,
+    };
+}
+/** Reads the ledger read-only and aggregates it. Throws when the ledger does not exist yet. */
+export function loadDashboardData() {
+    const db = new Database(CONFIG.LEDGER_PATH, { readonly: true, fileMustExist: true });
+    try {
+        return computeDashboardData(db.prepare('SELECT * FROM events').all());
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/dashboard/export.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Bakes the dashboard into a static site for free hosting (GitHub Pages).
+ *
+ * Writes <out>/index.html (the same page the local server serves), <out>/data.json
+ * (aggregates only: counts, token sums, minutes, dates — no prompts, tool names or
+ * skill names, so it is safe to publish; the timestamps do reveal when you work),
+ * and <out>/.nojekyll.
+ *
+ * Usage:
+ *   pnpm run dashboard:export [-- --out site]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG } from '../config.js';
+import { isEntryPoint } from '../utils/entry-point.js';
+import { loadDashboardData } from './data.js';
+function main() {
+    const args = process.argv.slice(2);
+    const outIdx = args.indexOf('--out');
+    const outDir = path.resolve(CONFIG.ROOT_DIR, outIdx >= 0 ? args[outIdx + 1] : 'site');
+    const data = loadDashboardData();
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.copyFileSync(path.join(CONFIG.ROOT_DIR, 'src', 'dashboard', 'index.html'), path.join(outDir, 'index.html'));
+    fs.writeFileSync(path.join(outDir, 'data.json'), JSON.stringify(data, null, 2));
+    fs.writeFileSync(path.join(outDir, '.nojekyll'), '');
+    console.log(`Exported ${data.realEvents + data.benchEvents} events of aggregates to ${outDir}/`);
+    console.log('Contains numbers and dates only — no prompts, tool names or skill names.');
+    console.log('\nTo publish on GitHub Pages:');
+    console.log('  1. git add site && commit && push (the Pages workflow deploys site/ from main)');
+    console.log('  2. Once, in the repository: Settings → Pages → Source: GitHub Actions');
+    console.log('  3. Your dashboard: https://<owner>.github.io/<repo>/');
+    console.log('\nOr view without hosting anything: open the page anywhere and drop this data.json on it.');
+}
+if (isEntryPoint(import.meta.url)) {
+    try {
+        main();
+    }
+    catch (err) {
+        console.error('dashboard:export failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}

package/dist/dashboard/serve.js

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Serves the metrics dashboard locally, live from the ledger.
+ *
+ * Read-only: the ledger is opened read-only per request and nothing is written anywhere.
+ * Local-only via the same rule as the gate's other servers (listenOnThisComputer).
+ *
+ * Usage:
+ *   pnpm run dashboard [-- --port 8790]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG } from '../config.js';
+import { isEntryPoint } from '../utils/entry-point.js';
+import { isLocalRequest, listenOnThisComputer } from '../utils/local-only.js';
+import { loadDashboardData } from './data.js';
+const PAGE_PATH = path.join(CONFIG.ROOT_DIR, 'src', 'dashboard', 'index.html');
+function handler(req, res) {
+    if (!isLocalRequest(req.headers)) {
+        res.writeHead(403).end('local requests only');
+        return;
+    }
+    const url = (req.url ?? '/').split('?')[0];
+    try {
+        if (url === '/' || url === '/index.html') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' }).end(fs.readFileSync(PAGE_PATH));
+        }
+        else if (url === '/data.json') {
+            res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(loadDashboardData()));
+        }
+        else {
+            res.writeHead(404).end('not found');
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        res.writeHead(500, { 'Content-Type': 'text/plain' }).end(/(ENOENT|does not exist)/i.test(message)
+            ? `No ledger at ${CONFIG.LEDGER_PATH} yet — it is created when the gate handles its first request.`
+            : message);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const portIdx = args.indexOf('--port');
+    const port = portIdx >= 0 ? Number(args[portIdx + 1]) : 8790;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error('--port takes a port number.');
+        process.exit(1);
+    }
+    await listenOnThisComputer({
+        handler,
+        port,
+        onListening: () => {
+            console.log(`SLM Gate metrics dashboard: http://localhost:${port}`);
+            console.log(`Reading ${CONFIG.LEDGER_PATH} (read-only, computed fresh on every reload). Ctrl-C to stop.`);
+        },
+    });
+}
+if (isEntryPoint(import.meta.url)) {
+    main().catch(err => {
+        console.error('dashboard failed to start:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}