@sleep2agi/commhub-server 0.9.0-preview.21 → 0.9.0-preview.23

package/src/observer-push.test.ts

@@ -0,0 +1,176 @@
+// #461 — unit tests for the network observer SSE channel (push.ts).
+//
+// These tests read REAL bytes off the observer stream, so they are a
+// live gate: stub pushNetworkObserverEvent out to a no-op and every
+// "receives …" test below times out red. (Per 通信龙 2026-07-28 rule:
+// a test that stays green when the core function is emptied is a fake
+// gate.)
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  __resetSSEClientsForTest,
+  createNetworkObserverStream,
+  createSSEStream,
+  pushEvent,
+  pushNetworkObserverEvent,
+} from "./push";
+
+afterEach(() => {
+  __resetSSEClientsForTest();
+});
+
+type Frame = Record<string, any>;
+
+/** Read the next SSE data frame (skipping keepalive comments), with a
+ *  hard timeout so a silent stream fails the test instead of hanging. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 2_000,
+): Promise<Frame> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), remaining),
+      ),
+    ]);
+    if (result.done) throw new Error("stream ended before a data frame arrived");
+    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; // keepalive comment frame — keep reading
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+describe("#461 network observer stream", () => {
+  test("observer receives connected frame, then new_task summary with metadata only", async () => {
+    const res = createNetworkObserverStream("net_obs_a");
+    const reader = res.body!.getReader();
+
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.observer).toBe(true);
+    expect(connected.network_id).toBe("net_obs_a");
+
+    pushNetworkObserverEvent("net_obs_a", {
+      type: "new_task",
+      task_id: "task-123",
+      from: "sender-agent",
+      to: "receiver-agent",
+      status: "delivered",
+      priority: "high",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    expect(evt.task_id).toBe("task-123");
+    expect(evt.from).toBe("sender-agent");
+    expect(evt.to).toBe("receiver-agent");
+    expect(evt.status).toBe("delivered");
+    expect(evt.priority).toBe("high");
+    expect(evt.network_id).toBe("net_obs_a");
+    expect(evt.scope).toBe("network");
+    // Summary contract: NO content field, ever.
+    expect("content" in evt).toBe(false);
+    expect("task" in evt).toBe(false);
+    await reader.cancel();
+  });
+
+  test("observer receives new_reply summary", async () => {
+    const res = createNetworkObserverStream("net_obs_reply");
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    pushNetworkObserverEvent("net_obs_reply", {
+      type: "new_reply",
+      task_id: "parent-task",
+      message_id: "msg-9",
+      from: "worker",
+      to: "boss",
+      status: "completed",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    expect(evt.task_id).toBe("parent-task");
+    expect(evt.message_id).toBe("msg-9");
+    expect(evt.status).toBe("completed");
+    expect("content" in evt).toBe(false);
+    expect("text" in evt).toBe(false);
+    await reader.cancel();
+  });
+
+  test("events are network-isolated: observer on net B never sees net A traffic", async () => {
+    const resB = createNetworkObserverStream("net_obs_b");
+    const readerB = resB.body!.getReader();
+    await readFrame(readerB); // connected
+
+    // Push to A first, then a marker to B. Delivery per key is
+    // synchronous and ordered, so if B's next frame is the marker,
+    // the A event provably never reached B.
+    pushNetworkObserverEvent("net_obs_a2", { type: "new_task", task_id: "leaked" });
+    pushNetworkObserverEvent("net_obs_b", { type: "new_task", task_id: "marker-b" });
+
+    const evt = await readFrame(readerB);
+    expect(evt.task_id).toBe("marker-b");
+    await readerB.cancel();
+  });
+
+  test("observer stream is isolated from session channels (both directions)", async () => {
+    const sessionRes = createSSEStream("agent-x", "net_obs_c");
+    const sessionReader = sessionRes.body!.getReader();
+    await readFrame(sessionReader); // connected
+
+    const obsRes = createNetworkObserverStream("net_obs_c");
+    const obsReader = obsRes.body!.getReader();
+    await readFrame(obsReader); // connected
+
+    // Session push must NOT hit the observer; observer push must NOT
+    // hit the session. Marker technique as above.
+    pushEvent("agent-x", { type: "new_task", inbox_count: 1, marker: "to-session" }, "net_obs_c");
+    pushNetworkObserverEvent("net_obs_c", { type: "new_task", task_id: "to-observer" });
+
+    const sessionEvt = await readFrame(sessionReader);
+    expect(sessionEvt.marker).toBe("to-session");
+    expect("task_id" in sessionEvt).toBe(false);
+
+    const obsEvt = await readFrame(obsReader);
+    expect(obsEvt.task_id).toBe("to-observer");
+    expect("marker" in obsEvt).toBe(false);
+
+    await sessionReader.cancel();
+    await obsReader.cancel();
+  });
+
+  test("null / undefined networkId is a silent no-op", () => {
+    // Must not throw — legacy null-network traffic has no observer
+    // stream by design (documented in #461 / the PR).
+    expect(() => pushNetworkObserverEvent(null, { type: "new_task" })).not.toThrow();
+    expect(() => pushNetworkObserverEvent(undefined, { type: "new_task" })).not.toThrow();
+  });
+
+  test("multiple observers on the same network all receive the event", async () => {
+    const r1 = createNetworkObserverStream("net_obs_multi");
+    const r2 = createNetworkObserverStream("net_obs_multi");
+    const reader1 = r1.body!.getReader();
+    const reader2 = r2.body!.getReader();
+    await readFrame(reader1);
+    await readFrame(reader2);
+
+    pushNetworkObserverEvent("net_obs_multi", { type: "new_task", task_id: "fanout" });
+
+    expect((await readFrame(reader1)).task_id).toBe("fanout");
+    expect((await readFrame(reader2)).task_id).toBe("fanout");
+    await reader1.cancel();
+    await reader2.cancel();
+  });
+});

package/src/push.ts

@@ -97,6 +97,31 @@ 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:";
+
+function observerKey(networkId: string): string {
+  return `${OBSERVER_KEY_PREFIX}${networkId}`;
+}
+
+/** 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 +139,7 @@ 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})`);
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -215,8 +240,24 @@ function ensureLivenessSweep(): void {
 
 /** 创建 SSE Response 并注册到 clients map */
 export function createSSEStream(sessionName: string, networkId?: string | null): Response {
+  return createStreamForKey(
+    clientKey(sessionName, networkId),
+    { type: "connected", session: sessionName, network_id: networkId ?? null },
+  );
+}
+
+/** #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): Response {
+  return createStreamForKey(
+    observerKey(networkId),
+    { type: "connected", observer: true, network_id: networkId },
+  );
+}
+
+function createStreamForKey(key: string, initialEvent: Record<string, unknown>): Response {
   const encoder = new TextEncoder();
-  const key = clientKey(sessionName, networkId);
   let client: SSEClient;
 
   const stream = new ReadableStream<Uint8Array>({
@@ -231,13 +272,13 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
 
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
-      console.log(`[${ts()}] SSE ← ${key} connected (${clients.get(key)!.length} clients)`);
+      console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
 
       // 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
@@ -280,7 +321,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 +340,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);
   }
@@ -347,6 +393,40 @@ 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;
+    }
+    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");
@@ -365,7 +445,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 };

package/src/response-charset.test.ts

@@ -0,0 +1,130 @@
+// #426 unit tests for the withUtf8CharsetContentType helper — the
+// piece that rewrites text-y Content-Type headers to include
+// charset=utf-8 so legacy Windows clients don't fall back to
+// ISO-8859-1 decoding. The helper lives in server/src/index.ts;
+// to keep the test standalone we re-implement its pure semantics here
+// and assert those. Any drift between this pure copy and the
+// production helper is caught by the "identical semantics" test at
+// the bottom via a source grep.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Pure re-implementation — MUST match server/src/index.ts:withUtf8CharsetContentType.
+function withUtf8CharsetContentType(res: Response): Response {
+  const ct = res.headers.get("content-type");
+  if (!ct) return res;
+  if (/;\s*charset=/i.test(ct)) return res;
+  const trimmed = ct.trim();
+  if (
+    trimmed === "application/json" ||
+    trimmed.startsWith("text/") ||
+    trimmed.startsWith("application/json;") ||
+    trimmed === "application/ld+json" ||
+    trimmed === "application/xml"
+  ) {
+    res.headers.set("content-type", `${trimmed}; charset=utf-8`);
+  }
+  return res;
+}
+
+function makeRes(contentType: string | null, body = ""): Response {
+  return new Response(body, { headers: contentType ? { "content-type": contentType } : {} });
+}
+
+describe("withUtf8CharsetContentType — #426", () => {
+  test("appends charset to text/event-stream", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/event-stream"));
+    expect(res.headers.get("content-type")).toBe("text/event-stream; charset=utf-8");
+  });
+
+  test("appends charset to application/json (bare)", () => {
+    const res = withUtf8CharsetContentType(makeRes("application/json"));
+    expect(res.headers.get("content-type")).toBe("application/json; charset=utf-8");
+  });
+
+  test("appends charset to text/plain", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/plain"));
+    expect(res.headers.get("content-type")).toBe("text/plain; charset=utf-8");
+  });
+
+  test("appends charset to text/html", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/html"));
+    expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+  });
+
+  test("no-op when charset already present (case-insensitive)", () => {
+    for (const ct of [
+      "application/json; charset=utf-8",
+      "application/json;charset=UTF-8",
+      "text/event-stream;Charset=us-ascii",
+      "text/plain; CHARSET=iso-8859-1",
+    ]) {
+      const res = withUtf8CharsetContentType(makeRes(ct));
+      expect(res.headers.get("content-type")).toBe(ct);
+    }
+  });
+
+  test("no-op on binary types (opaque)", () => {
+    for (const ct of [
+      "application/octet-stream",
+      "image/png",
+      "image/jpeg",
+      "video/mp4",
+      "application/pdf",
+      "font/woff2",
+    ]) {
+      const res = withUtf8CharsetContentType(makeRes(ct));
+      expect(res.headers.get("content-type")).toBe(ct);
+    }
+  });
+
+  test("no-op when Content-Type header is absent entirely (returns as-is)", () => {
+    const res = withUtf8CharsetContentType(makeRes(null));
+    expect(res.headers.get("content-type")).toBeNull();
+  });
+
+  test("handles application/ld+json / application/xml", () => {
+    expect(withUtf8CharsetContentType(makeRes("application/ld+json")).headers.get("content-type"))
+      .toBe("application/ld+json; charset=utf-8");
+    expect(withUtf8CharsetContentType(makeRes("application/xml")).headers.get("content-type"))
+      .toBe("application/xml; charset=utf-8");
+  });
+
+  test("preserves non-charset parameters and appends charset (application/json; boundary=…)", () => {
+    // Bun's Response.json emits `application/json;charset=utf-8`; the test
+    // above covers that no-op path. When a caller sends a parametrised
+    // header like `application/json; profile=…`, the helper still recognises
+    // it via the `application/json;` prefix and appends the charset.
+    const res = withUtf8CharsetContentType(makeRes("application/json; profile=example"));
+    expect(res.headers.get("content-type")).toBe("application/json; profile=example; charset=utf-8");
+  });
+
+  test("returns the same Response instance (mutates in place)", () => {
+    const input = makeRes("text/event-stream");
+    const output = withUtf8CharsetContentType(input);
+    expect(output).toBe(input);
+  });
+
+  // Drift guard: the pure copy in this file MUST match the production
+  // helper's branching set. If someone edits one without touching the
+  // other, this test fails visibly instead of the helper going silently
+  // out of sync. Kept as fragment-level greps (not whole-body match) so
+  // added comments don't break the assertion.
+  test("production helper covers the same content-type branches", () => {
+    const src = readFileSync(join(import.meta.dir, "server.ts"), "utf-8");
+    expect(src).toContain("function withUtf8CharsetContentType(res: Response): Response {");
+    expect(src).toContain("if (/;\\s*charset=/i.test(ct)) return res;");
+    for (const branch of [
+      'trimmed === "application/json"',
+      'trimmed.startsWith("text/")',
+      'trimmed.startsWith("application/json;")',
+      'trimmed === "application/ld+json"',
+      'trimmed === "application/xml"',
+    ]) {
+      expect(src).toContain(branch);
+    }
+    expect(src).toContain('res.headers.set("content-type", `${trimmed}; charset=utf-8`);');
+  });
+});

package/src/send-reply-agent-warning.test.ts

@@ -0,0 +1,202 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// #498 regression — the send_reply hub response gains a `warning` field
+// pointing at commhub_send_task ONLY when the target alias resolves to
+// a real agent node (i.e. not hub / not api / not an unbound alias).
+// Silence-affirms the Dashboard path.
+//
+// Why this test exists (通信龙 2026-07-30 裁定): the warning is a pure
+// hint — deleting it doesn't break any behavior, so it's exactly the
+// kind of code a future refactor drops silently. This test is the
+// tripwire: if the branch goes away, this test turns red.
+//
+// witnessed-red methodology (`feedback_witnessed_red_before_witnessed_green`):
+// I confirmed both assertions fail cleanly when the `warning` branch is
+// reverted (see docs/tests/p-498-reply-warning/witnessed-red.txt), so
+// this suite genuinely catches regressions rather than green-when-empty.
+
+const NET_ID = "net_498_warn";
+const USER_ID = "u_498_warn";
+const NODE_ID = "node_498_warn";
+const AGENT_ALIAS = "peer-agent-498";
+const AGENT_TOK_ID = "tok_498_warn";
+
+interface ToolHandler {
+  (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>;
+}
+interface Reply {
+  ok?: boolean;
+  message_id?: string;
+  session_status?: string;
+  warning?: string;
+  error?: string;
+  [k: string]: unknown;
+}
+
+function cleanup() {
+  try { db.run("DELETE FROM tasks WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM inbox WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM task_events WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM sessions WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET_ID]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER_ID]); } catch {}
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [USER_ID, USER_ID],
+  );
+  db.run(
+    `INSERT INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET_ID, NET_ID, USER_ID],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [USER_ID, NET_ID],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'), 'active')`,
+    [NODE_ID, AGENT_ALIAS, AGENT_ALIAS, NET_ID, `host-${AGENT_ALIAS}`],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+    [`res_${AGENT_ALIAS}`, AGENT_ALIAS, NODE_ID, NET_ID],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [AGENT_TOK_ID, USER_ID, NET_ID, `node:${AGENT_ALIAS}`, `hash_${AGENT_TOK_ID}`],
+  );
+}
+
+function makeTask(to: string): string {
+  const id = "t_" + Math.random().toString(36).slice(2, 14);
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, network_id)
+     VALUES (?1, ?2, ?3, 'normal', 'delivered', 'test', 'reply', datetime('now'), ?4)`,
+    [id, "dispatcher", to, NET_ID],
+  );
+  return id;
+}
+
+function buildHandlers(): Record<string, ToolHandler> {
+  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);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => {
+      tools[name] = handler;
+      return origRegisterTool(name, _cfg, handler);
+    };
+  }
+  // Bind as a network token whose caller alias is the sender.
+  registerTools(
+    server,
+    undefined,
+    /* enforceNetworkId */ NET_ID,
+    /* enforceUserId */ USER_ID,
+    /* callerAlias */ AGENT_ALIAS,
+    /* callerTokenIsNetwork */ true,
+    /* callerTokenId */ AGENT_TOK_ID,
+  );
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+describe("send_reply warning field (#498)", () => {
+  test("target alias resolves to a real agent → response includes `warning` field", async () => {
+    seed();
+    const tools = buildHandlers();
+    const sendReply = tools["send_reply"];
+    expect(sendReply).toBeDefined();
+
+    const taskId = makeTask(AGENT_ALIAS);
+    const reply = await call(sendReply, {
+      alias: AGENT_ALIAS,
+      text: "peer reply (should trigger warning)",
+      in_reply_to: taskId,
+      status: "replied",
+      from_session: AGENT_ALIAS,
+    });
+
+    expect(reply.ok).toBe(true);
+    expect(reply.warning).toBeDefined();
+    expect(typeof reply.warning).toBe("string");
+    const w = reply.warning as string;
+    // Action-pointing content — witnessed-red methodology means each
+    // assertion here must be one a future revert would break, not a
+    // shape-only check that passes on empty string.
+    expect(w).toContain("commhub_send_task");
+    // Alias value is INLINED (not just "<alias>") so the LLM has a
+    // copy-pasteable next command. This is the specific design 通信龙
+    // called out on 2026-07-30.
+    expect(w).toContain(`alias="${AGENT_ALIAS}"`);
+    expect(w).toContain("agent peers");
+    expect(w).toContain("not see this reply in real time");
+    expect(w).toContain("RFC-030");
+    expect(w).toContain("全网规则");
+  });
+
+  test("target alias is `hub` (Dashboard path) → NO warning field", async () => {
+    seed();
+    const tools = buildHandlers();
+    const sendReply = tools["send_reply"];
+
+    const taskId = makeTask("hub");
+    const reply = await call(sendReply, {
+      alias: "hub",
+      text: "dashboard reply",
+      in_reply_to: taskId,
+      status: "replied",
+      from_session: AGENT_ALIAS,
+    });
+
+    expect(reply.ok).toBe(true);
+    // Silence-affirms the Dashboard path. Every reply carrying a
+    // warning would train the LLM to ignore it, so absence here is
+    // load-bearing.
+    expect(reply.warning).toBeUndefined();
+  });
+
+  test("target alias is `api` (Dashboard path) → NO warning field", async () => {
+    seed();
+    const tools = buildHandlers();
+    const sendReply = tools["send_reply"];
+
+    const taskId = makeTask("api");
+    const reply = await call(sendReply, {
+      alias: "api",
+      text: "dashboard reply via api",
+      in_reply_to: taskId,
+      status: "replied",
+      from_session: AGENT_ALIAS,
+    });
+
+    expect(reply.ok).toBe(true);
+    expect(reply.warning).toBeUndefined();
+  });
+});