@sleep2agi/commhub-server 0.9.0-preview.54 → 0.9.0-preview.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.54",
+  "version": "0.9.0-preview.56",
   "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/alias-filter.test.ts

@@ -10,8 +10,8 @@ test("no filter given means no filtering, not an empty match", () => {
 });
 
 test("a single alias produces one placeholder", () => {
-  const f = parseAliasFilter("TM门户马");
-  expect(f.aliases).toEqual(["TM门户马"]);
+  const f = parseAliasFilter("节点甲");
+  expect(f.aliases).toEqual(["节点甲"]);
   expect(f.sql).toBe(" AND alias IN (?)");
 });
 

package/src/db.ts

@@ -123,6 +123,10 @@ for (const col of [
   { name: "process_in_flight_count", def: "INTEGER" },
   { name: "external_schedules", def: "TEXT" },
   { name: "peer_reply_inbox_capable", def: "INTEGER NOT NULL DEFAULT 0" },
+  // app#225 follow-up — a session (incl. claude-code sessions with no `nodes` row)
+  // that answers the rules-file doorbell. Sticky: set by a bound node token, never
+  // cleared by reports that omit it (agent-node status-only reports do).
+  { name: "rules_file_capable", def: "INTEGER NOT NULL DEFAULT 0" },
 ]) {
   try { db.exec(`ALTER TABLE sessions ADD COLUMN ${col.name} ${col.def}`); } catch {}
 }

package/src/messages-ack-by-agent-http.test.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, test } 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";
+
+// #1909 —— POST /api/messages/ack 的 `{ agent }` 形态:把调用者收到的、来自该 agent 的
+// 两张表(user_inbox + inbox reply/task/message)全部标已读。角标分母 unread_by_agent
+// 数的是全集,按 id 只能 ack 拉到的那一页 ⇒ 老行永远清不掉,这一形态补上。
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-ack-by-agent-http-"));
+let server: any;
+let base = "";
+let tokenA = "";
+let tokenB = "";
+let userA = "";
+let userB = "";
+let userIdA = "";
+let userIdB = "";
+let netA = "";
+let netB = "";
+
+const AGENT = "ack-agent-x";
+const OTHER = "ack-agent-y";
+
+function seed() {
+  const ui = (id: string, net: string, uid: string, from: string) =>
+    db.run(
+      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, content) VALUES (?1, ?2, ?3, ?4, 'agent_message', 'x')`,
+      [id, net, uid, from],
+    );
+  const ib = (id: string, net: string, to: string, from: string, type: string) =>
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, content, from_session, network_id) VALUES (?1, ?2, ?3, 'x', ?4, ?5)`,
+      [id, to, type, from, net],
+    );
+  ui("ui_a_x_1", netA, userIdA, AGENT);
+  ui("ui_a_x_2", netA, userIdA, AGENT);
+  ui("ui_a_y_1", netA, userIdA, OTHER);
+  ui("ui_b_x_1", netB, userIdB, AGENT);
+  ib("ib_a_x_reply", netA, userA, AGENT, "reply");
+  ib("ib_a_x_task", netA, userA, AGENT, "task");
+  ib("ib_a_x_status", netA, userA, AGENT, "status"); // 不在 reply/task/message 内,不该被 ack
+  ib("ib_a_y_reply", netA, userA, OTHER, "reply");
+  ib("ib_b_x_reply", netB, userB, AGENT, "reply");
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  const stamp = `${Date.now()}_${process.pid}`;
+  userA = `ack_agent_a_${stamp}`;
+  userB = `ack_agent_b_${stamp}`;
+  const a = register(userA, "AckAgent123!", undefined, "seed");
+  const b = register(userB, "AckAgent123!", undefined, "seed");
+  expect(a.ok).toBe(true);
+  expect(b.ok).toBe(true);
+  tokenA = a.token!; netA = a.network_id!;
+  tokenB = b.token!; netB = b.network_id!;
+  userIdA = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [userA])!.user_id;
+  userIdB = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [userB])!.user_id;
+  seed();
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+async function ack(token: string, body: unknown): Promise<{ status: number; body: any }> {
+  const response = await fetch(`${base}/api/messages/ack`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+const uiAcked = (id: string) => db.get<{ acked: number }>("SELECT acked FROM user_inbox WHERE message_id = ?1", [id])!.acked;
+const ibAcked = (id: string) => db.get<{ acked: number }>("SELECT acked FROM inbox WHERE id = ?1", [id])!.acked;
+
+async function unreadByAgent(token: string): Promise<Record<string, number>> {
+  const response = await fetch(`${base}/api/messages?scope=user&limit=5`, { headers: { Authorization: `Bearer ${token}` } });
+  expect(response.status).toBe(200);
+  return ((await response.json()) as any).unread_by_agent ?? {};
+}
+
+describe("POST /api/messages/ack { agent } (#1909)", () => {
+  test("missing everything → message_id_required; agent + ids → ambiguous_ack", async () => {
+    const none = await ack(tokenA, {});
+    expect(none.status).toBe(400);
+    expect(none.body.error).toBe("message_id_required");
+    const both = await ack(tokenA, { agent: AGENT, message_ids: ["ui_a_x_1"] });
+    expect(both.status).toBe(400);
+    expect(both.body.error).toBe("ambiguous_ack");
+    // 拒绝的那次不能有副作用
+    expect(uiAcked("ui_a_x_1")).toBe(0);
+  });
+
+  test("unread_by_agent counts the seeded rows before ack", async () => {
+    const by = await unreadByAgent(tokenA);
+    expect(by[AGENT]).toBe(4); // 2 user_inbox + reply + task (status 不计)
+    expect(by[OTHER]).toBe(2);
+  });
+
+  test("agent form acks both tables, only that agent, only the caller", async () => {
+    const r = await ack(tokenA, { agent: `  ${AGENT}  ` });
+    expect(r.status).toBe(200);
+    expect(r.body).toMatchObject({ ok: true, scope: "agent", agent: AGENT, acked: 4, acked_user_inbox: 2, acked_inbox: 2 });
+    expect(uiAcked("ui_a_x_1")).toBe(1);
+    expect(uiAcked("ui_a_x_2")).toBe(1);
+    expect(ibAcked("ib_a_x_reply")).toBe(1);
+    expect(ibAcked("ib_a_x_task")).toBe(1);
+    // 不该动的:别的 agent、非 reply/task/message 类型、别的用户
+    expect(uiAcked("ui_a_y_1")).toBe(0);
+    expect(ibAcked("ib_a_x_status")).toBe(0);
+    expect(ibAcked("ib_a_y_reply")).toBe(0);
+    expect(uiAcked("ui_b_x_1")).toBe(0);
+    expect(ibAcked("ib_b_x_reply")).toBe(0);
+    const by = await unreadByAgent(tokenA);
+    expect(by[AGENT] ?? 0).toBe(0);
+    expect(by[OTHER]).toBe(2);
+    expect((await unreadByAgent(tokenB))[AGENT]).toBe(2);
+  });
+
+  test("agent form is idempotent: second call changes 0 rows", async () => {
+    const r = await ack(tokenA, { agent: AGENT });
+    expect(r.status).toBe(200);
+    expect(r.body.acked).toBe(0);
+  });
+
+  test("id form still works and now reports scope ids", async () => {
+    const r = await ack(tokenA, { message_ids: ["ui_a_y_1", "ib_a_y_reply", "ui_b_x_1"] });
+    expect(r.status).toBe(200);
+    expect(r.body).toMatchObject({ ok: true, scope: "ids", acked: 2, acked_user_inbox: 1, acked_inbox: 1 });
+    expect(uiAcked("ui_a_y_1")).toBe(1);
+    expect(ibAcked("ib_a_y_reply")).toBe(1);
+    expect(uiAcked("ui_b_x_1")).toBe(0); // 别人的 id 匹配不到
+  });
+});

package/src/rest-explicit-columns-http.test.ts

@@ -45,7 +45,7 @@ const GOLDEN_RESPONSE_KEYS = {
     "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
     "process_in_flight_count", "network_id", "registered_at", "updated_at",
     "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
-    "external_schedules", "runtime", "host", "process_telemetry",
+    "external_schedules", "rules_file_capable", "runtime", "host", "process_telemetry",
   ],
   task: [
     "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",

package/src/rest-projections.ts

@@ -19,7 +19,7 @@ export const SESSION_REST_COLUMNS = [
   "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
   "process_in_flight_count", "network_id", "registered_at", "updated_at",
   "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
-  "external_schedules",
+  "external_schedules", "rules_file_capable",
 ] as const;
 
 export const AUDIT_LOG_REST_COLUMNS = [

package/src/rules-file-session-target.test.ts

@@ -0,0 +1,207 @@
+// app#225 follow-up — rules-file requests to a SESSION that has no `nodes` row
+// (claude-code sessions launched by `anet node start` + the channel server).
+//
+// Hub-side contract verified here:
+//   1. report_status { rules_file_capable: true } marks the session capable only
+//      when the caller is a node token bound to that same alias (a user token or
+//      another node's token cannot mark it); omitting the field later does not clear it.
+//   2. read/write_node_rules_file { alias } reach such a session: the node pulls
+//      with its own token (queue key `session:<alias>`), acks, the client polls done.
+//   3. An alias that has neither a node row nor a capable session is refused up
+//      front (no request row, no 60 s timeout for the user to sit through).
+//   4. Network isolation: a same-named alias in another network neither sees nor
+//      acks the request; a caller in the other network cannot enqueue to it.
+//   5. The original node_id path is unchanged (node row wins when both exist).
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/rules-session.db bun test src/rules-file-session-target.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_rules_session";
+const OTHER_NET = "net_rules_session_other";
+const USER = "u_rules_session_owner";
+const SESSION_ALIAS = "rules-session-cc";
+const SESSION_RESUME = "cc-rules-session-1";
+const OTHER_ALIAS = "rules-session-peer";
+const NODE_ROW_ALIAS = "rules-session-noderow";
+const NODE_ROW_ID = "node_rules_session_noderow";
+const T_SESSION = "tok_rules_session_cc";
+const T_PEER = "tok_rules_session_peer";
+const T_OTHER_NET_SAME_ALIAS = "tok_rules_session_other_net";
+const T_NODE_ROW = "tok_rules_session_noderow";
+
+function cleanup() {
+  for (const net of [NET, OTHER_NET]) {
+    try { db.run("DELETE FROM node_rules_requests WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM sessions WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [net]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+}
+
+function seedWorld() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [USER, USER]);
+  for (const net of [NET, OTHER_NET]) {
+    db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [net, net, USER]);
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [USER, net]);
+  }
+  const tok = (id: string, net: string, alias: string) => 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)`,
+    [id, USER, net, `node:${alias}`, `hash_${id}`],
+  );
+  tok(T_SESSION, NET, SESSION_ALIAS);
+  tok(T_PEER, NET, OTHER_ALIAS);
+  tok(T_OTHER_NET_SAME_ALIAS, OTHER_NET, SESSION_ALIAS);
+  tok(T_NODE_ROW, NET, NODE_ROW_ALIAS);
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [NODE_ROW_ID, NODE_ROW_ALIAS, NODE_ROW_ALIAS, NET],
+  );
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_rules_session_user" };
+const asOtherNetUser: Identity = { net: OTHER_NET, alias: USER, isNetworkToken: false, tokenId: "tok_rules_session_user2" };
+const asSession: Identity = { net: NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_SESSION };
+const asPeer: Identity = { net: NET, alias: OTHER_ALIAS, isNetworkToken: true, tokenId: T_PEER };
+const asOtherNetSameAlias: Identity = { net: OTHER_NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_OTHER_NET_SAME_ALIAS };
+const asNodeRow: Identity = { net: NET, alias: NODE_ROW_ALIAS, isNetworkToken: true, tokenId: T_NODE_ROW };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "rules-session-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "rules-session-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (!first || first.type !== "text") throw new Error(`no text result from ${name}: ${JSON.stringify(r).slice(0, 300)}`);
+    return JSON.parse(first.text);
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+const capable = (alias: string, net = NET) =>
+  db.get<{ c: number }>("SELECT rules_file_capable AS c FROM sessions WHERE alias = ?1 AND network_id = ?2", alias, net)?.c;
+
+async function registerSession(id: Identity, alias: string, resume: string, flag: boolean) {
+  const c = await connect(id);
+  try {
+    return await c.call("report_status", { resume_id: resume, alias, status: "idle", agent: "claude-code", ...(flag ? { rules_file_capable: true } : {}) });
+  } finally { await c.close(); }
+}
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("rules_file_capable is set only by the session's own node token", () => {
+  test("bound node token sets it; a later report without the field does not clear it", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, false);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+  }, 20_000);
+
+  // The hub already refuses these reports outright (network_token_required /
+  // alias_identity_mismatch); the bound-token check on the UPDATE is defence in
+  // depth. The real session row is registered first so "stays 0" is not vacuous.
+  test("a user token reporting for the alias is refused and cannot mark it capable", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, false);
+    expect(capable(SESSION_ALIAS)).toBe(0);
+    const r = await registerSession(asUser, SESSION_ALIAS, SESSION_RESUME, true);
+    expect(r).toMatchObject({ ok: false, error: "network_token_required" });
+    expect(capable(SESSION_ALIAS)).toBe(0);
+  }, 20_000);
+
+  test("another node's token is refused and cannot mark someone else's session capable", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, false);
+    const r = await registerSession(asPeer, SESSION_ALIAS, SESSION_RESUME, true);
+    expect(r).toMatchObject({ ok: false, error: "alias_identity_mismatch" });
+    expect(capable(SESSION_ALIAS)).toBe(0);
+  }, 20_000);
+});
+
+describe("read/write by alias reach a session with no nodes row", () => {
+  test("read round trip: enqueue by alias → session pulls with its own token → ack → done", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: SESSION_ALIAS });
+      expect(enq).toMatchObject({ ok: true, op: "read" });
+      expect(db.get<{ node_id: string }>("SELECT node_id FROM node_rules_requests WHERE request_id = ?1", enq.request_id)?.node_id).toBe(`session:${SESSION_ALIAS}`);
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "read" });
+      expect(await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: "# rules\n" })).toMatchObject({ ok: true, status: "done" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "done", file_name: "CLAUDE.md", exists: true, content: "# rules\n" });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("write carries content to the session", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("write_node_rules_file", { alias: SESSION_ALIAS, content: "new body\n" });
+      expect(enq).toMatchObject({ ok: true, op: "write" });
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "write", content: "new body\n" });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("alias with neither a node row nor a capable session is refused before any row is written", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, false);
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "rules_file_target_not_found" });
+      expect(db.get<{ c: number }>("SELECT COUNT(*) AS c FROM node_rules_requests WHERE network_id = ?1", NET)?.c).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("network isolation: same alias in another network neither pulls nor acks; other-network user cannot enqueue", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const x = await connect(asOtherNetSameAlias);
+    const ou = await connect(asOtherNetUser);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: SESSION_ALIAS });
+      expect(enq.ok).toBe(true);
+      expect(await x.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+      expect(await x.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "stolen" })).toMatchObject({ ok: true, ignored: "unknown_or_foreign_request" });
+      expect(db.get<{ s: string }>("SELECT status AS s FROM node_rules_requests WHERE request_id = ?1", enq.request_id)?.s).toBe("pending");
+      expect(await ou.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "rules_file_target_not_found" });
+    } finally { await u.close(); await x.close(); await ou.close(); }
+  }, 20_000);
+
+  test("a peer node in the same network cannot pull or ack the session's request", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const p = await connect(asPeer);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: SESSION_ALIAS });
+      expect(await p.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+      expect(await p.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "x" })).toMatchObject({ ok: true, ignored: "unknown_or_foreign_request" });
+    } finally { await u.close(); await p.close(); }
+  }, 20_000);
+
+  test("alias that has a nodes row resolves to that node_id (original queue key)", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNodeRow);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: NODE_ROW_ALIAS });
+      expect(enq.ok).toBe(true);
+      expect(db.get<{ node_id: string }>("SELECT node_id FROM node_rules_requests WHERE request_id = ?1", enq.request_id)?.node_id).toBe(NODE_ROW_ID);
+      expect((await n.call("get_rules_file_request", {})).request?.request_id).toBe(enq.request_id);
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});

package/src/rules-file-transport.test.ts

@@ -105,8 +105,10 @@ describe("app#225 rules file — schema has no path", () => {
         const shape = schema?.shape ?? schema?._def?.shape?.() ?? schema ?? {};
         return Object.keys(shape).sort();
       };
-      expect(shapeKeys("read_node_rules_file")).toEqual(["child_node_id", "network_id", "node_id"]);
-      expect(shapeKeys("write_node_rules_file")).toEqual(["child_node_id", "content", "network_id", "node_id"]);
+      // `alias` (app#225 follow-up) names a TARGET node/session, not a file —
+      // the no-path regex below still covers it.
+      expect(shapeKeys("read_node_rules_file")).toEqual(["alias", "child_node_id", "network_id", "node_id"]);
+      expect(shapeKeys("write_node_rules_file")).toEqual(["alias", "child_node_id", "content", "network_id", "node_id"]);
       expect(shapeKeys("get_rules_file_request")).toEqual([]);
       // ack 的 file_name 是节点**回报**它用了哪个文件,不是客户端**指定**用哪个文件。
       expect(shapeKeys("ack_rules_file_request")).toEqual(["content", "error", "exists", "file_name", "request_id", "status"]);

package/src/server.ts

@@ -1680,6 +1680,8 @@ return Bun.serve({
         return {
           ...publicSession,
           external_schedules: externalSchedules,
+          // app#225 follow-up — sqlite INTEGER 0/1 → boolean on the wire.
+          rules_file_capable: s.rules_file_capable === 1,
           model: s.model ?? null,
           runtime: normalizeRuntime(s.agent),
           host: {
@@ -2755,6 +2757,34 @@ return Bun.serve({
       const ids: string[] = Array.isArray(body?.message_ids)
         ? body.message_ids.filter((x: unknown) => typeof x === "string" && x.length > 0)
         : (typeof body?.message_id === "string" && body.message_id ? [body.message_id] : []);
+      // #1909 —— 按 agent 整体 ack:`{ agent: "<alias>" }`。角标的分母是 `unread_by_agent`,
+      //    它数的是**全部**未 ack 行,而客户端一页只看得到最近 200/300 条 ⇒ 老行永远 ack 不到,
+      //    红点永远清不掉(生产 admin:user_inbox 522 + inbox 5660 行)。这一形态把调用者
+      //    收到的、来自该 agent 的两张表全部标已读;同样只动自己的行。
+      const agentRaw = typeof body?.agent === "string" ? body.agent.trim() : "";
+      if (agentRaw && ids.length > 0) {
+        return withCors(req, Response.json({ ok: false, error: "ambiguous_ack" }, { status: 400 }));
+      }
+      if (agentRaw) {
+        const uiParams: any[] = [callerUserId, agentRaw];
+        let uiSql = `UPDATE user_inbox SET acked = 1, acked_at = datetime('now')
+                     WHERE user_id = ?1 AND from_session = ?2 AND acked = 0`;
+        uiSql = addNetworkScope(uiSql, uiParams, restScope);
+        const uiAcked = db.run(uiSql, uiParams).changes ?? 0;
+        let agentInboxAcked = 0;
+        const agentCallerUsername = restAuth?.username ?? "";
+        if (agentCallerUsername && !userInboxAliasCollides(agentCallerUsername, restScope)) {
+          const ibAgentParams: any[] = [agentCallerUsername, agentRaw];
+          let ibAgentSql = `UPDATE inbox SET acked = 1
+                            WHERE session_name = ?1 AND from_session = ?2 AND acked = 0 AND type IN ('reply', 'task', 'message')`;
+          ibAgentSql = addNetworkScope(ibAgentSql, ibAgentParams, restScope);
+          agentInboxAcked = db.run(ibAgentSql, ibAgentParams).changes ?? 0;
+        }
+        return withCors(req, Response.json({
+          ok: true, scope: "agent", agent: agentRaw,
+          acked: uiAcked + agentInboxAcked, acked_user_inbox: uiAcked, acked_inbox: agentInboxAcked,
+        }));
+      }
       if (ids.length === 0) {
         return withCors(req, Response.json({ ok: false, error: "message_id_required" }, { status: 400 }));
       }
@@ -2781,7 +2811,7 @@ return Bun.serve({
         ibSql = addNetworkScope(ibSql, ibParams, restScope);
         inboxAcked = db.run(ibSql, ibParams).changes ?? 0;
       }
-      return withCors(req, Response.json({ ok: true, acked: (res.changes ?? 0) + inboxAcked, acked_user_inbox: res.changes ?? 0, acked_inbox: inboxAcked }));
+      return withCors(req, Response.json({ ok: true, scope: "ids", acked: (res.changes ?? 0) + inboxAcked, acked_user_inbox: res.changes ?? 0, acked_inbox: inboxAcked }));
     }
 
     // ── REST: stats summary ──

package/src/tools.ts

@@ -713,8 +713,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           create_capability_observed_ms_ago: z.number().nullable().catch(null).optional(),
         }).optional(),
       }).optional().describe("RFC-024 — masked node config snapshot"),
+      // app#225 follow-up — the reporting process answers the `rules_file`
+      // doorbell (agent-node, and the claude-code channel server node-server).
+      // Top-level instead of config_snapshot: claude-code sessions usually have
+      // no `nodes` row, and config_snapshot is persisted per node_id. Only a
+      // node token bound to this same alias can set it; see the UPDATE below.
+      rules_file_capable: z.literal(true).optional(),
     },
-    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap }) => {
+    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap, rules_file_capable: rulesFileCapable }) => {
       const effectiveNetId = getNetworkId(netId);
       const sessionNetId = effectiveNetId ?? "default";
       if (!callerTokenIsNetwork || !enforceNetworkId) {
@@ -913,6 +919,13 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
              handover.registered_at ?? null],
           );
         }
+        // app#225 follow-up — separate statement on purpose: the INSERT above is
+        // byte-pinned by test698's mutation harness. Sticky: only ever set to 1,
+        // and only by a node token bound to this alias (a user token or another
+        // node cannot mark someone else's session as able to serve its files).
+        if (rulesFileCapable === true && callerTokenIsNetwork && callerAlias && callerAlias === effectiveAlias) {
+          db.run("UPDATE sessions SET rules_file_capable = 1 WHERE resume_id = ?1", [resume_id]);
+        }
         if (host || proc) {
           db.run(
             `INSERT INTO agent_telemetry (id, network_id, resume_id, alias, hostname, ip, cpu_load_1min, cpu_cores, mem_total_gb, mem_used_gb, mem_avail_gb, disk_total_gb, disk_used_gb, disk_avail_gb, process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count, created_at)
@@ -3102,21 +3115,51 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   const enqueueRulesFileRequest = (
     op: "read" | "write",
-    a: { node_id?: string; child_node_id?: string; network_id?: string; content?: string },
+    a: { node_id?: string; child_node_id?: string; alias?: string; network_id?: string; content?: string },
   ) => {
-    const idArg = resolveNodeIdArg({ node_id: a.node_id, child_node_id: a.child_node_id });
-    if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
-    const nodeId = idArg.node_id;
     const effectiveNetId = getNetworkId(a.network_id);
     if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, `${op} rules file`);
 
-    const { row: node, sec1Ok } = resolveTargetNode(nodeId, effectiveNetId);
-    if (!node) {
-      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_found", node_id: nodeId }) }] };
-    }
-    if (!sec1Ok) {
-      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node", message: "node belongs to another network" }) }] };
+    // Target: a `nodes` row by node_id (original path), or — app#225 follow-up —
+    // an alias. An alias resolves to its `nodes` row when there is one; otherwise
+    // to a live session in the caller's network that advertised
+    // rules_file_capable (claude-code sessions mostly have no `nodes` row). The
+    // queue key for such a session is `session:<alias>`, network-scoped.
+    let node: { node_id: string; alias: string; network_id: string | null } | null = null;
+    if (a.node_id || a.child_node_id || !a.alias) {
+      const idArg = resolveNodeIdArg({ node_id: a.node_id, child_node_id: a.child_node_id });
+      if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+      const nodeId = idArg.node_id;
+      const resolved = resolveTargetNode(nodeId, effectiveNetId);
+      if (!resolved.row) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_found", node_id: nodeId }) }] };
+      }
+      if (!resolved.sec1Ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node", message: "node belongs to another network" }) }] };
+      }
+      node = resolved.row as any;
+    } else {
+      const scopeNet = effectiveNetId || "default";
+      const byAlias = db.get<{ node_id: string; alias: string; network_id: string | null }>(
+        "SELECT node_id, alias, network_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
+        a.alias,
+        scopeNet,
+      );
+      if (byAlias) {
+        node = byAlias;
+      } else {
+        const session = db.get<{ alias: string; network_id: string | null }>(
+          "SELECT alias, network_id FROM sessions WHERE alias = ?1 AND network_id = ?2 AND rules_file_capable = 1 ORDER BY updated_at DESC LIMIT 1",
+          a.alias,
+          scopeNet,
+        );
+        if (!session) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "rules_file_target_not_found", alias: a.alias, message: "no node with this alias in the network, and no session with this alias that can serve rules files (its channel server may be too old)" }) }] };
+        }
+        node = { node_id: `session:${session.alias}`, alias: session.alias, network_id: session.network_id };
+      }
     }
+    const nodeId = node.node_id;
     if (op === "write") {
       if (typeof a.content !== "string") {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "invalid_content", reason: "content must be a string" }) }] };
@@ -3157,8 +3200,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   server.tool(
     "read_node_rules_file",
     "Ask a node to send back its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) from its working directory. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
-    { ...NODE_ID_ALIAS_FIELDS, network_id: z.string().max(200).optional() },
-    async ({ node_id, child_node_id, network_id }) => enqueueRulesFileRequest("read", { node_id, child_node_id, network_id }),
+    {
+      ...NODE_ID_ALIAS_FIELDS,
+      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported rules_file_capable (claude-code sessions)."),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("read", { node_id, child_node_id, alias, network_id }),
   );
 
   server.tool(
@@ -3166,10 +3213,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node to overwrite its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) in its working directory with `content`. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
     {
       ...NODE_ID_ALIAS_FIELDS,
+      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported rules_file_capable (claude-code sessions)."),
       content: z.string().max(RULES_FILE_MAX_BYTES).describe("Full new file content (UTF-8). The node writes it atomically."),
       network_id: z.string().max(200).optional(),
     },
-    async ({ node_id, child_node_id, content, network_id }) => enqueueRulesFileRequest("write", { node_id, child_node_id, content, network_id }),
+    async ({ node_id, child_node_id, alias, content, network_id }) => enqueueRulesFileRequest("write", { node_id, child_node_id, alias, content, network_id }),
   );
 
   server.tool(
@@ -3189,12 +3237,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         callerAlias,
         enforceNetworkId,
       );
-      if (!node) {
-        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request: null }) }] };
-      }
+      // app#225 follow-up — no `nodes` row: this is a session-only target
+      // (claude-code). Its queue key is `session:<alias>`, always paired with the
+      // caller's network so a same-named alias in another network never matches.
+      const queueKey: string = node ? node.node_id : `session:${callerAlias}`;
       const req = db.get<any>(
-        "SELECT request_id, op, content FROM node_rules_requests WHERE node_id = ?1 AND status = 'pending' ORDER BY created_at ASC LIMIT 1",
-        node.node_id,
+        "SELECT request_id, op, content FROM node_rules_requests WHERE node_id = ?1 AND network_id = ?2 AND status = 'pending' ORDER BY created_at ASC LIMIT 1",
+        queueKey,
+        enforceNetworkId,
       );
       if (!req) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request: null }) }] };
@@ -3242,15 +3292,13 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         callerAlias,
         enforceNetworkId,
       );
-      if (!node) {
-        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "alias_unknown" }) }] };
-      }
+      const queueKey: string = node ? node.node_id : `session:${callerAlias}`;
       const req = db.get<any>(
-        "SELECT request_id, node_id, status FROM node_rules_requests WHERE request_id = ?1",
+        "SELECT request_id, node_id, network_id, status FROM node_rules_requests WHERE request_id = ?1",
         requestId,
       );
-      // 跨租户闸：只能 ack 自己的请求；别人的当不存在处理。
-      if (!req || req.node_id !== node.node_id) {
+      // 跨租户闸：只能 ack 自己的请求；别人的当不存在处理。session 键另外核网络。
+      if (!req || req.node_id !== queueKey || req.network_id !== enforceNetworkId) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "unknown_or_foreign_request" }) }] };
       }
       if (req.status === "done" || req.status === "failed" || req.status === "timeout") {

package/src/uploads.ts

@@ -336,7 +336,7 @@ export type TaskAttachment = {
  * returns `{file_id, path}` where `path` is a hub-machine-local
  * absolute path. Senders sometimes echo `path` back into meta.attachments.
  * When the receiving agent runs on a different host (Vincent 2026-06-30
- * toodadev2 case), that path string is meaningless. agent-node's
+ * a partner-team host case), that path string is meaningless. agent-node's
  * fetch-attachment.ts will fetch via `file_id` regardless, but leaving
  * the stale `path` in the JSON misleads any tooling that reads it.
  *