@sleep2agi/commhub-server 0.9.0-preview.92 → 0.9.0-preview.94

package/src/server.ts

@@ -3,8 +3,10 @@ import { markGzipReusable, maybeGzipResponse, trimLightTask } from "./http-gzip"
 import { ifNoneMatchHits, memoStatusBody } from "./status-read-cache";
 import { statusAliasResolverRead } from "./status-alias-resolver.js";
 import { readNodeHealth } from "./node-health-store.js";
+import { wantsAllTools } from "./tool-audience.js";
 import { assertNodeHealthy, degradedLayers } from "./node-health-guard.js";
 import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setMemberDepartment, updateDepartment } from "./departments.js";
+import { addManualMember, canManageGroup, createDepartmentGroup, getDepartmentGroup, groupById, groupTx, groupViewerCan, isGroupMember, listGroupMembers, listVisibleGroups, readGroup, removeManualMember, renameGroup, syncDepartmentGroups } from "./department-groups.js";
 import { DEPARTMENT_SCOPE_DENIED, departmentLeaders, departmentSubtree, headScope, listDepartmentProjectGrants, managedDepartmentIds, membersIn, replaceDepartmentProjectGrants } from "./department-heads.js";
 import { redactMessageRow } from "./redact-tokens.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -22,6 +24,7 @@ import { pendingInboxCount } from "./inbox-count.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
+import { groupMemberSeesFile, groupUnreadFor, listGroupMessages, listGroupThreads, markGroupRead, memberGroup, sendGroupMessage } from "./group-messages.js";
 import { getTaskAccessMode, isTaskScoped, listProjectGrants, replaceTaskGrants, NEW_MEMBER_TASK_ACCESS } from "./task-access.js";
 import { canMessageAgent, isAgentRestricted, listAgentGrants, listGroupGrants, getAgentAccessMode, replaceAgentGrants, restrictedNetworkIds, usernameIsAgentAlias, listAgentGroups, createAgentGroup, updateAgentGroup, replaceAgentGroupMembers, deleteAgentGroup, usersGrantedGroup } from "./agent-access.js";
 import { broadcastVerdict, dispatchVerdict, humanOnlyVerdict, NODE_PERMISSION_MODES, nodeDecide, nodeIdentity, nodePermissionDeniedBody, nodePermissionsFlag, streamVerdict, writeVerdict, type NodeIdentity, type NodePermissionMode, type Verdict } from "./node-permissions.js";
@@ -67,6 +70,7 @@ import { resolveRestFromSession } from "./rest-identity.js";
 import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js";
 import { diagnoseTask } from "./task-diagnostic.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
+import { startDueReminderTimer } from "./requirement-due-reminders.js";
 import { handleRequirementsRequest } from "./requirements.js";
 import { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats, setRouteCallerMasterToken, setRouteCallerTokenReader } from "./route-timing.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
@@ -124,7 +128,11 @@ const SERVER_VERSION = (() => {
 })();
 
 // Feature flags advertised on /health (see the /health handler). Exported for tests.
-export const HUB_HEALTH_CAPABILITIES = ["status_node_id"] as const;
+// node_permission_mode(#489):节点有 permission_mode、GET /api/nodes 每行带 viewer_can.permission_mode,
+// PUT /api/nodes/:id/permission-mode 与 GET /api/networks/:id/node-permission-report 可用(RFC-041 第一阶段)。
+// chat_groups(RFC-042,#457):部门群可用 —— …/departments/:dept/group、…/chat-groups(资料 / 成员 / 消息 / 已读)、
+// GET /api/dm/threads 的 group_threads;群对象带 viewer_can {manage, post},会话行带 last_message 预览,成员带 username / display_name。
+export const HUB_HEALTH_CAPABILITIES = ["status_node_id", "node_permission_mode", "chat_groups"] as const;
 
 // In-memory log ring buffer — last N lines streamed via /api/server-logs.
 // Wraps console.log/info/warn/error so EVERY existing log call lands here
@@ -180,12 +188,12 @@ function sweepStaleRateLimits(): void {
 }
 
 // ── Factory: 每个请求创建新的 McpServer（stateless 模式）──
-function createServer(clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null): McpServer {
+function createServer(clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null, includeProtocolTools = false): McpServer {
   const server = new McpServer({
     name: "commhub",
     version: "0.5.0",
   });
-  registerTools(server, clientIP, enforceNetworkId, enforceUserId, callerAlias, callerTokenIsNetwork, callerTokenId);
+  registerTools(server, clientIP, enforceNetworkId, enforceUserId, callerAlias, callerTokenIsNetwork, callerTokenId, { includeProtocol: includeProtocolTools });
   return server;
 }
 
@@ -453,6 +461,10 @@ export function normalizeEntry(
 //     legacy master token still pass above, as for every other file.
 //     Files uploaded any other way never become DM-scoped, including when
 //     they are later forwarded into a DM.
+//     RFC-042 (#457, group messages): a DM-scoped file is also readable by
+//     the CURRENT members of a chat group with a message carrying it
+//     (group-messages.ts groupMemberSeesFile); the same widening applies to
+//     restricted members below. Removed members lose it immediately.
 //   - Everything else → deny (404). New uploads in production always
 //     carry a truthy owner_id (requireAuth blocks the null-owner-
 //     producing path when DEV_OPEN=off and no legacy master token is
@@ -480,12 +492,12 @@ export function authorizeFileDownload(
     // 私信文件:只看是不是这段私信里的人,与受限 / 不受限无关。
     if (entry.dmScoped) {
       if (entry.ownerId !== null && entry.ownerId === principal.userId) return true;
-      return !!fileId && dmParticipantSeesFile(principal.userId, entry.networkId, fileId);
+      return !!fileId && (dmParticipantSeesFile(principal.userId, entry.networkId, fileId) || groupMemberSeesFile(principal.userId, entry.networkId, fileId));
     }
     // 多用户 Agent 权限:受限成员只能下载自己传的,或者出现在自己与授权 Agent 往来 / 自己收件箱里的文件。
     if (!isAgentRestricted(principal.userId, entry.networkId)) return true;
     if (entry.ownerId !== null && entry.ownerId === principal.userId) return true;
-    return !!fileId && restrictedMemberSeesFile(principal.userId, principal.username, entry.networkId, fileId);
+    return !!fileId && (restrictedMemberSeesFile(principal.userId, principal.username, entry.networkId, fileId) || groupMemberSeesFile(principal.userId, entry.networkId, fileId));
   }
 
   if (principal.kind === "ntok" || principal.kind === "utok") {
@@ -992,7 +1004,8 @@ return Bun.serve({
         }
         labelRoute(req, mcpParsedBody === undefined ? "?" : mcpRouteLabel(mcpParsedBody));
       }
-      const mcpServer = createServer(clientIP, enforceNetId, authCtx?.userId || null, callerAlias, !!token?.startsWith("ntok_"), authCtx?.tokenId || null);
+      // #478:tools/list 按调用者过滤;X-Anet-Tools: all / ?tools=all 时节点令牌也列出协议工具。
+      const mcpServer = createServer(clientIP, enforceNetId, authCtx?.userId || null, callerAlias, !!token?.startsWith("ntok_"), authCtx?.tokenId || null, wantsAllTools(req, url));
       await mcpServer.connect(transport);
       const response = await transport.handleRequest(req, mcpParsedBody === undefined ? undefined : { parsedBody: mcpParsedBody });
       // Disconnect after response to prevent McpServer leak
@@ -1749,7 +1762,7 @@ return Bun.serve({
     // 在这棵子树里也能写;越出子树 → 403 department_scope_denied(固定一个错误)。不是负责人的成员与以前逐字节相同。 ──
     const deptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments(?:\/([^/]+))?$/);
     const memberDeptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/members\/([^/]+)\/department$/);
-    const deptSubMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments\/([^/]+)\/(project-grants|nodes)$/);
+    const deptSubMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments\/([^/]+)\/(project-grants|nodes|group)$/);
     if (deptMatch || memberDeptMatch || deptSubMatch) {
       const token = requestToken(req, { allowQueryToken: false });
       const resolved = token ? resolveToken(token) : null;
@@ -1797,6 +1810,35 @@ return Bun.serve({
           });
           return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, nodes }));
         }
+        if (deptSubMatch[3] === "group") {
+          // RFC-042(#457)部门群:GET 看部门挂着的群,POST 建群。Agent(节点令牌)不进群,一律 403。
+          // 建:owner / admin / Hub 管理员,或这个部门(含上级)的负责人。读:上面这些人,和群成员;别人 → 404(不暴露有没有群)。
+          if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "humans_only" }, { status: 403 }));
+          const mayCreate = canManage || head.managed.has(deptId);
+          if (req.method === "GET") {
+            const linked = getDepartmentGroup(netId, deptId);
+            // 兜底对账(RFC-042 §4):读之前先把成员对齐,再判「是不是成员」。
+            if (linked) groupTx(() => { syncDepartmentGroups(netId, linked.id); });
+            const group = linked ? getDepartmentGroup(netId, deptId) : null;
+            if (!group || (!mayCreate && !isGroupMember(group.id, resolved.user.user_id))) {
+              return withCors(req, Response.json({ ok: false, error: "department_group_not_found" }, { status: 404 }));
+            }
+            const viewerCan = groupViewerCan(group, isGroupMember(group.id, resolved.user.user_id), canManage, head.managed);
+            return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, group: { ...group, viewer_can: viewerCan }, members: listGroupMembers(group.id) }));
+          }
+          if (req.method !== "POST") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+          if (!mayCreate) return isHead ? scopeDenied() : withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+          let groupBody: Record<string, unknown> = {};
+          try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; groupBody = b && typeof b === "object" && !Array.isArray(b) ? b as Record<string, unknown> : {}; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
+          const r = createDepartmentGroup(netId, deptId, resolved.user.user_id, groupBody);
+          if (!r.ok) {
+            const { ok: _ok, status, ...rest } = r;
+            return withCors(req, Response.json({ ok: false, ...rest }, { status }));
+          }
+          auditDepartment(resolved.user, "department_group_created", netId, JSON.stringify({ id: deptId, group_id: r.group.id, members: r.members.length, ...(canManage ? {} : { via: "leader" }) }));
+          const createdCan = groupViewerCan(r.group, r.members.some((m) => m.user_id === resolved.user.user_id), canManage, head.managed);
+          return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, group: { ...r.group, viewer_can: createdCan }, members: r.members }, { status: 201 }));
+        }
         // 部门项目授权:只有 owner / admin(和按人授权一样)。
         if (!canManage) return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
         if (req.method === "GET") {
@@ -1887,6 +1929,108 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
     }
 
+    // ── RFC-042(#457):群(目前只有部门群)。
+    // GET …/chat-groups = 我在里面的群(owner / admin / Hub 管理员看到全部);GET …/chat-groups/:gid = 群资料 + 成员
+    // (群成员、owner / admin、该部门(含上级)负责人;别人 404)。建群走 POST …/departments/:dept/group。
+    // 第二个 PR:PATCH …/chat-groups/:gid {name} 改群名;POST …/chat-groups/:gid/members {user_id} 手动拉人;
+    // DELETE …/chat-groups/:gid/members/:uid 手动移人(source='department' 的人 → 409 department_member)。
+    // 管群 = owner / admin / Hub 管理员,或挂部门的群的该部门(含上级)负责人。看得见但管不了 → 403 group_manage_denied;
+    // 看不见 → 404 group_not_found(不暴露有没有群)。Agent(节点令牌)不进群,一律 403 humans_only。 ──
+    const chatGroupsMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/chat-groups(?:\/([^/]+)(?:\/(members|messages|read)(?:\/([^/]+))?)?)?$/);
+    if (chatGroupsMatch) {
+      const token = requestToken(req, { allowQueryToken: false });
+      const resolved = token ? resolveToken(token) : null;
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "humans_only" }, { status: 403 }));
+      const netId = decodeURIComponent(chatGroupsMatch[1]);
+      const hubAdmin = isHubAdminCredential(resolved);
+      const role = getUserNetworkRole(resolved.user.user_id, netId);
+      if (!hubAdmin && !role) return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
+      const canManage = hubAdmin || role === "owner" || role === "admin";
+      const gid = chatGroupsMatch[2] ? decodeURIComponent(chatGroupsMatch[2]) : null;
+      const sub = chatGroupsMatch[3];
+      const memberUid = chatGroupsMatch[4] ? decodeURIComponent(chatGroupsMatch[4]) : null;
+      // viewer 当负责人不获得任何东西(headScope 已保证);owner / admin 本来全管,不必算。
+      const managed = canManage ? new Set<string>() : headScope(netId, resolved.user.user_id).managed;
+      if (!gid) {
+        if (req.method !== "GET") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+        // 第三个 PR:每个群附上我的 unread / last_message_at(只对我在里面的群;管理者看到的非成员群是 0 / null —— 不让管理身份窥探消息时间)。
+        // App 补口(只增):last_message 预览(同一口径,非成员群 null)和 viewer_can {manage, post}(与写接口同一判据)。
+        // listGroupThreads 已经批量带上 last_message,整张列表固定几次查询,不逐群查。
+        const threads = new Map(listGroupThreads(netId, resolved.user.user_id).map((t) => [t.group_id, t]));
+        const groups = listVisibleGroups(netId, resolved.user.user_id, canManage).map((g) => {
+          const t = g.is_member ? threads.get(g.id) : undefined;
+          return { ...g, unread: t?.unread ?? 0, last_message_at: t?.last_at ?? null, last_message: t?.last_message ?? null, viewer_can: groupViewerCan(g, g.is_member, canManage, managed) };
+        });
+        return withCors(req, Response.json({ ok: true, network_id: netId, groups }));
+      }
+      const notFound = () => withCors(req, Response.json({ ok: false, error: "group_not_found" }, { status: 404 }));
+      // 第三个 PR(群消息):GET / POST …/:gid/messages、POST …/:gid/read。只认**当前群成员** —— owner / admin / 负责人
+      // 不是成员也读不到消息(他们看得到群资料,但消息只给群里的人);别人(含被移出的人)一律 404 group_not_found。
+      if (sub === "messages" || sub === "read") {
+        if (memberUid) return notFound();
+        const ok = (sub === "messages" && (req.method === "GET" || req.method === "POST")) || (sub === "read" && req.method === "POST");
+        if (!ok) return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+        if (!memberGroup(netId, gid, resolved.user.user_id)) return notFound();
+        const failedMsg = (r: { status: number; error: string }) => withCors(req, Response.json({ ok: false, error: r.error }, { status: r.status }));
+        if (sub === "messages" && req.method === "GET") {
+          const page = listGroupMessages(gid, resolved.user.user_id, Number(url.searchParams.get("limit")) || 50, url.searchParams.get("before"));
+          if ("ok" in page) return failedMsg(page);
+          return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, ...page, unread: groupUnreadFor(gid, resolved.user.user_id) }));
+        }
+        let mbody: Record<string, unknown> = {};
+        try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; if (!b || typeof b !== "object" || Array.isArray(b)) throw new Error("not an object"); mbody = b as Record<string, unknown>; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
+        if (sub === "read") {
+          const r = markGroupRead(netId, gid, resolved.user.user_id, mbody.seq);
+          if (!r.ok) return failedMsg(r);
+          return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, last_read_seq: r.last_read_seq, unread: r.unread }));
+        }
+        const sent = sendGroupMessage({
+          networkId: netId, groupId: gid,
+          sender: { userId: resolved.user.user_id, username: resolved.user.username },
+          message: mbody.message, attachments: mbody.attachments, clientRequestId: mbody.client_request_id,
+        });
+        if (!sent.ok) return failedMsg(sent);
+        return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, message: sent.message, duplicate: sent.duplicate, delivered_to: sent.delivered_to }));
+      }
+      if (!sub && req.method === "GET") {
+        const got = readGroup(netId, gid, resolved.user.user_id, canManage, managed);
+        if (!got) return notFound();
+        return withCors(req, Response.json({ ok: true, network_id: netId, ...got }));
+      }
+      const allowed = (!sub && req.method === "PATCH") || (sub === "members" && !memberUid && req.method === "POST") || (sub === "members" && memberUid && req.method === "DELETE");
+      if (!allowed) return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+      const group = groupById(netId, gid);
+      if (!group) return notFound();
+      if (!canManageGroup(group, canManage, managed)) {
+        return isGroupMember(gid, resolved.user.user_id)
+          ? withCors(req, Response.json({ ok: false, error: "group_manage_denied" }, { status: 403 }))
+          : notFound();
+      }
+      let body: Record<string, unknown> = {};
+      if (req.method !== "DELETE") {
+        try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; body = b && typeof b === "object" && !Array.isArray(b) ? b as Record<string, unknown> : {}; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
+      }
+      const via = canManage ? {} : { via: "leader" };
+      const failed = (r: { status: number; error: string }) => withCors(req, Response.json({ ok: false, error: r.error }, { status: r.status }));
+      if (!sub) {
+        const r = renameGroup(netId, gid, body);
+        if (!r.ok) return failed(r);
+        auditDepartment(resolved.user, "chat_group_renamed", netId, JSON.stringify({ group_id: gid, name: r.group.name, ...via }));
+        return withCors(req, Response.json({ ok: true, network_id: netId, group: { ...r.group, viewer_can: groupViewerCan(r.group, isGroupMember(gid, resolved.user.user_id), canManage, managed) } }));
+      }
+      if (!memberUid) {
+        const r = addManualMember(netId, gid, body.user_id);
+        if (!r.ok) return failed(r);
+        auditDepartment(resolved.user, "chat_group_member_added", netId, JSON.stringify({ group_id: gid, user_id: r.member.user_id, ...via }));
+        return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, member: r.member }, { status: 201 }));
+      }
+      const r = removeManualMember(netId, gid, memberUid);
+      if (!r.ok) return failed(r);
+      auditDepartment(resolved.user, "chat_group_member_removed", netId, JSON.stringify({ group_id: gid, user_id: memberUid, ...via }));
+      return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, removed: memberUid }));
+    }
+
     // ── V3.13: Network members + invites ──
     const membersMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/members(?:\/([^/]+))?$/);
     if (membersMatch) {
@@ -2376,7 +2520,8 @@ return Bun.serve({
           return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
         }
         if (url.pathname === "/api/dm/threads") {
-          return withCors(req, Response.json({ ok: true, network_id: dmNet, threads: listDmThreads(dmNet, restAuth.userId) }));
+          // group_threads(RFC-042 第三个 PR,只增字段):我在里面的群,每个带 unread / last_at / last_message 预览 —— App 私信未读角标可以一起算。
+          return withCors(req, Response.json({ ok: true, network_id: dmNet, threads: listDmThreads(dmNet, restAuth.userId), group_threads: listGroupThreads(dmNet, restAuth.userId) }));
         }
         const other = url.searchParams.get("with") ?? "";
         if (!other) return withCors(req, Response.json({ ok: false, error: "with_required" }, { status: 400 }));
@@ -4363,7 +4508,7 @@ return Bun.serve({
                         config_path, channels, server, hostname,
                         network_id, created_at, updated_at,
                         config_snapshot, lifecycle_state, avatar_url,
-                        display_name, team, tags, attrs_revision, permission_mode
+                        display_name, team, tags, attrs_revision, permission_mode, owner_user_id
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });
@@ -4404,6 +4549,17 @@ return Bun.serve({
         }
       })();
 
+      // RFC-041(#489):调用者能不能改这个节点的权限模式 —— 与 PUT /api/nodes/:id/permission-mode 同一判据
+      // (节点主人、网络 owner / admin、Hub 管理员;只给用户令牌)。客户端据此决定显示「权限」一行,不自己推导规则。
+      const netRoles = new Map<string, string | null>();
+      const canSetPermissionMode = (r: Record<string, any>): boolean => {
+        if (!restAuth || restAuth.networkId) return false;
+        if (isAdmin || (r.owner_user_id && r.owner_user_id === restAuth.userId)) return true;
+        if (!r.network_id) return false;
+        if (!netRoles.has(r.network_id)) netRoles.set(r.network_id, getUserNetworkRole(restAuth.userId, r.network_id));
+        const role = netRoles.get(r.network_id);
+        return role === "owner" || role === "admin";
+      };
       const rows = rawRows.map(r => {
         let role: string | null = null;
         const snap = r.config_snapshot;
@@ -4411,7 +4567,7 @@ return Bun.serve({
           try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
           catch { /* malformed snapshot — leave role null */ }
         }
-        const { config_snapshot, ...rest } = r;
+        const { config_snapshot, owner_user_id, ...rest } = r;
         // `tags` is stored as JSON text; hand the dashboard a real array so
         // it can map() without a guard, and normalise legacy/absent values
         // to [] rather than null. attrs_revision is normalised to a number
@@ -4427,6 +4583,7 @@ return Bun.serve({
           role,
           lifecycle_controllable,
           lifecycle_daemon_node_id: controllable.get(r.node_id) ?? null,
+          viewer_can: { permission_mode: canSetPermissionMode(r) },
         };
       });
       return withCors(req, Response.json({ ok: true, nodes: rows, count: rows.length }));
@@ -4754,6 +4911,8 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
   patrolDeliveredStaleTasks();
   const deliveredStalePatrolTimer = setInterval(patrolDeliveredStaleTasks, deliveredStalePatrolMs);
   const scheduledTaskTimer = startScheduledTaskScheduler();
+  // #492 —— 任务到期提醒(默认每 10 分钟;COMMHUB_DUE_REMINDERS=0 关掉)。bootServer 不起它,测试按需直接调 runDueReminders。
+  const dueReminderTimer = startDueReminderTimer();
 
   // The Bun.serve socket is what keeps the process alive; the periodic
   // jobs must not — otherwise a test (or a future caller) that stops the
@@ -4764,6 +4923,7 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
   (taskPatrolTimer as any)?.unref?.();
   (deliveredStalePatrolTimer as any)?.unref?.();
   (scheduledTaskTimer as any)?.unref?.();
+  (dueReminderTimer as any)?.unref?.();
 
   // ── Graceful shutdown ───────────────────────────────
   function shutdown() {
@@ -4774,6 +4934,7 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
     clearInterval(taskPatrolTimer);
     clearInterval(deliveredStalePatrolTimer);
     clearInterval(scheduledTaskTimer);
+    if (dueReminderTimer) clearInterval(dueReminderTimer);
     db.close();
     process.exit(0);
   }

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";
+}