@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.100

package/src/project-viewer-can-http.test.ts

@@ -0,0 +1,114 @@
+// GET /api/requirements/projects 的每行 viewer_can.edit(app 任务页审计 L13)—— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// 客户端据此只在新建 / 挪卡的项目下拉里列「能编辑」的项目。判据必须与真写卡时一致,所以这里对每个项目
+// 都真建一张卡,断言「viewer_can.edit === 建卡成功」,而不是另抄一份规则来比。
+//   admin —— Hub 管理员 + 网络 owner:未归档项目全 true,归档的 false(projectRef 拒归档)
+//   alice —— scoped 成员:P1 只看 → false,P2 可改 → true(只列得到这两个)
+//   carol —— task_access='all' 的成员:未归档全 true
+//   vic   —— scoped viewer,P3 只看:false(viewer 本来就不能写卡)
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-project-viewer-can-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ProjViewerCanPassw0rd!x";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+const P: Record<string, string> = {};
+
+type R = { status: number; body: any };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+const projects = async (who: string) => {
+  const r = await send(U[who].token, "GET", `/api/requirements/projects?network_id=${NET}`);
+  expect(r.status).toBe(200);
+  return Object.fromEntries((r.body.projects as any[]).map((p) => [p.name, p]));
+};
+
+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(`pvc_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  U.admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.admin.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 send(U.admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await send("", "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.alice = await mk(`pvc_alice_${stamp}`, "member");
+  U.carol = await mk(`pvc_carol_${stamp}`, "member");
+  U.vic = await mk(`pvc_vic_${stamp}`, "viewer");
+  db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, U.carol.id]);
+
+  for (const name of ["pvc-P1", "pvc-P2", "pvc-P3", "pvc-P4"]) {
+    const r = await send(U.admin.token, "POST", "/api/requirements/projects", { network_id: NET, name });
+    expect(r.status).toBe(201);
+    P[name] = r.body.project.id;
+  }
+  expect((await send(U.admin.token, "PATCH", `/api/requirements/projects/${P["pvc-P4"]}?network_id=${NET}`, { archived: true })).status).toBe(200);
+  expect((await send(U.admin.token, "PUT", `/api/networks/${NET}/members/${U.alice.id}/task-grants`, { task_access: "scoped", project_grants: [{ project_id: P["pvc-P1"] }, { project_id: P["pvc-P2"], can_edit: true }] })).status).toBe(200);
+  expect((await send(U.admin.token, "PUT", `/api/networks/${NET}/members/${U.vic.id}/task-grants`, { task_access: "scoped", project_grants: [P["pvc-P3"]] })).status).toBe(200);
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/requirements/projects 的 viewer_can.edit", () => {
+  test("每个调用者的取值", async () => {
+    const edit = (rows: Record<string, any>) => Object.fromEntries(Object.entries(rows).map(([n, p]) => [n, p.viewer_can?.edit]));
+    expect(edit(await projects("admin"))).toEqual({ "pvc-P1": true, "pvc-P2": true, "pvc-P3": true, "pvc-P4": false });
+    expect(edit(await projects("carol"))).toEqual({ "pvc-P1": true, "pvc-P2": true, "pvc-P3": true, "pvc-P4": false });
+    expect(edit(await projects("alice"))).toEqual({ "pvc-P1": false, "pvc-P2": true });
+    expect(edit(await projects("vic"))).toEqual({ "pvc-P3": false });
+  });
+
+  test("只加字段:其余键与之前逐字相同", async () => {
+    const row = (await projects("alice"))["pvc-P2"];
+    expect(Object.keys(row).sort()).toEqual(["archived", "color", "createdAt", "id", "name", "sort", "viewer_can"]);
+    expect(Object.keys(row.viewer_can)).toEqual(["edit"]);
+  });
+
+  test("与真写卡一致:edit === 往这个项目建卡成功", async () => {
+    let checked = 0;
+    for (const who of ["admin", "carol", "alice", "vic"]) {
+      for (const [name, p] of Object.entries(await projects(who))) {
+        const r = await send(U[who].token, "POST", "/api/requirements", { network_id: NET, name: `pvc-card-${who}-${name}`, project_id: p.id });
+        expect({ who, name, created: r.status === 201 }).toEqual({ who, name, created: p.viewer_can.edit });
+        checked++;
+      }
+    }
+    expect(checked).toBe(11);
+  });
+
+  test("授权改成可编辑后立即反映", async () => {
+    expect((await send(U.admin.token, "PUT", `/api/networks/${NET}/members/${U.alice.id}/task-grants`, { project_grants: [{ project_id: P["pvc-P1"], can_edit: true }, { project_id: P["pvc-P2"], can_edit: true }] })).status).toBe(200);
+    expect((await projects("alice"))["pvc-P1"].viewer_can.edit).toBe(true);
+  });
+});

package/src/push.ts

@@ -84,6 +84,40 @@ type SSEClient = {
   keepaliveTimer?: ReturnType<typeof setInterval>;
   /** Stable key for log/diagnostic context. */
   key: string;
+  /** 多用户 Agent 权限:订阅者的 user_id(有的话),权限变化时据此断开重连重新鉴权。 */
+  subscriberUserId?: string;
+  /** 只推满足条件的事件(受限成员的网络观察流用)。缺省 = 全推。 */
+  eventFilter?: (event: Record<string, unknown>) => boolean;
+  /** #507 — set only on a node's OWN task stream (/events/<alias> opened with the
+   *  node token bound to that alias). Dashboard monitors / master-token streams on
+   *  the same key leave it unset and are never superseded or counted here. */
+  node?: NodeSubscriberInfo;
+};
+
+/** #507 — what the Hub knows about one node-scoped SSE connection. No tokens. */
+export type NodeSubscriberInfo = {
+  nodeId: string | null;
+  /** Optional, client-supplied (`X-Anet-Instance-Id` header or `?instance_id=`).
+   *  null = the client did not say (every agent-node released so far). */
+  instanceId: string | null;
+  remote: string | null;
+  userAgent: string | null;
+  connectedAt: number;
+};
+
+/** #507 — one supersede of a node-scoped connection by a newer one. */
+export type NodeIdentityConflict = {
+  key: string;
+  alias: string;
+  networkId: string | null;
+  nodeId: string | null;
+  /** "same" = both connections carried the same instance id (a reconnect of the
+   *  same process; not reported as a conflict). "different" = both carried ids and
+   *  they differ (two live copies). "unknown" = at least one carried none. */
+  instanceMatch: "same" | "different" | "unknown";
+  superseded: NodeSubscriberInfo;
+  current: NodeSubscriberInfo;
+  at: number;
 };
 
 // 一个 session 可能有多个 SSE 连接（重连时短暂并存）
@@ -97,6 +131,45 @@ function clientKey(sessionName: string, networkId?: string | null): string {
   return `${networkId || "global"}:${sessionName}`;
 }
 
+// ── #461 network observer channels ───────────────────────────────────
+// Dashboard (or any network member) subscribes GET /events/network/:id
+// and receives SUMMARY events for ALL new_task / new_reply traffic in
+// that network — not just tasks it sent/received. Summary events carry
+// ids + routing metadata only, never task/reply content.
+//
+// Key scheme: leading NUL byte makes an observer key impossible to
+// forge from the session scheme above (`${networkId}:${sessionName}`)
+// for any networkId the hub itself issues (net_* / "global"). Only a
+// master-token caller could even inject a NUL into network_id via the
+// legacy ?network_id= path, and master token is root already.
+const OBSERVER_KEY_PREFIX = "\u0000netobs:";
+const USER_KEY_PREFIX = "\u0000user:";
+
+/** Printable form of `OBSERVER_KEY_PREFIX` — the shape emitted by
+ *  `printableKey()` (below) and therefore the shape callers see via
+ *  `getSSEStats().sessions`. Exported so downstream consumers (e.g.
+ *  `/health` filter in server.ts) key off the same literal instead of
+ *  each side re-writing the escape sequence — CR3 audit 4703b0e7
+ *  found server.ts had `"netobs:"` (no `\\0`) which never matched and
+ *  silently over-filtered observer keys. */
+export const PRINTABLE_OBSERVER_KEY_PREFIX = "\\0netobs:";
+
+function observerKey(networkId: string): string {
+  return `${OBSERVER_KEY_PREFIX}${networkId}`;
+}
+
+function userKey(networkId: string, userId: string): string {
+  return `${USER_KEY_PREFIX}${networkId}:${userId}`;
+}
+
+/** Render a client key for logs / stats. Observer keys embed a raw NUL
+ *  byte (collision guard above); printing that verbatim makes grep treat
+ *  hub logs as binary and breaks log shippers, and getSSEStats feeds
+ *  /health. Display as a visible "\\0" escape instead. */
+function printableKey(key: string): string {
+  return key.split("\u0000").join("\\0");
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // Close + dispatch helpers
 // ─────────────────────────────────────────────────────────────────────
@@ -114,7 +187,14 @@ function closeClient(client: SSEClient, reason: string): void {
     // Already closed by the runtime, or controller errored. Either way
     // we're done with it.
   }
-  console.log(`[${ts()}] SSE ✕ ${client.key} closed (reason=${reason})`);
+  console.log(`[${ts()}] SSE ✕ ${printableKey(client.key)} closed (reason=${reason})`);
+  if (client.node && reason !== SUPERSEDED_REASON && !hasLiveNodeClient(client.key)) {
+    notifyNodeDrained(client.key);
+  }
+  if (isUserStreamClient(client)) {
+    touchUserSeen(client.subscriberUserId!);
+    if (!isUserOnline(client.subscriberUserId!)) notifyPresence(client.subscriberUserId!, false);
+  }
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -213,10 +293,144 @@ function ensureLivenessSweep(): void {
 // Public API
 // ─────────────────────────────────────────────────────────────────────
 
-/** 创建 SSE Response 并注册到 clients map */
-export function createSSEStream(sessionName: string, networkId?: string | null): Response {
+/** 创建 SSE Response 并注册到 clients map。
+ *  #507 — pass `opts.node` only for a node's own stream (node token bound to this
+ *  alias); such a stream supersedes any older node-scoped stream on the same key. */
+export function createSSEStream(
+  sessionName: string,
+  networkId?: string | null,
+  opts: { node?: Omit<NodeSubscriberInfo, "connectedAt"> } = {},
+): Response {
+  return createStreamForKey(
+    clientKey(sessionName, networkId),
+    { type: "connected", session: sessionName, network_id: networkId ?? null },
+    opts.node ? { node: { ...opts.node, connectedAt: Date.now() } } : {},
+  );
+}
+
+// ── #507 node identity conflict: at most ONE node-scoped subscriber per key ──
+//
+// Before #507 every connection on `${networkId}:${alias}` received every push. A
+// node directory copied verbatim (same node token, same alias) and started
+// elsewhere therefore got every new_task twice — both copies ran it — and either
+// copy's shutdown report_status(offline) marked the node offline while the other
+// was still connected.
+//
+// Policy: NEWEST CONNECTION WINS. Measured reconnect path (agent-node connectSSE →
+// superviseChild): a restarted process's old socket is closed by the OS, so a
+// legit restart never overlaps its own previous stream; an overlap only happens
+// with (a) a half-open ghost the Hub has not reaped yet (up to STUCK_CLOSE_MS) or
+// (b) a second live copy. In (a) the new connection is the real one — keeping the
+// old would park tasks on a dead socket — so the newest must win. In (b) the
+// loser reconnects ~1 s later and wins back: the copies flap, which is loud
+// (log + node_identity_conflict event + /api/stats/sse) instead of silently
+// double-executing. An "only if both alive > N s" rule cannot tell (a) from (b):
+// a ghost looks alive to the Hub until it is reaped.
+export const SUPERSEDED_REASON = "superseded_by_new_connection";
+const REPLACED_REASON = "replaced_by_reconnect";
+
+let nodeConflictListener: ((c: NodeIdentityConflict) => void) | null = null;
+let nodeDrainedListener: ((alias: string, networkId: string | null) => void) | null = null;
+
+/** Called for every supersede whose instances are not provably the same process. */
+export function onNodeIdentityConflict(cb: ((c: NodeIdentityConflict) => void) | null): void {
+  nodeConflictListener = cb;
+}
+
+/** Called when the LAST node-scoped subscriber of a key goes away (not when it is
+ *  superseded — the newer connection is still there). */
+export function onNodeSubscribersDrained(cb: ((alias: string, networkId: string | null) => void) | null): void {
+  nodeDrainedListener = cb;
+}
+
+function splitClientKey(key: string): { alias: string; networkId: string | null } {
+  const i = key.indexOf(":");
+  const net = key.slice(0, i);
+  return { alias: key.slice(i + 1), networkId: net === "global" ? null : net };
+}
+
+function hasLiveNodeClient(key: string): boolean {
+  return (clients.get(key) ?? []).some((c) => !c.closed && !!c.node);
+}
+
+function notifyNodeDrained(key: string): void {
+  if (!nodeDrainedListener) return;
+  const { alias, networkId } = splitClientKey(key);
+  try { nodeDrainedListener(alias, networkId); } catch (e: any) {
+    console.log(`[${ts()}] node drained listener failed: ${e?.message || e}`);
+  }
+}
+
+/** Is a node-scoped (node-token) subscriber connected on this alias right now? */
+export function hasNodeSubscriber(sessionName: string, networkId?: string | null): boolean {
+  return hasLiveNodeClient(clientKey(sessionName, networkId));
+}
+
+/** Keep only `keep` among the node-scoped clients of `key`; close the others with
+ *  a final `node_connection_superseded` frame. Dashboard monitors are untouched. */
+function enforceSingleNodeSubscriber(key: string, keep: SSEClient): void {
+  const arr = clients.get(key);
+  if (!arr || !keep.node) return;
+  for (const old of arr) {
+    if (old === keep || old.closed || !old.node) continue;
+    const a = old.node.instanceId, b = keep.node.instanceId;
+    const instanceMatch: NodeIdentityConflict["instanceMatch"] = a && b ? (a === b ? "same" : "different") : "unknown";
+    const reason = instanceMatch === "same" ? REPLACED_REASON : SUPERSEDED_REASON;
+    tryEnqueueBytes(old, old.encoder.encode(`data: ${JSON.stringify({
+      type: "node_connection_superseded",
+      reason,
+      instance_match: instanceMatch,
+      // The newer connection's network origin, so the loser's log says WHERE the
+      // other copy runs. Never a token.
+      by: { instance_id: keep.node.instanceId, remote: keep.node.remote },
+    })}\n\n`));
+    closeClient(old, reason);
+    if (instanceMatch !== "same" && nodeConflictListener) {
+      const { alias, networkId } = splitClientKey(key);
+      try {
+        nodeConflictListener({
+          key: printableKey(key), alias, networkId,
+          nodeId: keep.node.nodeId ?? old.node.nodeId,
+          instanceMatch, superseded: old.node, current: keep.node, at: Date.now(),
+        });
+      } catch (e: any) {
+        console.log(`[${ts()}] node conflict listener failed: ${e?.message || e}`);
+      }
+    }
+  }
+  pruneClosed(key);
+}
+
+/** #461 — 创建网络级观察者 SSE Response（dashboard 观察第三方流量）。
+ *  Shares the exact same registration / backpressure / liveness
+ *  machinery as session streams; only the key scheme differs. */
+export function createNetworkObserverStream(
+  networkId: string,
+  opts: { subscriberUserId?: string; eventFilter?: (event: Record<string, unknown>) => boolean } = {},
+): Response {
+  return createStreamForKey(
+    observerKey(networkId),
+    { type: "connected", observer: true, network_id: networkId },
+    opts,
+  );
+}
+
+/** Desktop/user client SSE stream. Keyed by authenticated user_id, not
+ *  alias/session, so Desktop does not need to mint a pseudo node token. */
+export function createUserEventStream(networkId: string, userId: string): Response {
+  return createStreamForKey(
+    userKey(networkId, userId),
+    { type: "connected", user: true, network_id: networkId, user_id: userId },
+    { subscriberUserId: userId },
+  );
+}
+
+function createStreamForKey(
+  key: string,
+  initialEvent: Record<string, unknown>,
+  opts: { subscriberUserId?: string; eventFilter?: (event: Record<string, unknown>) => boolean; node?: NodeSubscriberInfo } = {},
+): Response {
   const encoder = new TextEncoder();
-  const key = clientKey(sessionName, networkId);
   let client: SSEClient;
 
   const stream = new ReadableStream<Uint8Array>({
@@ -227,17 +441,24 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
         stuckSince: null,
         closed: false,
         key,
+        ...(opts.subscriberUserId ? { subscriberUserId: opts.subscriberUserId } : {}),
+        ...(opts.eventFilter ? { eventFilter: opts.eventFilter } : {}),
+        ...(opts.node ? { node: opts.node } : {}),
       };
 
+      const presenceUser = isUserStreamClient(client) ? client.subscriberUserId! : null;
+      const wasOnline = presenceUser ? isUserOnline(presenceUser) : true;
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
-      console.log(`[${ts()}] SSE ← ${key} connected (${clients.get(key)!.length} clients)`);
+      if (presenceUser) touchUserSeen(presenceUser);
+      console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
+      if (client.node) enforceSingleNodeSubscriber(key, client);
 
       // Send initial connected frame through the backpressure guard so
       // even the first byte respects the contract.
       tryEnqueueBytes(
         client,
-        encoder.encode(`data: ${JSON.stringify({ type: "connected", session: sessionName, network_id: networkId ?? null })}\n\n`),
+        encoder.encode(`data: ${JSON.stringify(initialEvent)}\n\n`),
       );
 
       // Periodic keepalive doubles as a half-open probe — if the
@@ -249,6 +470,7 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
           return;
         }
         const result = tryEnqueueBytes(client, encoder.encode(`: keepalive\n\n`));
+        if (result === "ok" && isUserStreamClient(client)) touchUserSeen(client.subscriberUserId!);
         if (result === "dead") {
           // closeClient already cleared the timer; just make sure we
           // also prune from the map.
@@ -258,6 +480,8 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
       (client.keepaliveTimer as any)?.unref?.();
 
       ensureLivenessSweep();
+      // 在线状态的广播放在 connected 帧之后:订阅方先拿到自己的 connected,再看到别人的变化。
+      if (presenceUser && !wasOnline) notifyPresence(presenceUser, true);
     },
     cancel() {
       // Consumer side hangup — straightforward path, mark closed and
@@ -280,7 +504,12 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
 
   return new Response(stream, {
     headers: {
-      "Content-Type": "text/event-stream",
+      // #426: explicit charset so legacy Windows clients (PowerShell 5.1's
+      // Invoke-RestMethod / Invoke-WebRequest default to ISO-8859-1 when
+      // Content-Type omits the charset) decode UTF-8 payloads correctly.
+      // Hub itself was already writing clean UTF-8 bytes; the client-side
+      // 双重编码样式 mojibake was the header telling the client to guess.
+      "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       "Connection": "keep-alive",
     },
@@ -294,7 +523,7 @@ function pruneClosed(key: string): void {
   const alive = arr.filter((c) => !c.closed);
   if (alive.length === 0) {
     clients.delete(key);
-    console.log(`[${ts()}] SSE ✕ ${key} disconnected (0 remaining)`);
+    console.log(`[${ts()}] SSE ✕ ${printableKey(key)} disconnected (0 remaining)`);
   } else if (alive.length !== arr.length) {
     clients.set(key, alive);
   }
@@ -312,9 +541,16 @@ function rekeyClient(oldSessionName: string, newSessionName: string, networkId?:
   for (const c of oldClients) c.key = newKey;
 
   const existing = clients.get(newKey) || [];
-  clients.set(newKey, existing.concat(oldClients));
+  const merged = existing.concat(oldClients);
+  clients.set(newKey, merged);
   clients.delete(oldKey);
   console.log(`[${ts()}] SSE ↔ rekey ${oldKey} → ${newKey} (${oldClients.length} clients)`);
+  // #507 — a rename can merge two node-scoped streams onto one key; newest wins.
+  const nodeClients = merged.filter((c) => !c.closed && c.node);
+  if (nodeClients.length > 1) {
+    const newest = nodeClients.reduce((a, b) => (b.node!.connectedAt >= a.node!.connectedAt ? b : a));
+    enforceSingleNodeSubscriber(newKey, newest);
+  }
   return oldClients.length;
 }
 
@@ -327,6 +563,17 @@ eventBus.on("rename-committed", (event: RenameCommittedEvent) => {
 });
 
 /** 推送事件给指定 session 的所有 SSE 连接 */
+/** 这个 alias 上此刻是否真的有活着的 SSE 订阅者。
+ *
+ *  这是投递可达性的**实测**，区别于 resolveDeliveryTarget 里那个基于
+ *  last_seen_at 的**猜测**。一个安静但连着的会话（例如遵守「停发心跳」
+ *  规则的 MCP 会话）在时间戳判据下是 offline，在这里是 true。 */
+export function hasSubscribers(sessionName: string, networkId?: string | null): boolean {
+  const arr = clients.get(clientKey(sessionName, networkId));
+  if (!arr) return false;
+  return arr.some((c) => !c.closed);
+}
+
 export function pushEvent(sessionName: string, event: Record<string, unknown>, networkId?: string | null): void {
   const key = clientKey(sessionName, networkId ?? (event.network_id as string | null | undefined));
   const arr = clients.get(key);
@@ -347,11 +594,183 @@ export function pushEvent(sessionName: string, event: Record<string, unknown>, n
   if (needPrune) pruneClosed(key);
 }
 
+/** #461 — 推送网络级摘要事件给该网络的所有观察者连接。
+ *
+ *  Callers pass ROUTING METADATA ONLY (task_id / from / to / status /
+ *  priority / message_id) — never task or reply content. The event is
+ *  stamped with `network_id` + `scope: "network"` here so observers can
+ *  always tell which network the event belongs to and that it came from
+ *  the observer stream rather than their personal channel.
+ *
+ *  No-op when networkId is falsy: legacy null-network traffic has no
+ *  observer stream (the route requires an explicit network id). */
+export function pushNetworkObserverEvent(
+  networkId: string | null | undefined,
+  event: Record<string, unknown>,
+): void {
+  if (!networkId) return;
+  const key = observerKey(networkId);
+  const arr = clients.get(key);
+  if (!arr || arr.length === 0) return;
+
+  const data = `data: ${JSON.stringify({ ...event, network_id: networkId, scope: "network" })}\n\n`;
+  let needPrune = false;
+
+  for (const c of arr) {
+    if (c.closed) {
+      needPrune = true;
+      continue;
+    }
+    if (c.eventFilter) {
+      let pass = false;
+      try { pass = c.eventFilter(event); } catch { pass = false; }
+      if (!pass) continue;
+    }
+    const result = tryEnqueueBytes(c, c.encoder.encode(data));
+    if (result === "dead") needPrune = true;
+  }
+
+  if (needPrune) pruneClosed(key);
+}
+
+/** Push an event to every active Desktop/web client for one user in one
+ *  network. No-op for falsy network/user ids; auth must be enforced by
+ *  the caller before invoking this helper. */
+/** 这个用户此刻是否真的有活着的 SSE 订阅者。
+ *
+ *  与 alias 版 `hasSubscribers` 同形状：投递可达性的**实测**，
+ *  调用方据此把「送到了」和「没人听」区分开，而不是一律报成功。 */
+export function hasUserSubscribers(
+  networkId: string | null | undefined,
+  userId: string | null | undefined,
+): boolean {
+  if (!networkId || !userId) return false;
+  const arr = clients.get(userKey(networkId, userId));
+  if (!arr) return false;
+  return arr.some((c) => !c.closed);
+}
+
+export function pushUserEvent(
+  networkId: string | null | undefined,
+  userId: string | null | undefined,
+  event: Record<string, unknown>,
+): void {
+  if (!networkId || !userId) return;
+  const key = userKey(networkId, userId);
+  const arr = clients.get(key);
+  if (!arr || arr.length === 0) return;
+
+  const data = `data: ${JSON.stringify({ ...event, network_id: networkId, user_id: userId, scope: "user" })}\n\n`;
+  let needPrune = false;
+
+  for (const c of arr) {
+    if (c.closed) {
+      needPrune = true;
+      continue;
+    }
+    const result = tryEnqueueBytes(c, c.encoder.encode(data));
+    if (result === "dead") needPrune = true;
+  }
+
+  if (needPrune) pruneClosed(key);
+}
+
+// ── 人类成员在线状态(人员列表的在线点)──────────────────────────────────
+// 判据就是上面这张用户流(/events/users/me)注册表:此刻有活着的用户流 = 在线。按**用户**算,
+// 不按网络 —— 桌面端同一时刻只连当前网络的用户流,按网络算会把正在别的网络里的人画成离线。
+// last_seen 只在内存:连上、每次 keepalive 成功、断开时刷新。Hub 重启后清空(未知 = null,
+// 调用方不要把 null 画成「很久以前」)。
+
+const userLastSeen = new Map<string, number>();
+let presenceListener: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null = null;
+
+function isUserStreamClient(client: SSEClient): boolean {
+  return !!client.subscriberUserId && client.key.startsWith(USER_KEY_PREFIX);
+}
+
+function touchUserSeen(userId: string): void {
+  userLastSeen.set(userId, Date.now());
+}
+
+function isUserOnline(userId: string): boolean {
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    if (arr.some((c) => !c.closed && c.subscriberUserId === userId)) return true;
+  }
+  return false;
+}
+
+function lastSeenIso(userId: string): string | null {
+  const ms = userLastSeen.get(userId);
+  return ms === undefined ? null : new Date(ms).toISOString();
+}
+
+function notifyPresence(userId: string, online: boolean): void {
+  if (!presenceListener) return;
+  try {
+    presenceListener(userId, online, lastSeenIso(userId));
+  } catch (e: any) {
+    console.log(`[${ts()}] presence listener failed: ${e?.message || e}`);
+  }
+}
+
+/** 用户的第一条用户流连上 / 最后一条断开时回调(server.ts 用它向同网络成员推 member_presence)。 */
+export function onUserPresenceChange(cb: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null): void {
+  presenceListener = cb;
+}
+
+/** 一批用户此刻的在线状态。鉴权由调用方负责。 */
+export function getUserPresence(userIds: readonly string[]): Map<string, { online: boolean; last_seen_at: string | null }> {
+  const online = new Set<string>();
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    for (const c of arr) if (!c.closed && c.subscriberUserId) online.add(c.subscriberUserId);
+  }
+  const out = new Map<string, { online: boolean; last_seen_at: string | null }>();
+  for (const uid of userIds) out.set(uid, { online: online.has(uid), last_seen_at: lastSeenIso(uid) });
+  return out;
+}
+
+/** 推给某网络里所有连着用户流的人(可排除一个)。鉴权由调用方负责。 */
+export function pushUserEventToNetwork(networkId: string, event: Record<string, unknown>, exceptUserId?: string): number {
+  const prefix = `${USER_KEY_PREFIX}${networkId}:`;
+  const recipients: string[] = [];
+  for (const key of clients.keys()) {
+    if (!key.startsWith(prefix)) continue;
+    const uid = key.slice(prefix.length);
+    if (uid && uid !== exceptUserId) recipients.push(uid);
+  }
+  for (const uid of recipients) pushUserEvent(networkId, uid, event);
+  return recipients.length;
+}
+
+/**
+ * 多用户 Agent 权限:某用户在某网络的授权 / 成员资格变了,断开他在这个网络里**订阅时带了身份**
+ * 的流(网络观察流、用户流),客户端重连时按新权限重新鉴权。返回断开的条数。
+ * Agent 频道(/events/<alias>)受限成员本来就订阅不了,不需要这里处理。
+ */
+export function closeUserStreamsInNetwork(networkId: string, userId: string): number {
+  let closed = 0;
+  for (const key of [observerKey(networkId), userKey(networkId, userId)]) {
+    const arr = clients.get(key);
+    if (!arr) continue;
+    for (const c of arr) {
+      if (!c.closed && c.subscriberUserId === userId) {
+        closeClient(c, "access-changed");
+        closed++;
+      }
+    }
+    pruneClosed(key);
+  }
+  return closed;
+}
+
 export function __resetSSEClientsForTest(): void {
   for (const arr of clients.values()) {
     for (const c of arr) closeClient(c, "reset-for-test");
   }
   clients.clear();
+  userLastSeen.clear();
   if (livenessSweepTimer) {
     clearInterval(livenessSweepTimer);
     livenessSweepTimer = null;
@@ -365,7 +784,7 @@ export function getSSEStats(): { total: number; sessions: Record<string, number>
   for (const [name, arr] of clients) {
     const alive = arr.filter((c) => !c.closed);
     if (alive.length === 0) continue;
-    sessions[name] = alive.length;
+    sessions[printableKey(name)] = alive.length;
     total += alive.length;
   }
   return { total, sessions };