@sleep2agi/commhub-server 0.9.0-preview.32 → 0.9.0-preview.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.32",
+  "version": "0.9.0-preview.33",
   "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",

package/src/create-node-tool-schema.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+type ToolHandler = (args: any) => Promise<any> | any;
+
+function captureSchemas(): Record<string, Record<string, any>> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const schemas: Record<string, Record<string, any>> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, desc: string, schema: any, handler: ToolHandler) => {
+    schemas[name] = schema;
+    return origTool(name, desc, schema, handler);
+  };
+  registerTools(server, undefined, null, "u_schema_test", "schema-test", false, null);
+  return schemas;
+}
+
+describe("create_node MCP schema", () => {
+  test("model is optional on daemon create specs but empty strings stay invalid", () => {
+    const schemas = captureSchemas();
+    const nodeSpec = schemas.create_node.node_spec;
+
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+    }).success).toBe(true);
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+      model: null,
+    }).success).toBe(true);
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+      model: "",
+    }).success).toBe(false);
+  });
+});

package/src/create-node-validate.test.ts

@@ -169,6 +169,16 @@ describe("buildAnetArgs (§4.2.2 F2 — fully validated argv)", () => {
     expect(args).toContain("--permission-mode");
     expect(args[args.indexOf("--permission-mode") + 1]).toBe("plan");
   });
+  test("omitted model is allowed and does not emit --model", () => {
+    const args = buildAnetArgs({
+      name: "x", runtime: "codex-sdk",
+      flags: { permissionMode: "plan" },
+    });
+    expect(args).toEqual(["node", "create", "x", "--runtime", "codex-sdk", "--permission-mode", "plan"]);
+  });
+  test("empty model is still rejected", () => {
+    expect(() => buildAnetArgs({ name: "x", runtime: "codex-sdk", model: "" })).toThrow(ValidationError);
+  });
   test("rejects bad name with shell metachar", () => {
     expect(() => buildAnetArgs({ name: ";rm -rf /", runtime: "claude-agent-sdk", model: "x" })).toThrow(ValidationError);
   });

package/src/create-node-validate.ts

@@ -46,7 +46,8 @@ export function validateRuntime(s: unknown): asserts s is Runtime {
   }
 }
 
-export function validateModel(s: unknown): asserts s is string {
+export function validateModel(s: unknown): asserts s is string | undefined | null {
+  if (s === undefined || s === null) return;
   if (typeof s !== "string" || s.length === 0 || s.length > 100 || !MODEL_RE.test(s)) {
     throw new ValidationError("model_invalid", { value: typeof s === "string" ? s.slice(0, 80) : typeof s });
   }
@@ -173,7 +174,7 @@ export function validateChannelsP1(channels: unknown): void {
 export interface NodeSpec {
   name: string;
   runtime: Runtime;
-  model: string;
+  model?: string | null;
   flags?: Record<string, unknown>;
   channels?: unknown;
 }
@@ -192,7 +193,8 @@ export function buildAnetArgs(spec: NodeSpec): string[] {
   validateModel(spec.model);
   validateChannelsP1(spec.channels);
 
-  const args: string[] = ["node", "create", spec.name, "--runtime", spec.runtime, "--model", spec.model];
+  const args: string[] = ["node", "create", spec.name, "--runtime", spec.runtime];
+  if (spec.model) args.push("--model", spec.model);
   if (spec.flags && typeof spec.flags === "object") {
     for (const [k, v] of Object.entries(spec.flags)) {
       if (!(FLAG_KEYS as readonly string[]).includes(k)) {

package/src/db.ts

@@ -543,7 +543,7 @@ db.exec(`
     child_name        TEXT NOT NULL,
     network_id        TEXT NOT NULL,
     runtime           TEXT NOT NULL,
-    model             TEXT NOT NULL,
+    model             TEXT,
     flags_json        TEXT NOT NULL,
     env_keys          TEXT NOT NULL,
     status            TEXT NOT NULL,
@@ -560,6 +560,63 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_ncr_network ON node_create_requests(network_id);
   CREATE INDEX IF NOT EXISTS idx_ncr_child_name ON node_create_requests(child_name);
 `);
+function migrateNodeCreateRequestsModelNullable() {
+  if (db.dialect === "postgres") {
+    try { db.exec("ALTER TABLE node_create_requests ALTER COLUMN model DROP NOT NULL"); } catch {}
+    return;
+  }
+
+  let needsRebuild = false;
+  try {
+    const createSql = db.get<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'node_create_requests'");
+    needsRebuild = !!createSql?.sql && /\bmodel\s+TEXT\s+NOT\s+NULL\b/i.test(createSql.sql);
+  } catch {}
+  if (!needsRebuild) return;
+
+  db.transaction(() => {
+    db.exec("DROP TABLE IF EXISTS node_create_requests_migrated");
+    db.exec(`
+      CREATE TABLE node_create_requests_migrated (
+        request_id        TEXT PRIMARY KEY,
+        daemon_node_id    TEXT NOT NULL,
+        child_name        TEXT NOT NULL,
+        network_id        TEXT NOT NULL,
+        runtime           TEXT NOT NULL,
+        model             TEXT,
+        flags_json        TEXT NOT NULL,
+        env_keys          TEXT NOT NULL,
+        status            TEXT NOT NULL,
+        error             TEXT,
+        child_token_id    TEXT,
+        created_at        INTEGER NOT NULL,
+        created_by_token  TEXT NOT NULL,
+        delivered_at      INTEGER,
+        acked_at          INTEGER,
+        child_node_id     TEXT
+      )
+    `);
+    db.exec(`
+      INSERT INTO node_create_requests_migrated (
+        request_id, daemon_node_id, child_name, network_id, runtime, model,
+        flags_json, env_keys, status, error, child_token_id, created_at,
+        created_by_token, delivered_at, acked_at, child_node_id
+      )
+      SELECT
+        request_id, daemon_node_id, child_name, network_id, runtime, model,
+        flags_json, env_keys, status, error, child_token_id, created_at,
+        created_by_token, delivered_at, acked_at, child_node_id
+      FROM node_create_requests
+    `);
+    db.exec("DROP TABLE node_create_requests");
+    db.exec("ALTER TABLE node_create_requests_migrated RENAME TO node_create_requests");
+  });
+}
+migrateNodeCreateRequestsModelNullable();
+db.exec(`
+  CREATE INDEX IF NOT EXISTS idx_ncr_daemon_status ON node_create_requests(daemon_node_id, status);
+  CREATE INDEX IF NOT EXISTS idx_ncr_network ON node_create_requests(network_id);
+  CREATE INDEX IF NOT EXISTS idx_ncr_child_name ON node_create_requests(child_name);
+`);
 try {
   // Single-flight per (daemon, child_name) — prevents racing dashboard
   // create on same name. Mirrors RFC-024 uniq_ncu_node_inflight.

package/src/desktop-message.test.ts

@@ -0,0 +1,222 @@
+// Desktop user push contract.
+//
+// Pins the new user-keyed SSE path and send_desktop_message MCP tool:
+// - user streams are keyed by networkId:userId, never alias
+// - ntok callers cannot cross network by supplying a foreign to_user_id/network_id
+// - target ambiguity/miss is fail-closed before audit/push
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import {
+  __resetSSEClientsForTest,
+  createUserEventStream,
+  pushUserEvent,
+} from "./push.js";
+
+const NET_A = "net_desktop_a";
+const NET_B = "net_desktop_b";
+const NODE_USER = "u_desktop_node_owner";
+const SENDER_USER = "u_desktop_sender";
+const TARGET_A = "u_desktop_target_a";
+const TARGET_B = "u_desktop_target_b";
+const TARGET_BOTH = "u_desktop_target_both";
+const ALL_USERS = [NODE_USER, SENDER_USER, TARGET_A, TARGET_B, TARGET_BOTH];
+
+type ToolHandler = (args: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE action = 'send_desktop_message' OR network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, `${u}_name`],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, SENDER_USER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, TARGET_B]);
+  const member = (userId: string, networkId: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [userId, networkId, role]);
+  member(NODE_USER, NET_A, "member");
+  member(SENDER_USER, NET_A, "owner");
+  member(TARGET_A, NET_A, "member");
+  member(TARGET_B, NET_B, "member");
+  member(TARGET_BOTH, NET_A, "member");
+  member(TARGET_BOTH, NET_B, "member");
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterEach(() => { __resetSSEClientsForTest(); });
+afterAll(cleanup);
+
+function buildHandlers(opts: { netId?: string | null; userId?: string | null; alias?: string | null; isNetwork?: boolean }) {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  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);
+  };
+  registerTools(
+    server,
+    undefined,
+    opts.netId ?? null,
+    opts.userId ?? null,
+    opts.alias ?? opts.userId ?? null,
+    opts.isNetwork ?? false,
+    "tok_desktop_test",
+  );
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Record<string, any>> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text);
+}
+
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 2_000,
+): Promise<Record<string, any>> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), deadline - Date.now()),
+      ),
+    ]);
+    if (result.done) throw new Error("SSE stream ended unexpectedly");
+    buf += decoder.decode(result.value, { stream: true });
+    const sep = buf.indexOf("\n\n");
+    if (sep === -1) continue;
+    const rawFrame = buf.slice(0, sep);
+    buf = buf.slice(sep + 2);
+    const dataLine = rawFrame.split("\n").find((l) => l.startsWith("data: "));
+    if (!dataLine) continue;
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+function auditCount() {
+  return db.get<{ n: number }>("SELECT COUNT(*) AS n FROM audit_log WHERE action = 'send_desktop_message'")?.n ?? 0;
+}
+
+describe("send_desktop_message", () => {
+  test("ntok caller can push to a user in the same bound network", async () => {
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      message: "desktop hello",
+      severity: "success",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.message_id).toStartWith("dm_");
+    expect(auditCount()).toBe(1);
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("desktop_message");
+    expect(evt.message_id).toBe(result.message_id);
+    expect(evt.message).toBe("desktop hello");
+    expect(evt.from).toBe("node-a");
+    expect(evt.network_id).toBe(NET_A);
+    expect(evt.user_id).toBe(TARGET_A);
+    expect(evt.scope).toBe("user");
+    await reader.cancel();
+  });
+
+  test("utok caller can push with explicit network_id to a member user", async () => {
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ userId: SENDER_USER, alias: "sender-user" });
+    const result = await call(tools.send_desktop_message, {
+      to_username: `${TARGET_A}_name`,
+      network_id: NET_A,
+      title: "Heads up",
+      message: "from user token",
+    });
+
+    expect(result.ok).toBe(true);
+    const evt = await readFrame(reader);
+    expect(evt.title).toBe("Heads up");
+    expect(evt.message).toBe("from user token");
+    expect(evt.network_id).toBe(NET_A);
+    await reader.cancel();
+  });
+
+  test("ntok caller cannot cross network with foreign network_id and to_user_id; no audit or push happens first", async () => {
+    const stream = createUserEventStream(NET_B, TARGET_B);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_B,
+      network_id: NET_B,
+      message: "must not cross",
+    });
+
+    expect(result).toEqual({ ok: false, error: "desktop_target_not_in_network", network_id: NET_A });
+    expect(auditCount()).toBe(0);
+
+    pushUserEvent(NET_B, TARGET_B, { type: "desktop_message", message_id: "marker_after_denied" });
+    expect((await readFrame(reader)).message_id).toBe("marker_after_denied");
+    await reader.cancel();
+  });
+
+  test("missing target is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, { message: "nobody" });
+    expect(result).toEqual({
+      ok: false,
+      error: "desktop_target_required",
+      message: "to_user_id or to_username is required",
+    });
+    expect(auditCount()).toBe(0);
+  });
+
+  test("conflicting to_user_id and to_username is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      to_username: `${TARGET_BOTH}_name`,
+      message: "conflict",
+    });
+    expect(result).toEqual({
+      ok: false,
+      error: "desktop_target_mismatch",
+      to_user_id: TARGET_A,
+      to_username: `${TARGET_BOTH}_name`,
+    });
+    expect(auditCount()).toBe(0);
+  });
+
+  test("unknown target is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_username: "not_a_real_user",
+      message: "lost",
+    });
+    expect(result).toEqual({ ok: false, error: "desktop_target_not_found", field: "to_username" });
+    expect(auditCount()).toBe(0);
+  });
+});

package/src/observer-avatar-http.test.ts

@@ -187,6 +187,81 @@ describe("#461 GET /events/network/:id — auth", () => {
   });
 });
 
+describe("GET /events/users/me — Desktop user stream auth", () => {
+  test("anonymous → 401", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`);
+    expect(res.status).toBe(401);
+  });
+
+  test("ntok is refused for user stream", async () => {
+    const minted = createNetworkTokenForNode(memberUserId, memberNetworkId, "desktop-ntok-probe");
+    expect(minted.ok).toBe(true);
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(minted.token!) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.error).toBe("user_token_required");
+  });
+
+  test("utok without network_id → 400", async () => {
+    const res = await fetch(`${BASE}/events/users/me`, { headers: auth(memberToken) });
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error).toBe("network_id required");
+  });
+
+  test("non-member utok → 403", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(outsiderToken) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.error).toBe("not a member of this network");
+  });
+
+  test("member utok → user stream connected frame keyed to authenticated user", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(memberToken) });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type") || "").toContain("text/event-stream");
+    const reader = res.body!.getReader();
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.user).toBe(true);
+    expect(connected.network_id).toBe(memberNetworkId);
+    expect(connected.user_id).toBe(memberUserId);
+    await reader.cancel();
+  });
+});
+
+describe("GET /api/messages — client inbox count", () => {
+  test("alias filter returns only that inbox and pending_count for unacked rows", async () => {
+    const selfAlias = `user-${memberUserId}`;
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, ?2, 'task', 'normal', 'unread self', 'agent-a', 0, ?3, datetime('now'))`,
+      [`msg_self_unread_${Date.now()}`, selfAlias, memberNetworkId],
+    );
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, ?2, 'task', 'normal', 'read self', 'agent-a', 1, ?3, datetime('now'))`,
+      [`msg_self_read_${Date.now()}`, selfAlias, memberNetworkId],
+    );
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, 'other-alias', 'task', 'normal', 'other inbox', 'agent-b', 0, ?2, datetime('now'))`,
+      [`msg_other_${Date.now()}`, memberNetworkId],
+    );
+
+    const res = await fetch(`${BASE}/api/messages?alias=${encodeURIComponent(selfAlias)}&network_id=${encodeURIComponent(memberNetworkId)}&limit=20`, {
+      headers: auth(memberToken),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(body.pending_count).toBe(1);
+    expect(body.messages.length).toBeGreaterThanOrEqual(2);
+    expect(body.messages.every((m: any) => m.to_alias === selfAlias)).toBe(true);
+    expect(body.messages.some((m: any) => m.content === "other inbox")).toBe(false);
+  });
+});
+
 describe("#461 observer receives third-party traffic summaries", () => {
   test("REST /api/task dispatch → observer gets new_task summary, no content", async () => {
     const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });

package/src/observer-push.test.ts

@@ -11,8 +11,10 @@ import {
   __resetSSEClientsForTest,
   createNetworkObserverStream,
   createSSEStream,
+  createUserEventStream,
   pushEvent,
   pushNetworkObserverEvent,
+  pushUserEvent,
 } from "./push";
 
 afterEach(() => {
@@ -174,3 +176,77 @@ describe("#461 network observer stream", () => {
     await reader2.cancel();
   });
 });
+
+describe("Desktop user SSE stream", () => {
+  test("user stream receives connected frame, then desktop_message", async () => {
+    const res = createUserEventStream("net_user_a", "u_user_a");
+    const reader = res.body!.getReader();
+
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.user).toBe(true);
+    expect(connected.network_id).toBe("net_user_a");
+    expect(connected.user_id).toBe("u_user_a");
+
+    pushUserEvent("net_user_a", "u_user_a", {
+      type: "desktop_message",
+      message_id: "dm_one",
+      from: "agent-a",
+      message: "hello",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("desktop_message");
+    expect(evt.message_id).toBe("dm_one");
+    expect(evt.from).toBe("agent-a");
+    expect(evt.message).toBe("hello");
+    expect(evt.network_id).toBe("net_user_a");
+    expect(evt.user_id).toBe("u_user_a");
+    expect(evt.scope).toBe("user");
+    await reader.cancel();
+  });
+
+  test("user stream is isolated from alias and observer key spaces", async () => {
+    const userRes = createUserEventStream("net_user_iso", "u_iso");
+    const userReader = userRes.body!.getReader();
+    await readFrame(userReader);
+
+    const sessionRes = createSSEStream("u_iso", "net_user_iso");
+    const sessionReader = sessionRes.body!.getReader();
+    await readFrame(sessionReader);
+
+    const observerRes = createNetworkObserverStream("net_user_iso");
+    const observerReader = observerRes.body!.getReader();
+    await readFrame(observerReader);
+
+    pushEvent("u_iso", { type: "alias_marker", marker: "alias" }, "net_user_iso");
+    pushNetworkObserverEvent("net_user_iso", { type: "observer_marker", marker: "observer" });
+    pushUserEvent("net_user_iso", "u_iso", { type: "desktop_message", marker: "user" });
+
+    expect((await readFrame(sessionReader)).marker).toBe("alias");
+    expect((await readFrame(observerReader)).marker).toBe("observer");
+    expect((await readFrame(userReader)).marker).toBe("user");
+
+    await userReader.cancel();
+    await sessionReader.cancel();
+    await observerReader.cancel();
+  });
+
+  test("same user and network fan out to multiple live clients; cancelling one leaves the other live", async () => {
+    const r1 = createUserEventStream("net_user_multi", "u_multi");
+    const r2 = createUserEventStream("net_user_multi", "u_multi");
+    const reader1 = r1.body!.getReader();
+    const reader2 = r2.body!.getReader();
+    await readFrame(reader1);
+    await readFrame(reader2);
+
+    pushUserEvent("net_user_multi", "u_multi", { type: "desktop_message", message_id: "dm_fanout_1" });
+    expect((await readFrame(reader1)).message_id).toBe("dm_fanout_1");
+    expect((await readFrame(reader2)).message_id).toBe("dm_fanout_1");
+
+    await reader1.cancel();
+    pushUserEvent("net_user_multi", "u_multi", { type: "desktop_message", message_id: "dm_fanout_2" });
+    expect((await readFrame(reader2)).message_id).toBe("dm_fanout_2");
+    await reader2.cancel();
+  });
+});

package/src/push.ts

@@ -109,6 +109,7 @@ function clientKey(sessionName: string, networkId?: string | null): string {
 // 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
@@ -123,6 +124,10 @@ 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
@@ -265,6 +270,15 @@ export function createNetworkObserverStream(networkId: string): Response {
   );
 }
 
+/** 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 },
+  );
+}
+
 function createStreamForKey(key: string, initialEvent: Record<string, unknown>): Response {
   const encoder = new TextEncoder();
   let client: SSEClient;
@@ -447,6 +461,34 @@ export function pushNetworkObserverEvent(
   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. */
+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);
+}
+
 export function __resetSSEClientsForTest(): void {
   for (const arr of clients.values()) {
     for (const c of arr) closeClient(c, "reset-for-test");

package/src/server.ts

@@ -6,7 +6,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
-import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
+import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { addNetworkScope, canRestWriteNetwork, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
@@ -871,6 +871,32 @@ return Bun.serve({
       return createNetworkObserverStream(observedNetId);
     }
 
+    // GET /events/users/me?network_id=... → Desktop/user-client stream.
+    // This is intentionally keyed by authenticated user_id, not alias.
+    // Desktop must use its utok_; ntok_ is a node credential and cannot
+    // subscribe to user channels.
+    if (url.pathname === "/events/users/me" && req.method === "GET") {
+      const authErr = requireAuth(req);
+      if (authErr) return authErr;
+      const token = requestToken(req);
+      if (!token?.startsWith("utok_")) {
+        return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
+      }
+      const authCtx = resolveRequestAuth(req);
+      if (!authCtx) {
+        return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 403 }));
+      }
+      const networkId = url.searchParams.get("network_id");
+      if (!networkId) {
+        return withCors(req, Response.json({ ok: false, error: "network_id required" }, { status: 400 }));
+      }
+      const role = getUserNetworkRole(authCtx.userId, networkId);
+      if (!role) {
+        return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
+      }
+      return createUserEventStream(networkId, authCtx.userId);
+    }
+
     // ── SSE push: Agent 实时接收任务推送 ──
     // GET /events/知识哥 → 保持长连接，send_task 时秒推
     const eventsMatch = url.pathname.match(/^\/events\/(.+)$/);
@@ -2599,13 +2625,27 @@ return Bun.serve({
     if (url.pathname === "/api/messages") {
       const limit = Math.min(Number(url.searchParams.get("limit")) || 100, 500);
       const since = url.searchParams.get("since") ?? new Date(Date.now() - 3600000).toISOString().replace("T", " ").slice(0, 19);
+      const alias = url.searchParams.get("alias")?.trim() || null;
       const params: any[] = [since];
-      let sql = "SELECT id, session_name as to_alias, from_session as from_alias, type, priority, content, created_at, network_id FROM inbox WHERE created_at >= ?1";
+      let sql = "SELECT id, session_name as to_alias, from_session as from_alias, type, priority, content, acked, created_at, network_id FROM inbox WHERE created_at >= ?1";
+      if (alias) {
+        params.push(alias);
+        sql += ` AND session_name = ?${params.length}`;
+      }
       sql = addNetworkScope(sql, params, restScope);
       sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
       const rows = db.all(sql, ...params);
-      return withCors(req, Response.json({ ok: true, messages: rows }));
+
+      let pendingCount: number | undefined;
+      if (alias) {
+        const countParams: any[] = [alias];
+        let countSql = "SELECT COUNT(*) AS cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
+        countSql = addNetworkScope(countSql, countParams, restScope);
+        pendingCount = db.get<{ cnt: number }>(countSql, ...countParams)?.cnt ?? 0;
+      }
+
+      return withCors(req, Response.json({ ok: true, messages: rows, ...(alias ? { pending_count: pendingCount ?? 0 } : {}) }));
     }
 
     // ── REST: stats summary ──

package/src/tools.ts

@@ -4,7 +4,7 @@ import { z } from "zod/v4";
 import { parseAliasFilter } from "./alias-filter.js";
 import { createHash } from "node:crypto";
 import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken, syncScheduledRunForTask } from "./db.js";
-import { getSSEStats, hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
+import { getSSEStats, hasSubscribers, pushEvent, pushNetworkObserverEvent, pushUserEvent } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { canRestWriteNetwork, getUserNetworkIds, singleNetworkId } from "./network-scope.js";
@@ -2181,6 +2181,97 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     }
   );
 
+  server.tool(
+    "send_desktop_message",
+    "Push a message to a user's active Desktop/web clients in one network. Targets user identity, not node alias.",
+    {
+      to_user_id: z.string().min(1).max(200).optional().describe("Target user_id. Mutually checked with to_username when both are supplied."),
+      to_username: z.string().min(1).max(50).optional().describe("Target username. Mutually checked with to_user_id when both are supplied."),
+      title: z.string().max(200).optional(),
+      message: z.string().min(1).max(10000),
+      severity: z.enum(["info", "success", "warning", "error"]).optional().default("info"),
+      kind: z.string().min(1).max(80).optional().default("agent_message"),
+      meta: z.record(z.unknown()).optional(),
+      from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens; ntok stays bound to its network)."),
+    },
+    async ({ to_user_id, to_username, title, message, severity, kind, meta, from_session: _fromIn, network_id: netId }) => {
+      const fromMismatch = fromIdentityMismatchReply(_fromIn);
+      if (fromMismatch) return fromMismatch;
+      const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
+      if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
+      if (!effectiveNetId) return writeDeniedReply(effectiveNetId, "write");
+
+      if (!to_user_id && !to_username) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_required", message: "to_user_id or to_username is required" }) }] };
+      }
+
+      const byId = to_user_id
+        ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE user_id = ?1", to_user_id)
+        : null;
+      const byName = to_username
+        ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE username = ?1", to_username)
+        : null;
+
+      if (to_user_id && !byId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_not_found", field: "to_user_id" }) }] };
+      }
+      if (to_username && !byName) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_not_found", field: "to_username" }) }] };
+      }
+      if (byId && byName && byId.user_id !== byName.user_id) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_mismatch", to_user_id, to_username }) }] };
+      }
+
+      const target = byId ?? byName;
+      if (!target) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_not_found" }) }] };
+      }
+
+      const targetRole = getUserNetworkRole(target.user_id, effectiveNetId);
+      if (!targetRole) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "desktop_target_not_in_network", network_id: effectiveNetId }) }] };
+      }
+
+      const messageId = `dm_${uuidv4()}`;
+      const event = {
+        type: "desktop_message",
+        message_id: messageId,
+        kind,
+        from: from_session,
+        title: title || null,
+        message,
+        severity,
+        created_at: new Date().toISOString(),
+        ...(meta && Object.keys(meta).length ? { meta } : {}),
+      };
+
+      db.run(
+        `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+         VALUES (?1, ?2, 'send_desktop_message', 'user', ?3, ?4, ?5)`,
+        [
+          enforceUserId || null,
+          callerAlias || null,
+          target.user_id,
+          JSON.stringify({
+            message_id: messageId,
+            to_username: target.username,
+            from: from_session,
+            severity,
+            kind,
+            title: title || null,
+            meta_keys: meta && typeof meta === "object" ? Object.keys(meta) : [],
+          }),
+          effectiveNetId,
+        ],
+      );
+      pushUserEvent(effectiveNetId, target.user_id, event);
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, message_id: messageId, delivered_to_user_id: target.user_id, network_id: effectiveNetId }) }] };
+    },
+  );
+
   server.tool(
     "broadcast",
     "Send a message to multiple sessions.",
@@ -2886,7 +2977,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       node_spec: z.object({
         name: z.string().min(1).max(64),
         runtime: z.string().min(1).max(64),
-        model: z.string().min(1).max(100),
+        model: z.string().min(1).max(100).optional().nullable(),
         flags: z.record(z.unknown()).optional(),
         env_refs: z.array(z.string().max(64)).optional(),
         channels: z.array(z.unknown()).optional(),
@@ -3042,7 +3133,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
          VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'pending', ?9, ?10, ?11)`,
         [
           requestId, daemon_node_id, node_spec.name, networkIdForChild,
-          node_spec.runtime, node_spec.model, JSON.stringify(node_spec.flags || {}),
+          node_spec.runtime, node_spec.model ?? null, JSON.stringify(node_spec.flags || {}),
           JSON.stringify(envKeys), childTokenId, Date.now(), callerTokenId || "unknown",
         ],
       );
@@ -3062,7 +3153,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           daemon_node_id,
           child_name: node_spec.name,
           runtime: node_spec.runtime,
-          model: node_spec.model,
+          model: node_spec.model ?? null,
           flag_keys: Object.keys(node_spec.flags || {}),
           env_keys: envKeys,
         },
@@ -3126,7 +3217,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "env_blob_unavailable" }) }] };
       }
       // Hydrate spec from row.
-      const specRow = db.get<{ child_name: string; runtime: string; model: string; flags_json: string }>(
+      const specRow = db.get<{ child_name: string; runtime: string; model: string | null; flags_json: string }>(
         `SELECT child_name, runtime, model, flags_json FROM node_create_requests WHERE request_id = ?1`,
         request_id,
       );