@sleep2agi/commhub-server 0.9.0-preview.223 → 0.9.0-preview.224

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sleep2agi/commhub-server",
3
- "version": "0.9.0-preview.223",
3
+ "version": "0.9.0-preview.224",
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",
@@ -34,6 +34,7 @@ export const PUBLIC_HEALTH_KEY_READERS: Readonly<Record<string, AnonReaderEntry>
34
34
  status: { reader: "cli", why: "客户端展示 Hub 的细分状态(ok / degraded)" },
35
35
  status_reasons: { reader: "cli", why: "anet status 把 status_reasons 拼成一行原因给用户看(bin/cli.ts)" },
36
36
  version: { reader: "cli", why: "版本不一致提示(anet 与 hub 的版本对齐)" },
37
+ version_source: { reader: "operator", why: "运维判断「版本没变」是没发出去还是被 env 覆盖;仓内无代码读" },
37
38
  version_role: { reader: "external", why: "docs/release-hub-runbook.md 描述的仓外 dashboard 读它区分构建;仓内无消费者,未验" },
38
39
  api_version: { reader: "cli", why: "客户端与 Hub 协商协议版本,不匹配时给出升级提示" },
39
40
  transport: { reader: "cli", why: "协议协商(streamable-http)" },
@@ -1099,6 +1099,42 @@ describe("#473 anonymous /health — watchdog contract intact, no topology leak"
1099
1099
  }
1100
1100
  });
1101
1101
 
1102
+ // 2026-10-31 —— **有覆盖、零仲裁**(外部复核 (d)):version 有两个来源
1103
+ // (standalone 二进制注入的 env / 磁盘 package.json),此前只报结果、不报谁赢了。
1104
+ // version_source 就是那个仲裁位;下面四例钉住它的语义。
1105
+ test("version_source names which override won (embedded_env / package_json / unknown)", async () => {
1106
+ const { resolveServerVersion } = await import("./server.js");
1107
+ expect(resolveServerVersion("0.9.0-preview.999", () => "0.9.0-preview.1"))
1108
+ .toEqual({ version: "0.9.0-preview.999", source: "embedded_env" });
1109
+ // env 形状不对 ⇒ 落到磁盘,而不是把非法值当版本号
1110
+ expect(resolveServerVersion("latest", () => "0.9.0-preview.1"))
1111
+ .toEqual({ version: "0.9.0-preview.1", source: "package_json" });
1112
+ // 磁盘读失败 ⇒ unknown,而不是伪装成某个来源
1113
+ expect(resolveServerVersion(undefined, () => { throw new Error("ENOENT"); }))
1114
+ .toEqual({ version: "?", source: "unknown" });
1115
+ expect(resolveServerVersion(" ", () => "?"))
1116
+ .toEqual({ version: "?", source: "unknown" });
1117
+
1118
+ // 线上读数与语义自洽:unknown ⇔ version 是 "?"
1119
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
1120
+ expect(["embedded_env", "package_json", "unknown"]).toContain(body.version_source);
1121
+ if (body.version_source === "unknown") expect(body.version).toBe("?");
1122
+ else expect(body.version).not.toBe("?");
1123
+ });
1124
+
1125
+ // 2026-10-31 —— **granularity=instant 的字段必须写出反事实**(外部复核 (c):
1126
+ // 「判法改为对『这个值变了,世界上什么变了』做反事实询问」)。
1127
+ // 这一类的共同陷阱:值在变,看起来有信息,而它变的可能只是**读的时刻**。
1128
+ test("every instant-granularity field states its counterfactual (why is mandatory)", async () => {
1129
+ const { HEALTH_FIELD_META } = await import("./server.js");
1130
+ const instant = Object.entries(HEALTH_FIELD_META).filter(([, m]: any) => m.granularity === "instant");
1131
+ expect(instant.length).toBeGreaterThanOrEqual(2);
1132
+ const missing = instant.filter(([, m]: any) => !(m.why && String(m.why).length > 8)).map(([k]) => k);
1133
+ if (missing.length) {
1134
+ throw new Error(`instant 字段没有写「变了意味着什么」:${missing.join(", ")}\n ⇒ 它可能只是读的时刻在变,而不是状态在变。`);
1135
+ }
1136
+ });
1137
+
1102
1138
  test("no dead entries: every allow-listed key is actually served to anonymous callers", async () => {
1103
1139
  const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
1104
1140
  const plain = await (await fetch(`${BASE}/health`)).json() as any;
package/src/server.ts CHANGED
@@ -165,14 +165,39 @@ const MCP_LABEL_MAX_BYTES = 1024 * 1024;
165
165
  // Read version from package.json so banners and /health stay in sync.
166
166
  // ANET_EMBEDDED_COMMHUB_VERSION is set only by the standalone anet binary
167
167
  // (bin/anet-bin.ts). npm/bunx leaves it unset and keeps the disk read.
168
- const SERVER_VERSION = (() => {
169
- const embedded = process.env.ANET_EMBEDDED_COMMHUB_VERSION?.trim() ?? "";
170
- if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(embedded)) return embedded;
168
+ /**
169
+ * 2026-10-31 —— **有覆盖、零仲裁**(外部复核 (d):
170
+ * 「`versionSource`/`versionEnvIgnored` 在本仓库 0 命中 ⇒ `version` 是『有覆盖、零仲裁』的缺陷形态」)。
171
+ *
172
+ * 这个值有两个可能来源(standalone 二进制注入的 env / 磁盘 package.json),
173
+ * 而 `/health` 只报结果、不报**谁赢了**。后果:
174
+ * · 有人改了 package.json 却发现线上版本没变(被 env 覆盖)
175
+ * · 或以为在用二进制内嵌版本,其实是磁盘那个
176
+ * 两个方向都只能靠猜。⇒ 现在把来源作为字段一起给出。
177
+ */
178
+ export type VersionSource = "embedded_env" | "package_json" | "unknown";
179
+ export function resolveServerVersion(
180
+ embeddedRaw: string | undefined,
181
+ readPackageVersion: () => string,
182
+ ): { version: string; source: VersionSource } {
183
+ const embedded = (embeddedRaw ?? "").trim();
184
+ if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(embedded)) {
185
+ return { version: embedded, source: "embedded_env" };
186
+ }
171
187
  try {
172
- const url = new URL("../package.json", import.meta.url);
173
- return JSON.parse(require("fs").readFileSync(url, "utf8")).version || "?";
174
- } catch { return "?"; }
175
- })();
188
+ const v = readPackageVersion();
189
+ if (v && v !== "?") return { version: v, source: "package_json" };
190
+ return { version: "?", source: "unknown" };
191
+ } catch {
192
+ return { version: "?", source: "unknown" };
193
+ }
194
+ }
195
+ const RESOLVED_VERSION = resolveServerVersion(process.env.ANET_EMBEDDED_COMMHUB_VERSION, () => {
196
+ const url = new URL("../package.json", import.meta.url);
197
+ return JSON.parse(require("fs").readFileSync(url, "utf8")).version || "?";
198
+ });
199
+ const SERVER_VERSION = RESOLVED_VERSION.version;
200
+ const SERVER_VERSION_SOURCE = RESOLVED_VERSION.source;
176
201
 
177
202
  // Feature flags advertised on /health (see the /health handler). Exported for tests.
178
203
  // node_permission_mode(#489):节点有 permission_mode、GET /api/nodes 每行带 viewer_can.permission_mode,
@@ -993,7 +1018,7 @@ function corsHeaders(req: Request): Record<string, string> {
993
1018
  */
994
1019
  export const PUBLIC_HEALTH_KEYS: ReadonlySet<string> = new Set([
995
1020
  // 存活/版本:外部 watchdog 与运维只靠这些判断「活没活」
996
- "ok", "status", "status_reasons", "version", "version_role", "api_version", "transport", "uptime", "startedAt",
1021
+ "ok", "status", "status_reasons", "version", "version_source", "version_role", "api_version", "transport", "uptime", "startedAt",
997
1022
  // 规模与健康度聚合(不含拓扑明细)
998
1023
  "sessions_count", "sse_connections", "mcp_inflight", "mcp_inflight_peak",
999
1024
  // 事件循环停顿是**一个对象**(event_loop: {max_gap_ms, recent_stalls,…}),
@@ -1134,6 +1159,11 @@ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
1134
1159
  why: "粗粒度版本号;精确字节身份由 git_commit 承担,而它不匿名",
1135
1160
  identity_class: "declaration",
1136
1161
  },
1162
+ version_source: {
1163
+ class: "gauge",
1164
+ granularity: "label",
1165
+ why: "同一字段的**仲裁位**:说明 version 是 env 注入(standalone 二进制)还是磁盘 package.json;不暴露路径或提交",
1166
+ },
1137
1167
  version_role: {
1138
1168
  class: "gauge",
1139
1169
  granularity: "label",
@@ -1164,7 +1194,14 @@ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
1164
1194
  limits: { class: "gauge", granularity: "label" },
1165
1195
  capabilities: { class: "gauge", granularity: "label" },
1166
1196
  // ⚠️ 例外:**形似启动快照,但会变** —— 它的全部价值在于变,标成快照会毁掉它。
1167
- served_at: { class: "gauge", granularity: "instant" },
1197
+ served_at: {
1198
+ class: "gauge",
1199
+ granularity: "instant",
1200
+ // 2026-10-31 —— granularity=instant 的字段必须写出**反事实**(外部复核 (c):
1201
+ // 「判法应改为对『这个值变了,世界上什么变了』做反事实询问」):
1202
+ // 它变的不是世界,是**这一次读取的时刻**;所以它只能当窗口端点,不能当「新鲜度」。
1203
+ why: "这一次读取的服务端时刻:变了不代表 Hub 状态变化,只代表又问了一次;用作窗口右端,不证明新鲜",
1204
+ },
1168
1205
  build_identified: {
1169
1206
  class: "gauge",
1170
1207
  granularity: "verdict",
@@ -3534,6 +3571,7 @@ return Bun.serve({
3534
3571
  status: statusReasons.length === 0 ? "ok" : "degraded",
3535
3572
  status_reasons: statusReasons,
3536
3573
  version: SERVER_VERSION,
3574
+ version_source: SERVER_VERSION_SOURCE,
3537
3575
  // 2026-10-31 —— **version 是部署标签,不是代码指纹**(生产实例:4 分钟内 version 变、
3538
3576
  // buildCommit 一字未变,同 commit 重新打包)。
3539
3577
  // ⇒ 任何以 version 为键的巡检/回滚检测都会假跳或永远不跳。