@sleep2agi/commhub-server 0.9.0-preview.1 → 0.9.0-preview.101

package/src/lifecycle-guard.ts

@@ -0,0 +1,50 @@
+// RFC-027 §2.3 race-free invariant — shared helper for the inbox-
+// enqueue lifecycle guard.
+//
+// PR1.1 (#346) added an `assertNodeActive` helper inside the
+// registerTools() closure and applied it at the 6 INSERT INTO inbox
+// sites in server/src/tools.ts. PR1.1 review (通信龙 #346 ack) caught
+// that the closure scope made the helper unreachable from REST
+// handlers in server/src/index.ts — POST /api/task (:1631) and
+// POST /api/broadcast (:1706) are dashboard's "Dispatch" entry
+// points and bypassed the guard, leaving the §2.3 race open on the
+// REST path.
+//
+// PR1.2a (#346 follow-up) extracts the helper to this module so both
+// the MCP tools and the REST handlers can import the same code path,
+// per team rule (grep every write site before adding a guard): any SQL-level
+// guard's helper lives at module scope so every write site
+// (MCP + REST + internal db.ts helpers) can use it.
+//
+// Behaviour:
+//   - no nodes row for the alias → ok:true (brand-new alias allowed;
+//     could be the first INSERT for a child about to register)
+//   - lifecycle_state = 'active' OR NULL (pre-RFC-027 row) → ok:true
+//   - anything else (stopping / stopped / stop_failed / deleting) →
+//     ok:false + structured `node_not_active` reply
+//
+// COALESCE on the WHERE keeps NULL-network inbox rows / legacy nodes
+// rows correctly scoped (PR1 SF-5 lineage).
+
+import { db } from "./db.js";
+
+export type LifecycleGuardResult =
+  | { ok: true }
+  | { ok: false; error: "node_not_active"; lifecycle_state: string; alias: string };
+
+export function assertNodeActive(
+  sessionAlias: string,
+  networkId: string | null,
+): LifecycleGuardResult {
+  if (!sessionAlias) return { ok: true };
+  const row = db.get<{ lifecycle_state: string | null }>(
+    networkId
+      ? `SELECT lifecycle_state FROM nodes WHERE alias = ?1 AND COALESCE(network_id, ?2) = ?2 LIMIT 1`
+      : `SELECT lifecycle_state FROM nodes WHERE alias = ?1 LIMIT 1`,
+    ...(networkId ? [sessionAlias, networkId] : [sessionAlias]),
+  );
+  if (!row) return { ok: true };
+  const st = row.lifecycle_state ?? "active";
+  if (st === "active") return { ok: true };
+  return { ok: false, error: "node_not_active", lifecycle_state: st, alias: sessionAlias };
+}

package/src/list-host-supervisors.test.ts

@@ -0,0 +1,314 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db, hashToken, generateId } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// RFC-026 §9.2 / #338 PR2 v2 — list_host_supervisors HANDLER tests.
+//
+// PR2 v1 used a mirror-SQL pattern (re-implemented the query in the test
+// itself) → trivially passed but didn't exercise the handler. 通信龙 audit
+// caught: that style misses the SEC-1 scope-derivation bug
+// (`getNetworkId(clientNetId)` returns the unchecked client-supplied
+// network_id for utok_ callers when enforceNetworkId is null, leaking
+// cross-tenant daemons). This rewrite drives the registered MCP tool
+// through registerTools() so the auth context is real.
+//
+// Covers:
+//   SEC-1.1 — cross-tenant utok_ caller with foreign network_id: DENIED
+//   SEC-1.2 — admin caller with own network_id: returns own daemons
+//   SEC-1.3 — caller with no network_id: returns daemons in all member networks
+//   masking — non-admin viewer: host_telemetry IP/cpu/mem stripped, alert_level still surfaces
+//   revoked — DELETEd token row (revokeToken path): daemon excluded
+//   revoked — revoked_at SET token: daemon excluded
+//   self-declare — runtimes_supported/allowed_secret_keys surface from columns
+//   pre-PR2 daemon — empty arrays on NULL columns (back-compat)
+
+const NET_ALPHA = "net_lhs_alpha";
+const NET_BETA = "net_lhs_beta";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface Reply { ok?: boolean; error?: string; daemons?: any[]; count?: number; }
+
+function cleanup() {
+  for (const n of [NET_ALPHA, NET_BETA]) {
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM sessions WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [n]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id LIKE 'u_lhs_%'"); } catch {}
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seedUser(user_id: string) {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [user_id, user_id],
+  );
+}
+function seedNetwork(net_id: string, owner_id = "u_lhs_owner") {
+  db.run(
+    `INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [net_id, net_id, owner_id],
+  );
+}
+function seedMembership(user_id: string, net_id: string, role: "owner" | "admin" | "member" | "viewer" = "member") {
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [user_id, net_id, role],
+  );
+}
+function seedDaemon(opts: {
+  network_id: string, alias: string, node_id?: string,
+  role?: string,
+  runtimes?: string[],
+  secrets?: string[],
+  sessionAgeMs?: number,
+  mintToken?: boolean,
+  tokenRevokedAt?: boolean,
+  tokenDeleted?: boolean,
+}) {
+  const node_id = opts.node_id || `node_${opts.network_id}_${opts.alias}`;
+  const snapshot = JSON.stringify({
+    model: "claude-opus", flags: {}, role: opts.role ?? "host_supervisor",
+    runtimes_supported: opts.runtimes ?? ["claude-agent-sdk"],
+    allowed_secret_keys: opts.secrets ?? [],
+  });
+  db.run(
+    `INSERT OR REPLACE INTO nodes (
+      node_id, node_name, alias, network_id,
+      runtimes_supported, allowed_secret_keys,
+      config_snapshot, hostname,
+      created_at, updated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, datetime('now'), datetime('now'))`,
+    [node_id, opts.alias, opts.alias, opts.network_id,
+     JSON.stringify(opts.runtimes ?? ["claude-agent-sdk"]),
+     JSON.stringify(opts.secrets ?? []),
+     snapshot, `host-${opts.alias}`],
+  );
+  if (opts.sessionAgeMs !== undefined) {
+    const ts = new Date(Date.now() - opts.sessionAgeMs).toISOString().replace("T", " ").replace(/\..+/, "");
+    db.run(
+      `INSERT OR REPLACE INTO sessions (resume_id, alias, network_id, last_seen_at, status, cpu_cores, mem_total_gb, ip)
+       VALUES (?1, ?2, ?3, ?4, 'idle', 8, 16, '10.0.0.5')`,
+      [`s_${node_id}`, opts.alias, opts.network_id, ts],
+    );
+  }
+  if (opts.mintToken !== false && !opts.tokenDeleted) {
+    db.run(
+      `INSERT OR REPLACE 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, ?6)`,
+      [`tok_${node_id}`, `u_seed_${node_id}`, opts.network_id, `node:${opts.alias}`,
+       `hash_${node_id}`,
+       opts.tokenRevokedAt ? new Date().toISOString().replace("T", " ").replace(/\..+/, "") : null],
+    );
+  }
+  return node_id;
+}
+
+/** Build a server with registerTools wired to a specific enforceUserId. */
+function buildToolHandler(enforceUserId: string | null): ToolHandler {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  // Capture the registered tool function. The MCP SDK's server.tool stores
+  // the handler internally; we intercept by overriding before registerTools.
+  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);
+  };
+  // Some tools use registerTool; intercept that too
+  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 */ null,
+    /* enforceUserId */ enforceUserId,
+    /* callerAlias */ null,
+    /* callerTokenIsNetwork */ false,
+    /* callerTokenId */ null,
+  );
+  const h = tools["list_host_supervisors"];
+  if (!h) throw new Error("list_host_supervisors tool not registered");
+  return h;
+}
+
+async function callList(handler: ToolHandler, args: any = {}): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+describe("list_host_supervisors HANDLER tests (RFC-026 §9.2, PR2 v2)", () => {
+  test("SEC-1.1: cross-tenant utok_ caller with foreign network_id → DENIED", async () => {
+    const userA = "u_lhs_alice"; // belongs to NET_ALPHA only
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedNetwork(NET_BETA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_BETA, alias: "secret-beta-daemon" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_BETA });
+    // PR2 v1 BUG: this returned ok:true with secret-beta-daemon in the list.
+    expect(reply.ok).toBe(false);
+    expect(reply.error).toMatch(/access denied|not a member/i);
+    // Belt: hostname not in error payload
+    expect(JSON.stringify(reply)).not.toContain("secret-beta-daemon");
+    expect(JSON.stringify(reply)).not.toContain("host-secret-beta-daemon");
+  });
+
+  test("SEC-1.2: admin caller with own network_id returns own daemons", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alpha-daemon-1" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "alpha-daemon-2" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    expect(reply.ok).toBe(true);
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toEqual(["alpha-daemon-1", "alpha-daemon-2"]);
+  });
+
+  test("SEC-1.3: caller without network_id arg → returns daemons across member networks only", async () => {
+    const userA = "u_lhs_alice"; // member of NET_ALPHA only
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedNetwork(NET_BETA);
+    seedMembership(userA, NET_ALPHA, "member");
+    seedDaemon({ network_id: NET_ALPHA, alias: "ok-daemon" });
+    seedDaemon({ network_id: NET_BETA, alias: "forbidden-daemon" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler);
+    expect(reply.ok).toBe(true);
+    const aliases = (reply.daemons ?? []).map(d => d.alias);
+    expect(aliases).toContain("ok-daemon");
+    expect(aliases).not.toContain("forbidden-daemon");
+  });
+
+  test("masking: member caller gets host_telemetry without IP/cpu/mem; admin gets full", async () => {
+    const userMember = "u_lhs_bob_member";
+    const userAdmin = "u_lhs_carol_admin";
+    seedUser(userMember);
+    seedUser(userAdmin);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userMember, NET_ALPHA, "member");
+    seedMembership(userAdmin, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "telemetry-daemon", sessionAgeMs: 5_000 });
+
+    const memberHandler = buildToolHandler(userMember);
+    const memberReply = await callList(memberHandler, { network_id: NET_ALPHA });
+    expect(memberReply.daemons?.[0].host_telemetry.alert_level).toBeDefined();
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("cpu_cores");
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("mem_gb");
+    expect(memberReply.daemons?.[0].host_telemetry).not.toHaveProperty("ip_internal");
+
+    const adminHandler = buildToolHandler(userAdmin);
+    const adminReply = await callList(adminHandler, { network_id: NET_ALPHA });
+    expect(adminReply.daemons?.[0].host_telemetry.cpu_cores).toBe(8);
+    expect(adminReply.daemons?.[0].host_telemetry.mem_gb).toBe(16);
+    expect(adminReply.daemons?.[0].host_telemetry.ip_internal).toBe("10.0.0.5");
+  });
+
+  test("revoked: DELETEd token row (revokeToken path) excludes daemon", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alive-daemon" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "deleted-token-daemon", tokenDeleted: true });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toContain("alive-daemon");
+    expect(aliases).not.toContain("deleted-token-daemon");
+  });
+
+  test("revoked: token with revoked_at SET also excludes daemon", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "alive-daemon" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "revoked-at-daemon", tokenRevokedAt: true });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toContain("alive-daemon");
+    expect(aliases).not.toContain("revoked-at-daemon");
+  });
+
+  test("role filter: regular member nodes (role=member) excluded after extraction", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({ network_id: NET_ALPHA, alias: "real-daemon", role: "host_supervisor" });
+    seedDaemon({ network_id: NET_ALPHA, alias: "regular-node", role: "member" });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const aliases = (reply.daemons ?? []).map(d => d.alias).sort();
+    expect(aliases).toEqual(["real-daemon"]);
+  });
+
+  test("self-declare: runtimes_supported + allowed_secret_keys surface from columns", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    seedDaemon({
+      network_id: NET_ALPHA, alias: "rich-daemon",
+      runtimes: ["claude-agent-sdk", "codex-sdk", "grok-build-acp"],
+      secrets: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+    });
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const d = reply.daemons?.[0];
+    expect(d.runtimes_supported).toEqual(["claude-agent-sdk", "codex-sdk", "grok-build-acp"]);
+    expect(d.allowed_secret_keys).toEqual(["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]);
+  });
+
+  test("pre-PR2 daemon (NULL columns) extracts to empty arrays back-compat", async () => {
+    const userA = "u_lhs_alice";
+    seedUser(userA);
+    seedNetwork(NET_ALPHA);
+    seedMembership(userA, NET_ALPHA, "admin");
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, runtimes_supported, allowed_secret_keys, created_at, updated_at)
+       VALUES (?1, 'legacy', 'legacy', ?2, ?3, NULL, NULL, datetime('now'), datetime('now'))`,
+      ["node_legacy_alpha", NET_ALPHA, JSON.stringify({ role: "host_supervisor" })],
+    );
+    // Seed active token so the EXISTS guard lets it through
+    db.run(
+      `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash)
+       VALUES ('tok_legacy', 'u_seed_legacy', ?1, 'network', 'node:legacy', 'hash_legacy')`,
+      [NET_ALPHA],
+    );
+
+    const handler = buildToolHandler(userA);
+    const reply = await callList(handler, { network_id: NET_ALPHA });
+    const d = reply.daemons?.find(d => d.alias === "legacy");
+    expect(d).toBeTruthy();
+    expect(d.runtimes_supported).toEqual([]);
+    expect(d.allowed_secret_keys).toEqual([]);
+  });
+});

package/src/mcp-context-cost-http.test.ts

@@ -0,0 +1,119 @@
+// #476(#469 MCP 审计的最后一项)—— Hub MCP 面的上下文成本。
+//
+// 钉住:
+//   1. tools/list 的总字节有上限(TOOLS_LIST_MAX_BYTES):描述 / 参数说明不能悄悄长回去。每个工具也有上限,
+//      单条工具描述有上限。要加新工具 / 新说明,改这里的数字 —— 改的时候就会被看见。
+//   2. requirements_events 不带 requirement_id(全网动态)默认 50 条、从新到旧、next_cursor 翻更早的;
+//      带 requirement_id 的单卡调用不变(默认 200);REST /api/requirements/events 不变(默认 200,App 用它)。
+//   3. requirements_events 参数严格:不认识的参数 → -32602,列出能用的参数。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/mcp-context-cost-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register } from "./auth.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("mcp-context-cost requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+/**
+ * tools/list 整份 JSON 的字节上限。#476 之前(main,含 #475)74 个工具 76,824 B;修剪后 71,399 B。
+ * #478 起 tools/list 按调用者给:这里的调用者是用户令牌,看到 56 个工具 54,780 B(不含节点 / 协议工具)。
+ * 上限跟着收到用户这一档(~1.7 KB 余量);节点 / 全部工具的上限在 tool-audience-http.test.ts。
+ * 加工具或加说明超过它,就在这里改数字并在 PR 里说为什么。
+ */
+const TOOLS_LIST_MAX_BYTES = 56_500;
+/** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
+const TOOL_MAX_BYTES = 9_000;
+/** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */
+const DESCRIPTION_MAX_BYTES = 1_000;
+const NETWORK_EVENTS = 80;
+
+let server: any;
+let base = "";
+let token = "", netId = "";
+let close: () => Promise<void>;
+let client: Client;
+const call = async (name: string, args: Record<string, unknown>) => {
+  const r: any = await client.callTool({ name, arguments: args });
+  const text = String(r.content?.[0]?.text ?? "");
+  return r.isError ? { mcpError: true, text } : { ...JSON.parse(text), _bytes: Buffer.byteLength(text, "utf8") };
+};
+let busyId = "";
+
+beforeAll(async () => {
+  const u = register(`ctx_${Date.now()}`, "CtxCost123!", undefined, "seed");
+  token = u.token!; netId = u.network_id!;
+  const s = new McpServer({ name: "ctx", version: "1" });
+  registerTools(s, undefined, null, u.user!.user_id, u.user!.username, false, "tok_user");
+  client = new Client({ name: "ctx-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  close = async () => { await client.close(); await s.close(); };
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  // 一张卡上 60 条评论(单卡调用要能拿到 > 50 条),再加 20 张卡各一条
+  const busy = await call("requirements_create", { network_id: netId, name: "busy task" });
+  busyId = busy.requirement.id;
+  for (let i = 0; i < 60; i++) expect((await call("requirements_comment", { network_id: netId, id: busyId, text: `进展 ${i}:这一步完成了` })).ok).toBe(true);
+  for (let i = 0; i < NETWORK_EVENTS - 60; i++) {
+    const r = await call("requirements_create", { network_id: netId, name: `task ${i}` });
+    await call("requirements_comment", { network_id: netId, id: r.requirement.id, text: "已开始" });
+  }
+}, 120_000);
+afterAll(async () => { await close?.(); server?.stop?.(true); });
+
+describe("#476 tools/list size", () => {
+  test("total, per tool and per description stay under their ceilings", async () => {
+    const { tools } = await client.listTools();
+    const total = Buffer.byteLength(JSON.stringify({ tools }), "utf8");
+    const sizes = tools.map((t: any) => ({ name: t.name, all: Buffer.byteLength(JSON.stringify(t)), desc: Buffer.byteLength(t.description ?? "") }));
+    sizes.sort((a, b) => b.all - a.all);
+    console.log(`tools/list: ${tools.length} tools, ${total} B; largest ${sizes.slice(0, 3).map(x => `${x.name}=${x.all}`).join(", ")}`);
+    expect(total).toBeLessThanOrEqual(TOOLS_LIST_MAX_BYTES);
+    for (const x of sizes) {
+      expect(x.all, x.name).toBeLessThanOrEqual(TOOL_MAX_BYTES);
+      expect(x.desc, x.name).toBeLessThanOrEqual(DESCRIPTION_MAX_BYTES);
+    }
+  });
+});
+
+describe("#476 requirements_events defaults", () => {
+  test("network-wide: 50 newest by default, next_cursor pages older events", async () => {
+    const p1 = await call("requirements_events", { network_id: netId });
+    expect(p1.events.length).toBe(50);
+    expect(typeof p1.next_cursor).toBe("string");
+    const times = p1.events.map((e: any) => e.at ?? e.created_at);
+    expect([...times].sort().reverse()).toEqual(times);
+    const p2 = await call("requirements_events", { network_id: netId, cursor: p1.next_cursor });
+    const ids = new Set([...p1.events, ...p2.events].map((e: any) => e.id));
+    expect(ids.size).toBe(p1.events.length + p2.events.length);
+    console.log(`network events page of 50: ${p1._bytes} B`);
+    expect(p1._bytes).toBeLessThan(25_000);
+  });
+
+  test("an explicit limit still wins; one task's timeline keeps its old default (200)", async () => {
+    expect((await call("requirements_events", { network_id: netId, limit: 70 })).events.length).toBe(70);
+    const one = await call("requirements_events", { network_id: netId, requirement_id: busyId });
+    expect(one.events.filter((e: any) => e.kind === "comment").length).toBe(60);
+  });
+
+  test("REST GET /api/requirements/events is unchanged (default 200)", async () => {
+    const res = await fetch(`${base}/api/requirements/events?network_id=${netId}`, { headers: { Authorization: `Bearer ${token}` } });
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.events.length).toBeGreaterThan(50);
+  });
+
+  test("unknown parameters → -32602 listing the valid ones", async () => {
+    const r = await call("requirements_events", { network_id: netId, task_id: busyId });
+    expect(r.mcpError).toBe(true);
+    expect(r.text).toContain("-32602");
+    expect(r.text).toContain("unknown parameter(s): task_id; valid parameters: network_id, requirement_id, since, limit, cursor");
+  });
+});

package/src/mcp-projects-events-http.test.ts

@@ -0,0 +1,162 @@
+// MCP projects_create / projects_update / requirements_events(app 任务页审计 2026-10-02 M3:Agent 能做人能做的)。
+// HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。三个工具都走 app 用的同一套 REST 处理(handleRequirementsRequest),
+// 所以这里不另抄一份权限规则:对每类调用者(网络 owner、全部任务成员、仅相关任务成员、viewer、节点令牌)都同时调
+// MCP 和 REST,断言状态码 / 结果逐项一致。再钉住正向行为(建 / 改名 / 归档 / 取消归档、读流水、"#N")和工具出现在 tools/list 里。
+
+import { describe, expect, test, beforeAll, afterAll } 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";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-mcp-projects-events-"));
+let BASE = "";
+let hub: any = null;
+const PW = "McpProjectsEventsPassw0rd!x";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function rpc(token: string, method: string, params?: unknown): Promise<any> {
+  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" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, ...(params === undefined ? {} : { params }) }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const out = await rpc(token, "tools/call", { name, arguments: args });
+  return JSON.parse(out.result.content[0].text);
+}
+// MCP error bodies from the REST handler carry its status (requirementsCall). Anything else that isn't ok (e.g. a tool-level
+// gate) is NOT a success — a body without `status` must never be read as the 2xx (that hid a gate in the first draft).
+const mcpStatus = (r: any, okStatus: number) => (r?.ok === true || (r && r.ok === undefined && (r.project || r.events)) ? okStatus : typeof r?.status === "number" ? r.status : -1);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`mpe_owner_${Date.now()}`, PW, undefined, "Owner");
+  expect(a.ok).toBe(true);
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string, role: string) => {
+    expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  U.member = await mk(`mpe_member_${stamp}`, "member");
+  U.scoped = await mk(`mpe_scoped_${stamp}`, "member");
+  U.viewer = await mk(`mpe_viewer_${stamp}`, "viewer");
+  db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, U.member.id]);
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.scoped.id}/task-grants`, { task_access: "scoped", project_grants: [] })).status).toBe(200);
+  const node = createNetworkTokenForNode(U.owner.id, NET, "mpe-node", "node_mpe");
+  U.node = { token: node.token!, id: "node_mpe" };
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("discoverable", () => {
+  test("tools/list carries the three tools with descriptions", async () => {
+    const list = await rpc(U.owner.token, "tools/list");
+    const byName = new Map((list.result.tools as any[]).map(t => [t.name, t]));
+    for (const n of ["projects_create", "projects_update", "requirements_events"]) {
+      expect(byName.has(n)).toBe(true);
+      expect(String(byName.get(n).description).length).toBeGreaterThan(40);
+    }
+    expect(String(byName.get("projects_list").description)).toContain("projects_create");
+  });
+});
+
+describe("projects_create / projects_update", () => {
+  test("owner: create, rename, recolour, archive, unarchive — same rows the app sees", async () => {
+    const created = await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-项目甲" });
+    expect(created.ok).toBe(true);
+    const id = created.project.id as string;
+    expect(created.project.name).toBe("mpe-项目甲");
+    const renamed = await mcp(U.owner.token, "projects_update", { network_id: NET, id, name: "mpe-项目乙", color: "#16a34a" });
+    expect(renamed.project.name).toBe("mpe-项目乙");
+    expect(renamed.project.color).toBe("#16a34a");
+    expect((await mcp(U.owner.token, "projects_update", { network_id: NET, id, archived: true })).project.archived).toBe(true);
+    const seen = await rest(U.owner.token, "GET", `/api/requirements/projects?network_id=${NET}`);
+    expect(seen.body.projects.find((p: any) => p.id === id).archived).toBe(true);
+    expect((await mcp(U.owner.token, "projects_update", { network_id: NET, id, archived: false })).project.archived).toBe(false);
+  });
+
+  test("validation comes from the REST handler: duplicate name 409, unknown id 404", async () => {
+    await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-重名" });
+    const dup = await mcp(U.owner.token, "projects_create", { network_id: NET, name: "mpe-重名" });
+    expect(dup.ok).toBe(false);
+    expect(dup.status).toBe(409);
+    const missing = await mcp(U.owner.token, "projects_update", { network_id: NET, id: "proj_nobody", name: "x" });
+    expect(missing.status).toBe(404);
+  });
+
+  test("permission parity with the app's REST path, for every kind of caller", async () => {
+    const results: Record<string, { mcp: number; rest: number }> = {};
+    for (const who of ["owner", "member", "scoped", "viewer", "node"]) {
+      const name = `mpe-parity-${who}`;
+      const viaMcp = await mcp(U[who].token, "projects_create", { network_id: NET, name: `${name}-mcp` });
+      const viaRest = await rest(U[who].token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `${name}-rest` });
+      results[who] = { mcp: mcpStatus(viaMcp, 201), rest: viaRest.status };
+    }
+    for (const r of Object.values(results)) expect(r.mcp).toBe(r.rest);
+    // the rule itself (RFC-038 §9): task-scoped members and viewers can't manage projects; the others can
+    expect(results.owner.rest).toBe(201);
+    expect(results.member.rest).toBe(201);
+    expect(results.scoped.rest).toBe(403);
+    expect(results.viewer.rest).toBe(403);
+  });
+});
+
+describe("requirements_events", () => {
+  test("one task's timeline by id and by #N, same rows as GET /api/requirements/events", async () => {
+    const card = await rest(U.owner.token, "POST", "/api/requirements", { network_id: NET, name: "mpe-流水示例" });
+    expect(card.status).toBe(201);
+    const id = card.body.requirement.id as string, seq = card.body.requirement.seq as number;
+    expect((await rest(U.owner.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { priority: "high" })).status).toBe(200);
+    const viaMcp = await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: id });
+    const viaRest = await rest(U.owner.token, "GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`);
+    expect(viaMcp.ok).toBe(true);
+    expect(viaMcp.events.length).toBeGreaterThan(0);
+    expect(viaMcp.events.map((e: any) => e.id)).toEqual(viaRest.body.events.map((e: any) => e.id));
+    expect(viaMcp.events.every((e: any) => e.requirement_id === id)).toBe(true);
+    const bySeq = await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: `#${seq}` });
+    expect(bySeq.events.map((e: any) => e.id)).toEqual(viaMcp.events.map((e: any) => e.id));
+    // paging / bad input come from the REST handler too
+    expect((await mcp(U.owner.token, "requirements_events", { network_id: NET, since: "not-a-date" })).status).toBe(400);
+    expect((await mcp(U.owner.token, "requirements_events", { network_id: NET, requirement_id: "#999999" })).status).toBe(404);
+  });
+
+  test("visibility parity: a task-scoped member doesn't get events for a task they can't see", async () => {
+    const hidden = await rest(U.owner.token, "POST", "/api/requirements", { network_id: NET, name: "mpe-看不见的" });
+    const id = hidden.body.requirement.id as string;
+    await rest(U.owner.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { priority: "low" });
+    for (const who of ["scoped", "member", "node"]) {
+      const viaMcp = await mcp(U[who].token, "requirements_events", { network_id: NET, requirement_id: id });
+      const viaRest = await rest(U[who].token, "GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`);
+      expect((viaMcp.events ?? []).map((e: any) => e.id)).toEqual((viaRest.body?.events ?? []).map((e: any) => e.id));
+    }
+    expect((await mcp(U.scoped.token, "requirements_events", { network_id: NET, requirement_id: id })).events ?? []).toHaveLength(0);
+    expect((await mcp(U.member.token, "requirements_events", { network_id: NET, requirement_id: id })).events.length).toBeGreaterThan(0);
+  });
+});