@sleep2agi/commhub-server 0.9.0-preview.91 → 0.9.0-preview.93

package/src/tool-audience-http.test.ts

@@ -0,0 +1,195 @@
+// #478 —— tools/list 按调用者给(tool-audience.ts)。钉住:
+//   1. 每个注册的工具都在 TOOL_AUDIENCE 里归了类(新工具忘了归类 → 红),表里也没有已经不存在的工具;
+//   2. 兼容回放:对每种调用者(节点:正常 / 只读 / 受限 / enforce 开关;人:owner / member / viewer),把每个工具都真调一次 ——
+//      今天调得通的(不是那几种「不看参数就拒」的错误),一定还在它的列表里(协议工具在 opt-in 的列表里);
+//      列表里藏起来的,调用一定回那几种拒绝之一。tools/call 不受影响(只滤列表)。
+//   3. 每种角色的 tools/list 字节数(打印 before / after),各有上限(#476 的总上限仍管「全部工具」)。
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/tool-audience-http.test.ts(PG 在 tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } 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";
+import { TOOL_AUDIENCE } from "./tool-audience.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-tool-audience-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ToolAudiencePassw0rd!x";
+let NET = "";
+const T: Record<string, string> = {};
+
+/** 处理函数里「不看参数就拒」的错误码(用户令牌调节点工具 / 节点令牌调人的工具 / #487 的拒绝)。 */
+const REFUSALS = new Set(["network_token_required", "node_token_required", "caller_not_a_daemon", "user_token_required", "node_token_cannot_browse_files", "node_token_cannot_read_logs", "node_permission_denied"]);
+
+async function rpc(token: string, method: string, params: unknown, headers: Record<string, string> = {}) {
+  const res = await fetch(`${BASE}/mcp`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26", ...headers }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
+  const raw = await res.text();
+  const line = raw.split("\n").filter(x => x.startsWith("data:")).at(-1);
+  return { json: line ? JSON.parse(line.slice(5)) : JSON.parse(raw), bytes: 0 };
+}
+async function listTools(token: string, all = false): Promise<{ names: string[]; bytes: number; tools: any[] }> {
+  const { json } = await rpc(token, "tools/list", {}, all ? { "X-Anet-Tools": "all" } : {});
+  const tools = json.result.tools as any[];
+  return { names: tools.map(t => t.name), bytes: Buffer.byteLength(JSON.stringify({ tools }), "utf8"), tools };
+}
+
+// 参数:按 inputSchema 生成;名字认得的用真值;schema 有格式要求的给合法值(不给 → -32602,测试会让你补)。
+const OVERRIDES: Record<string, Record<string, unknown>> = {
+  get_skill: { skill_id: "skill_probe" },
+  review_skill: { skill_id: "skill_probe" },
+  mark_tasks_runtime_submitted: { task_ids: ["task_probe"] },
+  mark_tasks_consumed: { task_ids: ["task_probe"] },
+  upsert_network_secret: { key: "PROBE_KEY" },
+  update_provider: { provider_id: "prov_probe" },
+};
+function fill(schema: any, key: string, ctx: Record<string, unknown>): unknown {
+  if (!schema) return "probe";
+  if (ctx[key] !== undefined) return ctx[key];
+  if (schema.enum) return schema.enum[0];
+  if (schema.anyOf) return fill(schema.anyOf.find((s: any) => s.type !== "null") ?? schema.anyOf[0], key, ctx);
+  const t = Array.isArray(schema.type) ? schema.type.find((x: string) => x !== "null") : schema.type;
+  if (t === "string") return schema.minLength && schema.minLength > 5 ? "p".repeat(schema.minLength) : "probe";
+  if (t === "integer" || t === "number") return schema.minimum ?? 1;
+  if (t === "boolean") return false;
+  if (t === "array") return [];
+  if (t === "object") { const o: Record<string, unknown> = {}; for (const k of schema.required ?? []) o[k] = fill(schema.properties?.[k], k, ctx); return o; }
+  return "probe";
+}
+let ALL_TOOLS: any[] = [];
+const argsFor = (tool: any) => ({ ...(fill(tool.inputSchema, "", { network_id: NET, alias: "probe-victim", new_alias: "probe-victim", node_id: "node_ta_victim" }) as object), ...(OVERRIDES[tool.name] ?? {}) });
+async function callOutcome(token: string, tool: any): Promise<{ refused: boolean; schema: boolean; code: string }> {
+  const { json } = await rpc(token, "tools/call", { name: tool.name, arguments: argsFor(tool) });
+  if (json.error) return { refused: false, schema: json.error.code === -32602, code: `rpc:${json.error.code}` };
+  const text = String(json.result?.content?.[0]?.text ?? "");
+  if (/^MCP error -32602/.test(text)) return { refused: false, schema: true, code: "schema" };
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  const code = body && body.ok === false ? String(body.error) : "ok";
+  // 受限成员的闸(agent_access_restricted)跑在处理函数前面,看传的 network_id;对节点 / 协议工具,处理函数后面还有一道
+  // 不看参数的 network_token_required(用户令牌换哪个网络都过不去),所以这时它也算拒。对「两边都能用」的工具不算。
+  const masked = code === "agent_access_restricted" && (TOOL_AUDIENCE[tool.name] === "node" || TOOL_AUDIENCE[tool.name] === "protocol");
+  return { refused: REFUSALS.has(code) || masked, schema: false, code };
+}
+
+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";
+  delete process.env.COMMHUB_NODE_PERMISSIONS;
+  const owner = register(`ta_owner_${Date.now()}`, PW, undefined, "Owner");
+  NET = owner.network_id!;
+  T.owner = owner.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}`;
+  const mk = async (k: string, role: string) => {
+    const username = `ta_${k}_${Date.now()}`;
+    await fetch(`${BASE}/api/admin/users`, { method: "POST", headers: { Authorization: `Bearer ${T.owner}`, "Content-Type": "application/json" }, body: JSON.stringify({ username, password: PW, network_id: NET, role }) });
+    T[k] = (await (await fetch(`${BASE}/api/auth/login`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ username, password: PW }) })).json()).token;
+  };
+  await mk("member", "member");
+  await mk("viewer", "viewer");
+  for (const mode of ["normal", "readonly", "restricted"]) {
+    T[`node_${mode}`] = createNetworkTokenForNode(owner.user!.user_id, NET, `ta-${mode}`, `node_ta_${mode}`).token!;
+    db.run("UPDATE nodes SET permission_mode = ?1 WHERE node_id = ?2", [mode, `node_ta_${mode}`]);
+  }
+  createNetworkTokenForNode(owner.user!.user_id, NET, "probe-victim", "node_ta_victim");
+  // 没有身份的调用者 = 不过滤:用 owner 的「全部」作为全集(owner 是用户令牌,协议工具对它不列;全集取并集)。
+  const a = await listTools(T.node_normal, true);
+  const b = await listTools(T.owner);
+  const byName = new Map([...a.tools, ...b.tools].map(t => [t.name, t]));
+  ALL_TOOLS = [...byName.values()];
+}, 60_000);
+
+afterAll(() => {
+  delete process.env.COMMHUB_NODE_PERMISSIONS;
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("every tool is classified", () => {
+  test("registry == TOOL_AUDIENCE (no unclassified tool, no stale entry)", async () => {
+    const registered = ALL_TOOLS.map(t => t.name).sort();
+    expect(registered.length).toBeGreaterThan(70);
+    expect(registered.filter(n => !TOOL_AUDIENCE[n])).toEqual([]);
+    expect(Object.keys(TOOL_AUDIENCE).filter(n => !registered.includes(n))).toEqual([]);
+  });
+});
+
+describe("compat replay: nothing callable today disappears from the list", () => {
+  const cases: Array<[string, string, string | null]> = [
+    ["node (normal, log)", "node_normal", null], ["node (readonly)", "node_readonly", null], ["node (restricted)", "node_restricted", null],
+    ["node (normal, enforce)", "node_normal", "enforce"], ["owner", "owner", null], ["member", "member", null], ["viewer", "viewer", null],
+  ];
+  for (const [label, key, flag] of cases) {
+    test(label, async () => {
+      if (flag) process.env.COMMHUB_NODE_PERMISSIONS = flag; else delete process.env.COMMHUB_NODE_PERMISSIONS;
+      try {
+        const isNode = key.startsWith("node_");
+        const listed = new Set((await listTools(T[key], isNode)).names);
+        // 「调得通 ⇒ 列着」,等价于「藏起来的 ⇒ 一定是那几种拒绝」。
+        const lost: string[] = [], schema: string[] = [];
+        for (const tool of ALL_TOOLS) {
+          const out = await callOutcome(T[key], tool);
+          if (out.schema) schema.push(tool.name);
+          if (!out.refused && !listed.has(tool.name)) lost.push(`${tool.name}(${out.code})`);
+        }
+        expect(schema).toEqual([]); // 每个工具都真跑到了处理函数(否则判不出能不能用)
+        expect(lost).toEqual([]);
+      } finally { delete process.env.COMMHUB_NODE_PERMISSIONS; }
+    }, 120_000);
+  }
+});
+
+describe("what each caller sees", () => {
+  test("node: no human-only tools; protocol tools only with X-Anet-Tools: all; user: no node / protocol tools", async () => {
+    const node = new Set((await listTools(T.node_normal)).names);
+    const nodeAll = new Set((await listTools(T.node_normal, true)).names);
+    const user = new Set((await listTools(T.owner)).names);
+    for (const [name, a] of Object.entries(TOOL_AUDIENCE)) {
+      expect([name, node.has(name)]).toEqual([name, a === "both" || a === "node"]);
+      expect([name, nodeAll.has(name)]).toEqual([name, a !== "user"]);
+      expect([name, user.has(name)]).toEqual([name, a === "both" || a === "user"]);
+    }
+    // ?tools=all is the same switch for clients that cannot set headers
+    const viaQuery = await fetch(`${BASE}/mcp?tools=all`, { method: "POST", headers: { Authorization: `Bearer ${T.node_normal}`, "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/list", params: {} }) });
+    const raw = await viaQuery.text();
+    const parsed = JSON.parse(raw.split("\n").filter(x => x.startsWith("data:")).at(-1)!.slice(5));
+    expect(parsed.result.tools.length).toBe(nodeAll.size);
+  });
+
+  test("node modes: readonly / restricted drop broadcast + node writes + human-only; enforce drops human-only for normal nodes", async () => {
+    const ro = new Set((await listTools(T.node_readonly)).names);
+    for (const n of ["broadcast", "update_node_config", "create_node", "upsert_provider"]) expect([n, ro.has(n)]).toEqual([n, false]);
+    for (const n of ["send_task", "requirements_update", "report_status", "get_all_status"]) expect([n, ro.has(n)]).toEqual([n, true]); // 看参数才拒的照列
+    expect(new Set((await listTools(T.node_normal)).names).has("upsert_provider")).toBe(true); // log 模式:调得通,照列
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    try { expect(new Set((await listTools(T.node_normal)).names).has("upsert_provider")).toBe(false); } finally { delete process.env.COMMHUB_NODE_PERMISSIONS; }
+  });
+
+  test("a hidden tool still answers tools/call exactly as before (only the list changes)", async () => {
+    const p = await rpc(T.node_normal, "tools/call", { name: "projects_create", arguments: { network_id: NET, name: "示例项目" } });
+    expect(JSON.parse(p.json.result.content[0].text).error).toBe("user_token_required");
+    const r = await rpc(T.owner, "tools/call", { name: "report_status", arguments: argsFor(ALL_TOOLS.find(t => t.name === "report_status")) });
+    expect(JSON.parse(r.json.result.content[0].text).error).toBe("network_token_required");
+    const g = await rpc(T.node_normal, "tools/call", { name: "get_config_update", arguments: {} });
+    expect(JSON.parse(g.json.result.content[0].text).ok).toBe(true); // 协议工具默认不列,但照常能调
+  });
+});
+
+describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
+  // 全部工具(= 改动前每个调用者拿到的)71–72 KB;改动后按角色。改数字时在 PR 里写为什么。
+  // 量出来(#478 合入时):全部 74 个工具 71,559 B;节点 52 个 57,632 B(−19%);人 56 个 54,780 B(−23%)。留 ~1.5 KB 余量。
+  const CEILINGS = { node: 59_000, user: 56_500, all: 72_500 } as const;
+  test("node / user / all", async () => {
+    const node = await listTools(T.node_normal);
+    const user = await listTools(T.owner);
+    const all = { bytes: Buffer.byteLength(JSON.stringify({ tools: ALL_TOOLS }), "utf8"), names: ALL_TOOLS.map(t => t.name) };
+    console.log(`tools/list bytes — all ${all.names.length} tools ${all.bytes} B; node ${node.names.length} tools ${node.bytes} B (−${Math.round(100 - node.bytes / all.bytes * 100)}%); user ${user.names.length} tools ${user.bytes} B (−${Math.round(100 - user.bytes / all.bytes * 100)}%)`);
+    expect(node.bytes).toBeLessThanOrEqual(CEILINGS.node);
+    expect(user.bytes).toBeLessThanOrEqual(CEILINGS.user);
+    expect(all.bytes).toBeLessThanOrEqual(CEILINGS.all);
+  });
+});

package/src/tool-audience.ts

@@ -0,0 +1,109 @@
+// #478 —— tools/list 按调用者给:只列这个令牌真能用的工具。
+//
+// 以前每个调用者拿到同一份 ~71 KB 的 tools/list:Agent 节点看见只有人能用的工具(项目管理、浏览别的节点的文件 / 日志),
+// 人看见只有节点能用的心跳和 agent-node / daemon 之间的协议工具。这些调用本来就会被拒,只是白白占模型的上下文。
+//
+// 🔴 只改「列出来的」,不改「能不能调」:工具照旧全部注册,tools/call 的结果逐字节不变(隐藏的工具照样回它今天回的那个错误)。
+// 🔴 只藏「一定会被拒」的:判据是处理函数里**不看参数**的那道闸 —— 用户令牌调节点工具一律 network_token_required /
+//    node_token_required / caller_not_a_daemon;节点令牌调人的工具一律 user_token_required / node_token_cannot_*;
+//    #487 的节点权限只在「不看参数就必拒」时才藏(见 nodeHidden)。看参数才决定的(派活给谁、哪个网络)一律照列。
+//    受限成员(只看授权 Agent)的拒绝取决于传的 network_id,所以不按它藏。
+// 🔴 protocol 类(agent-node / anet daemon 和 Hub 之间的拉取 / 确认)节点令牌能调,但没有模型该调它们:默认不列,
+//    客户端带 `X-Anet-Tools: all`(或 /mcp?tools=all)时照列 —— 调用不受影响,agent-node 本来就按名字直接调、从不 list。
+// 新注册的工具必须在 TOOL_AUDIENCE 里归类(tool-audience-http.test.ts 钉住,漏了就红)。
+
+import { NODE_TOOL_CLASS, nodeIdentity, nodePermissionsFlag, broadcastVerdict, humanOnlyVerdict, writeVerdict, type Verdict } from "./node-permissions.js";
+
+/**
+ * both     —— 人和节点都能调(按参数 / 网络再判的,也算这一类)。
+ * node     —— 只有节点令牌(用户令牌一律 network_token_required):节点自己的心跳,模型会调,照列给节点。
+ * protocol —— 只有节点令牌,而且是 agent-node / daemon 和 Hub 之间的协议(拉请求、确认、运行证据):默认不列,opt-in 才列。
+ * user     —— 只有人(节点令牌一律被拒)。
+ */
+export type ToolAudience = "both" | "node" | "protocol" | "user";
+
+export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
+  // ── 节点:用户令牌一律 network_token_required ──
+  report_status: "node",
+  // ── 协议:用户令牌一律 network_token_required / node_token_required / caller_not_a_daemon ──
+  mark_tasks_runtime_submitted: "protocol", mark_tasks_consumed: "protocol",
+  get_config_update: "protocol", ack_config_update: "protocol",
+  get_rules_file_request: "protocol", ack_rules_file_request: "protocol",
+  list_my_pending_create_requests: "protocol", list_my_pending_lifecycle_requests: "protocol", list_my_children: "protocol",
+  get_create_request: "protocol", ack_create_request: "protocol",
+  get_stop_request: "protocol", ack_stop_request: "protocol",
+  get_start_request: "protocol", ack_start_request: "protocol",
+  get_probe_request: "protocol", ack_probe_request: "protocol",
+  // ── 人:节点令牌一律 user_token_required(项目管理)/ node_token_cannot_browse_files / node_token_cannot_read_logs ──
+  projects_create: "user", projects_update: "user",
+  list_node_files: "user", read_node_file: "user", tail_node_logs: "user",
+  // ── 两边都能调 ──
+  submit_skill: "both", list_skills: "both", get_skill: "both", review_skill: "both",
+  report_completion: "both", get_inbox: "both", ack_inbox: "both",
+  get_all_status: "both", get_session_status: "both",
+  send_task: "both", send_message: "both", send_reply: "both", send_peer_reply: "both", send_ack: "both",
+  retry_task: "both", get_task: "both", list_tasks: "both", cancel_task: "both", reassign_task: "both",
+  send_desktop_message: "both", broadcast: "both", get_completions: "both",
+  update_node_config: "both", read_node_rules_file: "both", write_node_rules_file: "both",
+  list_node_skills: "both", read_node_skill: "both", get_rules_file_result: "both",
+  restart_node: "both", list_host_supervisors: "both", create_node: "both", stop_node: "both", delete_node: "both", start_node: "both",
+  upsert_network_secret: "both", list_network_secrets: "both", upsert_provider: "both", update_provider: "both",
+  list_providers: "both", probe_provider_model: "both", get_probe_results: "both",
+  requirements_list: "both", requirements_people: "both", requirements_get: "both", requirements_create: "both",
+  requirements_update: "both", requirements_checklist_toggle: "both", requirements_upsert_by_external_ref: "both",
+  requirements_events: "both", requirements_comment: "both", projects_list: "both",
+};
+
+/** 调用者:节点令牌(绑定网络)/ 用户令牌 / 没有身份(旧的全局令牌、未开鉴权)—— 最后一种什么都不藏。 */
+export type ToolCaller =
+  | { kind: "node"; tokenId: string | null; networkId: string | null; includeProtocol: boolean }
+  | { kind: "user"; includeProtocol: boolean }
+  | { kind: "unknown" };
+
+/** #487 的判定里「不看参数就必拒」的那几类;和 nodeDecide 同一规则(显式模式恒拒,其余看开关),只是不记日志。 */
+function nodeHidden(name: string, verdictFor: (cls: string) => Verdict): boolean {
+  const cls = NODE_TOOL_CLASS[name];
+  if (cls !== "broadcast" && cls !== "node_write" && cls !== "human_only") return false;
+  const v = verdictFor(cls);
+  if (!v) return false;
+  if (v.reason === "mode_readonly" || v.reason === "mode_restricted_not_assigned") return true;
+  return nodePermissionsFlag() === "enforce";
+}
+
+/** 这个调用者的 tools/list 里留哪些。没归类的工具一律留下(宁可多列;测试保证不会有没归类的)。 */
+export function listedToolFilter(caller: ToolCaller): (name: string) => boolean {
+  if (caller.kind === "unknown") return () => true;
+  if (caller.kind === "user") return name => { const a = TOOL_AUDIENCE[name]; return a !== "node" && a !== "protocol"; };
+  const id = caller.tokenId && caller.networkId ? nodeIdentity(caller.tokenId, caller.networkId) : null;
+  const verdictFor = (cls: string): Verdict => {
+    if (!id) return null;
+    if (cls === "broadcast") return broadcastVerdict(id);
+    if (cls === "node_write") return writeVerdict(id);
+    return humanOnlyVerdict(id);
+  };
+  return name => {
+    const a = TOOL_AUDIENCE[name];
+    if (a === "user") return false;
+    if (a === "protocol" && !caller.includeProtocol) return false;
+    return !nodeHidden(name, verdictFor);
+  };
+}
+
+/**
+ * 给一个已经注册完工具的 McpServer 换上按调用者过滤的 tools/list。只包 tools/list 的处理函数(先跑 SDK 原来的、
+ * 再滤掉不列的),tools/call 不碰。SDK 的处理函数表是内部字段:取不到就不滤(宁可多列),测试会红。
+ */
+export function scopeToolsList(server: unknown, keep: (name: string) => boolean): void {
+  const handlers = (server as { server?: { _requestHandlers?: Map<string, (req: unknown, extra: unknown) => unknown> } }).server?._requestHandlers;
+  const inner = handlers?.get("tools/list");
+  if (!handlers || !inner) return;
+  handlers.set("tools/list", async (req: unknown, extra: unknown) => {
+    const result = await inner(req, extra) as { tools?: Array<{ name: string }> };
+    return Array.isArray(result?.tools) ? { ...result, tools: result.tools.filter(t => keep(t.name)) } : result;
+  });
+}
+
+/** 客户端要不要看协议工具:`X-Anet-Tools: all` 或 /mcp?tools=all。 */
+export function wantsAllTools(req: Request, url: URL): boolean {
+  return (req.headers.get("x-anet-tools") ?? "").trim().toLowerCase() === "all" || url.searchParams.get("tools") === "all";
+}

package/src/tools-list-json-schema.test.ts

@@ -19,7 +19,8 @@ import { registerTools } from "./tools.js";
 
 async function connect() {
   const server = new McpServer({ name: "list-tools-test", version: "1" });
-  registerTools(server, undefined, "net_list_tools", "u_list_tools", "u_list_tools", false, "tok_list_tools");
+  // 没有用户 / 节点身份的调用者 = tools/list 不按角色过滤(#478),这里要的正是「每个登记的工具」。
+  registerTools(server, undefined, "net_list_tools", null, "u_list_tools", false, "tok_list_tools");
   const client = new Client({ name: "list-tools-client", version: "1" });
   const [ct, st] = InMemoryTransport.createLinkedPair();
   await server.connect(st);

package/src/tools.ts

@@ -12,7 +12,9 @@ import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { addAgentNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { canMessageAgent, restrictedNetworkIds, RESTRICTED_MEMBER_TOOLS } from "./agent-access.js";
+import { canMessageAgent, restrictedNetworkIds, RESTRICTED_MEMBER_TOOLS, type AgentRef } from "./agent-access.js";
+import { listedToolFilter, scopeToolsList, type ToolCaller } from "./tool-audience.js";
+import { broadcastVerdict, dispatchVerdict, humanOnlyVerdict, NODE_TOOL_CLASS, nodeDecide, nodeIdentity, nodePermissionDeniedBody, writeVerdict, type NodeIdentity, type Verdict } from "./node-permissions.js";
 import { restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { errorBody } from "./requirements-errors.js";
 import { handleRequirementsRequest } from "./requirements.js";
@@ -200,11 +202,69 @@ function guardRestrictedMemberTools(server: McpServer, restrictedNets: string[],
   }
 }
 
-export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null) {
+// RFC-041 第一阶段(#487):节点令牌的每个 MCP 工具先按 NODE_TOOL_CLASS 判一次(node-permissions.ts)。
+// log 模式下正常节点照常放行、只记录;显式的只读 / 受限模式立刻生效。requirements_* 在 requirements.ts 里按卡判。
+function guardNodePermissionTools(server: McpServer, tokenId: string, networkId: string): void {
+  const denied = (reason: Parameters<typeof nodePermissionDeniedBody>[0], route: string) => ({
+    content: [{ type: "text" as const, text: JSON.stringify(nodePermissionDeniedBody(reason, route)) }],
+  });
+  const taskTarget = (taskId: unknown): { to: AgentRef; from: string | null } | null => {
+    if (typeof taskId !== "string" || !taskId) return null;
+    const t = db.get<{ to_name: string | null; to_node_id: string | null; from_name: string | null }>(
+      "SELECT to_name, to_node_id, from_name FROM tasks WHERE task_id = ?1 AND network_id = ?2", taskId, networkId);
+    return t ? { to: { alias: t.to_name, nodeId: t.to_node_id }, from: t.from_name } : null;
+  };
+  const aliasTarget = (alias: unknown): AgentRef | null => {
+    if (typeof alias !== "string" || !alias.trim()) return null;
+    const canonical = resolveCanonicalAlias(networkId, alias.trim()).alias;
+    const session = db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", canonical, networkId);
+    return { alias: canonical, nodeId: session?.node_id ?? null };
+  };
+  const verdictFor = (id: NodeIdentity, name: string, args: Record<string, unknown>): Verdict => {
+    switch (NODE_TOOL_CLASS[name]) {
+      case "dispatch": {
+        if (name === "retry_task" || name === "cancel_task") {
+          const t = taskTarget(args.task_id);
+          if (!t) return null; // 没这个任务:交给工具自己回 not found
+          if (name === "cancel_task" && t.from && id.aliases.includes(t.from)) return null; // 撤回自己派的
+          return dispatchVerdict(id, t.to);
+        }
+        const target = aliasTarget(name === "reassign_task" ? args.new_alias : args.alias);
+        return target ? dispatchVerdict(id, target) : null;
+      }
+      case "broadcast": return broadcastVerdict(id);
+      case "node_write": return writeVerdict(id, name);
+      case "human_only": return humanOnlyVerdict(id, name);
+      default: return null; // always / read / requirements(按卡判)/ 没归类的(test 保证没有)
+    }
+  };
+  const wrap = (name: string, handler: (...callArgs: any[]) => any) => async (...callArgs: any[]) => {
+    const cls = NODE_TOOL_CLASS[name];
+    if (cls && cls !== "always" && cls !== "read" && cls !== "requirements") {
+      const id = nodeIdentity(tokenId, networkId);
+      const args = callArgs[0] && typeof callArgs[0] === "object" ? callArgs[0] as Record<string, unknown> : {};
+      const verdict = id ? verdictFor(id, name, args) : null;
+      if (id && nodeDecide(id, `mcp:${name}`, verdict)) return denied(verdict!.reason, `mcp:${name}`);
+    }
+    return handler(...callArgs);
+  };
+  const anyServer = server as any;
+  for (const method of ["tool", "registerTool"] as const) {
+    const original = anyServer[method].bind(server);
+    anyServer[method] = (...regArgs: any[]) => {
+      const last = regArgs.length - 1;
+      if (typeof regArgs[0] === "string" && typeof regArgs[last] === "function") regArgs[last] = wrap(regArgs[0], regArgs[last]);
+      return original(...regArgs);
+    };
+  }
+}
+
+export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null, listing: { includeProtocol?: boolean } = {}) {
   // 多用户 Agent 权限:用户令牌调用者在哪些网络里是受限成员(只看授权 Agent)。
   // 网络令牌不会走到这里 —— 受限成员的网络令牌在 resolveToken 就被拒了。
   const restrictedNets = enforceUserId && !callerTokenIsNetwork && !enforceNetworkId ? restrictedNetworkIds(enforceUserId) : [];
   if (restrictedNets.length) guardRestrictedMemberTools(server, restrictedNets, enforceUserId!);
+  if (callerTokenIsNetwork && callerTokenId && enforceNetworkId) guardNodePermissionTools(server, callerTokenId, enforceNetworkId);
   // Default from_session for outbound tools — extracted from the calling
   // token's binding (ntok_ → node alias, utok_ → username). Without this,
   // an agent's send_task call always claimed from='hub' and peer agents
@@ -6074,6 +6134,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
     async ({ id, text, network_id }) => requirementsCall("POST", `/api/requirements/${encodeURIComponent(id)}/comments`, network_id, { text }),
   );
+
+  // #478:tools/list 只列这个调用者真能用的工具(tool-audience.ts)。只滤列表,tools/call 不变。
+  const caller: ToolCaller = callerTokenIsNetwork
+    ? { kind: "node", tokenId: callerTokenId ?? null, networkId: enforceNetworkId ?? null, includeProtocol: listing.includeProtocol === true }
+    : enforceUserId ? { kind: "user", includeProtocol: listing.includeProtocol === true } : { kind: "unknown" };
+  scopeToolsList(server, listedToolFilter(caller));
 }
 
 // ────────────────────────────────────────────────────────────────────