@sleep2agi/commhub-server 0.9.0-preview.77 → 0.9.0-preview.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.77",
+  "version": "0.9.0-preview.78",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/mcp-route-label-http.test.ts

@@ -0,0 +1,120 @@
+// POST /mcp in /api/stats/routes carries the JSON-RPC method and, for tools/call, the tool name
+// ("POST /mcp tools/call report_status"). Production showed POST /mcp as the biggest route (15 req/s,
+// ~13% of a core) with no way to tell which tool. This suite pins, over real HTTP:
+//   - the labels (tools/call <name>, tools/list, batch) and that MCP responses are unchanged in kind;
+//   - arguments never reach the stats (a marker in arguments / a hostile tool name never shows up);
+//   - odd bodies still get the transport's own answers (invalid JSON → -32700, oversized → parsed by
+//     the transport itself) and are labelled "?";
+//   - unauthenticated /mcp stays plain "POST /mcp" (the body is never read before auth).
+
+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";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-mcp-route-label-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "McpRouteLabelPassw0rd!";
+const MARKER = "zz-argument-marker-7f3a";
+let BASE = "";
+let hub: any = null;
+let admin = "";
+
+const MCP_HEADERS = { "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" };
+async function mcpRaw(token: string, body: string): Promise<{ status: number; text: string }> {
+  const res = await fetch(`${BASE}/mcp`, { method: "POST", headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...MCP_HEADERS }, body });
+  return { status: res.status, text: await res.text() };
+}
+function rpc(text: string): any {
+  const lines = text.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(text);
+}
+async function routes(): Promise<{ text: string; keys: string[]; rows: any[] }> {
+  const res = await fetch(`${BASE}/api/stats/routes?minutes=5`, { headers: { Authorization: `Bearer ${admin}` } });
+  const text = await res.text();
+  const rows = JSON.parse(text).routes as any[];
+  return { text, keys: rows.map(r => r.route), rows };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`mrl_admin_${Date.now()}`, PW);
+  admin = a.token!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [a.user!.user_id]);
+  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("POST /mcp route label", () => {
+  test("tools/call is labelled with the tool name and still answers normally", async () => {
+    const r = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "get_all_status", arguments: { note: MARKER } } }));
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result).toBeDefined();
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/call get_all_status");
+  });
+
+  test("tools/list and a batch get their own labels", async () => {
+    const list = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }));
+    expect(list.status).toBe(200);
+    expect(rpc(list.text).result.tools.length).toBeGreaterThan(10);
+    await mcpRaw(admin, JSON.stringify([{ jsonrpc: "2.0", id: 3, method: "tools/list" }]));
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/list");
+    expect(keys).toContain("POST /mcp batch");
+  });
+
+  test("arguments and hostile tool names never reach the stats", async () => {
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: `x ${MARKER}`, arguments: { a: MARKER } } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "n".repeat(500), arguments: {} } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 6, method: `tools/${MARKER} with spaces` }));
+    const { text, keys } = await routes();
+    expect(text).not.toContain(MARKER);
+    expect(text).not.toContain("n".repeat(65));
+    expect(keys).toContain("POST /mcp tools/call ?");
+    expect(keys).toContain("POST /mcp ?");
+    for (const k of keys) expect(k.length).toBeLessThan(200);
+  });
+
+  test("invalid JSON still gets the transport's parse error, labelled ?", async () => {
+    const r = await mcpRaw(admin, `{"jsonrpc":"2.0","method":"tools/list",`);
+    expect(r.status).toBe(400);
+    expect(rpc(r.text).error.code).toBe(-32700);
+    expect(rpc(r.text).error.message).toBe("Parse error: Invalid JSON");
+    const notRpc = await mcpRaw(admin, "null");
+    expect(notRpc.status).toBe(400);
+    expect(rpc(notRpc.text).error.code).toBe(-32700);
+  });
+
+  test("a body over the label limit is left to the transport and still works, labelled ?", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const padded = JSON.stringify({ jsonrpc: "2.0", id: 7, method: "tools/list" }).replace("{", "{" + " ".repeat(1024 * 1024 + 10));
+    const r = await mcpRaw(admin, padded);
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result.tools.length).toBeGreaterThan(10);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp ?");
+    expect(keys).not.toContain("POST /mcp tools/list");
+  });
+
+  test("unauthenticated /mcp is refused as before and not labelled", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const r = await mcpRaw("", JSON.stringify({ jsonrpc: "2.0", id: 8, method: "tools/list" }));
+    expect(r.status).toBe(401);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp");
+    expect(keys.filter(k => k.startsWith("POST /mcp "))).toEqual([]);
+  });
+});

package/src/route-timing.test.ts

@@ -1,7 +1,13 @@
 import { expect, test } from "bun:test";
-import { __resetRouteTimingForTest, recordRouteTiming, routeKey, routeStats, ROUTE_RING_SIZE } from "./route-timing";
+import {
+  __resetRouteTimingForTest, labelRoute, mcpRouteLabel, recordRouteTiming, routeKey, routeStats,
+  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");
@@ -13,12 +19,9 @@ test("routeKey collapses ids, aliases and file names, keeps payload-shaping para
   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 the ring keeps only the newest samples", () => {
+test("routeStats groups the window, sorts by total time, and counts every request (no sample cap)", () => {
   __resetRouteTimingForTest();
-  const now = 1_000_000;
-  const req = (path: string) => new Request(`http://hub${path}`);
-  const res = (status = 200, len?: number) => new Response("x", { status, headers: len === undefined ? {} : { "Content-Length": String(len) } });
-  const at = (ms: number) => performance.now() - ms;
+  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);
@@ -32,9 +35,103 @@ test("routeStats groups the window, sorts by total time, and the ring keeps only
   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);
-  for (let i = 0; i < ROUTE_RING_SIZE + 10; i++) recordRouteTiming(req("/api/tasks"), at(1), res(), now);
+  // 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.samples).toBe(ROUTE_RING_SIZE);
-  expect(after.routes.map(r => r.route)).toEqual(["GET /api/tasks"]);
+  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 ?");
 });

package/src/route-timing.ts

@@ -1,11 +1,29 @@
-// 每个路由的耗时环(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
-// 说不清是谁在吃 CPU。这里在 fetch 入口记最近 ROUTE_RING_SIZE 个请求(路由形状、耗时、状态、字节),
-// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者。
-export const ROUTE_RING_SIZE = 4096;
+// 每个路由的耗时统计(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
+// 说不清是谁在吃 CPU。这里在 fetch 入口按路由形状累计次数、耗时、状态、字节,
+// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者、不记请求体。
+//
+// 2026-10-01 —— 原来是 4096 条样本的环:生产上 212 s 就写满,?minutes=10 实际只覆盖三分半钟。
+// 改成按分钟分桶的累计器:每个桶里每个路由一行(次数 / 总耗时 / 最大值 / 字节 / 5xx / 耗时直方图),
+// 保留 ROUTE_BUCKET_RETENTION 个桶(24 小时),窗口多长就真覆盖多长。p95 从直方图取(桶上沿,不超过 max)。
+export const ROUTE_BUCKET_MS = 60_000;
+export const ROUTE_BUCKET_RETENTION = 1440;
+/** 每个分钟桶里最多这么多个不同的路由;再多的记到 ROUTE_OVERFLOW_KEY,防止怪路径 / 怪工具名把内存撑大。 */
+export const ROUTE_MAX_KEYS_PER_BUCKET = 256;
+export const ROUTE_OVERFLOW_KEY = "(other)";
 
-type Sample = { at: number; route: string; ms: number; status: number; bytes: number | null };
-const ring: Sample[] = [];
-let next = 0;
+// 耗时直方图:第 i 格的上沿 = HIST_BASE_MS · 2^(i/2),0.05 ms … ~52 s;最后一格收下更慢的。
+const HIST_BASE_MS = 0.05;
+const HIST_BINS = 41;
+function histBin(ms: number): number {
+  if (!(ms > HIST_BASE_MS)) return 0;
+  return Math.min(HIST_BINS - 1, Math.ceil(2 * Math.log2(ms / HIST_BASE_MS)));
+}
+const histUpper = (bin: number) => HIST_BASE_MS * 2 ** (bin / 2);
+
+type Agg = { count: number; totalMs: number; maxMs: number; bytes: number; errors: number; hist: Uint32Array };
+type Bucket = { minute: number; routes: Map<string, Agg> };
+// 按 minute 升序;新的一分钟追加在尾部,超出保留期从头部丢。
+const buckets: Bucket[] = [];
 
 /** 路由的形状:id / 别名 / 文件名这类段换成 :id,几个会改变载荷形状的参数保留(light / view / scope / changes)。 */
 const SHAPE_PARAMS = ["changes", "light", "scope", "view"];
@@ -18,46 +36,112 @@ export function routeKey(method: string, url: URL): string {
   return `${method} ${segments.join("/")}${shape ? `?${shape}` : ""}`;
 }
 
+// 处理器给某个请求补一段标签(比如 POST /mcp 的 JSON-RPC 方法名),recordRouteTiming 拼到路由形状后面。
+const labels = new WeakMap<Request, string>();
+export function labelRoute(req: Request, label: string): void {
+  labels.set(req, label);
+}
+
+const MCP_METHOD_RE = /^[A-Za-z][A-Za-z0-9_./-]{0,63}$/;
+const MCP_TOOL_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * POST /mcp 的标签:JSON-RPC 方法名,tools/call 再带工具名,如 "tools/call report_status"。
+ * 只读 method 和 params.name 两个字段,别的(尤其 arguments)一概不碰;形状不对的一律折成 "?",
+ * 批量请求记 "batch"。名字只放行短的 ASCII 标识符,防止拿请求体造出任意多、任意长的路由键。
+ */
+export function mcpRouteLabel(body: unknown): string {
+  if (Array.isArray(body)) return "batch";
+  if (!body || typeof body !== "object") return "?";
+  const method = (body as { method?: unknown }).method;
+  if (typeof method !== "string" || !MCP_METHOD_RE.test(method)) return "?";
+  if (method !== "tools/call") return method;
+  const params = (body as { params?: unknown }).params;
+  const name = params && typeof params === "object" ? (params as { name?: unknown }).name : undefined;
+  return `tools/call ${typeof name === "string" && MCP_TOOL_RE.test(name) ? name : "?"}`;
+}
+
 /** 记一次请求;原样返回 res,方便套在 fetch 处理器的 return 上。WebSocket 升级(res 为空)不记。 */
 export function recordRouteTiming<T extends Response | undefined>(req: Request, started: number, res: T, now: number = Date.now()): T {
   if (!res) return res;
   let url: URL;
   try { url = new URL(req.url); } catch { return res; }
+  const label = labels.get(req);
+  const route = label ? `${routeKey(req.method, url)} ${label}` : routeKey(req.method, url);
   const length = Number(res.headers.get("content-length"));
-  const sample: Sample = { at: now, route: routeKey(req.method, url), ms: performance.now() - started, status: res.status, bytes: Number.isFinite(length) && res.headers.has("content-length") ? length : null };
-  if (ring.length < ROUTE_RING_SIZE) ring.push(sample);
-  else ring[next] = sample;
-  next = (next + 1) % ROUTE_RING_SIZE;
+  const bytes = Number.isFinite(length) && res.headers.has("content-length") ? length : 0;
+  addSample(route, performance.now() - started, res.status, bytes, now);
   return res;
 }
 
+function addSample(route: string, ms: number, status: number, bytes: number, now: number): void {
+  const minute = Math.floor(now / ROUTE_BUCKET_MS);
+  let bucket = buckets[buckets.length - 1];
+  if (!bucket || minute > bucket.minute) {
+    buckets.push(bucket = { minute, routes: new Map() });
+    const oldest = minute - ROUTE_BUCKET_RETENTION + 1;
+    let drop = 0;
+    while (drop < buckets.length && buckets[drop].minute < oldest) drop++;
+    if (drop) buckets.splice(0, drop);
+  } else if (minute < bucket.minute) {
+    // 时间戳比最新的桶早(时钟回拨,或测试里乱序记):放回它自己的那一分钟;比保留期还早的丢掉。
+    if (minute < bucket.minute - ROUTE_BUCKET_RETENTION + 1) return;
+    let i = buckets.length - 1;
+    while (i > 0 && buckets[i - 1].minute >= minute) i--;
+    if (buckets[i].minute !== minute) buckets.splice(i, 0, { minute, routes: new Map() });
+    bucket = buckets[i];
+  }
+  let agg = bucket.routes.get(route);
+  if (!agg) {
+    if (bucket.routes.size >= ROUTE_MAX_KEYS_PER_BUCKET) route = ROUTE_OVERFLOW_KEY;
+    agg = bucket.routes.get(route);
+    if (!agg) bucket.routes.set(route, agg = { count: 0, totalMs: 0, maxMs: 0, bytes: 0, errors: 0, hist: new Uint32Array(HIST_BINS) });
+  }
+  agg.count++;
+  agg.totalMs += ms;
+  if (ms > agg.maxMs) agg.maxMs = ms;
+  agg.bytes += bytes;
+  if (status >= 500) agg.errors++;
+  agg.hist[histBin(ms)]++;
+}
+
 export type RouteStat = { route: string; count: number; total_ms: number; avg_ms: number; p95_ms: number; max_ms: number; bytes: number; errors: number };
 
-/** 最近 windowMs 内的样本按路由汇总,按总耗时降序。 */
+/**
+ * 最近 windowMs 内的请求按路由汇总,按总耗时降序。粒度是分钟桶:窗口起点落在哪个桶,就从那个桶算起。
+ * oldest_at 是窗口里最早一个有数据的桶的起点 —— 它比 now - window_ms 晚很多,说明 hub 是那之后才起来的。
+ */
 export function routeStats(windowMs: number, now: number = Date.now()): { window_ms: number; samples: number; oldest_at: string | null; routes: RouteStat[] } {
-  const since = now - windowMs;
-  const groups = new Map<string, Sample[]>();
+  const fromMinute = Math.floor((now - windowMs) / ROUTE_BUCKET_MS);
+  const merged = new Map<string, Agg>();
   let oldest: number | null = null;
-  for (const s of ring) {
-    if (s.at < since) continue;
-    if (oldest === null || s.at < oldest) oldest = s.at;
-    let g = groups.get(s.route);
-    if (!g) groups.set(s.route, g = []);
-    g.push(s);
+  for (const bucket of buckets) {
+    if (bucket.minute < fromMinute) continue;
+    if (oldest === null) oldest = bucket.minute * ROUTE_BUCKET_MS;
+    for (const [route, a] of bucket.routes) {
+      let m = merged.get(route);
+      if (!m) merged.set(route, m = { count: 0, totalMs: 0, maxMs: 0, bytes: 0, errors: 0, hist: new Uint32Array(HIST_BINS) });
+      m.count += a.count;
+      m.totalMs += a.totalMs;
+      if (a.maxMs > m.maxMs) m.maxMs = a.maxMs;
+      m.bytes += a.bytes;
+      m.errors += a.errors;
+      for (let i = 0; i < HIST_BINS; i++) m.hist[i] += a.hist[i];
+    }
   }
   const round = (n: number) => Math.round(n * 10) / 10;
-  const routes = [...groups].map(([route, samples]): RouteStat => {
-    const ms = samples.map(s => s.ms).sort((a, b) => a - b);
-    const total = ms.reduce((a, b) => a + b, 0);
+  const routes = [...merged].map(([route, a]): RouteStat => {
+    const rank = Math.min(a.count, Math.floor(a.count * 0.95) + 1);
+    let seen = 0, bin = 0;
+    for (; bin < HIST_BINS - 1; bin++) { seen += a.hist[bin]; if (seen >= rank) break; }
     return {
       route,
-      count: samples.length,
-      total_ms: round(total),
-      avg_ms: round(total / samples.length),
-      p95_ms: round(ms[Math.min(ms.length - 1, Math.floor(ms.length * 0.95))]),
-      max_ms: round(ms[ms.length - 1]),
-      bytes: samples.reduce((n, s) => n + (s.bytes ?? 0), 0),
-      errors: samples.filter(s => s.status >= 500).length,
+      count: a.count,
+      total_ms: round(a.totalMs),
+      avg_ms: round(a.totalMs / a.count),
+      p95_ms: round(Math.min(histUpper(bin), a.maxMs)),
+      max_ms: round(a.maxMs),
+      bytes: a.bytes,
+      errors: a.errors,
     };
   }).sort((a, b) => b.total_ms - a.total_ms);
   return { window_ms: windowMs, samples: routes.reduce((n, r) => n + r.count, 0), oldest_at: oldest === null ? null : new Date(oldest).toISOString(), routes };
@@ -65,6 +149,5 @@ export function routeStats(windowMs: number, now: number = Date.now()): { window
 
 /** Test-only. */
 export function __resetRouteTimingForTest(): void {
-  ring.length = 0;
-  next = 0;
+  buckets.length = 0;
 }

package/src/server.ts

@@ -61,7 +61,7 @@ import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js"
 import { diagnoseTask } from "./task-diagnostic.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
 import { handleRequirementsRequest } from "./requirements.js";
-import { recordRouteTiming, routeStats } from "./route-timing.js";
+import { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats } from "./route-timing.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
 import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
 import { SIDE_THREAD_FEATURE_FLAG, SideThreadCoordinator, SideThreadPortRegistry, SideThreadStore, type SideThreadActor, type SideThreadAttachmentRef, type SideThreadExecutionPort } from "./side-thread.js";
@@ -103,6 +103,9 @@ if (AUTH_TOKEN) {
   console.warn("[commhub] COMMHUB_AUTH_TOKEN is deprecated and will be removed in v1.0. See RFC-001.");
 }
 
+// POST /mcp bodies up to this size are parsed once up front to label the route (see the /mcp handler).
+const MCP_LABEL_MAX_BYTES = 1024 * 1024;
+
 // Read version from package.json so banners and /health stay in sync.
 const SERVER_VERSION = (() => {
   try {
@@ -111,6 +114,9 @@ const SERVER_VERSION = (() => {
   } catch { return "?"; }
 })();
 
+// Feature flags advertised on /health (see the /health handler). Exported for tests.
+export const HUB_HEALTH_CAPABILITIES = ["status_node_id"] as const;
+
 // In-memory log ring buffer — last N lines streamed via /api/server-logs.
 // Wraps console.log/info/warn/error so EVERY existing log call lands here
 // without source changes. Dashboard tails this buffer for "hub server log
@@ -941,9 +947,22 @@ return Bun.serve({
       const transport = new WebStandardStreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
       });
+      // 2026-10-01 —— /api/stats/routes 里 POST /mcp 是最大的一项(生产 15 req/s),但看不出是哪个工具。
+      // 请求体我们自己读一次、解析一次,只取 method / params.name 做路由标签(mcpRouteLabel),
+      // 解析结果作为 parsedBody 交给 transport,不重复解析。没有 Content-Length 或超过 MCP_LABEL_MAX_BYTES
+      // 的请求体不碰,由 transport 照旧自己读。不是合法 JSON 时不传 parsedBody:transport 读已消费的
+      // body 失败,落进它自己的 catch,回的仍是原来那条 -32700「Parse error: Invalid JSON」(测试钉住)。
+      let mcpParsedBody: unknown;
+      if (req.method === "POST") {
+        const declared = Number(req.headers.get("content-length"));
+        if (req.headers.has("content-length") && Number.isFinite(declared) && declared <= MCP_LABEL_MAX_BYTES) {
+          try { mcpParsedBody = JSON.parse(await req.text()); } catch { mcpParsedBody = undefined; }
+        }
+        labelRoute(req, mcpParsedBody === undefined ? "?" : mcpRouteLabel(mcpParsedBody));
+      }
       const mcpServer = createServer(clientIP, enforceNetId, authCtx?.userId || null, callerAlias, !!token?.startsWith("ntok_"), authCtx?.tokenId || null);
       await mcpServer.connect(transport);
-      const response = await transport.handleRequest(req);
+      const response = await transport.handleRequest(req, mcpParsedBody === undefined ? undefined : { parsedBody: mcpParsedBody });
       // Disconnect after response to prevent McpServer leak
       setImmediate(() => mcpServer.close().catch(() => {}));
       // #426: the MCP SDK's WebStandardStreamableHTTPServerTransport builds
@@ -2007,6 +2026,11 @@ return Bun.serve({
           max_upload_bytes: MAX_UPLOAD_BYTES,
           max_request_content_length: MAX_REQUEST_CONTENT_LENGTH,
         },
+        // Public, stable feature flags for REST reads whose own response can't carry them.
+        // status_node_id: GET /api/status accepts ?node_id=<id> (one node's rows; with light=1 the
+        // row also carries node_id). The /api/status body stays byte-identical without the param, so
+        // the flag lives here — agent-nodes already read /health once at boot.
+        capabilities: HUB_HEALTH_CAPABILITIES,
       };
       if (scopedSessions !== undefined) body.sse_sessions = scopedSessions;
       return withCors(req, Response.json(body));
@@ -2180,9 +2204,10 @@ return Bun.serve({
       // is unchanged so the dashboard / scripts that read full telemetry are
       // unaffected.
       const isLight = url.searchParams.get("light") === "1";
+      const nodeIdFilter = url.searchParams.get("node_id")?.trim();
       const params: any[] = [];
       let sql = isLight
-        ? "SELECT alias, status, agent, task, server, updated_at, network_id FROM sessions WHERE 1=1"
+        ? `SELECT alias, status, agent, task, server, updated_at, network_id${nodeIdFilter ? ", node_id" : ""} FROM sessions WHERE 1=1`
         : `SELECT ${SESSION_REST_SELECT} FROM sessions WHERE 1=1`;
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });
       // `?alias=<name>` narrows to that one agent's rows (same projection, same scope). The app's
@@ -2195,6 +2220,15 @@ return Bun.serve({
         params.push(aliasFilter);
         sql += ` AND alias = ?${params.length}`;
       }
+      // `?node_id=<id>` narrows to one node's rows the same way (same scope, same projection). Every
+      // agent-node resolves its own current alias every 30 s; unfiltered that is the whole network's
+      // full projection (~91 KB gzip per call on production) to read one row. Advertised in /health
+      // `capabilities` ("status_node_id") because old hubs ignore the parameter and — in the light
+      // projection, which has no node_id — the caller could not tell its row from anyone else's.
+      if (nodeIdFilter) {
+        params.push(nodeIdFilter);
+        sql += ` AND node_id = ?${params.length}`;
+      }
       sql += " ORDER BY updated_at DESC";
       // `model` comes straight from the explicit sessions projection; `runtime` is
       // derived from the raw `agent` field. Both default to null for old nodes
@@ -2211,6 +2245,8 @@ return Bun.serve({
             updated_at: s.updated_at ?? null,
             runtime: normalizeRuntime(s.agent),
             network_id: s.network_id ?? null,
+            // Only when filtering by node_id, so the unfiltered light response keeps its exact bytes.
+            ...(nodeIdFilter ? { node_id: s.node_id ?? null } : {}),
           };
         }
         const externalSchedules = (() => {

package/src/status-node-id-filter-http.test.ts

@@ -0,0 +1,161 @@
+// GET /api/status?node_id=<id> — one node's rows instead of the whole network.
+// Every agent-node resolves its own current alias every 30 s (CurrentAliasResolver). Unfiltered that
+// is the whole network's full projection (~91 KB gzip per call on production, ~90 nodes ⇒ ~3 req/s)
+// to read one row. This suite pins that the filter narrows, never widens (it is exactly the caller's
+// unfiltered rows with that node_id, for every kind of caller), that it combines with light=1 (which
+// then carries node_id so the caller can check the row is its own), that an unknown id is an empty
+// list rather than an error, that no/blank node_id is byte-identical to the old response, and that
+// /health advertises it.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-node-id-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusNodeIdPassw0rd!";
+let aToken = "", aId = "", NET_A = "";
+let bToken = "", bId = "", NET_B = "";
+let nodeToken = "";
+
+async function raw(token: string | null, path: string) {
+  const res = await fetch(`${BASE}${path}`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+  return { status: res.status, text: await res.text() };
+}
+async function get(token: string, path: string) {
+  const r = await raw(token, path);
+  return { status: r.status, body: JSON.parse(r.text) as any };
+}
+function seed(alias: string, node: string, net: string, owner: string, minutesAgo: number) {
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, net, owner]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, ?5, datetime('now', ?6), datetime('now'))`,
+    [`r_${node}`, alias, node, net, `task of ${alias}`, `-${minutesAgo} minutes`],
+  );
+}
+const nodeIds = (rows: any[]) => rows.map(r => r.node_id);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sn_owner_a_${Date.now()}`, PW);
+  aToken = a.token!; aId = a.user!.user_id; NET_A = a.network_id!;
+  const b = register(`sn_owner_b_${Date.now()}`, PW);
+  bToken = b.token!; bId = b.user!.user_id; NET_B = b.network_id!;
+  seed("sn-one", "node_sn_one", NET_A, aId, 1);
+  seed("sn-two", "node_sn_two", NET_A, aId, 2);
+  seed("sn-three", "node_sn_three", NET_A, aId, 3);
+  seed("sn-b-only", "node_sn_b_only", NET_B, bId, 0);
+  const minted = createNetworkTokenForNode(aId, NET_A, "sn-two", "node_sn_two");
+  nodeToken = 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("/api/status?node_id=", () => {
+  test("node_id narrows the full projection to that node", async () => {
+    const r = await get(aToken, `/api/status?network_id=${NET_A}&node_id=node_sn_two`);
+    expect(r.status).toBe(200);
+    expect(nodeIds(r.body.sessions)).toEqual(["node_sn_two"]);
+    expect(r.body.sessions[0].alias).toBe("sn-two");
+    expect(typeof r.body.sessions[0].rules_file_capable).toBe("boolean");
+    expect(r.body.sessions[0].host).toBeDefined();
+    expect(r.body.summary.total).toBe(1);
+  });
+
+  test("combines with light=1: light projection, one row, and it carries node_id", async () => {
+    const r = await get(aToken, `/api/status?light=1&network_id=${NET_A}&node_id=node_sn_three`);
+    expect(r.status).toBe(200);
+    expect(r.body.sessions).toHaveLength(1);
+    expect(r.body.sessions[0].alias).toBe("sn-three");
+    expect(r.body.sessions[0].node_id).toBe("node_sn_three");
+    expect(r.body.sessions[0].host).toBeUndefined();
+    expect(Object.keys(r.body.sessions[0]).sort()).toEqual(
+      ["agent", "alias", "network_id", "node_id", "runtime", "server", "status", "task", "updated_at"],
+    );
+  });
+
+  test("unknown id is an empty list with 200, not a 404", async () => {
+    for (const path of [`/api/status?network_id=${NET_A}&node_id=node_nobody`, `/api/status?light=1&node_id=node_nobody`]) {
+      const r = await get(aToken, path);
+      expect(r.status).toBe(200);
+      expect(r.body.ok).toBe(true);
+      expect(r.body.sessions).toEqual([]);
+      expect(r.body.summary.total).toBe(0);
+    }
+  });
+
+  test("absent or blank node_id: response bytes identical to the old read (full and light)", async () => {
+    for (const base of [`/api/status?network_id=${NET_A}`, `/api/status?light=1&network_id=${NET_A}`, `/api/status`]) {
+      const plain = await raw(aToken, base);
+      const blank = await raw(aToken, `${base}${base.includes("?") ? "&" : "?"}node_id=%20`);
+      expect(plain.status).toBe(200);
+      expect(blank.text).toBe(plain.text);
+    }
+    // the light rows without the param never gained a node_id field
+    const light = await get(aToken, `/api/status?light=1&network_id=${NET_A}`);
+    expect(light.body.sessions.length).toBe(3);
+    for (const s of light.body.sessions) expect("node_id" in s).toBe(false);
+  });
+
+  test("never widens: for every caller, filtered == that caller's unfiltered rows with that node_id", async () => {
+    const callers = [aToken, bToken, nodeToken];
+    const ids = ["node_sn_one", "node_sn_two", "node_sn_three", "node_sn_b_only", "node_nobody"];
+    for (const tok of callers) {
+      const full = await get(tok, `/api/status`);
+      expect(full.status).toBe(200);
+      for (const id of ids) {
+        const one = await get(tok, `/api/status?node_id=${id}`);
+        expect(one.status).toBe(full.status);
+        expect(one.body.sessions).toEqual(full.body.sessions.filter((s: any) => s.node_id === id));
+      }
+    }
+  });
+
+  test("a member of another network gets nothing for a node outside their network", async () => {
+    const r = await get(bToken, `/api/status?node_id=node_sn_one`);
+    expect(r.status).toBe(200);
+    expect(r.body.sessions).toEqual([]);
+    const own = await get(bToken, `/api/status?node_id=node_sn_b_only`);
+    expect(nodeIds(own.body.sessions)).toEqual(["node_sn_b_only"]);
+  });
+
+  test("a node token reads its own row (light) and nothing from another network", async () => {
+    const own = await get(nodeToken, `/api/status?light=1&node_id=node_sn_two`);
+    expect(own.status).toBe(200);
+    expect(own.body.sessions.map((s: any) => [s.node_id, s.alias])).toEqual([["node_sn_two", "sn-two"]]);
+    const foreign = await get(nodeToken, `/api/status?light=1&node_id=node_sn_b_only`);
+    expect(foreign.status).toBe(200);
+    expect(foreign.body.sessions).toEqual([]);
+    // explicit other network_id is refused exactly as without the filter
+    const cross = await raw(nodeToken, `/api/status?network_id=${NET_B}&node_id=node_sn_b_only`);
+    const crossNoFilter = await raw(nodeToken, `/api/status?network_id=${NET_B}`);
+    expect(cross.status).toBe(crossNoFilter.status);
+    if (cross.status !== 200) expect(cross.text).toBe(crossNoFilter.text);
+    else expect(JSON.parse(cross.text).sessions).toEqual([]);
+  });
+
+  test("unauthenticated read is refused exactly as without the filter", async () => {
+    const withFilter = await raw(null, `/api/status?node_id=node_sn_one`);
+    const without = await raw(null, `/api/status`);
+    expect(withFilter.status).toBe(without.status);
+    expect(withFilter.text).toBe(without.text);
+  });
+
+  test("/health advertises status_node_id", async () => {
+    const r = await raw(null, `/health`);
+    expect(r.status).toBe(200);
+    expect(JSON.parse(r.text).capabilities).toContain("status_node_id");
+  });
+});