@sleep2agi/commhub-server 0.9.0-preview.219 → 0.9.0-preview.220

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/package.json +1 -1
  2. package/src/agent-acl-slice3-http.test.ts +388 -1
  3. package/src/config-apply-validate.test.ts +68 -0
  4. package/src/config-apply-validate.ts +69 -0
  5. package/src/cors-origins.test.ts +40 -0
  6. package/src/create-node-network-id.test.ts +12 -0
  7. package/src/department-heads-http.test.ts +20 -0
  8. package/src/departments-agent-count.test.ts +3 -0
  9. package/src/etag-of.test.ts +57 -0
  10. package/src/event-loop-lag.ts +20 -0
  11. package/src/health-anon-readers.ts +59 -0
  12. package/src/health-host-disk-2756.test.ts +23 -1
  13. package/src/health-redaction.test.ts +1063 -0
  14. package/src/hub-catalog-read-http.test.ts +79 -0
  15. package/src/hub-provider-config.test.ts +17 -0
  16. package/src/hub-provider-config.ts +19 -0
  17. package/src/license-state.test.ts +56 -0
  18. package/src/license-state.ts +48 -0
  19. package/src/list-host-supervisors.test.ts +10 -0
  20. package/src/mcp-projects-events-http.test.ts +3 -0
  21. package/src/mcp-write-network-resolution.test.ts +3 -0
  22. package/src/node-caller-identity-http.test.ts +9 -1
  23. package/src/node-health-dispatch-http.test.ts +58 -2
  24. package/src/node-health-guard.ts +16 -0
  25. package/src/node-skills-transport.test.ts +3 -0
  26. package/src/opencode-v2-catalog.ts +4 -0
  27. package/src/redact-tokens.test.ts +22 -1
  28. package/src/redact-tokens.ts +4 -1
  29. package/src/rejection-counters.test.ts +72 -0
  30. package/src/rejection-counters.ts +173 -0
  31. package/src/requirement-events-http.test.ts +27 -0
  32. package/src/route-callers-http.test.ts +1 -1
  33. package/src/serve-error.test.ts +35 -0
  34. package/src/serve-error.ts +33 -4
  35. package/src/server.ts +913 -17
  36. package/src/shared/probe-host-allowlist-drift.test.ts +45 -0
  37. package/src/skillhub-http.test.ts +35 -1
  38. package/src/status-read-cache.ts +8 -1
  39. package/src/task-late-reply-http.test.ts +7 -0
  40. package/src/task-rejection-log.ts +10 -1
  41. package/src/tmux-allowlist.test.ts +48 -0
  42. package/src/tool-audience.ts +10 -3
  43. package/src/tools.ts +99 -15
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sleep2agi/commhub-server",
3
- "version": "0.9.0-preview.219",
3
+ "version": "0.9.0-preview.220",
4
4
  "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).",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -10,7 +10,7 @@ import { describe, expect, test, beforeAll, afterAll } from "bun:test";
10
10
  import { mkdtempSync, rmSync } from "fs";
11
11
  import { join } from "path";
12
12
  import { tmpdir } from "os";
13
- import { register, addNetworkMember } from "./auth.js";
13
+ import { register, addNetworkMember, createNetworkTokenForNode } from "./auth.js";
14
14
  import { db } from "./db.js";
15
15
  import { replaceAgentGrants } from "./agent-access.js";
16
16
  import { dispatchScheduledOccurrence } from "./scheduled-tasks.js";
@@ -218,6 +218,18 @@ describe("human ↔ human DM (/api/dm): restricted members can talk to people",
218
218
  const threads = await get(daveToken, `/api/dm/threads?network_id=${NET}`);
219
219
  expect(threads.body.threads).toEqual([expect.objectContaining({ other_user_id: carolId, unread: 1 })]);
220
220
  expect((await get(daveToken, `/api/messages?scope=user&network_id=${NET}`)).body.messages.map((m: any) => m.content)).toContain("hi dave");
221
+ // 2026-10-31 —— **顺序承载语义**的行为对照(#3214)。
222
+ // `/api/messages` 在 server.ts 里有两处::5581 是 `?scope=user`,:5648 是通用(inbox,按 Agent)。
223
+ // 若有人把通用分支挪到前面,这一句带 scope 的请求会被它吃掉 —— 而响应仍是合法 200,
224
+ // 只是形状从 user_inbox 变成 inbox。两组断言必须同时在场,才能把这件事钉住。
225
+ const withScope = await get(daveToken, `/api/messages?scope=user&network_id=${NET}`);
226
+ const withoutScope = await get(daveToken, `/api/messages?network_id=${NET}`);
227
+ // user 视角:来自 user_inbox,字段是 message_id / acked_at
228
+ expect(withScope.body.messages[0]).toHaveProperty("message_id");
229
+ // 通用视角:来自 inbox,字段是 id / to_alias / from_alias
230
+ expect(withoutScope.body.messages[0] ?? {}).not.toHaveProperty("message_id");
231
+ expect(withScope.body.messages.map((m: any) => m.content)).toContain("hi dave");
232
+ expect((withoutScope.body.messages ?? []).map((m: any) => m.content)).not.toContain("hi dave");
221
233
  expect((await send(daveToken, "POST", "/api/dm", { network_id: NET, to_username: "acl3_carol", message: "hi carol" })).status).toBe(200);
222
234
  const thread = await get(carolToken, `/api/dm?network_id=${NET}&with=${daveId}`);
223
235
  expect(thread.body.messages.map((m: any) => [m.direction, m.content])).toEqual([["in", "hi carol"], ["out", "hi dave"]]);
@@ -265,3 +277,378 @@ describe("human ↔ human DM (/api/dm): restricted members can talk to people",
265
277
  expect(r.status).toBeGreaterThanOrEqual(401);
266
278
  });
267
279
  });
280
+
281
+ // 响应体是契约:update_node_config 的成功体被客户端按字段名读取,
282
+ // 任何「多加一栏」都应当是一次**有意识的**决定,而不是顺手。
283
+ // 这条测试钉住当前的键集(顺序无关,sorted 后比较),
284
+ // 让下一次加字段必须先让它变红、再明确决定要不要更新契约。
285
+ describe("update_node_config 响应键集(exact key set)", () => {
286
+ test("成功体恰好 {apply_mode, ok, update_id},不多不少", async () => {
287
+ const r = await tool(adminToken, "update_node_config", {
288
+ node_id: X.node, base_revision: 0, patch: { model: "exact-keys-model" }, network_id: NET,
289
+ });
290
+ expect(r.ok).toBe(true);
291
+ expect(Object.keys(r).sort()).toEqual(["apply_mode", "ok", "update_id"]);
292
+ });
293
+
294
+ test("在途冲突恰好 {age_ms, error, existing_update_id, ok}", async () => {
295
+ const r = await tool(adminToken, "update_node_config", {
296
+ node_id: X.node, base_revision: 0, patch: { model: "again" }, network_id: NET,
297
+ });
298
+ expect(r.ok).toBe(false);
299
+ expect(r.error).toBe("update_in_flight");
300
+ expect(Object.keys(r).sort()).toEqual(["age_ms", "error", "existing_update_id", "ok"]);
301
+ });
302
+
303
+ // 2026-10-31 —— 「意图」与「能力」两份不一致时,冲突必须被说出来。
304
+ // 否则 restart_supervised=true 会被读成「已验证」,而观测说没人拉它。
305
+ test("declared restart_supervised=true + observed not_supervised ⇒ the warning names the conflict", async () => {
306
+ const C = { alias: "acl3-conflict-c", node: "node_acl3_conflict_c" };
307
+ db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, config_snapshot)
308
+ VALUES (?1, ?2, ?2, ?3, ?4, ?5)`,
309
+ [C.node, C.alias, NET, adminId,
310
+ JSON.stringify({ restart_supervised: true, systemd_supervision: "not_supervised" })]);
311
+ db.run(`INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at)
312
+ VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`,
313
+ [`r_${C.node}`, C.alias, C.node, NET]);
314
+
315
+ const r = await tool(adminToken, "update_node_config", {
316
+ node_id: C.node, base_revision: 0, patch: { channels: [] }, network_id: NET,
317
+ });
318
+ expect(r.ok).toBe(true);
319
+ const w = (r.warnings || []).find((x: any) => x.code === "restart_requires_manual_respawn");
320
+ expect(w).toBeTruthy();
321
+ expect(w.message).toContain("DECLARES restart_supervised=true");
322
+ expect(w.message).toContain("the observation wins");
323
+ });
324
+
325
+ // 2026-10-31 —— #3171:剩下两个待核(get_all_status / list_node_skills)。
326
+ describe("get_all_status pinned (list_node_skills needs a live node → covered elsewhere)", () => {
327
+ test("⇒ {ok, sessions, sessions_returned, summary, summary_scope}; sessions 与 sessions_returned 同源", async () => {
328
+ const g = await tool(adminToken, "get_all_status", { network_id: NET });
329
+ expect(Object.keys(g).sort()).toEqual(["ok", "sessions", "sessions_returned", "summary", "summary_scope"]);
330
+ expect(Array.isArray(g.sessions)).toBe(true);
331
+ expect(g.sessions_returned).toBe(g.sessions.length); // 计数与数组同源
332
+ expect(typeof g.summary_scope).toBe("string");
333
+ });
334
+ });
335
+
336
+ // 2026-10-31 —— #3171:再补两个「文件级算过、邻近级没有」的工具。
337
+ describe("projects_list / get_session_status: pinned key sets next to the call", () => {
338
+ test("projects_list ⇒ {network_id, ok, projects}; get_session_status ⇒ {inbox_pending, ok, recent_completions, session}", async () => {
339
+ const pl = await tool(adminToken, "projects_list", { network_id: NET });
340
+ expect(Object.keys(pl).sort()).toEqual(["network_id", "ok", "projects"]);
341
+ expect(Array.isArray(pl.projects)).toBe(true);
342
+
343
+ const gs = await tool(adminToken, "get_session_status", { alias: "acl3-agent-x", network_id: NET });
344
+ expect(Object.keys(gs).sort()).toEqual(["inbox_pending", "ok", "recent_completions", "session"]);
345
+ expect(typeof gs.inbox_pending).toBe("number");
346
+ expect(Array.isArray(gs.recent_completions)).toBe(true);
347
+ });
348
+ });
349
+
350
+ // 2026-10-31 —— #3171:补一个「文件级算过、邻近级没有」的工具(list_tasks)。
351
+ // 之前该文件里唯一的 Object.keys 断言测的是 humans[0],与本工具无关 —— 这正是「测空气」。
352
+ describe("list_tasks: pinned key set next to the call", () => {
353
+ test("⇒ {count, next_cursor, ok, stats, tasks} and count === tasks.length", async () => {
354
+ const r = await tool(adminToken, "list_tasks", { network_id: NET });
355
+ // ⚠️ 我从源码里读到的形状(capability / next_terminal_seq)与实际返回不同 ——
356
+ // 这一条断言当场纠正了我:**读码得到的形状必须由一次真实调用确认**。
357
+ expect(Object.keys(r).sort()).toEqual(["count", "next_cursor", "ok", "stats", "tasks"]);
358
+ expect(Array.isArray(r.tasks)).toBe(true);
359
+ expect(r.count).toBe(r.tasks.length); // 计数与数组同源
360
+ });
361
+ });
362
+
363
+ // 2026-10-31 —— #3171 续:再一个节点侧读面(count/counts 同源的那类)。
364
+ describe("list_my_pending_create_requests: pinned key set", () => {
365
+ test("⇒ {clone_count, clone_requests, count, ok, requests}, and count === requests.length", async () => {
366
+ const N3 = { alias: "acl3-pend-n", node: "node_acl3_pend_n" };
367
+ seedAgent({ alias: N3.alias, node: N3.node });
368
+ const minted = createNetworkTokenForNode(adminId, NET, N3.alias, N3.node);
369
+ expect(minted.ok).toBe(true);
370
+ const r = await tool(minted.token!, "list_my_pending_create_requests", {});
371
+ expect(Object.keys(r).sort()).toEqual(["clone_count", "clone_requests", "count", "ok", "requests"]);
372
+ expect(Array.isArray(r.requests)).toBe(true);
373
+ expect(Array.isArray(r.clone_requests)).toBe(true);
374
+ expect(r.count).toBe(r.requests.length); // 计数与数组同源
375
+ expect(r.clone_count).toBe(r.clone_requests.length);
376
+ });
377
+ });
378
+
379
+ // 2026-10-31 —— #3171 续:两个节点侧只读工具的键集(有 ntok 夹具后成本很低)。
380
+ describe("node-side read tools: pinned key sets", () => {
381
+ test("list_my_children ⇒ {children, count, ok}; get_completions ⇒ {completions, ok}", async () => {
382
+ const N2 = { alias: "acl3-node-read-n", node: "node_acl3_node_read_n" };
383
+ seedAgent({ alias: N2.alias, node: N2.node });
384
+ const minted = createNetworkTokenForNode(adminId, NET, N2.alias, N2.node);
385
+ expect(minted.ok).toBe(true);
386
+ const ntok = minted.token!;
387
+
388
+ const children = await tool(ntok, "list_my_children", {});
389
+ expect(Object.keys(children).sort()).toEqual(["children", "count", "ok"]);
390
+ expect(Array.isArray(children.children)).toBe(true);
391
+ expect(children.count).toBe(children.children.length); // 计数与数组同源
392
+
393
+ const completions = await tool(ntok, "get_completions", {});
394
+ expect(Object.keys(completions).sort()).toEqual(["completions", "ok"]);
395
+ expect(Array.isArray(completions.completions)).toBe(true);
396
+ });
397
+ });
398
+
399
+ // 2026-10-31 —— #3171 续:org_whoami 也是**两支**(第二支多一个 pacing)。
400
+ // 它同时是「工具自带节流提示」的唯一一处,所以顺便把节流也钉住。
401
+ describe("org_whoami: base shape + the conditional pacing key", () => {
402
+ test("first call ⇒ no pacing; after the pacer trips ⇒ pacing appears (keys still pinned)", async () => {
403
+ const O = { alias: "acl3-whoami-o", node: "node_acl3_whoami_o" };
404
+ seedAgent({ alias: O.alias, node: O.node });
405
+ const minted = createNetworkTokenForNode(adminId, NET, O.alias, O.node);
406
+ expect(minted.ok).toBe(true);
407
+ const ntok = minted.token!;
408
+
409
+ const first = await tool(ntok, "org_whoami", {});
410
+ expect(first.ok).toBe(true);
411
+ expect(Object.keys(first)).not.toContain("pacing"); // 基线:第一次不该被提示
412
+
413
+ // 节流阈值 8 次/60 秒 ⇒ 连续调用后最后一条必须带 pacing
414
+ let last: any = null;
415
+ for (let i = 0; i < 10; i++) last = await tool(ntok, "org_whoami", {});
416
+ expect(Object.keys(last)).toContain("pacing");
417
+ expect(typeof last.pacing).toBe("object");
418
+ });
419
+ });
420
+
421
+ // 2026-10-31 —— #3171 续:**条件出现的键**(与 update_node_config 的 warnings 同族)。
422
+ // get_inbox 在 human 模式下多带一个 human_inbox —— 只钉无 flag 那一支,
423
+ // 等于允许另一支任意变形。
424
+ describe("get_inbox: both shapes are pinned (the second key is conditional)", () => {
425
+ test("default ⇒ {messages, ok}; human ⇒ {human_inbox, messages, ok} and human_inbox is {examined, mode, version}", async () => {
426
+ const I = { alias: "acl3-inbox-i", node: "node_acl3_inbox_i" };
427
+ seedAgent({ alias: I.alias, node: I.node });
428
+ const minted = createNetworkTokenForNode(adminId, NET, I.alias, I.node);
429
+ expect(minted.ok).toBe(true);
430
+ const ntok = minted.token!;
431
+
432
+ const plain = await tool(ntok, "get_inbox", { alias: I.alias, limit: 5 });
433
+ expect(Object.keys(plain).sort()).toEqual(["messages", "ok"]);
434
+ expect(Array.isArray(plain.messages)).toBe(true);
435
+
436
+ const human = await tool(ntok, "get_inbox", { alias: I.alias, limit: 5, human_first: true });
437
+ expect(Object.keys(human).sort()).toEqual(["human_inbox", "messages", "ok"]);
438
+ expect(Object.keys(human.human_inbox).sort()).toEqual(["examined", "mode", "version"]);
439
+ expect(human.human_inbox.mode).toBe("metadata-keyset");
440
+ });
441
+ });
442
+
443
+ // 2026-10-31 —— #3171 续:两个「读面」工具的键集。
444
+ // 选它们的理由:这两个是**客户端会按字段名逐个读**的(provider 列表 / 密钥名列表),
445
+ // 而它们此前没有任何精确键集断言 —— 覆盖率脚本把它们列在 59 个未覆盖里。
446
+ describe("read-surface tools have pinned key sets", () => {
447
+ test("list_providers ⇒ exactly {ok, providers}; list_network_secrets ⇒ exactly {keys, ok}", async () => {
448
+ const providers = await tool(adminToken, "list_providers", { network_id: NET });
449
+ // 2026-10-31 —— 载荷扩容:`[]` 有四种含义(未配 / 全停用 / 配了没模型 / 查询失败),
450
+ // 所以 `state` 与 `counts` 必须与 providers 同载荷;否则客户端只能显示「没有」。
451
+ // 键集有**两种合法形状**(不是放宽成数组包含):configured 时不给 hint,其余状态必须给 ——
452
+ // 「有理由」和「没理由」在载荷上必须可区分,否则客户端只能说「没有」。
453
+ const baseKeys = ["counts", "ok", "providers", "state"];
454
+ expect(Object.keys(providers).sort()).toEqual(
455
+ providers.state === "configured" ? baseKeys : [...baseKeys, "hint"].sort(),
456
+ );
457
+ if (providers.state !== "configured") expect(String(providers.hint).length).toBeGreaterThan(10);
458
+ expect(Object.keys(providers.counts).sort()).toEqual(
459
+ ["models_enabled", "providers_disabled", "providers_enabled", "providers_without_models"],
460
+ );
461
+ expect(["configured", "all_disabled", "unconfigured"]).toContain(providers.state);
462
+ // 唯一一条跨字段不变量:state 与 providers 数组必须自洽
463
+ expect(providers.state === "configured").toBe(providers.providers.length > 0);
464
+ expect(Array.isArray(providers.providers)).toBe(true);
465
+
466
+ const secrets = await tool(adminToken, "list_network_secrets", { network_id: NET });
467
+ expect(Object.keys(secrets).sort()).toEqual(["keys", "ok"]);
468
+ expect(Array.isArray(secrets.keys)).toBe(true);
469
+ // 值永远不出来:这是 RFC-028 的承诺,键集测试顺手把它钉住
470
+ for (const k of secrets.keys) expect(typeof k).toBe("string");
471
+ });
472
+ });
473
+
474
+ // 2026-10-31 —— **空的 providers 数组有四种含义**(外部复核「兜底值必须说出自己是兜底」)。
475
+ // 这条测试把 ①②③ 三种状态逐个造出来,断言 state 与 hint 各自不同 ——
476
+ // 只测「空 == 空」的话,三种状态在载荷里长得一样,客户端的空状态就只能显示「没有」。
477
+ test("list_providers: an empty registry says WHY it is empty (unconfigured / all_disabled / no models)", async () => {
478
+ const pid = `acl3-probe-${Date.now()}`;
479
+ const readState = async () => await tool(adminToken, "list_providers", { network_id: NET });
480
+ const cleanup = () => {
481
+ db.run(`DELETE FROM provider_models WHERE provider_id = ?1`, [pid]);
482
+ db.run(`DELETE FROM providers WHERE provider_id = ?1`, [pid]);
483
+ };
484
+ try {
485
+ // ① 未配置
486
+ const a = await readState();
487
+ expect(a.providers.length).toBe(0);
488
+ expect(a.state).toBe("unconfigured");
489
+ expect(String(a.hint)).toContain("还没有任何 provider");
490
+
491
+ // ② 配过但停用
492
+ db.run(
493
+ `INSERT INTO providers (provider_id, network_id, name, vendor, base_url, secret_key_ref, created_at, created_by, enabled)
494
+ VALUES (?1, ?2, ?3, 'openai', 'https://api.example.com', 'K', ?4, 'test', 0)`,
495
+ [pid, NET, pid, Date.now()],
496
+ );
497
+ const b = await readState();
498
+ expect(b.providers.length).toBe(0);
499
+ expect(b.state).toBe("all_disabled");
500
+ expect(b.counts.providers_disabled).toBe(1);
501
+ expect(String(b.hint)).toContain("停用");
502
+
503
+ // ③ 启用但一条模型都没有
504
+ db.run(`UPDATE providers SET enabled = 1 WHERE provider_id = ?1`, [pid]);
505
+ const c = await readState();
506
+ expect(c.state).toBe("configured");
507
+ expect(c.providers.length).toBe(1);
508
+ expect(c.providers[0].models.length).toBe(0);
509
+ expect(c.providers[0].models_state).toBe("none_configured");
510
+ expect(c.counts.providers_without_models).toBe(1);
511
+ expect("hint" in c).toBe(false); // configured 时不带 hint(载荷不变胖)
512
+
513
+ // 2026-10-31 —— **键集变化必须是结构性可枚举的,不是「测到哪算哪」**(外部复核 (b):
514
+ // 「不造业务上限,改成结构性证明:键集对任意 n 恒定,不再依赖枚举」)。
515
+ // 本载荷的 n 是「provider 条数」,键集必须与 n 无关;唯一的条件字段是 `hint`,
516
+ // 且它只由 `state` 决定 ⇒ 用「所有 state 的键集集合」把这条结构钉死:
517
+ // 不同的键集恰好 2 种,且它们的差恰好是 {"hint"}。
518
+ // 这样新增第三个条件字段时会红 —— 而不是「反正测试里的 n 只有 0 和 1,没测到」。
519
+ // ④ 有模型但不启用 ⇒ all_disabled(不是 none_configured)
520
+ db.run(
521
+ `INSERT INTO provider_models (model_id, provider_id, model_name, enabled, created_at)
522
+ VALUES (?1, ?2, 'm1', 0, ?3)`,
523
+ [`${pid}-m1`, pid, Date.now()],
524
+ );
525
+ const d = await readState();
526
+ expect(d.providers[0].models_state).toBe("all_disabled");
527
+
528
+ // 结构性键集:四次读数覆盖 4 种 state,键集只允许有 2 种,且差恰好 {"hint"}
529
+ const keySets = new Map<string, string[]>();
530
+ for (const [label, payload] of [["unconfigured", a], ["all_disabled", b], ["configured", c], ["models disabled", d]] as const) {
531
+ keySets.set(label, Object.keys(payload).sort());
532
+ }
533
+ const distinct = [...new Set([...keySets.values()].map((k) => k.join(",")))];
534
+ expect(distinct.length).toBe(2);
535
+ const withHint = distinct.find((k) => k.includes("hint"))!;
536
+ const withoutHint = distinct.find((k) => !k.includes("hint"))!;
537
+ expect(withHint.split(",").filter((k) => !withoutHint.split(",").includes(k))).toEqual(["hint"]);
538
+ expect(withoutHint.split(",").filter((k) => !withHint.split(",").includes(k))).toEqual([]);
539
+ } finally {
540
+ cleanup();
541
+ }
542
+ });
543
+
544
+ // 2026-10-31 —— #3171 第 2 项:restart_node 的成功体与 update_node_config 同构。
545
+ describe("restart_node success body", () => {
546
+ test("pinned key set (same shape family as update_node_config)", async () => {
547
+ const R = { alias: "acl3-restart-r", node: "node_acl3_restart_r" };
548
+ seedAgent({ alias: R.alias, node: R.node });
549
+ const r = await tool(adminToken, "restart_node", { node_id: R.node, network_id: NET });
550
+ // 与 update_node_config 同构(不含 warnings:restart 不带 patch,分档固定为 restart_only)
551
+ expect(Object.keys(r).sort()).toEqual(["apply_mode", "ok", "update_id"]);
552
+ expect(r.ok).toBe(true);
553
+ expect(r.apply_mode).toBe("restart_only");
554
+ });
555
+ });
556
+
557
+ // 2026-10-31 —— #3171 第 3 项:get_config_update 的两态。
558
+ // 「有 pending」与「无 pending」是**两条不同形状**,而旧测试只在 SQL 层模拟过它们,
559
+ // 从没有一条断言钉住工具真正返回的那两个 JSON。
560
+ describe("get_config_update: both states have pinned shapes", () => {
561
+ test("no pending ⇒ exactly {ok, update:null}; with pending ⇒ exactly {ok, update:{apply_mode,base_revision,patch,update_id}}", async () => {
562
+ const N = { alias: "acl3-puller-n", node: "node_acl3_puller_n" };
563
+ seedAgent({ alias: N.alias, node: N.node });
564
+ const minted = createNetworkTokenForNode(adminId, NET, N.alias, N.node);
565
+ expect(minted.ok).toBe(true);
566
+ const ntok = minted.token!;
567
+
568
+ // ① 无 pending
569
+ const empty = await tool(ntok, "get_config_update", {});
570
+ expect(Object.keys(empty).sort()).toEqual(["ok", "update"]);
571
+ expect(empty.ok).toBe(true);
572
+ expect(empty.update).toBeNull();
573
+
574
+ // ② 有 pending
575
+ db.run(`INSERT INTO node_config_updates (update_id, node_id, network_id, patch_json, apply_mode, base_revision, status, created_at, created_by_token)
576
+ VALUES (?1, ?2, ?3, ?4, 'hot', 0, 'pending', ?5, 'test')`,
577
+ ["u_acl3_pending", N.node, NET, JSON.stringify({ model: "m" }), Date.now()]);
578
+ const one = await tool(ntok, "get_config_update", {});
579
+ expect(Object.keys(one).sort()).toEqual(["ok", "update"]);
580
+ expect(Object.keys(one.update).sort()).toEqual(["apply_mode", "base_revision", "patch", "update_id"]);
581
+ expect(one.update.update_id).toBe("u_acl3_pending");
582
+ expect(one.update.apply_mode).toBe("hot");
583
+
584
+ // ③ #3171 第 4 项:ack 成功回执恰好 {ok, status}
585
+ const ack = await tool(ntok, "ack_config_update", {
586
+ update_id: "u_acl3_pending", status: "applied", new_revision: 1,
587
+ });
588
+ expect(Object.keys(ack).sort()).toEqual(["ok", "status"]);
589
+ expect(ack.ok).toBe(true);
590
+ expect(ack.status).toBe("applied");
591
+ });
592
+ });
593
+
594
+ // 2026-10-31 —— #3171 第 5 项:错误信封的形状也要钉住。
595
+ // 今天它们是「约定俗成」:每个出口手写 {ok:false,error},
596
+ // 于是谁顺手多塞一个字段,客户端的分支就多一个没人知道的键。
597
+ describe("error envelope: exactly {ok, error} unless the error carries its own fields", () => {
598
+ test("get_config_update without a node token ⇒ exactly {error, ok}", async () => {
599
+ const r = await tool(adminToken, "get_config_update", {});
600
+ expect(r.ok).toBe(false);
601
+ expect(r.error).toBe("network_token_required");
602
+ expect(Object.keys(r).sort()).toEqual(["error", "ok"]);
603
+ });
604
+
605
+ test("ack_config_update without a node token ⇒ exactly {error, ok}", async () => {
606
+ const r = await tool(adminToken, "ack_config_update", {
607
+ update_id: "u_missing", status: "applied", network_id: NET,
608
+ });
609
+ expect(r.ok).toBe(false);
610
+ expect(r.error).toBe("network_token_required");
611
+ expect(Object.keys(r).sort()).toEqual(["error", "ok"]);
612
+ });
613
+ });
614
+
615
+ // 2026-10-31 —— #3171:warnings 出现时的成功体也必须被钉住。
616
+ // 上面那条钉的是「没有 warning」的形状;而 warnings 是**条件出现**的 ⇒
617
+ // 只断言前者,等于允许后者任意变形(今天它没出事,靠的是客户端宽松解析)。
618
+ test("带 warning 的成功体恰好 {apply_mode, ok, update_id, warnings},且 warning 项恰好 {code, message}", async () => {
619
+ const W = { alias: "acl3-agent-w", node: "node_acl3_w" };
620
+ db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, config_snapshot)
621
+ VALUES (?1, ?2, ?2, ?3, ?4, ?5)`,
622
+ [W.node, W.alias, NET, adminId, JSON.stringify({ systemd_supervision: "not_supervised" })]);
623
+ db.run(`INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at)
624
+ VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`,
625
+ [`r_${W.node}`, W.alias, W.node, NET]);
626
+
627
+ const r = await tool(adminToken, "update_node_config", {
628
+ node_id: W.node, base_revision: 0, patch: { channels: [] }, network_id: NET,
629
+ });
630
+
631
+ expect(r.ok).toBe(true);
632
+ expect(r.apply_mode).not.toBe("hot"); // restart-tier:这正是危险的那一档
633
+ // 两个方向都钉:少一个键红,多一个键也红
634
+ expect(Object.keys(r).sort()).toEqual(["apply_mode", "ok", "update_id", "warnings"]);
635
+ expect(Array.isArray(r.warnings)).toBe(true);
636
+ expect(r.warnings.length).toBe(1);
637
+ expect(Object.keys(r.warnings[0]).sort()).toEqual(["code", "message"]);
638
+ // code 是稳定枚举,不是自由文本 —— 客户端要靠它分支
639
+ expect(r.warnings[0].code).toBe("restart_requires_manual_respawn");
640
+ expect(typeof r.warnings[0].message).toBe("string");
641
+ });
642
+
643
+ test("revision 冲突恰好 {current_revision, error, ok}", async () => {
644
+ // 用另一台干净节点,避开上面那条的在途状态
645
+ const r = await tool(adminToken, "update_node_config", {
646
+ node_id: Z.node, base_revision: 99, patch: { model: "stale" }, network_id: NET,
647
+ });
648
+ expect(r.ok).toBe(false);
649
+ // 实际契约:code 是 revision_conflict(不是 config_revision_conflict),
650
+ // 且带 base_revision —— 顺手纠正了卡上写错的错误名。
651
+ expect(r.error).toBe("revision_conflict");
652
+ expect(Object.keys(r).sort()).toEqual(["base_revision", "current_revision", "error", "ok"]);
653
+ });
654
+ });
@@ -14,6 +14,8 @@ import {
14
14
  computeApplyMode,
15
15
  readOpencodeSnapshotFlags,
16
16
  readConfigUpdateCapable,
17
+ configUpdateCapabilityDivergence,
18
+ readSystemdSupervision,
17
19
  validatePatch,
18
20
  narrowChannelsPatch,
19
21
  } from "./config-apply-validate";
@@ -469,3 +471,69 @@ describe("readConfigUpdateCapable", () => {
469
471
  expect(readConfigUpdateCapable('{"config_update_capable":"false"}')).toBeNull();
470
472
  });
471
473
  });
474
+
475
+ describe("readConfigUpdateCapable — restart_supervised 优先", () => {
476
+ test("prefers the named key when both are present", () => {
477
+ expect(readConfigUpdateCapable('{"restart_supervised":true,"config_update_capable":false}')).toBe(true);
478
+ expect(readConfigUpdateCapable('{"restart_supervised":false,"config_update_capable":true}')).toBe(false);
479
+ });
480
+ test("falls back to the legacy key for old nodes", () => {
481
+ expect(readConfigUpdateCapable('{"config_update_capable":true}')).toBe(true);
482
+ });
483
+ test("non-boolean named value falls through to legacy, then unknown", () => {
484
+ expect(readConfigUpdateCapable('{"restart_supervised":"true","config_update_capable":false}')).toBe(false);
485
+ expect(readConfigUpdateCapable('{"restart_supervised":"true"}')).toBeNull();
486
+ });
487
+ });
488
+
489
+ // 2026-10-31 —— 「被遮住的值」必须能被看见。
490
+ // readConfigUpdateCapable 一旦选定 restart_supervised,config_update_capable 就再也读不到了;
491
+ // 而「两个一致」与「有一个被遮住了」在调用方看来完全一样 —— 这是隐式回退的通用形状。
492
+ describe("configUpdateCapabilityDivergence — 双写字段的分歧本身就是读数", () => {
493
+ test("reports both values when they disagree, in either direction", () => {
494
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":true,"config_update_capable":false}'))
495
+ .toEqual({ named: true, legacy: false });
496
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":false,"config_update_capable":true}'))
497
+ .toEqual({ named: false, legacy: true });
498
+ });
499
+ test("stays quiet when they agree — that is the documented normal case", () => {
500
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":true,"config_update_capable":true}')).toBeNull();
501
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":false,"config_update_capable":false}')).toBeNull();
502
+ });
503
+ test("no divergence to report when only one field is present or shapes are unusable", () => {
504
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":true}')).toBeNull();
505
+ expect(configUpdateCapabilityDivergence('{"config_update_capable":true}')).toBeNull();
506
+ expect(configUpdateCapabilityDivergence('{"restart_supervised":"true","config_update_capable":false}')).toBeNull();
507
+ expect(configUpdateCapabilityDivergence("")).toBeNull();
508
+ expect(configUpdateCapabilityDivergence("not json")).toBeNull();
509
+ expect(configUpdateCapabilityDivergence(null)).toBeNull();
510
+ expect(configUpdateCapabilityDivergence(undefined)).toBeNull();
511
+ });
512
+ test("accepts an already-parsed object (nodes may hand us either form)", () => {
513
+ expect(configUpdateCapabilityDivergence({ restart_supervised: true, config_update_capable: false }))
514
+ .toEqual({ named: true, legacy: false });
515
+ });
516
+ });
517
+
518
+
519
+ // 2026-10-31 —— #3168:节点自报的三态托管判定。
520
+ // 「它说自己没人拉」与「它说有人拉」处置相反;而「不知道」两边都不能当。
521
+ describe("readSystemdSupervision", () => {
522
+ test("reads the three declared states verbatim", () => {
523
+ expect(readSystemdSupervision(JSON.stringify({ systemd_supervision: "supervised" }))).toBe("supervised");
524
+ expect(readSystemdSupervision('{"systemd_supervision":"not_supervised"}')).toBe("not_supervised");
525
+ expect(readSystemdSupervision({ systemd_supervision: "unknown" })).toBe("unknown");
526
+ });
527
+
528
+ test("missing field ⇒ null, which is NOT the same as unknown", () => {
529
+ // 缺失 = 这一版还不会报(老节点);unknown = 会报但这次判不出来。
530
+ expect(readSystemdSupervision('{"config_update_capable":false}')).toBeNull();
531
+ expect(readSystemdSupervision("")).toBeNull();
532
+ expect(readSystemdSupervision("not json")).toBeNull();
533
+ });
534
+
535
+ test("rejects values outside the declared set (a typo must not silently mean 'supervised')", () => {
536
+ expect(readSystemdSupervision('{"systemd_supervision":"yes"}')).toBeNull();
537
+ expect(readSystemdSupervision('{"systemd_supervision":true}')).toBeNull();
538
+ });
539
+ });
@@ -248,10 +248,79 @@ export function readConfigUpdateCapable(configSnapshot: unknown): boolean | null
248
248
  } catch {
249
249
  return null;
250
250
  }
251
+ // 优先读更具名的 `restart_supervised`(agent-node 同时上报,永远同值);
252
+ // 旧客户端只报 config_update_capable,回退读它。
253
+ const named = parsed?.restart_supervised;
254
+ if (typeof named === "boolean") return named;
251
255
  const value = parsed?.config_update_capable;
252
256
  return typeof value === "boolean" ? value : null;
253
257
  }
254
258
 
259
+ /**
260
+ * 2026-10-31 —— 双写字段的**分歧**本身是一条读数,而今天它是静默的。
261
+ *
262
+ * `readConfigUpdateCapable` 在两个字段都在时优先读 `restart_supervised`,
263
+ * 文档说它们「永远同值」。所以「不同值」不是噪声,是一个真实信号:
264
+ * 半升级(wrapper 转发了一路、漏了另一路)、旧节点、或有人手改了快照。
265
+ *
266
+ * 🔴 为什么值得单独一个函数:
267
+ * 两个生产者的字段,只要**允许一个遮住另一个**,那个被遮住的值就再也读不到了 ——
268
+ * 而“读不到”与“两个一致”在调用方看来完全一样。这正是隐性回退的通用形状:
269
+ * 值从一个隐式来源解析出来,解析过程不留痕。
270
+ *
271
+ * 返回值:只在**两个都是布尔且不同**时给出两份值;其余一律 null(没有分歧可报)。
272
+ * 调用方负责把 `restart_supervision_flag_divergence` 放进 warnings —— 本函数不改判据。
273
+ */
274
+ export function configUpdateCapabilityDivergence(
275
+ configSnapshot: unknown,
276
+ ): { named: boolean; legacy: boolean } | null {
277
+ let parsed: any = null;
278
+ try {
279
+ parsed = typeof configSnapshot === "string"
280
+ ? (configSnapshot ? JSON.parse(configSnapshot) : null)
281
+ : configSnapshot;
282
+ } catch {
283
+ return null;
284
+ }
285
+ const named = parsed?.restart_supervised;
286
+ const legacy = parsed?.config_update_capable;
287
+ if (typeof named !== "boolean" || typeof legacy !== "boolean") return null;
288
+ return named === legacy ? null : { named, legacy };
289
+ }
290
+
291
+ /**
292
+ * 2026-10-31 —— 用节点**自己**报的托管判定取代「没有声明」(#3168 的自然下一步)。
293
+ *
294
+ * `config_update_capable=false` 只说明「没有声明 sentinel-75 重启包装」,
295
+ * 而 systemd/pm2 托管的节点也可能报 false(它们不走那套包装)⇒ 于是只能写成
296
+ * 「does not advertise」,把判断交给调用方 —— 那是对的,但不够具体。
297
+ *
298
+ * 节点现在会上报三态 `systemd_supervision`(supervised / not_supervised / unknown),
299
+ * 于是「它自己说没人拉它」与「它自己说有人拉它」可以被分开讲:
300
+ *
301
+ * not_supervised ⇒ 明确后果:exit 75 之后**没有东西会把它拉起来**
302
+ * supervised ⇒ 不做警告(具名判定优先,胜过 legacy 布尔)
303
+ * unknown/缺失 ⇒ 退回旧口径(「没有声明」),因为「不知道」不能当成「没人拉」
304
+ *
305
+ * 🔴 三态而不是布尔:`unknown` 与 `not_supervised` 在处置上完全相反 ——
306
+ * 前者要人去看,后者要人别发这类变更。
307
+ */
308
+ export function readSystemdSupervision(
309
+ configSnapshot: unknown,
310
+ ): "supervised" | "not_supervised" | "unknown" | null {
311
+ let parsed: any = null;
312
+ try {
313
+ parsed = typeof configSnapshot === "string"
314
+ ? (configSnapshot ? JSON.parse(configSnapshot) : null)
315
+ : configSnapshot;
316
+ } catch {
317
+ return null;
318
+ }
319
+ const v = parsed?.systemd_supervision;
320
+ if (v === "supervised" || v === "not_supervised" || v === "unknown") return v;
321
+ return null; // 老节点没有这个字段:**缺失 ≠ unknown**,缺失是「这一版还不会报」
322
+ }
323
+
255
324
  /**
256
325
  * Classify the patch's required apply mode. Empty patch (model + flags
257
326
  * both empty, no channels) → "restart_only" (used by restart_node tool).
@@ -0,0 +1,40 @@
1
+ // 2026-10-31 —— 「设了空」与「没设」是两件事。
2
+ //
3
+ // 起因(外部复核):`'TMAICLOUD_PUBLIC_ORIGIN' in process.env` 才能区分「设了空」与「没设」,
4
+ // 而 `if (process.env.X)` 把两者都判假。
5
+ //
6
+ // 在本仓的落点:COMMHUB_CORS_ORIGINS。
7
+ // · 未设 ⇒ 开发默认(localhost 两个端口)
8
+ // · 设了但为空 ⇒ **空清单**(谁都不许)
9
+ // 如果两者都判假并回退默认,那么运维写 `COMMHUB_CORS_ORIGINS=`(想「一个都不许」)
10
+ // 得到的却是「放行 localhost」—— 空落到了**更松**的一侧。
11
+ //
12
+ // 判据:写一个允许清单的默认值之前,先写出它的**最松值**。
13
+ // 这里最松值不是空(空 = 谁都不许 = 最严),而是 `*`。所以空绝不能被读成「用默认」。
14
+ import { describe, expect, test } from "bun:test";
15
+ import { parseCorsOrigins } from "./server.js";
16
+
17
+ describe("parseCorsOrigins: 未设 / 设空 / 设值 三态", () => {
18
+ test("未设 ⇒ 开发默认(localhost 两个端口)", () => {
19
+ expect(parseCorsOrigins(undefined)).toEqual(["http://localhost:3000", "http://localhost:3001"]);
20
+ });
21
+
22
+ test("设了但为空 ⇒ 空清单(谁都不许),**不回退默认**", () => {
23
+ expect(parseCorsOrigins("")).toEqual([]);
24
+ // 只写了分隔符 / 空白也是空清单,而不是"默认"
25
+ expect(parseCorsOrigins(",")).toEqual([]);
26
+ expect(parseCorsOrigins(" , ")).toEqual([]);
27
+ });
28
+
29
+ test("设了值 ⇒ 逐条 trim,空条目被丢掉(不许出现空字符串条目)", () => {
30
+ expect(parseCorsOrigins(" https://a.example , https://b.example ")).toEqual(["https://a.example", "https://b.example"]);
31
+ expect(parseCorsOrigins("https://a.example,")).toEqual(["https://a.example"]);
32
+ });
33
+
34
+ test("must-fire:'*' 不会被当成通配(本实现是精确匹配清单)", () => {
35
+ // 如果哪天有人把 '*' 当通配实现,这条仍会过 —— 但 corsHeaders 用的是 includes,
36
+ // 所以这里钉的是「清单里有什么就是什么」,不是「* 有特殊含义」。
37
+ expect(parseCorsOrigins("*")).toEqual(["*"]);
38
+ expect(parseCorsOrigins(undefined)).not.toContain("*");
39
+ });
40
+ });
@@ -75,5 +75,17 @@ describe("#1027 get_create_request returns network_id", () => {
75
75
  expect(g.ok).toBe(true);
76
76
  expect(g.network_id).toBe(NET);
77
77
  expect(g.node_spec?.name).toBe("child-1027");
78
+ // 2026-10-31 —— **精确键集**(#3171):上面全是字段级断言,
79
+ // 「多给一个字段」不会被发现,而这条响应会流到 daemon 侧按字段消费。
80
+ // ⚠️ 我先后猜了两次键集(第一次少了 child_token/env_blob,第二次多了 op/status),
81
+ // 两次都是断言把真实形状打出来的。这一条不写「我认为的形状」,写**它实际给的**。
82
+ expect(Object.keys(g).sort()).toEqual([
83
+ "child_token", "env_blob", "network_id", "node_spec", "ok", "request_id",
84
+ ].sort());
85
+ // 未知 id ⇒ 确定性两键**错误**形状(第三次被断言纠正:这里不是 {ok,request:null},
86
+ // 而是 {ok,error};两种都是「两键」,值不同 —— 正是精确键集要区分的那一格)。
87
+ const missing = await call(t.get_create_request, { request_id: "cr_does_not_exist" });
88
+ expect(Object.keys(missing).sort()).toEqual(["error", "ok"]);
89
+ expect(missing.ok).toBe(false);
78
90
  });
79
91
  });