@sleep2agi/commhub-server 0.9.0-preview.3 → 0.9.0-preview.30

package/README.md

@@ -7,10 +7,27 @@
 
 CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config when launched through `anet`.
 
-The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.10 at v0.10.11) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
+The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
 
 ## Quick start (verified)
 
+> ⚠️ **Do not run `bunx @sleep2agi/commhub-server` without a version**
+> Without a version this resolves to the npm `latest` dist-tag, and **`latest` is currently `0.8.8` (published 2026-06-24)**.
+> 
+> On `0.8.8` an anonymous `GET /health` **returns the `{networkId}:{alias}` of every live SSE connection** — no token required.
+> The redaction fix is [`7bacb729`](https://github.com/sleep2agi/agent-network/commit/7bacb729) (`security(#473)`, **2026-07-29**),
+> **35 days after** `0.8.8` shipped, so `0.8.8` does not contain it.
+> 
+> **Pin a version, or use the preview channel:**
+> 
+> ```bash
+> bunx --bun @sleep2agi/commhub-server@preview      # contains the redaction fix
+> ```
+> 
+> Or use the supported path, `anet hub start`, which pulls the version in `PINNED_SERVER_VERSION` rather than `latest`.
+> 
+> Self-check: `curl -sS http://<host>:9200/health | jq 'has("sse_sessions")'` — `true` means you are on an affected build.
+
 ```bash
 # Recommended — through the anet CLI
 npm install -g @sleep2agi/agent-network
@@ -38,13 +55,16 @@ Once running:
 
 ## Pairs with
 
-| Package | Version |
+| Package | |
 |---|---|
-| [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | 2.1.7 |
-| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | 0.4.2 |
-| [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | 2.3.0 |
+| [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | CLI |
+| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | Web UI |
+| [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | Agent runtime host |
+
+Install the matching versions with `npm install -g <pkg>` — the `latest` dist-tag on npm is
+authoritative. Pinning versions here goes stale on every release and nobody comes back to fix it.
 
-## MCP tools (17)
+## MCP tools
 
 ### Agent-side
 | Tool | Description |
@@ -71,6 +91,8 @@ Once running:
 | `list_tasks` | Task list, filterable by `network_id` |
 | `get_completions` | Completion history |
 
+> The table above lists the 17 **collaboration-core** tools. Node lifecycle / provider ops tools ship on the same MCP surface — the authoritative full list is [docs-site/docs/api/mcp-tools.md](../docs-site/docs/api/mcp-tools.md). Don't read the count above as "17 tools total".
+
 ## REST API
 
 The server exposes ~33 endpoints across health, auth, networks, and observability surfaces. The endpoints in use today by the verified flow are:
@@ -96,7 +118,7 @@ Network-management endpoints (`/api/networks…`) are present and used by the cu
 
 Auth: `Authorization: Bearer <token>` header, or `?token=<token>` query.
 
-## SQLite schema (13 tables)
+## SQLite schema
 
 Auto-created on first run.
 
@@ -146,6 +168,102 @@ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-serv
 | `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
 | `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
 
+## Running the unit tests
+
+### 先说该走哪条路:Docker
+
+仓库规约是测试在 Docker 里跑(`CLAUDE.md`「所有测试在 Docker 里跑:不碰本地
+环境,不改生产」)。`server/src` 的测试在 `tests/` 下已经有 **24 个**按主题分片的
+套件覆盖(实测:遍历 main 上 204 个套件目录,run.sh 里跑 `server/src/*.test.ts`
+的有 24 个),每个都在容器内自带 `COMMHUB_DB`。跑其中任意一个都是这个形状:
+
+```bash
+# 从仓根跑
+docker build --build-arg SOURCE_COMMIT="$(git rev-parse HEAD)" \
+  -t anet-test624 -f tests/test624-task-cursor-pagination/Dockerfile .
+docker run --rm anet-test624
+```
+
+（实跑过:退出码 0,`6 pass / 0 fail`,`RESULT: PASS`。换成 `tests/` 下别的
+`test*-*/Dockerfile` 同理,但 **build-arg 的名字要照抄那个 Dockerfile** ——
+main 上 66 处写的是 `SOURCE_COMMIT`,另有若干写成 `TEST<编号>_SOURCE_COMMIT`
+(如 `TEST686_SOURCE_COMMIT`、`TEST765_SOURCE_COMMIT`)。传错名字不会报错,
+只会让套件收到 `unknown` 然后按它自己的规则红或绿 —— 这不是你想要的那种绿。）
+
+> ⚠️ **目前没有一个套件跑「`server/src` 下的全部」单测。** 上面那些是按主题
+> 分片的;聚合门在 #798 里,尚未合入 main。所以「所有分片套件都绿」**不等于**
+> 69 个单测文件都跑过 —— 在 #798 合入之前,不要把前者当成后者。
+
+### 直接在宿主上跑时的两条契约
+
+下面这两条是上面那些套件在容器内**已经替你满足**的东西。你只有在本地迭代
+单个文件时才需要自己处理它们 —— 而那种跑法不构成任何门禁证据。
+
+
+1. **`COMMHUB_DB` must be set.** It is not optional — `~/.commhub/commhub.db` is a
+   *live* database on any machine that has ever run a hub. This one is enforced:
+   with `NODE_ENV=test` (which `bun test` sets) and no `COMMHUB_DB`, the adapter
+   refuses with `REFUSING to open the default SQLite database`.
+
+2. **Each test *file* needs its own database.** This is *not* enforced — a single
+   shared `COMMHUB_DB` passes the guard above and then fails a handful of tests
+   for reasons that look like product bugs but are not. `scripts/qa.sh` encodes
+   the real contract:
+
+   ```bash
+   # 从仓根跑(见下),每个文件一个全新的库
+   f=server/src/auth-validate.test.ts
+   db=/tmp/anet-$(basename "$f" .test.ts).db
+   rm -f "$db"                       # 复用上一次的库同样会破坏隔离
+   COMMHUB_DB="$db" bun test "$f"
+   ```
+
+   整套跑法:
+
+   ```bash
+   rc=0
+   # 用 find 而不是 `server/src/*.test.ts` —— glob 不进子目录,会漏掉
+   # server/src/shared/ 下的 3 个(实测:深度 1 是 66 个,递归是 69 个)。
+   # scripts/qa.sh 与 test798 用的就是 find,这里保持一致。
+   while IFS= read -r f; do
+     # 用完整路径派生库名,不用 basename:加入子目录之后,
+     # 两个不同目录下的同名文件会派生出同一个库(原来只扫单层时不可能)。
+     db=/tmp/anet-$(printf '%s' "${f%.test.ts}" | tr '/.' '--').db
+     rm -f "$db" "$db-wal" "$db-shm"
+     COMMHUB_DB="$db" bun test "$f" || { echo "FAILED: $f"; rc=1; }
+   done < <(find server/src -type f -name '*.test.ts' | sort)
+   [ "$rc" -eq 0 ]
+   ```
+
+   ⚠️ 最后那行 `[ "$rc" -eq 0 ]` 不是装饰,是这段的**门**。写成
+   `bun test "$f" || echo "FAILED: $f"` 会让循环打印一行然后继续,
+   整段的退出码恒为 0 —— **测试全红,脚本报绿**。用 `[ ... ]` 而不是
+   `exit "$rc"`,是为了这段直接粘进终端时不会把你的 shell 关掉;
+   存成脚本跑时,它是最后一条命令,脚本退出码就等于它。
+
+   ⚠️ 别把 `$name` 之类的占位符原样抄进命令行 —— 未定义的变量会展开成空串,
+   于是每个文件都写进**同一个** `/tmp/…-.db`,正好是这一节要避免的事。
+
+   Symptom if you ignore it: `bun test src/` under one database turns
+   `admin-networks-http` and `scheduled-tasks-http` red. Both are **global-count
+   assertions that are correct under the contract**:
+
+   ```ts
+   // admin-networks-http.test.ts — the admin sees EXACTLY this file's two networks
+   expect(new Set(rows.map((row) => row.network_id)))
+     .toEqual(new Set([adminNetworkId, memberNetworkId]));
+
+   // scheduled-tasks-http.test.ts — EXACTLY one due occurrence was processed
+   expect(runDueScheduledTasks().processed).toBe(1);
+   ```
+
+   Share a database and other files' networks and due schedules join the count.
+   Nothing is broken; the run violated the contract.
+
+   `scripts/qa.sh` 的 L0 目前只点名跑 5 个 server 测试(白名单),不是全量;
+   把 `server/src` 全域逐文件跑起来的那道 CI 门还在评审中(`#798`),
+   未进 `main` —— 所以本节描述的是**契约**,不是「已经有东西在替你执行它」。
+
 ## Auth modes
 
 1. **V3 user system (default)** — `POST /api/auth/register` and `/api/auth/login` issue `utok_…` tokens; nodes get `ntok_…`.

package/bin/commhub.ts

@@ -54,5 +54,13 @@ Examples:
   }
 }
 
-// Load the server
-import("../src/index.js");
+// Opt into the default production DB path before loading the server graph.
+// Ordinary imports / bun -e probes do not receive this capability.
+process.env.COMMHUB_SERVER = "1";
+
+// Load the server module (side-effect-free since the #438 corrective:
+// importing binds nothing) and start the hub EXPLICITLY. Never rely on
+// import side effects or import.meta.main here — this bin is a dynamic
+// importer, where import.meta.main is false inside the module.
+const { startHub } = await import("../src/server.js");
+startHub();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.3",
-  "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
+  "version": "0.9.0-preview.30",
+  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",
   "bin": {
@@ -12,9 +12,9 @@
     "bin"
   ],
   "scripts": {
-    "start": "bun run src/index.ts",
-    "dev": "bun --watch run src/index.ts",
-    "test": "COMMHUB_DB=/tmp/test-commhub-$$.db bun test src/"
+    "start": "COMMHUB_SERVER=1 bun run src/index.ts",
+    "dev": "COMMHUB_SERVER=1 bun --watch run src/index.ts",
+    "test": "bun run scripts/test-aggregate.ts"
   },
   "keywords": [
     "commhub",

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

@@ -0,0 +1,159 @@
+import { afterAll, beforeEach, 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 { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_ack_transport";
+const DAEMON_NODE_ID = "node_ack_transport_daemon";
+const DAEMON_ALIAS = "ack-transport-daemon";
+const DAEMON_USER = "u_ack_transport_owner";
+const DAEMON_TOKEN_ID = "tok_ack_transport_daemon";
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [DAEMON_USER]); } catch {}
+}
+
+function seedWorld() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [DAEMON_USER, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET, NET, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [DAEMON_USER, NET],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [DAEMON_NODE_ID, DAEMON_ALIAS, DAEMON_ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [DAEMON_TOKEN_ID, DAEMON_USER, NET, `node:${DAEMON_ALIAS}`, "hash_ack_transport_daemon"],
+  );
+}
+
+function seedRequest(requestId: string) {
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, created_at, created_by_token)
+     VALUES (?1, ?2, ?3, ?4, 'codex-sdk', 'x', '{}', '[]', 'delivered', ?5, ?6)`,
+    [requestId, DAEMON_NODE_ID, `child_${requestId}`, NET, Date.now(), DAEMON_TOKEN_ID],
+  );
+}
+
+async function connectClient() {
+  const server = new McpServer({ name: "ack-transport-test", version: "1" });
+  registerTools(
+    server,
+    undefined,
+    NET,
+    DAEMON_USER,
+    DAEMON_ALIAS,
+    true,
+    DAEMON_TOKEN_ID,
+  );
+  const client = new Client({ name: "ack-transport-client", version: "1" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  return { client, server };
+}
+
+type ToolResult = { content: Array<{ type: string; text?: string }>; isError?: boolean };
+
+function responseJson(result: ToolResult) {
+  const first = result.content[0];
+  if (!first || first.type !== "text" || typeof first.text !== "string") throw new Error("missing text tool result");
+  return JSON.parse(first.text) as { ok?: boolean; status?: string };
+}
+
+function expectTransportValidationError(result: ToolResult) {
+  expect(result.isError).toBe(true);
+  const first = result.content[0];
+  expect(first?.type).toBe("text");
+  expect(first?.text).toMatch(/Input validation error.*ack_create_request/i);
+}
+
+beforeEach(() => {
+  cleanup();
+  seedWorld();
+});
+afterAll(cleanup);
+
+describe("#344 ack_create_request real in-process MCP transport", () => {
+  test("accepts runtime_capability_check_failed plus string runtime through the SDK zod gate", async () => {
+    const requestId = "cr_transport_accept";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: {
+          request_id: requestId,
+          status: "runtime_capability_check_failed",
+          error: "child died within 5000ms post-spawn",
+          runtime: "codex-sdk",
+        },
+      });
+      expect(responseJson(result)).toMatchObject({ ok: true, status: "runtime_capability_check_failed" });
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("runtime_capability_check_failed");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  test("rejects unknown status at the transport gate before the handler mutates the row", async () => {
+    const requestId = "cr_transport_bad_status";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: { request_id: requestId, status: "capability_failed_typo", runtime: "codex-sdk" },
+      });
+      expectTransportValidationError(result);
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("delivered");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
+  test("rejects non-string runtime at the transport gate before the handler mutates the row", async () => {
+    const requestId = "cr_transport_bad_runtime";
+    seedRequest(requestId);
+    const { client, server } = await connectClient();
+    try {
+      const result = await client.callTool({
+        name: "ack_create_request",
+        arguments: { request_id: requestId, status: "runtime_capability_check_failed", runtime: 42 },
+      });
+      expectTransportValidationError(result);
+      expect(db.get<{ status: string }>("SELECT status FROM node_create_requests WHERE request_id = ?1", requestId)?.status)
+        .toBe("delivered");
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+});