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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.78",
+  "version": "0.9.0-preview.79",
   "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/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

@@ -1,6 +1,7 @@
 import { expect, test } from "bun:test";
 import {
-  __resetRouteTimingForTest, labelRoute, mcpRouteLabel, recordRouteTiming, routeKey, routeStats,
+  __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";
 
@@ -135,3 +136,76 @@ test("mcpRouteLabel: method, tool name, and nothing else", () => {
   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);
+});

package/src/route-timing.ts

@@ -1,6 +1,6 @@
 // 每个路由的耗时统计(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
 // 说不清是谁在吃 CPU。这里在 fetch 入口按路由形状累计次数、耗时、状态、字节,
-// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者、不记请求体。
+// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记请求体;调用者只记粗粒度类别(见下文 callerClass)。
 //
 // 2026-10-01 —— 原来是 4096 条样本的环:生产上 212 s 就写满,?minutes=10 实际只覆盖三分半钟。
 // 改成按分钟分桶的累计器:每个桶里每个路由一行(次数 / 总耗时 / 最大值 / 字节 / 5xx / 耗时直方图),
@@ -20,7 +20,8 @@ function histBin(ms: number): number {
 }
 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 Agg = { count: number; totalMs: number; maxMs: number; bytes: number; errors: number; hist: Uint32Array; callers?: Map<string, CallerAgg> };
+type CallerAgg = { count: number; bytes: number };
 type Bucket = { minute: number; routes: Map<string, Agg> };
 // 按 minute 升序;新的一分钟追加在尾部,超出保留期从头部丢。
 const buckets: Bucket[] = [];
@@ -60,6 +61,77 @@ export function mcpRouteLabel(body: unknown): string {
   return `tools/call ${typeof name === "string" && MCP_TOOL_RE.test(name) ? name : "?"}`;
 }
 
+// ── 调用方分类(2026-10-01)────────────────────────────────────────────────────────────
+// 生产上全量 GET /api/status 每秒 ~2.8 次,但大多数连接经 frp 隧道进来,来源全是 127.0.0.1,也没有访问日志,
+// 看不出是谁在拉。每个请求再记一个粗粒度的「调用方类别」= 令牌种类 + User-Agent 家族,
+// GET /api/stats/routes?by=caller 按路由给出各类别的次数 / 字节。
+// 🔴 只记类别:不记令牌、用户 / 节点 id、IP、完整 UA。UA 只认白名单里的产品名(其余一律 "other"),
+//    版本号只放行数字 + 一段预发布标记,浏览器一律折成 "browser"。
+/** 每个分钟桶里每个路由最多这么多个调用方类别;再多的记到 ROUTE_OVERFLOW_KEY。汇总输出也只给前这么多个。 */
+export const ROUTE_MAX_CALLERS_PER_ROUTE = 20;
+
+let masterToken = "";
+/** 启动时把 COMMHUB_AUTH_TOKEN 交进来,用于把它认成 "master";只做相等比较,不输出。 */
+export function setRouteCallerMasterToken(token: string | undefined): void {
+  masterToken = token || "";
+}
+
+// 取令牌走 server.ts 的 requestToken()(启动时交进来),与鉴权同一个优先级:先 Authorization,再 ?token=。
+// 这里不自己读 ?token=(query-token-ratchet 只许减少直接读的地方)。没交进来时只看 Authorization 头。
+let readToken: (req: Request) => string = req => req.headers.get("authorization")?.replace("Bearer ", "") || "";
+/** 返回原来的读取函数(测试用来还原)。 */
+export function setRouteCallerTokenReader(reader: (req: Request) => string): (req: Request) => string {
+  const previous = readToken;
+  readToken = reader;
+  return previous;
+}
+
+/** 令牌种类:ntok_ → node,utok_ → user,等于 master 令牌 → master,别的非空令牌 → token,没有 → anon。 */
+export function callerTokenKind(req: Request): string {
+  const token = readToken(req);
+  if (!token) return "anon";
+  if (token.startsWith("ntok_")) return "node";
+  if (token.startsWith("utok_")) return "user";
+  if (masterToken && token === masterToken) return "master";
+  return "token";
+}
+
+// UA 的第一个产品名(小写)→ 输出用的名字。只有这里列出的名字会原样出现在统计里。
+const UA_PRODUCTS = new Map([
+  "agent-node", "agent-network", "anet", "agent-network-desktop", "agent-network-dashboard", "commhub-server", "tauri-plugin-http",
+  "claude-code", "node", "undici", "node-fetch", "axios", "got", "bun", "deno", "okhttp", "cfnetwork", "dalvik",
+  "curl", "wget", "python-requests", "python-httpx", "python-urllib", "aiohttp", "go-http-client", "reqwest",
+  "postmanruntime", "httpie", "powershell",
+].map(n => [n, n]));
+const UA_HEAD_RE = /^([A-Za-z][A-Za-z0-9._-]{0,40})(?:\/(\S{1,64}))?/;
+const UA_VERSION_RE = /^\d{1,6}(?:\.\d{1,6}){0,2}(?:-[A-Za-z]{1,16}(?:\.\d{1,6})?)?/;
+
+/**
+ * User-Agent 家族:"agent-node/2.5.0-preview.88"、"node"、"Bun/1.2.3" → "bun/1.2.3"、"okhttp/4.12.0"、
+ * "curl/8.5.0";Mozilla/… → "browser";没有 UA → "none";不在白名单 → "other"。
+ * iOS 的 RN fetch 形如 "<App>/<build> CFNetwork/… Darwin/…",第一个产品名是 app 自己的,认 CFNetwork 记成 "cfnetwork"。
+ */
+export function userAgentFamily(ua: string | null): string {
+  const s = (ua || "").trim();
+  if (!s) return "none";
+  if (s.startsWith("Mozilla/")) return "browser";
+  const head = UA_HEAD_RE.exec(s);
+  let name = head ? UA_PRODUCTS.get(head[1].toLowerCase()) : undefined;
+  let rawVersion = head?.[2];
+  if (!name) {
+    if (!/\sCFNetwork\//.test(s)) return "other";
+    name = "cfnetwork";
+    rawVersion = /\sCFNetwork\/(\S{1,64})/.exec(s)?.[1];
+  }
+  const version = rawVersion ? UA_VERSION_RE.exec(rawVersion)?.[0] : undefined;
+  return version ? `${name}/${version}` : name;
+}
+
+/** 一个请求的调用方类别,如 "node agent-node/2.5.0-preview.88"、"user browser"、"anon none"。 */
+export function callerClass(req: Request): string {
+  return `${callerTokenKind(req)} ${userAgentFamily(req.headers.get("user-agent"))}`;
+}
+
 /** 记一次请求;原样返回 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;
@@ -69,11 +141,11 @@ export function recordRouteTiming<T extends Response | undefined>(req: Request,
   const route = label ? `${routeKey(req.method, url)} ${label}` : routeKey(req.method, url);
   const length = Number(res.headers.get("content-length"));
   const bytes = Number.isFinite(length) && res.headers.has("content-length") ? length : 0;
-  addSample(route, performance.now() - started, res.status, bytes, now);
+  addSample(route, performance.now() - started, res.status, bytes, now, callerClass(req));
   return res;
 }
 
-function addSample(route: string, ms: number, status: number, bytes: number, now: number): void {
+function addSample(route: string, ms: number, status: number, bytes: number, now: number, caller: string): void {
   const minute = Math.floor(now / ROUTE_BUCKET_MS);
   let bucket = buckets[buckets.length - 1];
   if (!bucket || minute > bucket.minute) {
@@ -102,15 +174,25 @@ function addSample(route: string, ms: number, status: number, bytes: number, now
   agg.bytes += bytes;
   if (status >= 500) agg.errors++;
   agg.hist[histBin(ms)]++;
+  const callers = agg.callers ??= new Map();
+  let c = callers.get(caller);
+  if (!c) {
+    if (callers.size >= ROUTE_MAX_CALLERS_PER_ROUTE) caller = ROUTE_OVERFLOW_KEY;
+    c = callers.get(caller);
+    if (!c) callers.set(caller, c = { count: 0, bytes: 0 });
+  }
+  c.count++;
+  c.bytes += bytes;
 }
 
-export type RouteStat = { route: string; count: number; total_ms: number; avg_ms: number; p95_ms: number; max_ms: number; bytes: number; errors: number };
+export type RouteStat = { route: string; count: number; total_ms: number; avg_ms: number; p95_ms: number; max_ms: number; bytes: number; errors: number; callers?: CallerStat[] };
+export type CallerStat = { class: string; count: number; bytes: number };
 
 /**
  * 最近 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[] } {
+export function routeStats(windowMs: number, now: number = Date.now(), opts: { byCaller?: boolean } = {}): { window_ms: number; samples: number; oldest_at: string | null; routes: RouteStat[] } {
   const fromMinute = Math.floor((now - windowMs) / ROUTE_BUCKET_MS);
   const merged = new Map<string, Agg>();
   let oldest: number | null = null;
@@ -126,6 +208,13 @@ export function routeStats(windowMs: number, now: number = Date.now()): { window
       m.bytes += a.bytes;
       m.errors += a.errors;
       for (let i = 0; i < HIST_BINS; i++) m.hist[i] += a.hist[i];
+      if (opts.byCaller && a.callers) {
+        const mc = m.callers ??= new Map();
+        for (const [cls, c] of a.callers) {
+          const t = mc.get(cls);
+          if (t) { t.count += c.count; t.bytes += c.bytes; } else mc.set(cls, { count: c.count, bytes: c.bytes });
+        }
+      }
     }
   }
   const round = (n: number) => Math.round(n * 10) / 10;
@@ -142,11 +231,27 @@ export function routeStats(windowMs: number, now: number = Date.now()): { window
       max_ms: round(a.maxMs),
       bytes: a.bytes,
       errors: a.errors,
+      ...(opts.byCaller ? { callers: callerStats(a.callers) } : {}),
     };
   }).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 };
 }
 
+/** 按次数降序;各分钟桶的类别合起来可能超过上限,超出的并进 ROUTE_OVERFLOW_KEY。 */
+function callerStats(callers: Map<string, CallerAgg> | undefined): CallerStat[] {
+  let other: CallerStat | undefined;
+  const named: CallerStat[] = [];
+  for (const [cls, c] of callers ?? []) {
+    if (cls === ROUTE_OVERFLOW_KEY) other = { class: cls, count: c.count, bytes: c.bytes };
+    else named.push({ class: cls, count: c.count, bytes: c.bytes });
+  }
+  named.sort((a, b) => b.count - a.count || b.bytes - a.bytes || (a.class < b.class ? -1 : 1));
+  if (!other && named.length <= ROUTE_MAX_CALLERS_PER_ROUTE) return named;
+  other ??= { class: ROUTE_OVERFLOW_KEY, count: 0, bytes: 0 };
+  for (const r of named.splice(ROUTE_MAX_CALLERS_PER_ROUTE - 1)) { other.count += r.count; other.bytes += r.bytes; }
+  return [...named, other];
+}
+
 /** Test-only. */
 export function __resetRouteTimingForTest(): void {
   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 { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats } from "./route-timing.js";
+import { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats, setRouteCallerMasterToken, setRouteCallerTokenReader } 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";
@@ -72,6 +72,8 @@ import { parseHubTimestamp } from "./hub-timestamp";
 const PORT = resolvePort(process.env.PORT);
 const HOST = process.env.HOST || "127.0.0.1";
 const AUTH_TOKEN = process.env.COMMHUB_AUTH_TOKEN;
+setRouteCallerMasterToken(AUTH_TOKEN);
+setRouteCallerTokenReader(req => requestToken(req)); // 函数声明会提升;与鉴权同一个取令牌优先级
 const DEV_OPEN = process.argv.includes("--dev-open") || process.env.COMMHUB_DEV_OPEN === "1";
 const TMUX_ENABLED = process.env.COMMHUB_ENABLE_TMUX === "1";
 const SECURITY_LABEL = DEV_OPEN ? "⚠️ DEV OPEN MODE" : "🔒 secured";
@@ -2154,12 +2156,14 @@ return Bun.serve({
 
     // ── REST: per-route timing (ops-only, same gate as /api/stats/sse) ──
     // ?minutes=N(默认 15,最多 1440):最近 N 分钟里每个路由的次数、总耗时、p95、最大、字节。
+    // &by=caller:每个路由再带 callers —— 令牌种类 + UA 家族的次数 / 字节(route-timing.ts callerClass)。不带时输出逐字节不变。
     if (url.pathname === "/api/stats/routes" && req.method === "GET") {
       if (restAuth && !isAdmin) {
         return withCors(req, Response.json({ ok: false, error: "admin or master token required" }, { status: 403 }));
       }
       const minutes = Math.min(Math.max(Number(url.searchParams.get("minutes")) || 15, 1), 1440);
-      return withCors(req, Response.json({ ok: true, ...routeStats(minutes * 60_000) }));
+      const byCaller = url.searchParams.get("by") === "caller";
+      return withCors(req, Response.json({ ok: true, ...routeStats(minutes * 60_000, Date.now(), { byCaller }) }));
     }
 
     // ── #473 REST: SSE connection detail (ops-only) ──