@sleep2agi/commhub-server 0.9.0-preview.7 → 0.9.0-preview.71

package/src/agent-acl-slice3-http.test.ts

@@ -0,0 +1,267 @@
+// 多用户账号与 Agent 权限 —— slice 3:剩下的面向 Agent 的路径。
+//
+// slice 1(agent-acl-http.test.ts)把默认作用域做成 fail-closed,并对核心路径逐条放行。
+// 这里补:授权后 task_events / messages 的「只看自己往来」、改名广播不外泄 alias、
+// 排程在建的人被收权后不再代派、用户名与后注册的 Agent alias 撞名、以及
+// rules / skills / files / logs 对受限成员(即使授权了)仍然拒绝 —— 这是一个明确的产品决定:
+// 授权 = 能看见、能对话;不等于能管理这个 Agent。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+import { replaceAgentGrants } from "./agent-access.js";
+import { dispatchScheduledOccurrence } from "./scheduled-tasks.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-acl3-"));
+let BASE = "";
+let hub: any = null;
+const PW = "AclSlice3Passw0rd!";
+let adminToken = "", adminId = "", adminName = "", NET = "";
+let carolToken = "", carolId = "";
+
+const X = { alias: "acl3-agent-x", node: "node_acl3_x" };
+const Z = { alias: "acl3-agent-z", node: "node_acl3_z" };
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+
+async function get(token: string, path: string) {
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { ...auth(token), "Content-Type": "application/json" }, body: payload === undefined ? undefined : JSON.stringify(payload) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function tool(token: string, name: string, args: Record<string, unknown>) {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { ...auth(token), "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const data = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = data.length ? JSON.parse(data.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = payload.result.content[0].text;
+  // 参数没过 zod 的调用根本没进到处理函数(也就没进到权限判定),当成测试写错了而不是「被拒」。
+  if (!text.startsWith("{")) throw new Error(`${name}: ${text}`);
+  return JSON.parse(text);
+}
+function seedAgent(a: { alias: string; node: string }) {
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [a.node, a.alias, NET, adminId]);
+  db.run(`INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`, [`r_${a.node}`, a.alias, a.node, NET]);
+}
+function seedTask(id: string, from: string, to: string, content: string) {
+  db.run(`INSERT INTO tasks (task_id, from_name, to_name, status, content, network_id) VALUES (?1, ?2, ?3, 'replied', ?4, ?5)`, [id, from, to, content, NET]);
+  db.run(`INSERT INTO inbox (id, task_id, session_name, type, priority, content, from_session, network_id) VALUES (?1, ?2, ?3, 'task', 'normal', ?4, ?5, ?6)`, [`ib_${id}`, id, to, content, from, NET]);
+  db.run(`INSERT INTO task_events (task_id, to_status, actor, network_id) VALUES (?1, 'replied', 'test', ?2)`, [id, NET]);
+}
+async function openStream(path: string, token: string) {
+  const ctrl = new AbortController();
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token), signal: ctrl.signal });
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  let pending: ReturnType<typeof reader.read> | null = null;
+  const readFor = async (ms: number) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      pending ??= reader.read();
+      const chunk = await Promise.race([pending, new Promise<null>(r => setTimeout(() => r(null), until - Date.now()))]);
+      if (!chunk) break;
+      pending = null;
+      if (chunk.done) break;
+      buf += decoder.decode(chunk.value);
+    }
+  };
+  return { status: res.status, readFor, events: () => buf.split("\n").filter(l => l.startsWith("data:")).map(l => JSON.parse(l.slice(5))), close: () => ctrl.abort() };
+}
+
+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";
+  adminName = `acl3_admin_${Date.now()}`;
+  const admin = register(adminName, PW);
+  adminToken = admin.token!; adminId = admin.user!.user_id; NET = admin.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  seedAgent(X); seedAgent(Z);
+  const carol = register("acl3_carol", PW);
+  carolToken = carol.token!; carolId = carol.user!.user_id;
+  expect(addNetworkMember(NET, carolId, "member", adminId).ok).toBe(true);
+  expect(replaceAgentGrants({ networkId: NET, userId: carolId, grants: [{ node_id: X.node }], actorUserId: adminId }).ok).toBe(true);
+  seedTask("t3_admin_x", adminName, X.alias, "admin to X");
+  seedTask("t3_carol_x", "acl3_carol", X.alias, "carol to X");
+  seedTask("t3_x_carol", X.alias, "acl3_carol", "X to carol");
+  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("granted member: task_events and messages are limited to own traffic", () => {
+  test("task_events: own exchange with X visible, admin's task to X not", async () => {
+    const mine = await get(carolToken, `/api/task_events?task_id=t3_carol_x`);
+    expect(mine.body.events.length).toBe(1);
+    expect((await get(carolToken, `/api/task_events?task_id=t3_x_carol`)).body.events.length).toBe(1);
+    expect((await get(carolToken, `/api/task_events?task_id=t3_admin_x`)).body.events).toEqual([]);
+    const all = await get(carolToken, `/api/task_events?network_id=${NET}`);
+    expect(all.body.events.map((e: any) => e.task_id).sort()).toEqual(["t3_carol_x", "t3_x_carol"]);
+  });
+  test("messages (alias branch): own inbox rows with X only; admin's never", async () => {
+    const r = await get(carolToken, `/api/messages?network_id=${NET}&since=2000-01-01`);
+    expect(r.body.messages.map((m: any) => m.content).sort()).toEqual(["X to carol", "carol to X"].sort());
+    const x = await get(carolToken, `/api/messages?alias=${X.alias}&since=2000-01-01`);
+    expect(x.body.messages.map((m: any) => m.content)).toEqual(["carol to X"]);
+    expect(x.body.pending_count).toBe(1);
+  });
+});
+
+describe("decision: granted ≠ administer — rules / skills / files / logs / config stay refused", () => {
+  test("every read and write admin op on the GRANTED agent is refused", async () => {
+    for (const [name, args] of [
+      ["read_node_rules_file", { alias: X.alias, network_id: NET }],
+      ["write_node_rules_file", { alias: X.alias, content: "x", network_id: NET }],
+      ["list_node_skills", { alias: X.alias, network_id: NET }],
+      ["list_node_files", { alias: X.alias, network_id: NET }],
+      ["tail_node_logs", { alias: X.alias, network_id: NET }],
+      ["update_node_config", { node_id: X.node, base_revision: 0, patch: { model: "m" }, network_id: NET }],
+      ["restart_node", { node_id: X.node, network_id: NET }],
+    ] as const) {
+      expect((await tool(carolToken, name, args as any)).error).toBe("agent_access_restricted");
+    }
+    expect((await send(carolToken, "PUT", `/api/nodes/${X.node}/attrs?network_id=${NET}`, { display_name: "pwned" })).status).toBeGreaterThanOrEqual(403);
+    expect(db.get<{ display_name: string | null }>("SELECT display_name FROM nodes WHERE node_id = ?1", X.node)?.display_name ?? null).toBeNull();
+  });
+});
+
+describe("rename broadcast does not leak aliases to restricted members", () => {
+  test("renaming Z (not granted) sends nothing to carol; renaming X (granted) does", async () => {
+    const s = await openStream(`/events/acl3_carol?network_id=${NET}`, carolToken);
+    expect(s.status).toBe(200);
+    await s.readFor(100);
+    const renameTo = async (oldAlias: string, newAlias: string) => {
+      const p = await send(adminToken, "POST", "/api/node-rename/prepare", { network_id: NET, old_alias: oldAlias, new_alias: newAlias });
+      expect(p.body.ok).toBe(true);
+      expect((await send(adminToken, "POST", "/api/node-rename/commit", { txn_id: p.body.txn_id })).body.ok).toBe(true);
+    };
+    await renameTo(Z.alias, "acl3-agent-z2");
+    await renameTo(X.alias, "acl3-agent-x2");
+    await s.readFor(400);
+    s.close();
+    const renamed = s.events().filter(e => e.type === "node.renamed").map(e => e.data.new_alias);
+    expect(renamed).toEqual(["acl3-agent-x2"]);
+    // 改名后授权(按 node_id)仍然有效。
+    expect((await get(carolToken, `/api/status?network_id=${NET}`)).body.sessions.map((r: any) => r.alias)).toEqual(["acl3-agent-x2"]);
+    await renameTo("acl3-agent-z2", Z.alias);
+    await renameTo("acl3-agent-x2", X.alias);
+  });
+});
+
+describe("schedules created before a restriction stop dispatching", () => {
+  function schedule(createdBy: string, target: { alias: string; node: string }) {
+    const id = `sched_acl3_${createdBy}_${target.node}`;
+    db.run(
+      `INSERT INTO scheduled_tasks (schedule_id, network_id, created_by, name, target_node_id, target_alias, task_content, schedule_type, schedule_json, next_run_at)
+       VALUES (?1, ?2, ?3, 'n', ?4, ?5, 'scheduled work', 'interval', '{"type":"interval","minutes":60}', datetime('now'))`,
+      [id, NET, createdBy, target.node, target.alias],
+    );
+    return db.get<any>("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", id);
+  }
+  test("carol (restricted) → Z (not granted): run fails creator_access_revoked, no task created", () => {
+    const row = schedule(carolId, Z);
+    const r = dispatchScheduledOccurrence(row, new Date().toISOString(), false);
+    expect(r.status).toBe("failed");
+    expect(r.taskId).toBeUndefined();
+    expect(db.get<{ error_code: string }>("SELECT error_code FROM scheduled_task_runs WHERE run_id = ?1", r.runId)?.error_code).toBe("creator_access_revoked");
+  });
+  test("carol → X (granted, can_message): dispatches", () => {
+    const r = dispatchScheduledOccurrence(schedule(carolId, X), new Date(Date.now() + 1000).toISOString(), false);
+    expect(r.taskId).toBeTruthy();
+  });
+  test("owner-created schedules are unaffected", () => {
+    const r = dispatchScheduledOccurrence(schedule(adminId, Z), new Date(Date.now() + 2000).toISOString(), false);
+    expect(r.taskId).toBeTruthy();
+  });
+});
+
+describe("username collides with an agent alias registered later", () => {
+  test("carol's own channel and own traffic close for that network", async () => {
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks.length).toBeGreaterThan(0);
+    db.run(`INSERT INTO sessions (resume_id, alias, status, network_id, updated_at, last_seen_at) VALUES ('r_collide', 'acl3_carol', 'idle', ?1, datetime('now'), datetime('now'))`, [NET]);
+    const s = await fetch(`${BASE}/events/acl3_carol?network_id=${NET}`, { headers: auth(carolToken) });
+    expect(s.status).toBe(403);
+    await s.body?.cancel();
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks).toEqual([]);
+    expect((await get(carolToken, `/api/messages?network_id=${NET}&since=2000-01-01`)).body.messages).toEqual([]);
+    db.run("DELETE FROM sessions WHERE resume_id = 'r_collide'");
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks.length).toBeGreaterThan(0);
+  });
+});
+
+describe("human ↔ human DM (/api/dm): restricted members can talk to people", () => {
+  let daveToken = "", daveId = "";
+  test("carol (restricted) DMs dave; dave sees it in thread + threads + user inbox and replies", async () => {
+    const dave = register("acl3_dave", PW);
+    daveToken = dave.token!; daveId = dave.user!.user_id;
+    expect(addNetworkMember(NET, daveId, "member", adminId).ok).toBe(true);
+    const sent = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "hi dave", client_request_id: "c1" });
+    expect(sent.status).toBe(200);
+    expect(sent.body.message.sender_user_id).toBe(carolId);
+    // 重试同一个气泡不产生第二条。
+    expect((await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "hi dave", client_request_id: "c1" })).body.message.message_id).toBe(sent.body.message.message_id);
+    const threads = await get(daveToken, `/api/dm/threads?network_id=${NET}`);
+    expect(threads.body.threads).toEqual([expect.objectContaining({ other_user_id: carolId, unread: 1 })]);
+    expect((await get(daveToken, `/api/messages?scope=user&network_id=${NET}`)).body.messages.map((m: any) => m.content)).toContain("hi dave");
+    expect((await send(daveToken, "POST", "/api/dm", { network_id: NET, to_username: "acl3_carol", message: "hi carol" })).status).toBe(200);
+    const thread = await get(carolToken, `/api/dm?network_id=${NET}&with=${daveId}`);
+    expect(thread.body.messages.map((m: any) => [m.direction, m.content])).toEqual([["in", "hi carol"], ["out", "hi dave"]]);
+    // 私信不进按 Agent 的未读(发信人不是 Agent)。
+    const inbox = await get(daveToken, `/api/messages?scope=user&network_id=${NET}`);
+    expect(inbox.body.unread_by_agent["acl3_carol"]).toBeUndefined();
+    const daveThread = await get(daveToken, `/api/dm?network_id=${NET}&with=${carolId}`);
+    expect(daveThread.body.messages.map((m: any) => m.direction)).toEqual(["out", "in"]);
+  });
+  test("sender identity comes from the token, not from the body", async () => {
+    await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "who am i", from: adminName, sender_user_id: adminId });
+    const row = db.get<{ sender_user_id: string; from_session: string }>("SELECT sender_user_id, from_session FROM user_inbox WHERE content = 'who am i'");
+    expect(row).toEqual({ sender_user_id: carolId, from_session: "acl3_carol" });
+  });
+  test("a third party cannot read someone else's thread", async () => {
+    const eve = register("acl3_eve", PW);
+    expect(addNetworkMember(NET, eve.user!.user_id, "member", adminId).ok).toBe(true);
+    // eve 查「她和 dave」的会话:空(carol↔dave 的不会出现)。
+    expect((await get(eve.token!, `/api/dm?network_id=${NET}&with=${daveId}`)).body.messages).toEqual([]);
+    expect((await get(eve.token!, `/api/dm/threads?network_id=${NET}`)).body.threads).toEqual([]);
+  });
+  test("non-members and outsiders are refused; unknown and outside users look the same", async () => {
+    const out = register("acl3_out", PW);
+    expect((await send(out.token!, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "x" })).status).toBe(403);
+    expect((await get(out.token!, `/api/dm/threads?network_id=${NET}`)).status).toBe(403);
+    const a = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: out.user!.user_id, message: "x" });
+    const b = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: "u_nobody", message: "x" });
+    expect(a).toEqual(b);
+    expect(a.status).toBe(404);
+  });
+  test("a restricted member cannot smuggle a file they cannot see into a DM", async () => {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array([1, 2, 3])]), "a.bin");
+    const up = await fetch(`${BASE}/api/upload?network_id=${NET}`, { method: "POST", body: form, headers: auth(adminToken) });
+    const fid = (await up.json()).file_id;
+    const r = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "f", attachments: [{ type: "file", file_id: fid }] });
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("attachment_not_accessible");
+    // 管理员(不受限)可以附带本网络文件发给 carol;carol 因此能下载它。
+    expect((await send(adminToken, "POST", "/api/dm", { network_id: NET, to_user_id: carolId, message: "file for you", attachments: [{ type: "file", file_id: fid }] })).status).toBe(200);
+    expect((await fetch(`${BASE}/api/files/${fid}`, { headers: auth(carolToken) })).status).toBe(200);
+  });
+  test("node tokens cannot use the DM API", async () => {
+    const r = await fetch(`${BASE}/api/dm/threads?network_id=${NET}`, { headers: { Authorization: "Bearer ntok_x" } });
+    expect(r.status).toBeGreaterThanOrEqual(401);
+  });
+});

package/src/agent-groups-perf.test.ts

@@ -0,0 +1,167 @@
+// Agent 分组的性能守卫(RFC-038 §8):visibleAgents() 每个请求多做一次「组授权 → 组成员」展开,
+// 这里量它的额外开销,并用 EXPLAIN QUERY PLAN 钉住展开查询走索引(不是全表扫)。
+//
+// 场景:NET 里 300 个节点;50 个组,每组 6 个节点(合起来覆盖全部 300 个)。
+//   baseline —— bob 直接授权这 300 个节点(没有组);
+//   groups   —— alice 授权这 50 个组(没有直接授权),可见集合与 bob 完全相同。
+// 两人看到的 Agent 一样多,差值就是「按组展开」本身的代价(交替量 15 轮,取每轮差值的中位数)。团队要求 ≈2 ms 以内(本机实测 −0.5~+1.9 ms);
+// 断言放宽到 max(5 ms, 基线的 15%)—— CI 容器比本机慢时两边一起变慢,绝对差也跟着放大。数字打印出来。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+import { visibleAgents } from "./agent-access.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-groups-perf-"));
+let BASE = "";
+let hub: any = null;
+const PW = "GroupPerfPassw0rd!x";
+let NET = "";
+let adminToken = "";
+let adminId = "";
+let alice = { token: "", id: "" };
+let bob = { token: "", id: "" };
+const NODES = 300;
+const GROUPS = 50;
+const PER_GROUP = NODES / GROUPS;
+const BOUND_MS = 5;
+const bound = (base: number) => Math.max(BOUND_MS, base * 0.15);
+// CI 容器里一次 visibleAgents() 约 65 ms(本机约 28 ms):原来 40 次 × 两边再加预热,顶破了 bun 默认的 5 s 单测超时(#2131 CI 实测)。
+// 15 次取中位数足够稳;性能用例另给显式超时。
+const WARMUP = 3;
+const ITER = 15;
+const PERF_TIMEOUT_MS = 60_000;
+
+const json = (token: string) => ({ Authorization: `Bearer ${token}`, "Content-Type": "application/json" });
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: json(token), body: payload === undefined ? undefined : JSON.stringify(payload) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+const median = (xs: number[]) => { const s = [...xs].sort((a, b) => a - b); return s[Math.floor(s.length / 2)]; };
+/**
+ * 交替计时:每一轮先量 A 再量 B,取「B − A」的中位数(再附上两边各自的中位数给人看)。
+ * 不能 A 连量 N 次再 B 连量 N 次:test638 在同一台机器上并发跑两份 aggregate,负载随时间变,
+ * 两段分开量时差值被负载漂移主导(--cpus=1 实测差出 26–33 ms,真实差值 < 1 ms)。
+ */
+function pairedDelta(a: () => void, b: () => void, n: number): { a: number; b: number; delta: number } {
+  for (let i = 0; i < WARMUP; i++) { a(); b(); }
+  const as: number[] = [], bs: number[] = [], ds: number[] = [];
+  for (let i = 0; i < n; i++) {
+    let t = performance.now(); a(); const ta = performance.now() - t;
+    t = performance.now(); b(); const tb = performance.now() - t;
+    as.push(ta); bs.push(tb); ds.push(tb - ta);
+  }
+  return { a: median(as), b: median(bs), delta: median(ds) };
+}
+async function pairedDeltaAsync(a: () => Promise<void>, b: () => Promise<void>, n: number): Promise<{ a: number; b: number; delta: number }> {
+  for (let i = 0; i < WARMUP; i++) { await a(); await b(); }
+  const as: number[] = [], bs: number[] = [], ds: number[] = [];
+  for (let i = 0; i < n; i++) {
+    let t = performance.now(); await a(); const ta = performance.now() - t;
+    t = performance.now(); await b(); const tb = performance.now() - t;
+    as.push(ta); bs.push(tb); ds.push(tb - ta);
+  }
+  return { a: median(as), b: median(bs), delta: median(ds) };
+}
+
+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 admin = register(`perf_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminId = admin.user!.user_id;
+  NET = admin.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  db.transaction(() => {
+    for (let i = 0; i < NODES; i++) {
+      const node = `node_perf_${i}`;
+      const alias = `perf-agent-${i}`;
+      db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, updated_at) VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'))`, [node, alias, NET, adminId]);
+      db.run(`INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`, [`resume_${node}`, alias, node, NET]);
+    }
+  });
+  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}`;
+
+  const mk = async (username: string) => {
+    const r = await send(adminToken, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  alice = await mk(`perf_alice_${Date.now()}`);
+  bob = await mk(`perf_bob_${Date.now()}`);
+
+  const groupIds: string[] = [];
+  for (let g = 0; g < GROUPS; g++) {
+    const nodeIds = Array.from({ length: PER_GROUP }, (_, k) => `node_perf_${g * PER_GROUP + k}`);
+    const r = await send(adminToken, "POST", `/api/networks/${NET}/agent-groups`, { name: `perf-group-${g}`, node_ids: nodeIds });
+    expect(r.status).toBe(200);
+    groupIds.push(r.body.group.group_id);
+  }
+  expect((await send(adminToken, "PUT", `/api/networks/${NET}/members/${alice.id}/agent-grants`, { group_grants: groupIds })).status).toBe(200);
+  expect((await send(adminToken, "PUT", `/api/networks/${NET}/members/${bob.id}/agent-grants`, { grants: Array.from({ length: NODES }, (_, i) => `node_perf_${i}`) })).status).toBe(200);
+}, 60_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("Agent 分组:性能守卫(50 组 × 300 节点)", () => {
+  test("两人可见集合相同(比较才公平)", () => {
+    const a = visibleAgents(alice.id, NET);
+    const b = visibleAgents(bob.id, NET);
+    expect(a.nodeIds.length).toBe(NODES);
+    expect([...a.nodeIds].sort()).toEqual([...b.nodeIds].sort());
+  });
+
+  test(`visibleAgents():组展开的额外开销 ≤ max(${BOUND_MS} ms, 基线 15%)(目标 ≈2 ms)`, () => {
+    const r = pairedDelta(() => { visibleAgents(bob.id, NET); }, () => { visibleAgents(alice.id, NET); }, ITER);
+    console.log(`[perf] visibleAgents median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    expect(r.delta).toBeLessThanOrEqual(bound(r.a));
+  }, PERF_TIMEOUT_MS);
+
+  test(`受限成员 GET /api/status:组授权比等量直接授权多出 ≤ max(${BOUND_MS} ms, 基线 15%)`, async () => {
+    const hit = async (token: string) => {
+      const r = await fetch(`${BASE}/api/status?network_id=${NET}`, { headers: json(token) });
+      const body = await r.json() as any;
+      if ((body.sessions ?? []).length !== NODES) throw new Error(`expected ${NODES} sessions, got ${(body.sessions ?? []).length}`);
+    };
+    const r = await pairedDeltaAsync(() => hit(bob.token), () => hit(alice.token), ITER);
+    console.log(`[perf] GET /api/status median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    expect(r.delta).toBeLessThanOrEqual(bound(r.a));
+  }, PERF_TIMEOUT_MS);
+
+  test("EXPLAIN QUERY PLAN:组展开走索引,不全表扫描", () => {
+    const plan = db.all<{ detail: string }>(
+      `EXPLAIN QUERY PLAN
+       SELECT m.node_id, g.can_message
+         FROM network_member_group_grants g
+         JOIN agent_groups ag ON ag.group_id = g.group_id AND ag.network_id = g.network_id
+         JOIN agent_group_members m ON m.group_id = g.group_id
+         JOIN nodes n ON n.node_id = m.node_id AND n.network_id = g.network_id
+        WHERE g.network_id = ?1 AND g.user_id = ?2`,
+      NET, alice.id,
+    ).map((r) => r.detail);
+    console.log(`[perf] plan:\n  ${plan.join("\n  ")}`);
+    // 四张表都是 SEARCH(按主键 / 索引定位),没有一张是 SCAN。
+    expect(plan.length).toBeGreaterThanOrEqual(4);
+    expect(plan.filter((d) => /^SCAN\b/.test(d))).toEqual([]);
+    expect(plan.every((d) => /^SEARCH\b/.test(d) && /(PRIMARY KEY|INDEX)/.test(d))).toBe(true);
+  });
+
+  test("EXPLAIN QUERY PLAN:按组找被授权成员(改组成员时断流用)走 group_id 索引", () => {
+    const plan = db.all<{ detail: string }>(
+      "EXPLAIN QUERY PLAN SELECT user_id FROM network_member_group_grants WHERE group_id = ?1", "x",
+    ).map((r) => r.detail);
+    console.log(`[perf] plan (usersGrantedGroup): ${plan.join(" | ")}`);
+    expect(plan.some((d) => /SEARCH .*idx_group_grants_group/.test(d))).toBe(true);
+  });
+});

package/src/alias-filter.test.ts

@@ -0,0 +1,72 @@
+import { expect, test } from "bun:test";
+import { parseAliasFilter } from "./alias-filter";
+
+test("no filter given means no filtering, not an empty match", () => {
+  for (const raw of [undefined, null, "", "   ", ",", " , , "]) {
+    const f = parseAliasFilter(raw as any);
+    expect(f.aliases).toEqual([]);
+    expect(f.sql).toBe("");
+  }
+});
+
+test("a single alias produces one placeholder", () => {
+  const f = parseAliasFilter("节点甲");
+  expect(f.aliases).toEqual(["节点甲"]);
+  expect(f.sql).toBe(" AND alias IN (?)");
+});
+
+test("several aliases keep their order and count", () => {
+  const f = parseAliasFilter("A站内容,A站内容牛,hub");
+  expect(f.aliases).toEqual(["A站内容", "A站内容牛", "hub"]);
+  expect(f.sql).toBe(" AND alias IN (?,?,?)");
+});
+
+test("surrounding whitespace is trimmed", () => {
+  expect(parseAliasFilter(" a , b ").aliases).toEqual(["a", "b"]);
+});
+
+// The point of the module. A trailing comma must not become `alias = ''`,
+// which matches nothing and reads exactly like "those nodes do not exist".
+test("blank entries are dropped, never turned into a match-nothing term", () => {
+  const f = parseAliasFilter("a,,b,");
+  expect(f.aliases).toEqual(["a", "b"]);
+  expect(f.sql).toBe(" AND alias IN (?,?)");
+  expect(f.aliases).not.toContain("");
+});
+
+test("a filter of only commas is the same as no filter — it must not silently match zero rows", () => {
+  const f = parseAliasFilter(",,,");
+  expect(f.sql).toBe("");
+});
+
+test("placeholder count always equals alias count, so params can never misalign", () => {
+  for (const raw of ["a", "a,b", "a,,b", " a , b , c ", ",x,"]) {
+    const f = parseAliasFilter(raw);
+    expect((f.sql.match(/\?/g) ?? []).length).toBe(f.aliases.length);
+  }
+});
+
+test("aliases are passed through verbatim — no globbing, no case folding", () => {
+  const f = parseAliasFilter("A站内容,a站内容");
+  expect(f.aliases).toEqual(["A站内容", "a站内容"]);
+  expect(f.sql).not.toContain("LIKE");
+});
+
+// Wiring: the tool must actually use this module, and must say what its
+// `summary` counted — a caller who asked about three aliases and gets back
+// "idle: 96" can easily read the 96 as being about their three.
+import { readFileSync } from "fs";
+import { join } from "path";
+
+test("get_all_status uses parseAliasFilter and declares what summary counted", () => {
+  const source = readFileSync(join(import.meta.dir, "tools.ts"), "utf8");
+  const a = source.indexOf('"get_all_status"');
+  expect(a).toBeGreaterThan(-1);
+  const body = source.slice(a, source.indexOf('server.tool(', a + 10));
+  expect(body).toContain("filter_alias");
+  expect(body).toContain("parseAliasFilter(filter_alias)");
+  expect(body).toContain("summary_scope");
+  expect(body).toContain("sessions_returned");
+  // The alias list must go through parameters, never be interpolated.
+  expect(body).not.toMatch(/alias IN \(\$\{/);
+});

package/src/alias-filter.ts

@@ -0,0 +1,32 @@
+// Parse the `filter_alias` argument of `get_all_status` into an exact-match
+// IN list.
+//
+// Why this exists at all: on a 222-session hub the unfiltered response is about
+// 259 KB — past what an MCP client accepts in one result. A caller who wanted
+// the status of three specific nodes could not get it from the tool, and had to
+// go around it to the REST API. The filter is the fix; this module is the part
+// of it worth pinning, because the interesting behaviour is what happens to the
+// inputs that are not a clean alias.
+//
+// Blank entries are DROPPED rather than matched. A trailing comma would
+// otherwise produce `alias = ''`, which matches no row — and "no rows" reads
+// exactly like "those nodes do not exist". The failure and the true answer
+// would be indistinguishable to the caller, which is the thing to avoid.
+
+export interface AliasFilter {
+  /** Exact aliases to match. Empty means "no alias filtering". */
+  aliases: string[];
+  /** SQL fragment to append, or "" when there is nothing to filter on. */
+  sql: string;
+}
+
+export function parseAliasFilter(raw: string | undefined | null): AliasFilter {
+  const aliases = (raw ?? "")
+    .split(",")
+    .map(a => a.trim())
+    .filter(Boolean);
+  return {
+    aliases,
+    sql: aliases.length > 0 ? ` AND alias IN (${aliases.map(() => "?").join(",")})` : "",
+  };
+}