@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.100

package/src/retention.ts

@@ -0,0 +1,281 @@
+// Round-2/4 review ② — retention sweep + incremental VACUUM.
+//
+// Background maintenance for the commhub database. Multi-tenant
+// public-facing hubs (e.g. <hub-domain>) write to high-frequency tables
+// on every heartbeat (agent_telemetry, task_events, completions) — left
+// unswept these grow unbounded, slow down indexed scans, and bloat the
+// on-disk footprint. SQLite never reclaims freed pages without VACUUM,
+// so a row delete by itself doesn't shrink the file.
+//
+// This module exposes:
+//   - sweepRetention(cfg): one-shot sweep across high-growth tables
+//   - startRetentionSweeper(): wires a 1-hour setInterval, fires once
+//     at startup with an immediate (non-blocking) sweep
+//
+// Defaults are conservative — long-tail debugging traces survive a
+// week. Operators can override per env (COMMHUB_RETENTION_*_DAYS) for
+// hot hubs.
+//
+// Run isolated tests against retention.test.ts:
+//   COMMHUB_DB=/tmp/test-retention.db bun test src/retention.test.ts
+
+import { db } from "./db.js";
+import { sweepNodeRequestContent, type NodeRequestSweepResult } from "./node-request-retention.js";
+
+export type RetentionConfig = {
+  // High-frequency telemetry; default = 7 days.
+  // Heartbeat is ~30s → 50 agents × 86400 s/day ÷ 30 s = 144000 rows/day.
+  // At 7d that's ~1M rows. Indexed scans stay fast; raw disk = a few MB.
+  telemetryDays: number;
+  // Task state-change audit; default = 30 days.
+  // One row per status transition. Useful for incident forensics.
+  taskEventsDays: number;
+  // Acked inbox; default = 7 days post-ack.
+  // Once acked the row is no longer hot — keep a week for debugging.
+  // Unacked rows are NEVER swept (could be in-flight delivery).
+  ackedInboxDays: number;
+  // Completed/cancelled/failed tasks; default = 30 days.
+  // Active tasks (created/delivered/acked/running/replied less than
+  // 30 days old) are NEVER swept.
+  terminalTasksDays: number;
+  // Audit log; default = 90 days.
+  // Longer retention because audit_log is a security artifact.
+  auditLogDays: number;
+};
+
+export type SweepResult = {
+  startedAt: string;
+  durationMs: number;
+  deletes: {
+    agent_telemetry: number;
+    task_events: number;
+    inbox: number;
+    tasks: number;
+    audit_log: number;
+  };
+  // node_rules_requests: file bytes purged by age / after read, rows deleted
+  // after 30 days. Fixed policy (privacy, not disk) — no env opt-out.
+  nodeRequests: NodeRequestSweepResult;
+  vacuum: {
+    walCheckpointPagesMoved: number | null;
+    incrementalFreedPages: number | null;
+    errored: boolean;
+  };
+};
+
+const DEFAULTS: RetentionConfig = {
+  telemetryDays: 7,
+  taskEventsDays: 30,
+  ackedInboxDays: 7,
+  terminalTasksDays: 30,
+  auditLogDays: 90,
+};
+
+function readEnvDays(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const n = Number(raw);
+  // Negative = disable that table's sweep entirely (operator opt-out).
+  // NaN / non-finite falls back to default — guard against fat-fingered env.
+  if (!Number.isFinite(n)) return fallback;
+  return n;
+}
+
+export function readRetentionConfig(): RetentionConfig {
+  return {
+    telemetryDays: readEnvDays("COMMHUB_RETENTION_TELEMETRY_DAYS", DEFAULTS.telemetryDays),
+    taskEventsDays: readEnvDays("COMMHUB_RETENTION_TASK_EVENTS_DAYS", DEFAULTS.taskEventsDays),
+    ackedInboxDays: readEnvDays("COMMHUB_RETENTION_INBOX_ACKED_DAYS", DEFAULTS.ackedInboxDays),
+    terminalTasksDays: readEnvDays("COMMHUB_RETENTION_TASKS_TERMINAL_DAYS", DEFAULTS.terminalTasksDays),
+    auditLogDays: readEnvDays("COMMHUB_RETENTION_AUDIT_DAYS", DEFAULTS.auditLogDays),
+  };
+}
+
+function sweepOne(
+  sql: string,
+  params: (string | number)[],
+  days: number,
+): number {
+  // days < 0 → operator opt-out for this table; skip the DELETE.
+  // days === 0 is a legitimate "sweep everything older than now"
+  // (effectively a TRUNCATE); we honour it.
+  if (days < 0) return 0;
+  try {
+    const res = db.run(sql, params);
+    return res.changes ?? 0;
+  } catch (e: any) {
+    console.log(`[commhub retention] sweep failed: ${e?.message ?? e}`);
+    return 0;
+  }
+}
+
+export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): SweepResult {
+  const startedAt = new Date().toISOString();
+  const t0 = Date.now();
+
+  const telemetry = sweepOne(
+    `DELETE FROM agent_telemetry WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.telemetryDays} days`],
+    cfg.telemetryDays,
+  );
+  const taskEvents = sweepOne(
+    `DELETE FROM task_events WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.taskEventsDays} days`],
+    cfg.taskEventsDays,
+  );
+  // Only sweep ACKED inbox rows — unacked may be in-flight delivery
+  // for an agent that's offline but coming back. Acked rows have
+  // served their purpose and exist only for debugging.
+  const inbox = sweepOne(
+    `DELETE FROM inbox WHERE acked = 1 AND created_at < datetime('now', ?1)`,
+    [`-${cfg.ackedInboxDays} days`],
+    cfg.ackedInboxDays,
+  );
+  // Terminal-task sweep — split into two DELETEs:
+  //
+  // (a) "safe terminals": cancelled / failed / expired / (theoretical)
+  //     completed have no chain-ancestor risk and are safe to reap
+  //     unconditionally past the horizon. NOTE: as of this writing
+  //     'completed' is dead code — no code path sets it (every reply
+  //     uses 'replied'/'failed'/'cancelled' via send_reply or
+  //     chainReplyToParent). Kept in the IN-list as a forward guard:
+  //     if someone introduces a 'completed' write later, the sweep
+  //     picks it up without code changes.
+  //
+  // (b) "replied" — was excluded entirely in the original PR, which
+  //     missed the goal: every fulfilled task lives at 'replied'
+  //     status, so the tasks table's MAIN GROWTH SOURCE would never
+  //     be reclaimed. Reviewer caught this. Fix: child-ref-aware
+  //     delete — reap an old replied row ONLY IF no other task
+  //     references it as parent_task_id. A row with no children is
+  //     not a chain ancestor and is safe to drop.
+  //
+  // **Time field** (both DELETEs): use COALESCE(completed_at, created_at).
+  // Terminal status means the server set `completed_at` at the
+  // reply/fail/cancel moment. Sweeping on `created_at` alone would
+  // reap a task created 60d ago but completed today the instant it
+  // entered terminal state — zero post-terminal retention. The
+  // COALESCE falls back to created_at for legacy rows that pre-date
+  // the completed_at column (back-compat).
+  const tasksSafeTerminal = sweepOne(
+    `DELETE FROM tasks
+     WHERE status IN ('completed', 'cancelled', 'failed', 'expired')
+       AND COALESCE(completed_at, created_at) < datetime('now', ?1)`,
+    [`-${cfg.terminalTasksDays} days`],
+    cfg.terminalTasksDays,
+  );
+  const tasksRepliedChildSafe = sweepOne(
+    `DELETE FROM tasks
+     WHERE status = 'replied'
+       AND COALESCE(completed_at, created_at) < datetime('now', ?1)
+       AND NOT EXISTS (
+         SELECT 1 FROM tasks AS child
+         WHERE child.parent_task_id = tasks.task_id
+       )`,
+    [`-${cfg.terminalTasksDays} days`],
+    cfg.terminalTasksDays,
+  );
+  const tasks = tasksSafeTerminal + tasksRepliedChildSafe;
+  const auditLog = sweepOne(
+    `DELETE FROM audit_log WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.auditLogDays} days`],
+    cfg.auditLogDays,
+  );
+
+  const nodeRequests = sweepNodeRequestContent();
+
+  // VACUUM:
+  //   - wal_checkpoint(TRUNCATE): trims the WAL file. Works on every
+  //     SQLite DB regardless of auto_vacuum setting. Useful after
+  //     big DELETEs so the WAL doesn't stay bloated until the next
+  //     natural checkpoint.
+  //   - incremental_vacuum: ONLY reclaims main-DB pages on databases
+  //     created with `PRAGMA auto_vacuum = INCREMENTAL`. On legacy
+  //     DBs (the default mode 0) this is a no-op and the main file
+  //     does NOT shrink — freed pages stay in the freelist for
+  //     future inserts. Operators who want disk reclamation on old
+  //     DBs must run a one-time blocking `VACUUM` themselves (out of
+  //     scope for the sweeper, which deliberately stays non-
+  //     blocking).
+  //   Both are SQLite PRAGMAs; on PostgreSQL autovacuum does this job and
+  //   the two counters stay null (RFC-039 S3).
+  let walCheckpointPagesMoved: number | null = null;
+  let incrementalFreedPages: number | null = null;
+  let errored = false;
+  const sqliteVacuum = db.dialect === "sqlite";
+  if (sqliteVacuum) try {
+    // wal_checkpoint(TRUNCATE) returns a row { busy, log, checkpointed }.
+    // We expose `log` (page count moved into the main DB) for ops visibility.
+    const checkpoint = db.get<{ busy: number; log: number; checkpointed: number }>(
+      "PRAGMA wal_checkpoint(TRUNCATE)",
+    );
+    walCheckpointPagesMoved = checkpoint?.log ?? null;
+  } catch (e: any) {
+    console.log(`[commhub retention] wal_checkpoint failed: ${e?.message ?? e}`);
+    errored = true;
+  }
+  if (sqliteVacuum) try {
+    // incremental_vacuum is a no-op on databases not created with
+    // PRAGMA auto_vacuum = INCREMENTAL. For existing prod DBs that
+    // weren't, the operator would have to run a full one-time VACUUM
+    // to migrate — out of scope for the sweeper.
+    const freelistBefore = db.get<{ freelist_count: number }>("PRAGMA freelist_count");
+    db.exec("PRAGMA incremental_vacuum");
+    const freelistAfter = db.get<{ freelist_count: number }>("PRAGMA freelist_count");
+    incrementalFreedPages =
+      (freelistBefore?.freelist_count ?? 0) - (freelistAfter?.freelist_count ?? 0);
+  } catch (e: any) {
+    console.log(`[commhub retention] incremental_vacuum failed: ${e?.message ?? e}`);
+    errored = true;
+  }
+
+  return {
+    startedAt,
+    durationMs: Date.now() - t0,
+    deletes: {
+      agent_telemetry: telemetry,
+      task_events: taskEvents,
+      inbox,
+      tasks,
+      audit_log: auditLog,
+    },
+    nodeRequests,
+    vacuum: { walCheckpointPagesMoved, incrementalFreedPages, errored },
+  };
+}
+
+// Used by index.ts to wire the periodic sweeper. Returns the timer so
+// callers can stop it in tests / shutdown.
+export function startRetentionSweeper(
+  intervalMs = 60 * 60 * 1000, // 1 hour
+  cfg?: RetentionConfig,
+): ReturnType<typeof setInterval> {
+  const sweep = () => {
+    try {
+      const r = sweepRetention(cfg);
+      const totalDeletes =
+        r.deletes.agent_telemetry +
+        r.deletes.task_events +
+        r.deletes.inbox +
+        r.deletes.tasks +
+        r.deletes.audit_log;
+      const nr = r.nodeRequests;
+      if (totalDeletes > 0 || nr.purged > 0 || nr.deleted > 0 || nr.timedOut > 0 || r.vacuum.errored) {
+        console.log(
+          `[commhub retention] swept in ${r.durationMs}ms — ` +
+            `telemetry=${r.deletes.agent_telemetry} events=${r.deletes.task_events} ` +
+            `inbox=${r.deletes.inbox} tasks=${r.deletes.tasks} audit=${r.deletes.audit_log} ` +
+            `nodeReqPurged=${nr.purged} nodeReqDeleted=${nr.deleted} nodeReqTimedOut=${nr.timedOut} ` +
+            `walPages=${r.vacuum.walCheckpointPagesMoved} freedPages=${r.vacuum.incrementalFreedPages}`,
+        );
+      }
+    } catch (e: any) {
+      console.log(`[commhub retention] sweep top-level failed: ${e?.message ?? e}`);
+    }
+  };
+  // Fire once on startup so a long-running hub eventually catches up
+  // even if it's restarted just after the previous sweep. setImmediate
+  // (vs synchronous) keeps server startup from blocking on the sweep.
+  setImmediate(sweep);
+  return setInterval(sweep, intervalMs);
+}

package/src/route-callers-http.test.ts

@@ -0,0 +1,120 @@
+// GET /api/stats/routes?by=caller — per-route caller classes (token kind + User-Agent family).
+// Production serves the full GET /api/status ~2.8/s and every caller arrives as 127.0.0.1 through the
+// frp tunnel, with no access log; this breakdown is how we tell who it is. Pinned over real HTTP:
+//   - without by=caller the body is byte-for-byte what routeStats() produced before this change;
+//   - with it, each route carries callers [{class, count, bytes}] counted per class;
+//   - no token, user id, node id, username or raw User-Agent text ever reaches the output;
+//   - distinct classes per route are capped, the rest folded into "(other)";
+//   - still admin-only.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ROUTE_MAX_CALLERS_PER_ROUTE, ROUTE_OVERFLOW_KEY, routeStats } from "./route-timing.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-route-callers-"));
+process.env.HOME = DIR;
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "RouteCallersPassw0rd!";
+const NODE_ID = "node_route_callers_probe";
+const NODE_NAME = "rc-probe-node";
+const UA_MARKER = "zz-ua-marker-41c9";
+let BASE = "";
+let hub: any = null;
+let admin = "";
+let adminId = "";
+let adminName = "";
+let member = "";
+let ntok = "";
+
+const get = (path: string, headers: Record<string, string> = {}) => fetch(`${BASE}${path}`, { headers });
+const auth = (token: string, ua?: string) => ({ Authorization: `Bearer ${token}`, ...(ua === undefined ? {} : { "User-Agent": ua }) });
+async function byCaller(): Promise<{ text: string; rows: any[] }> {
+  const res = await get("/api/stats/routes?minutes=5&by=caller", auth(admin));
+  expect(res.status).toBe(200);
+  const text = await res.text();
+  return { text, rows: JSON.parse(text).routes };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  adminName = `rc_admin_${Date.now()}`;
+  const a = register(adminName, PW);
+  admin = a.token!;
+  adminId = a.user!.user_id;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  member = register(`rc_member_${Date.now()}`, PW).token!;
+  const minted = createNetworkTokenForNode(adminId, a.network_id!, NODE_NAME, NODE_ID);
+  expect(minted.ok).toBe(true);
+  ntok = minted.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/stats/routes?by=caller", () => {
+  test("without by=caller the body is exactly the pre-existing routeStats() output", async () => {
+    await get("/api/status", auth(admin, "node"));
+    await get("/api/status?light=1", auth(ntok, "agent-node/2.5.0-preview.88"));
+    // The stats request is recorded only after its body is built, so nothing lands between these two.
+    const expected = JSON.stringify({ ok: true, ...routeStats(5 * 60_000) });
+    const res = await get("/api/stats/routes?minutes=5", auth(admin));
+    expect(await res.text()).toBe(expected);
+    const body = JSON.parse(expected);
+    expect(Object.keys(body)).toEqual(["ok", "window_ms", "samples", "oldest_at", "routes"]);
+    for (const r of body.routes) expect(Object.keys(r)).toEqual(["route", "count", "total_ms", "avg_ms", "p95_ms", "max_ms", "bytes", "errors"]);
+  });
+
+  test("callers are counted per class: token kind + UA family", async () => {
+    const before = (await byCaller()).rows.find(r => r.route === "GET /api/status")?.callers ?? [];
+    const count = (cs: any[], cls: string) => cs.find(c => c.class === cls)?.count ?? 0;
+    for (let i = 0; i < 3; i++) expect((await get("/api/status", auth(member, "node"))).status).toBe(200);
+    await get("/api/status", auth(ntok, `agent-node/2.5.0-preview.88 (${UA_MARKER})`));
+    await get("/api/status", auth(member, `Mozilla/5.0 (X11; ${UA_MARKER}) Chrome/130.0`));
+    await get("/api/status", { "User-Agent": "curl/8.5.0" }); // anonymous → 401, still counted
+    const row = (await byCaller()).rows.find(r => r.route === "GET /api/status")!;
+    const callers = row.callers as any[];
+    expect(count(callers, "user node") - count(before, "user node")).toBe(3);
+    expect(count(callers, "node agent-node/2.5.0-preview.88") - count(before, "node agent-node/2.5.0-preview.88")).toBe(1);
+    expect(count(callers, "user browser") - count(before, "user browser")).toBe(1);
+    expect(count(callers, "anon curl/8.5.0") - count(before, "anon curl/8.5.0")).toBe(1);
+    expect(callers.reduce((n: number, c: any) => n + c.count, 0)).toBe(row.count);
+    expect(callers.reduce((n: number, c: any) => n + c.bytes, 0)).toBe(row.bytes);
+    for (const c of callers) expect(Object.keys(c)).toEqual(["class", "count", "bytes"]);
+  });
+
+  test("no token, id, username or raw User-Agent text in the output", async () => {
+    await get(`/api/status?token=${ntok}`, { "User-Agent": `${UA_MARKER}/1.0` });
+    const { text, rows } = await byCaller();
+    for (const secret of [admin, member, ntok, adminId, adminName, NODE_ID, NODE_NAME, UA_MARKER, "Mozilla", "X11", "127.0.0.1", "ntok_", "utok_"]) {
+      expect(text).not.toContain(secret);
+    }
+    const classes = rows.flatMap(r => r.callers.map((c: any) => c.class));
+    expect(classes).toContain("node other");
+    for (const cls of classes) expect(cls).toMatch(/^(\(other\)|(node|user|master|token|anon) [a-z0-9._-]+(\/[0-9A-Za-z.-]+)?)$/);
+  });
+
+  test("distinct classes per route are capped, the rest folded into (other)", async () => {
+    const n = ROUTE_MAX_CALLERS_PER_ROUTE + 5;
+    for (let i = 0; i < n; i++) await get("/api/networks", auth(member, `curl/${i}.0.0`));
+    const row = (await byCaller()).rows.find(r => r.route === "GET /api/networks")!;
+    expect(row.callers.length).toBe(ROUTE_MAX_CALLERS_PER_ROUTE);
+    expect(row.callers.at(-1).class).toBe(ROUTE_OVERFLOW_KEY);
+    expect(row.callers.reduce((s: number, c: any) => s + c.count, 0)).toBe(row.count);
+  });
+
+  test("still admin-only", async () => {
+    expect((await get("/api/stats/routes?by=caller", auth(member))).status).toBe(403);
+    expect((await get("/api/stats/routes?by=caller", auth(ntok))).status).toBe(403);
+  });
+});

package/src/route-timing.test.ts

@@ -0,0 +1,211 @@
+import { expect, test } from "bun:test";
+import {
+  __resetRouteTimingForTest, callerTokenKind, labelRoute, mcpRouteLabel, recordRouteTiming, routeKey, routeStats,
+  setRouteCallerMasterToken, setRouteCallerTokenReader, userAgentFamily, ROUTE_MAX_CALLERS_PER_ROUTE,
+  ROUTE_BUCKET_MS, ROUTE_BUCKET_RETENTION, ROUTE_MAX_KEYS_PER_BUCKET, ROUTE_OVERFLOW_KEY,
+} from "./route-timing";
+
+const u = (s: string) => new URL(`http://hub${s}`);
+const req = (path: string, method = "GET") => new Request(`http://hub${path}`, { method });
+const res = (status = 200, len?: number) => new Response("x", { status, headers: len === undefined ? {} : { "Content-Length": String(len) } });
+const at = (ms: number) => performance.now() - ms;
+
+test("routeKey collapses ids, aliases and file names, keeps payload-shaping params", () => {
+  expect(routeKey("GET", u("/api/requirements?network_id=net_1&limit=500"))).toBe("GET /api/requirements");
+  expect(routeKey("GET", u("/api/requirements?view=summary&network_id=n"))).toBe("GET /api/requirements?view=summary");
+  expect(routeKey("PATCH", u("/api/requirements/req_3f9a/checklist/c1"))).toBe("PATCH /api/requirements/:id/checklist/:id");
+  expect(routeKey("GET", u("/api/requirements/stats"))).toBe("GET /api/requirements/stats");
+  expect(routeKey("GET", u("/api/status?light=1"))).toBe("GET /api/status?light=1");
+  expect(routeKey("GET", u(`/api/nodes/${encodeURIComponent("通信牛")}/config`))).toBe("GET /api/nodes/:id/config");
+  expect(routeKey("GET", u("/api/messages?scope=user&limit=50"))).toBe("GET /api/messages?scope=user");
+});
+
+test("routeStats groups the window, sorts by total time, and counts every request (no sample cap)", () => {
+  __resetRouteTimingForTest();
+  const now = 1_000_000_000;
+  recordRouteTiming(req("/api/requirements"), at(30), res(200, 1000), now);
+  recordRouteTiming(req("/api/requirements"), at(10), res(200, 500), now);
+  recordRouteTiming(req("/api/status?light=1"), at(5), res(503), now);
+  recordRouteTiming(req("/api/status?light=1"), at(100), res(), now - 10 * 60_000); // 窗口外
+  expect(recordRouteTiming(req("/ws"), 0, undefined, now)).toBeUndefined();
+  const stats = routeStats(60_000, now);
+  expect(stats.samples).toBe(3);
+  expect(stats.routes.map(r => r.route)).toEqual(["GET /api/requirements", "GET /api/status?light=1"]);
+  const r0 = stats.routes[0];
+  expect(r0.count).toBe(2);
+  expect(r0.bytes).toBe(1500);
+  expect(r0.max_ms).toBeGreaterThanOrEqual(29);
+  expect(r0.total_ms).toBeGreaterThanOrEqual(39);
+  expect(r0.p95_ms).toBeLessThanOrEqual(r0.max_ms);
+  expect(stats.routes[1].errors).toBe(1);
+  // The old 4096-sample ring dropped everything past its size; the buckets count all of it.
+  for (let i = 0; i < 10_000; i++) recordRouteTiming(req("/api/tasks"), at(1), res(), now);
+  const after = routeStats(60_000, now);
+  expect(after.routes.find(r => r.route === "GET /api/tasks")!.count).toBe(10_000);
+  expect(after.samples).toBe(10_003);
+});
+
+test("?minutes=10 really covers 10 minutes: a steady 15 req/s stream is fully counted, older traffic is not", () => {
+  __resetRouteTimingForTest();
+  const t0 = 2_000_000_000 - (2_000_000_000 % ROUTE_BUCKET_MS); // bucket-aligned
+  // 20 minutes at 15 req/s — the old ring filled in ~4.5 minutes of this.
+  for (let s = 0; s < 20 * 60; s++) {
+    for (let k = 0; k < 15; k++) recordRouteTiming(req("/mcp", "POST"), at(1), res(), t0 + s * 1000);
+  }
+  const now = t0 + 20 * 60_000;
+  const ten = routeStats(10 * 60_000, now);
+  // window starts at t0+10min → the ten minute buckets t0+10 … t0+19
+  expect(ten.samples).toBe(10 * 60 * 15);
+  expect(ten.oldest_at).toBe(new Date(t0 + 10 * 60_000).toISOString());
+  expect(routeStats(20 * 60_000, now).samples).toBe(20 * 60 * 15);
+  expect(routeStats(60 * 60_000, now).samples).toBe(20 * 60 * 15);
+});
+
+test("buckets older than the retention are dropped", () => {
+  __resetRouteTimingForTest();
+  const now = 3_000_000_000;
+  const old = now - (ROUTE_BUCKET_RETENTION + 5) * ROUTE_BUCKET_MS;
+  recordRouteTiming(req("/api/old"), at(1), res(), old);
+  expect(routeStats(ROUTE_BUCKET_RETENTION * 2 * ROUTE_BUCKET_MS, old).samples).toBe(1);
+  recordRouteTiming(req("/api/new"), at(1), res(), now);
+  const s = routeStats(ROUTE_BUCKET_RETENTION * 2 * ROUTE_BUCKET_MS, now);
+  expect(s.routes.map(r => r.route)).toEqual(["GET /api/new"]);
+});
+
+test("p95 comes from the histogram: close to the true value and never above max", () => {
+  __resetRouteTimingForTest();
+  const now = 4_000_000_000;
+  // 96 fast (~1 ms) and 4 slow (~200 ms): p95 (the 96th of 100, same rank as the old ring's
+  // sorted[floor(n·0.95)]) must be in the fast band, max in the slow band.
+  for (let i = 0; i < 96; i++) recordRouteTiming(req("/api/p"), at(1), res(), now);
+  for (let i = 0; i < 4; i++) recordRouteTiming(req("/api/p"), at(200), res(), now);
+  const r = routeStats(60_000, now).routes[0];
+  expect(r.p95_ms).toBeGreaterThanOrEqual(1);
+  expect(r.p95_ms).toBeLessThan(5);
+  expect(r.max_ms).toBeGreaterThanOrEqual(200);
+  __resetRouteTimingForTest();
+  recordRouteTiming(req("/api/q"), at(3), res(), now);
+  const one = routeStats(60_000, now).routes[0];
+  expect(one.p95_ms).toBe(one.max_ms);
+});
+
+test("distinct routes per bucket are capped; the rest land in the overflow key", () => {
+  __resetRouteTimingForTest();
+  const now = 5_000_000_000;
+  for (let i = 0; i < ROUTE_MAX_KEYS_PER_BUCKET + 50; i++) {
+    const r = req("/mcp", "POST");
+    labelRoute(r, `tools/call t${String.fromCharCode(97 + (i % 26))}${Math.floor(i / 26)}x`);
+    recordRouteTiming(r, at(1), res(), now);
+  }
+  const s = routeStats(60_000, now);
+  expect(s.routes.length).toBe(ROUTE_MAX_KEYS_PER_BUCKET + 1);
+  expect(s.routes.find(r => r.route === ROUTE_OVERFLOW_KEY)!.count).toBe(50);
+  expect(s.samples).toBe(ROUTE_MAX_KEYS_PER_BUCKET + 50);
+});
+
+test("a label is appended to the route shape of that request only", () => {
+  __resetRouteTimingForTest();
+  const now = 6_000_000_000;
+  const a = req("/mcp", "POST");
+  labelRoute(a, "tools/call report_status");
+  recordRouteTiming(a, at(1), res(), now);
+  recordRouteTiming(req("/mcp", "POST"), at(1), res(), now);
+  expect(routeStats(60_000, now).routes.map(r => r.route).sort()).toEqual(["POST /mcp", "POST /mcp tools/call report_status"]);
+});
+
+test("mcpRouteLabel: method, tool name, and nothing else", () => {
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "report_status", arguments: { task: "secret" } } })).toBe("tools/call report_status");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "tools/list" })).toBe("tools/list");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", method: "notifications/initialized" })).toBe("notifications/initialized");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "initialize", params: { name: "x" } })).toBe("initialize");
+  // odd shapes collapse to "?"
+  expect(mcpRouteLabel([{ method: "tools/list" }])).toBe("batch");
+  expect(mcpRouteLabel(null)).toBe("?");
+  expect(mcpRouteLabel("tools/list")).toBe("?");
+  expect(mcpRouteLabel(42)).toBe("?");
+  expect(mcpRouteLabel({})).toBe("?");
+  expect(mcpRouteLabel({ method: 7 })).toBe("?");
+  expect(mcpRouteLabel({ method: "x".repeat(65) })).toBe("?");
+  expect(mcpRouteLabel({ method: "tools/call x" })).toBe("?");
+  expect(mcpRouteLabel({ method: "通信" })).toBe("?");
+  expect(mcpRouteLabel({ method: "tools/call" })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: "report_status" })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: { toString: () => "x" } } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "a b" } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "../../etc/passwd" } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "n".repeat(65) } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "" } })).toBe("tools/call ?");
+});
+
+// ── caller classes (?by=caller) ──
+const reqAs = (path: string, headers: Record<string, string>) => new Request(`http://hub${path}`, { headers });
+
+test("userAgentFamily keeps only allow-listed product names and a sanitized version", () => {
+  expect(userAgentFamily("agent-node/2.5.0-preview.88")).toBe("agent-node/2.5.0-preview.88");
+  expect(userAgentFamily("node")).toBe("node");
+  expect(userAgentFamily("Bun/1.2.19")).toBe("bun/1.2.19");
+  expect(userAgentFamily("okhttp/4.12.0")).toBe("okhttp/4.12.0");
+  expect(userAgentFamily("curl/8.5.0")).toBe("curl/8.5.0");
+  expect(userAgentFamily("agent-network-desktop/0.2.170")).toBe("agent-network-desktop/0.2.170");
+  expect(userAgentFamily("tauri-plugin-http/2.5.9")).toBe("tauri-plugin-http/2.5.9");
+  expect(userAgentFamily("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15")).toBe("browser");
+  expect(userAgentFamily("SomeApp/42 CFNetwork/1568.100.1 Darwin/24.0.0")).toBe("cfnetwork/1568.100.1");
+  expect(userAgentFamily(null)).toBe("none");
+  expect(userAgentFamily("   ")).toBe("none");
+  // Free text never comes through: unknown product names, and anything after a version.
+  expect(userAgentFamily("my-laptop-hostname/1.0")).toBe("other");
+  expect(userAgentFamily("curl/8.5.0;user=alice@example.com")).toBe("curl/8.5.0");
+  expect(userAgentFamily("node/abc-secret")).toBe("node");
+});
+
+test("callerTokenKind recognises token kinds without keeping the token", () => {
+  setRouteCallerMasterToken("master-secret-xyz");
+  // Header-only reader, as installed by default; another test file in the same process may have booted server.ts.
+  const previous = setRouteCallerTokenReader(r => r.headers.get("authorization")?.replace("Bearer ", "") || "");
+  try {
+    const kind = (headers: Record<string, string>) => callerTokenKind(reqAs("/api/status", headers));
+    expect(kind({ Authorization: "Bearer ntok_abc" })).toBe("node");
+    expect(kind({ Authorization: "Bearer utok_abc" })).toBe("user");
+    expect(kind({ Authorization: "Bearer master-secret-xyz" })).toBe("master");
+    expect(kind({ Authorization: "Bearer something-else" })).toBe("token");
+    expect(kind({})).toBe("anon");
+    // ?token= is read only through the reader server.ts installs (requestToken); a header-only reader ignores it.
+    expect(callerTokenKind(reqAs("/events/x?token=ntok_q", {}))).toBe("anon");
+    setRouteCallerTokenReader(r => new URL(r.url).searchParams.get("t") || "");
+    expect(callerTokenKind(reqAs("/events/x?t=ntok_q", {}))).toBe("node");
+  } finally {
+    setRouteCallerMasterToken(undefined);
+    setRouteCallerTokenReader(previous);
+  }
+});
+
+test("routeStats({byCaller}) counts per class; without it the rows have no callers field", () => {
+  __resetRouteTimingForTest();
+  const now = 3_000_000_000;
+  const status = (headers: Record<string, string>, len: number) => recordRouteTiming(reqAs("/api/status", headers), at(1), res(200, len), now);
+  for (let i = 0; i < 3; i++) status({ Authorization: "Bearer utok_secret1", "User-Agent": "node" }, 100);
+  status({ Authorization: "Bearer ntok_secret2", "User-Agent": "agent-node/2.5.0-preview.88" }, 10);
+  status({ "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) Chrome/130.0" }, 1);
+  const plain = routeStats(60_000, now);
+  expect(plain.routes[0]).not.toHaveProperty("callers");
+  const by = routeStats(60_000, now, { byCaller: true });
+  expect(by.routes[0].callers).toEqual([
+    { class: "user node", count: 3, bytes: 300 },
+    { class: "node agent-node/2.5.0-preview.88", count: 1, bytes: 10 },
+    { class: "anon browser", count: 1, bytes: 1 },
+  ]);
+  expect(JSON.stringify(by)).not.toMatch(/secret|Mozilla|Linux|Chrome/);
+});
+
+test("caller classes are capped per route: per bucket and again after merging buckets", () => {
+  __resetRouteTimingForTest();
+  const now = 4_000_000_000 - (4_000_000_000 % ROUTE_BUCKET_MS);
+  // Minute 1: 30 distinct versions → 20 stored, 10 into (other). Minute 2: 25 more distinct ones.
+  for (let i = 0; i < 30; i++) recordRouteTiming(reqAs("/api/status", { "User-Agent": `curl/${i}.0` }), at(1), res(200, 1), now - ROUTE_BUCKET_MS);
+  for (let i = 100; i < 125; i++) recordRouteTiming(reqAs("/api/status", { "User-Agent": `curl/${i}.0` }), at(1), res(200, 1), now);
+  const callers = routeStats(5 * 60_000, now, { byCaller: true }).routes[0].callers!;
+  expect(callers.length).toBe(ROUTE_MAX_CALLERS_PER_ROUTE);
+  expect(callers.at(-1)!.class).toBe(ROUTE_OVERFLOW_KEY);
+  expect(callers.reduce((n, c) => n + c.count, 0)).toBe(55);
+  expect(callers.reduce((n, c) => n + c.bytes, 0)).toBe(55);
+});