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

package/src/ack-create-request.test.ts

@@ -0,0 +1,331 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// RFC-026 §9.3 D2 / #338 PR3 — ack_create_request HANDLER tests.
+//
+// 通信龙 pre-review caught B1 + B2: my first cut of PR3 added a new daemon
+// ack status `runtime_capability_check_failed` to create-node-daemon.ts but
+// the hub's zod enum only accepted ["started", "failed", "rejected"] — the
+// new status was silently zod-rejected on the hub side and the daemon's
+// `.catch(()=>{})` swallowed the rejection. The PR body also claimed
+// `daemon_capability_lied` audit was written when in fact the action wasn't
+// in the audit enum and no insert ran.
+//
+// This handler-driven suite captures and invokes the registered callback
+// directly. It validates handler branches and DB effects, but deliberately
+// does NOT claim to exercise the MCP SDK's zod transport gate. The
+// complementary in-process transport coverage lives in
+// ack-create-request-transport.test.ts (#344).
+
+const NET = "net_ack_t";
+const DAEMON_NODE_ID = "node_ack_daemon";
+const DAEMON_ALIAS = "ack-daemon";
+const DAEMON_USER = "u_ack_owner";
+const DAEMON_TOKEN_ID = "tok_ack_daemon";
+const DAEMON_TOKEN_HASH = "hash_ack_daemon";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface AckReply { ok?: boolean; error?: string; status?: string; }
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [DAEMON_USER]); } catch {}
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seedDaemonWorld() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [DAEMON_USER, DAEMON_USER],
+  );
+  db.run(
+    `INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET, NET, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [DAEMON_USER, NET],
+  );
+  // daemon node — must exist for resolveCallerDaemonTokenBound to bind.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [DAEMON_NODE_ID, DAEMON_ALIAS, DAEMON_ALIAS, NET],
+  );
+  // daemon ntok — bound to the daemon node via name='node:<alias>'.
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [DAEMON_TOKEN_ID, DAEMON_USER, NET, `node:${DAEMON_ALIAS}`, DAEMON_TOKEN_HASH],
+  );
+}
+
+function seedCreateRequest(opts: {
+  request_id: string,
+  child_token_id?: string,
+  status?: "pending" | "delivered" | "succeeded" | "failed",
+  child_name?: string,
+  runtime?: string,
+}) {
+  const childName = opts.child_name ?? `child_${opts.request_id}`;
+  if (opts.child_token_id) {
+    db.run(
+      `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+       VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+      [opts.child_token_id, DAEMON_USER, NET, `node:${childName}`, `hash_${opts.child_token_id}`],
+    );
+  }
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, child_token_id, created_at, created_by_token)
+     VALUES (?1, ?2, ?3, ?4, ?5, 'x', '{}', '[]', ?6, ?7, ?8, ?9)`,
+    [
+      opts.request_id, DAEMON_NODE_ID, childName, NET,
+      opts.runtime ?? "claude-agent-sdk",
+      opts.status ?? "delivered",
+      opts.child_token_id ?? null,
+      Date.now(),
+      DAEMON_TOKEN_ID,
+    ],
+  );
+}
+
+/** Build a server with registerTools wired as if the daemon's ntok bound. */
+function buildAckHandler(): ToolHandler {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, _schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    return origTool(name, _desc, _schema, handler);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => {
+      tools[name] = handler;
+      return origRegisterTool(name, _cfg, handler);
+    };
+  }
+  registerTools(
+    server,
+    /* clientIP */ undefined,
+    /* enforceNetworkId */ NET,
+    /* enforceUserId */ DAEMON_USER,
+    /* callerAlias */ DAEMON_ALIAS,
+    /* callerTokenIsNetwork */ true,
+    /* callerTokenId */ DAEMON_TOKEN_ID,
+  );
+  const h = tools["ack_create_request"];
+  if (!h) throw new Error("ack_create_request tool not registered");
+  return h;
+}
+
+async function callAck(handler: ToolHandler, args: any): Promise<AckReply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as AckReply;
+}
+
+function readRequest(request_id: string) {
+  return db.get<{ status: string; error: string | null; acked_at: number | null }>(
+    `SELECT status, error, acked_at FROM node_create_requests WHERE request_id = ?1`,
+    request_id,
+  );
+}
+
+function readToken(token_id: string) {
+  return db.get<{ revoked_at: string | null }>(
+    `SELECT revoked_at FROM api_tokens WHERE token_id = ?1`,
+    token_id,
+  );
+}
+
+function readAuditRows(action: string, target_id: string) {
+  return db.all<{ action: string; network_id: string; target_id: string; detail: string }>(
+    `SELECT action, network_id, target_id, detail FROM audit_log
+     WHERE action = ?1 AND target_id = ?2 ORDER BY id DESC`,
+    [action, target_id],
+  );
+}
+
+describe("ack_create_request HANDLER — B1 schema accepts runtime_capability_check_failed", () => {
+  test("schema accepts runtime_capability_check_failed + runtime field (no zod reject)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_accept";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "child died within 5000ms post-spawn",
+      runtime: "codex-sdk",
+    });
+    // PR3 v1 BUG: hub zod enum rejected this status → reply.ok=false /
+    // tool would even throw before getting here. Now must accept.
+    expect(reply.ok).toBe(true);
+    expect(reply.status).toBe("runtime_capability_check_failed");
+  });
+
+  test("request flips to terminal runtime_capability_check_failed status", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_terminal";
+    seedCreateRequest({ request_id: reqId, status: "delivered" });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "boom",
+      runtime: "codex-sdk",
+    });
+    const row = readRequest(reqId);
+    expect(row?.status).toBe("runtime_capability_check_failed");
+    expect(row?.error).toBe("boom");
+    expect(row?.acked_at).toBeGreaterThan(0);
+  });
+
+  test("child ntok is revoked on capability-check-failed (same teardown as 'failed')", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_revoke";
+    const childTok = "tok_ack_child_b1";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    expect(readToken(childTok)?.revoked_at).toBeNull();
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      runtime: "codex-sdk",
+    });
+    expect(readToken(childTok)?.revoked_at).not.toBeNull();
+  });
+});
+
+describe("ack_create_request HANDLER — B2 audit_log daemon_capability_lied", () => {
+  test("writes daemon_capability_lied audit row with runtime + daemon + error in detail", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_audit";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "OPENAI_API_KEY unset",
+      runtime: "codex-sdk",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    // PR3 v1 BUG: action wasn't in auditCreateNode enum → 0 rows + no
+    // surface for ops to spot lying daemons. Now must write exactly 1.
+    expect(rows.length).toBe(1);
+    expect(rows[0].network_id).toBe(NET);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.runtime).toBe("codex-sdk");
+    expect(detail.daemon_node_id).toBe(DAEMON_NODE_ID);
+    expect(detail.error).toBe("OPENAI_API_KEY unset");
+    expect(typeof detail.acked_at).toBe("number");
+  });
+
+  test("does NOT write daemon_capability_lied on generic 'failed' ack (status discriminates)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_no_audit_on_failed";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "failed",
+      error: "child died immediately after spawn",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(0);
+  });
+
+  test("does NOT write daemon_capability_lied on 'started' (happy path silence)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_no_audit_on_started";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, { request_id: reqId, status: "started", child_pid: 12345 });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(0);
+  });
+
+  test("runtime field nullable if daemon omitted it (older daemon back-compat)", async () => {
+    // Older daemon (preview.10 and earlier) wouldn't send `runtime`.
+    // The hub must still accept + audit, just with runtime=null.
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_nullable_runtime";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "child died",
+    });
+    expect(reply.ok).toBe(true);
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(1);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.runtime).toBeNull();
+  });
+
+  test("error string is truncated to 500 chars in audit detail (defense vs giant payload)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_trunc";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const giant = "x".repeat(900);
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: giant,
+      runtime: "codex-sdk",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(1);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.error.length).toBe(500);
+  });
+});
+
+describe("ack_create_request HANDLER — pre-existing happy-path stays green (regression)", () => {
+  test("status='started' still flips acked_at without terminal teardown", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_started_regression";
+    const childTok = "tok_ack_child_started";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, { request_id: reqId, status: "started", child_pid: 7777 });
+    expect(reply.ok).toBe(true);
+    expect(reply.status).toBe("awaiting_register");
+    const row = readRequest(reqId);
+    // 'started' doesn't flip to terminal; status stays 'delivered'.
+    expect(row?.status).toBe("delivered");
+    expect(row?.acked_at).toBeGreaterThan(0);
+    // child ntok is NOT revoked on 'started'.
+    expect(readToken(childTok)?.revoked_at).toBeNull();
+  });
+
+  test("status='failed' still revokes child + flips to failed (no audit_log daemon_capability_lied)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_failed_regression";
+    const childTok = "tok_ack_child_failed";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, { request_id: reqId, status: "failed", error: "fork failed" });
+    expect(reply.ok).toBe(true);
+    const row = readRequest(reqId);
+    expect(row?.status).toBe("failed");
+    expect(row?.error).toBe("fork failed");
+    expect(readToken(childTok)?.revoked_at).not.toBeNull();
+    expect(readAuditRows("daemon_capability_lied", reqId).length).toBe(0);
+  });
+});

package/src/admin-networks-http.test.ts

@@ -0,0 +1,88 @@
+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 { NETWORK_REST_COLUMNS } from "./rest-projections.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-admin-networks-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let adminToken = "";
+let memberToken = "";
+let nodeToken = "";
+let adminNetworkId = "";
+let memberNetworkId = "";
+
+async function listNetworks(token: string): Promise<any[]> {
+  const response = await fetch(`${base}/api/networks`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const body = await response.json() as any;
+  expect(body.ok).toBe(true);
+  return body.networks;
+}
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { createNetworkTokenForNode, register } = await import("./auth.js");
+
+  // The first registered user is the global Hub admin. The second user owns a
+  // separate network and is intentionally not a member of the admin's network.
+  const admin = register(`admin_networks_${Date.now()}`, "AdminNetworks-Strong-1!", undefined, "admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminNetworkId = admin.network_id!;
+
+  const member = register(`member_networks_${Date.now()}`, "MemberNetworks-Strong-1!", undefined, "member");
+  expect(member.ok).toBe(true);
+  memberToken = member.token!;
+  memberNetworkId = member.network_id!;
+
+  const memberUserId = db.get<{ user_id: string }>(
+    "SELECT user_id FROM users WHERE username LIKE 'member_networks_%' ORDER BY created_at DESC LIMIT 1",
+  )!.user_id;
+  const minted = createNetworkTokenForNode(memberUserId, memberNetworkId, "admin-networks-node");
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/networks global-admin visibility (#94)", () => {
+  test("global admin utok sees every network without losing public shape", async () => {
+    const rows = await listNetworks(adminToken);
+    expect(new Set(rows.map((row) => row.network_id))).toEqual(new Set([adminNetworkId, memberNetworkId]));
+
+    const own = rows.find((row) => row.network_id === adminNetworkId);
+    const foreign = rows.find((row) => row.network_id === memberNetworkId);
+    expect(own.member_role).toBe("owner");
+    expect(foreign.member_role).toBe("admin");
+    expect(Object.keys(foreign).sort()).toEqual([...NETWORK_REST_COLUMNS, "member_role", "name"].sort());
+  });
+
+  test("ordinary utok remains limited to member networks", async () => {
+    const rows = await listNetworks(memberToken);
+    expect(rows.map((row) => row.network_id)).toEqual([memberNetworkId]);
+    expect(rows.some((row) => row.network_id === adminNetworkId)).toBe(false);
+  });
+
+  test("network token remains limited to its bound network", async () => {
+    const rows = await listNetworks(nodeToken);
+    expect(rows.map((row) => row.network_id)).toEqual([memberNetworkId]);
+    expect(rows.some((row) => row.network_id === adminNetworkId)).toBe(false);
+  });
+});

package/src/agent-access.ts

@@ -0,0 +1,267 @@
+// 多用户账号与 Agent 权限 —— 「这个人在这个网络里能看见 / 能联系哪些 Agent」的唯一实现。
+//
+// 受限成员(restricted member):网络里 role 为 member/viewer、agent_access 不是 'all'、
+// 且不是 Hub 管理员的用户。他只能看见 network_member_agent_grants 里授权给他的 Agent,
+// 只能给其中 can_message=1 的发任务/消息;人类之间的私信不受影响。
+//
+// 判定是 fail-closed 的:agent_access 只有字面 'all' 才放开;role 只有 owner/admin 才豁免。
+// 读到任何别的值(包括未来新增的角色)都按受限处理。
+//
+// 这里只回答「能不能」,不管「是不是成员」——非成员返回 false(不受限),
+// 成员资格仍由调用方原有的 getUserNetworkRole 判定。两件事分开,别合并成一个判据。
+
+import { db } from "./db.js";
+
+const UNRESTRICTED_ROLES = new Set(["owner", "admin"]);
+
+export type AgentAccessMode = "all" | "granted";
+
+export type AgentGrant = {
+  node_id: string | null;
+  alias: string | null;
+  can_message: boolean;
+};
+
+/** 某受限成员在某网络里能看见 / 能联系的 Agent,已经展开成 alias 与 node_id 两份清单。 */
+export type VisibleAgents = {
+  aliases: string[];
+  nodeIds: string[];
+  messageAliases: string[];
+  messageNodeIds: string[];
+};
+
+export function isHubAdmin(userId: string): boolean {
+  return db.get<{ role: string | null }>("SELECT role FROM users WHERE user_id = ?1", userId)?.role === "admin";
+}
+
+function restrictedRow(row: { member_role: string | null; agent_access: string | null; user_role: string | null } | null | undefined): boolean {
+  if (!row) return false;
+  if (row.user_role === "admin") return false;
+  if (UNRESTRICTED_ROLES.has(String(row.member_role))) return false;
+  return row.agent_access !== "all";
+}
+
+export function isAgentRestricted(userId: string, networkId: string | null | undefined): boolean {
+  if (!userId || !networkId) return false;
+  const row = db.get<{ member_role: string | null; agent_access: string | null; user_role: string | null }>(
+    `SELECT nm.role AS member_role, nm.agent_access, u.role AS user_role
+       FROM network_members nm JOIN users u ON u.user_id = nm.user_id
+      WHERE nm.network_id = ?1 AND nm.user_id = ?2`,
+    networkId, userId,
+  );
+  return restrictedRow(row);
+}
+
+/** 该用户所有「只看授权 Agent」的网络。Hub 管理员恒为空。 */
+export function restrictedNetworkIds(userId: string): string[] {
+  if (!userId) return [];
+  return db.all<{ network_id: string; member_role: string | null; agent_access: string | null; user_role: string | null }>(
+    `SELECT nm.network_id, nm.role AS member_role, nm.agent_access, u.role AS user_role
+       FROM network_members nm
+       JOIN users u ON u.user_id = nm.user_id
+       JOIN networks n ON n.network_id = nm.network_id
+      WHERE nm.user_id = ?1`,
+    userId,
+  ).filter(restrictedRow).map((row) => row.network_id);
+}
+
+export function getAgentAccessMode(networkId: string, userId: string): AgentAccessMode | null {
+  const row = db.get<{ agent_access: string | null }>(
+    "SELECT agent_access FROM network_members WHERE network_id = ?1 AND user_id = ?2",
+    networkId, userId,
+  );
+  if (!row) return null;
+  return row.agent_access === "all" ? "all" : "granted";
+}
+
+export function listAgentGrants(networkId: string, userId: string): AgentGrant[] {
+  return db.all<{ node_id: string | null; alias: string | null; can_message: number }>(
+    `SELECT node_id, alias, can_message FROM network_member_agent_grants
+      WHERE network_id = ?1 AND user_id = ?2
+      ORDER BY COALESCE(node_id, alias)`,
+    networkId, userId,
+  ).map((row) => ({ node_id: row.node_id, alias: row.alias, can_message: row.can_message === 1 }));
+}
+
+/**
+ * 把授权展开成 alias / node_id 两份清单。
+ * node_id 授权同时带出:nodes 表里这个节点的 alias、sessions 表里同 node_id 的会话 alias
+ * (改名后 sessions 先于 nodes 更新的窗口里两者可能不同,两个都算)。都限定在同一网络。
+ */
+export function visibleAgents(userId: string, networkId: string): VisibleAgents {
+  const aliases = new Set<string>();
+  const nodeIds = new Set<string>();
+  const messageAliases = new Set<string>();
+  const messageNodeIds = new Set<string>();
+  for (const grant of listAgentGrants(networkId, userId)) {
+    const grantAliases: string[] = [];
+    if (grant.node_id) {
+      nodeIds.add(grant.node_id);
+      if (grant.can_message) messageNodeIds.add(grant.node_id);
+      for (const row of db.all<{ alias: string | null }>(
+        `SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2
+         UNION SELECT alias FROM sessions WHERE node_id = ?1 AND network_id = ?2`,
+        grant.node_id, networkId,
+      )) {
+        if (row.alias) grantAliases.push(row.alias);
+      }
+    } else if (grant.alias) {
+      grantAliases.push(grant.alias);
+    }
+    for (const alias of grantAliases) {
+      aliases.add(alias);
+      if (grant.can_message) messageAliases.add(alias);
+    }
+  }
+  return {
+    aliases: [...aliases],
+    nodeIds: [...nodeIds],
+    messageAliases: [...messageAliases],
+    messageNodeIds: [...messageNodeIds],
+  };
+}
+
+/** 这个用户名在该网络里是否同时是某个 Agent 的 alias(sessions 或 nodes)。 */
+export function usernameIsAgentAlias(networkId: string, username: string): boolean {
+  if (!username) return false;
+  return !!db.get(
+    `SELECT 1 WHERE EXISTS (SELECT 1 FROM sessions WHERE network_id = ?1 AND alias = ?2)
+        OR EXISTS (SELECT 1 FROM nodes WHERE network_id = ?1 AND alias = ?2)`,
+    networkId, username,
+  );
+}
+
+export type AgentRef = { alias?: string | null; nodeId?: string | null };
+
+function refMatches(ref: AgentRef, aliases: string[], nodeIds: string[]): boolean {
+  if (ref.nodeId && nodeIds.includes(ref.nodeId)) return true;
+  if (ref.alias && aliases.includes(ref.alias)) return true;
+  return false;
+}
+
+/** 不受限的成员恒为 true;受限成员只对授权的 Agent 为 true。不判断成员资格。 */
+export function canSeeAgent(userId: string, networkId: string | null | undefined, ref: AgentRef): boolean {
+  if (!networkId || !isAgentRestricted(userId, networkId)) return true;
+  const visible = visibleAgents(userId, networkId);
+  return refMatches(ref, visible.aliases, visible.nodeIds);
+}
+
+export function canMessageAgent(userId: string, networkId: string | null | undefined, ref: AgentRef): boolean {
+  if (!networkId || !isAgentRestricted(userId, networkId)) return true;
+  const visible = visibleAgents(userId, networkId);
+  return refMatches(ref, visible.messageAliases, visible.messageNodeIds);
+}
+
+export type AgentGrantInput = { node_id?: unknown; alias?: unknown; can_message?: unknown };
+
+export type ReplaceGrantsResult =
+  | { ok: true; agent_access: AgentAccessMode; grants: AgentGrant[] }
+  | { ok: false; error: string; status: number; detail?: unknown };
+
+const MAX_GRANTS = 1000;
+
+/**
+ * 整体替换某成员的授权(PUT 语义)。node_id 必须是本网络里存在的节点;alias 只用于没有
+ * node_id 的旧会话,也必须是本网络里存在的会话。任何一条不合法 ⇒ 整批拒绝,不做部分写入。
+ */
+export function replaceAgentGrants(input: {
+  networkId: string;
+  userId: string;
+  grants: unknown;
+  agentAccess?: unknown;
+  actorUserId: string;
+}): ReplaceGrantsResult {
+  const member = db.get<{ role: string }>(
+    "SELECT role FROM network_members WHERE network_id = ?1 AND user_id = ?2",
+    input.networkId, input.userId,
+  );
+  if (!member) return { ok: false, error: "member_not_found", status: 404 };
+
+  let mode: AgentAccessMode | undefined;
+  if (input.agentAccess !== undefined) {
+    if (input.agentAccess !== "all" && input.agentAccess !== "granted") {
+      return { ok: false, error: "invalid_agent_access", status: 400 };
+    }
+    mode = input.agentAccess;
+  }
+
+  let rows: Array<{ node_id: string | null; alias: string | null; can_message: number }> | undefined;
+  if (input.grants !== undefined) {
+    if (!Array.isArray(input.grants)) return { ok: false, error: "grants_must_be_array", status: 400 };
+    if (input.grants.length > MAX_GRANTS) return { ok: false, error: "too_many_grants", status: 400, detail: { limit: MAX_GRANTS } };
+    const seen = new Set<string>();
+    rows = [];
+    for (const [index, raw] of input.grants.entries()) {
+      // 兼容直接传 node_id 字符串数组。
+      const item: AgentGrantInput = typeof raw === "string" ? { node_id: raw } : (raw && typeof raw === "object" && !Array.isArray(raw) ? raw as AgentGrantInput : {});
+      const nodeId = typeof item.node_id === "string" && item.node_id.trim() ? item.node_id.trim() : null;
+      const alias = typeof item.alias === "string" && item.alias.trim() ? item.alias.trim() : null;
+      if ((nodeId === null) === (alias === null)) {
+        return { ok: false, error: "grant_needs_exactly_one_of_node_id_or_alias", status: 400, detail: { index } };
+      }
+      if (item.can_message !== undefined && typeof item.can_message !== "boolean") {
+        return { ok: false, error: "can_message_must_be_boolean", status: 400, detail: { index } };
+      }
+      const exists = nodeId
+        ? db.get("SELECT 1 FROM nodes WHERE node_id = ?1 AND network_id = ?2", nodeId, input.networkId)
+        : db.get("SELECT 1 FROM sessions WHERE alias = ?1 AND network_id = ?2", alias, input.networkId);
+      if (!exists) {
+        return { ok: false, error: "agent_not_in_network", status: 400, detail: { index, ...(nodeId ? { node_id: nodeId } : { alias }) } };
+      }
+      const key = nodeId ? `n:${nodeId}` : `a:${alias}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rows.push({ node_id: nodeId, alias, can_message: item.can_message === false ? 0 : 1 });
+    }
+  }
+
+  db.transaction(() => {
+    if (mode) {
+      db.run("UPDATE network_members SET agent_access = ?1 WHERE network_id = ?2 AND user_id = ?3", [mode, input.networkId, input.userId]);
+    }
+    if (rows) {
+      db.run("DELETE FROM network_member_agent_grants WHERE network_id = ?1 AND user_id = ?2", [input.networkId, input.userId]);
+      for (const row of rows) {
+        db.run(
+          `INSERT INTO network_member_agent_grants (network_id, user_id, node_id, alias, can_message, created_by)
+           VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
+          [input.networkId, input.userId, row.node_id, row.alias, row.can_message, input.actorUserId],
+        );
+      }
+    }
+  });
+
+  return {
+    ok: true,
+    agent_access: getAgentAccessMode(input.networkId, input.userId) ?? "granted",
+    grants: listAgentGrants(input.networkId, input.userId),
+  };
+}
+
+/** 成员被移出网络时一并清掉授权,重新加入时从零开始。 */
+export function deleteAgentGrants(networkId: string, userId: string): void {
+  db.run("DELETE FROM network_member_agent_grants WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
+}
+
+// 多用户 Agent 权限 —— 受限成员(只看授权 Agent 的成员)能调的 MCP 工具。每一个都逐条审过:
+// 要么自己按授权过滤 / 准入(get_all_status、get_session_status、get_task、list_tasks、send_task、
+// send_message),要么是人类侧(send_desktop_message、需求看板),要么只读且对受限网络 fail-closed
+// (get_completions)。其余工具:受限成员只能在**不受限的**网络里调(必须显式传 network_id),
+// 在受限网络里、或没说是哪个网络时一律拒绝 —— 新增的工具默认落在拒绝这边。
+export const RESTRICTED_MEMBER_TOOLS: ReadonlySet<string> = new Set([
+  "get_all_status",
+  "get_session_status",
+  "get_task",
+  "list_tasks",
+  "get_completions",
+  "send_task",
+  "send_message",
+  "send_desktop_message",
+  "requirements_list",
+  "requirements_get",
+  "requirements_create",
+  "requirements_update",
+  "requirements_checklist_toggle",
+  "requirements_upsert_by_external_ref",
+  "projects_list",
+]);