@sleep2agi/commhub-server 0.9.0-preview.113 → 0.9.0-preview.114

package/package.json

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

@@ -957,7 +957,7 @@ const NETWORK_CLEANUP_TABLES = [
   "network_members", "network_member_agent_grants", "network_invites", "api_tokens",
   "node_create_requests", "node_start_requests", "node_stop_requests", "node_rules_requests",
   "node_config_updates", "rename_txn", "probe_results", "agent_telemetry", "completions",
-  "task_events", "task_terminal_events", "scheduled_task_runs", "external_schedule_edits",
+  "task_events", "task_terminal_events", "task_late_replies", "scheduled_task_runs", "external_schedule_edits",
   // 标签颜色:网络本身的元数据(标签本体在 requirements 行里,那张表是阻断项)。
   "network_tags",
   // 组织架构(board #419):部门是网络本身的元数据。

package/src/db.ts

@@ -1489,6 +1489,31 @@ try { db.exec("ALTER TABLE tasks ADD COLUMN consumed_at TEXT"); } catch {}
 try { db.exec("ALTER TABLE tasks ADD COLUMN thread_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE tasks ADD COLUMN turn_id TEXT"); } catch {}
 
+// Board #710 — a result that arrives after the task is already terminal is
+// evidence about that exact runtime turn, not a second task transition. Keep
+// it in an additive table: old clients and old Hub code continue to read the
+// tasks row unchanged, while new detail readers can project `late_replies`.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS task_late_replies (
+    late_reply_id TEXT PRIMARY KEY,
+    inbox_id TEXT NOT NULL UNIQUE,
+    task_id TEXT NOT NULL,
+    network_id TEXT,
+    from_node_id TEXT NOT NULL,
+    thread_id TEXT NOT NULL,
+    turn_id TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('replied','failed','cancelled')),
+    result TEXT NOT NULL,
+    meta_json TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (task_id, thread_id, turn_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_late_replies_task_time
+    ON task_late_replies(task_id, created_at);
+  CREATE INDEX IF NOT EXISTS idx_task_late_replies_network
+    ON task_late_replies(network_id, created_at);
+`);
+
 // #1181 durable outbound terminal cursor.  A task's created_at cannot be used
 // as a recovery watermark because an old task may become terminal after newer
 // tasks.  Record terminal transitions in their own monotonically increasing
@@ -1613,6 +1638,10 @@ try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN misfire_policy TEXT NOT NU
 // whether the node had ever picked it up: not_received | in_progress.
 try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_task_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_state TEXT"); } catch {}
+// Board #733 — schedules an Agent created over MCP name the creating node. NULL = created by a person
+// (REST / Dashboard) or a row from before this column; old rows keep NULL and old code never reads it.
+try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN created_by_node_id TEXT"); } catch {}
+try { db.exec("CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_creator_node ON scheduled_tasks(network_id, created_by_node_id)"); } catch {}
 // #523 — consecutive-failure alert bookkeeping (scheduled-failures.ts). Additive and nullable:
 // an older Hub never reads them, so rolling back is safe. failure_alert_at = ISO time of the last
 // alert; failure_alert_key = the last successful run_id at that moment ('' = none yet), so a

package/src/node-permissions.ts

@@ -244,7 +244,7 @@ export function streamVerdict(id: NodeIdentity, target: AgentRef | "network"): V
 }
 
 // ── MCP:每个工具归一类(test 钉住「每个注册的工具都归了类」,新工具忘了归类会红) ──
-export type ToolClass = "always" | "read" | "dispatch" | "broadcast" | "requirements" | "node_write" | "human_only";
+export type ToolClass = "always" | "read" | "dispatch" | "broadcast" | "requirements" | "schedule" | "node_write" | "human_only";
 export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
   // 回复 / 上报 / 自己的收件箱 / 生命周期协议(节点自己的请求)—— 任何模式都能做
   report_status: "always", report_completion: "always", get_inbox: "always", ack_inbox: "always",
@@ -268,6 +268,9 @@ export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
   requirements_list: "requirements", requirements_people: "requirements", requirements_get: "requirements", requirements_create: "requirements",
   requirements_update: "requirements", requirements_checklist_toggle: "requirements", requirements_upsert_by_external_ref: "requirements",
   requirements_events: "requirements", requirements_comment: "requirements", projects_list: "requirements",
+  // 定时任务(#733):在 schedule-agent.ts 里按排程判(范围 / 目标 = send_task 的 dispatchVerdict / 配额)
+  schedule_list: "read", schedule_get: "read", schedule_runs: "read",
+  schedule_create: "schedule", schedule_update: "schedule", schedule_cancel: "schedule", schedule_run_now: "schedule",
   // 写节点 / 技能 / 探测:只读、受限不行;正常由 RFC-036 等既有规则管
   update_node_config: "node_write", write_node_rules_file: "node_write", restart_node: "node_write", create_node: "node_write",
   stop_node: "node_write", delete_node: "node_write", start_node: "node_write", submit_skill: "node_write", probe_provider_model: "node_write",

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

@@ -58,7 +58,7 @@ const GOLDEN_RESPONSE_KEYS = {
     "status", "content", "result", "in_reply_to", "requires_response", "scope",
     "created_at", "delivered_at", "started_at", "runtime_submitted_at", "consumed_at",
     "completed_at", "expires_at", "network_id", "parent_task_id", "meta_json",
-    "thread_id", "turn_id",
+    "thread_id", "turn_id", "late_replies",
   ],
   audit: [
     "id", "user_id", "username", "action", "target_type", "target_id", "detail",

package/src/rest-projections.ts

@@ -49,7 +49,7 @@ export const COMPLETION_REST_COLUMNS = [
 // `schedule_json` are intentionally selected for server-side auth/decoding,
 // then removed by decodeRow before the REST response is serialized.
 export const SCHEDULED_TASK_STORAGE_COLUMNS = [
-  "schedule_id", "network_id", "created_by", "name", "target_node_id",
+  "schedule_id", "network_id", "created_by", "created_by_node_id", "name", "target_node_id",
   "target_alias", "task_content", "priority", "schedule_type", "schedule_json",
   "timezone", "overlap_policy", "misfire_policy", "status", "next_run_at",
   "last_run_at", "revision", "created_at", "updated_at",

package/src/schedule-agent-mcp-http.test.ts

@@ -0,0 +1,297 @@
+// Board #733 — Agents manage Hub scheduled tasks over MCP (schedule_* tools, schedule-agent.ts).
+// All through the real HTTP entry (bootServer + /mcp + REST), throwaway DB.
+//
+// Pins:
+//   1. Happy path from a node: create (default target = self, and another reachable node) / list / get /
+//      update / pause / run_now / runs / cancel.
+//   2. Denials: another network, another node's schedule, an unreachable target, over quota, too-short interval,
+//      retargeting a schedule the node did not create, read-only node.
+//   3. Old clients unaffected: REST still 403 for node tokens, REST shape unchanged (no creator fields),
+//      people's schedules have created_by_node_id NULL, user tokens get network_token_required on the MCP tools.
+//   4. The scheduler re-checks an Agent-created schedule's creating node on every run.
+//
+// Run: cd server && COMMHUB_DB=/tmp/x.db bun test src/schedule-agent-mcp-http.test.ts
+//      PG: COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1 (registered in tests/test2123-hub-postgres-ladder)
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("schedule-agent-mcp requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "SchedAgent123!x";
+let server: any, base = "", net = "", net2 = "";
+const user: Record<string, { id: string; token: string }> = {};
+const node: Record<string, { id: string; alias: string; token: string }> = {};
+const EVERY_MIN = { type: "interval", every_seconds: 60 };
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(`${base}${path}`, {
+    method, headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await r.text();
+  let json: any = null; try { json = JSON.parse(text); } catch {}
+  return { status: r.status, body: json };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown> = {}): Promise<any> {
+  const r = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const text = await r.text();
+  const data = text.split("\n").find((l) => l.startsWith("data: "));
+  const msg = JSON.parse(data ? data.slice(6) : text);
+  const inner = msg.result?.content?.[0]?.text;
+  try { return JSON.parse(inner); } catch { return { raw: inner ?? msg }; }
+}
+const create = (k: string, extra: Record<string, unknown> = {}) =>
+  mcp(node[k].token, "schedule_create", { name: `${k}-${Math.random().toString(36).slice(2, 8)}`, task: "ping", schedule: EVERY_MIN, ...extra });
+const storedRow = (id: string) => db.get<{ created_by: string | null; created_by_node_id: string | null }>(
+  "SELECT created_by, created_by_node_id FROM scheduled_tasks WHERE schedule_id = ?1", id);
+
+beforeAll(async () => {
+  const boss = register(`sa_boss_${stamp}`, PW); net = boss.network_id!; user.boss = { id: boss.user!.user_id, token: boss.token! };
+  const rst = register(`sa_rst_${stamp}`, PW); user.rst = { id: rst.user!.user_id, token: rst.token! };
+  expect(addNetworkMember(net, user.rst.id, "member", user.boss.id, { agentAccess: "granted" }).ok).toBe(true); // restricted, no grants
+  const other = register(`sa_other_${stamp}`, PW); net2 = other.network_id!; user.other = { id: other.user!.user_id, token: other.token! };
+  for (const [key, owner, network] of [["a", "boss", net], ["b", "boss", net], ["q", "boss", net], ["c", "boss", net], ["ro", "boss", net], ["x", "other", net2]] as const) {
+    const alias = `sa-${key}-${stamp}`, id = `n_sa_${key}_${stamp}`;
+    const t = createNetworkTokenForNode(user[owner].id, network, alias, id);
+    expect(t.ok).toBe(true);
+    node[key] = { id, alias, token: t.token! };
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_${id}`, alias, id, network]);
+  }
+  // c: an adopted node whose owner is a restricted member without grants — its token (issued by boss) works,
+  // but send_task to anyone but itself is refused for it (dispatchVerdict → agent_not_granted_to_owner).
+  db.run("UPDATE nodes SET owner_user_id = ?1 WHERE node_id = ?2", [user.rst.id, node.c.id]);
+  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}`;
+  db.run("UPDATE nodes SET permission_mode = 'readonly' WHERE node_id = ?1", [node.ro.id]);
+}, 60_000);
+afterEach(() => { delete process.env.COMMHUB_AGENT_SCHEDULE_QUOTA; delete process.env.COMMHUB_NODE_PERMISSIONS; });
+afterAll(() => { server?.stop?.(true); });
+
+describe("happy path from a node", () => {
+  test("create (default target = self) → list / get / update / pause / run_now / runs / cancel", async () => {
+    const c = await create("a");
+    expect(c.ok).toBe(true);
+    const s = c.schedule;
+    expect(s.target_node_id).toBe(node.a.id);
+    expect(s.created_by_node_id).toBe(node.a.id);
+    expect(s.created_by).toBeUndefined();
+    // created_by = the node's owner, so the scheduler's per-run canMessageAgent(created_by) keeps checking grants.
+    expect(storedRow(s.schedule_id)).toEqual({ created_by: user.boss.id, created_by_node_id: node.a.id });
+
+    const l = await mcp(node.a.token, "schedule_list");
+    expect(l.schedules.map((x: any) => x.schedule_id)).toContain(s.schedule_id);
+    expect((await mcp(node.a.token, "schedule_get", { schedule_id: s.schedule_id })).schedule.name).toBe(s.name);
+
+    const u = await mcp(node.a.token, "schedule_update", { schedule_id: s.schedule_id, name: "renamed", schedule: { type: "daily", time: "09:30" }, timezone: "Asia/Shanghai" });
+    expect(u.ok).toBe(true);
+    expect(u.schedule).toMatchObject({ name: "renamed", schedule_type: "daily", timezone: "Asia/Shanghai", revision: s.revision + 1 });
+    const p = await mcp(node.a.token, "schedule_update", { schedule_id: s.schedule_id, status: "paused" });
+    expect(p.schedule).toMatchObject({ status: "paused", next_run_at: null });
+
+    const r = await mcp(node.a.token, "schedule_run_now", { schedule_id: s.schedule_id });
+    expect(r.ok).toBe(true);
+    expect(r.taskId).toBeTruthy();
+    expect(db.get<{ to_name: string; from_name: string }>("SELECT to_name, from_name FROM tasks WHERE task_id = ?1", r.taskId)).toEqual({ to_name: node.a.alias, from_name: "scheduler" });
+    const runs = await mcp(node.a.token, "schedule_runs", { schedule_id: s.schedule_id });
+    expect(runs.runs.map((x: any) => x.task_id)).toContain(r.taskId);
+
+    expect(await mcp(node.a.token, "schedule_cancel", { schedule_id: s.schedule_id })).toEqual({ ok: true, status: "cancelled" });
+    expect((await mcp(node.a.token, "schedule_get", { schedule_id: s.schedule_id })).schedule.status).toBe("cancelled");
+    expect((await mcp(node.a.token, "schedule_run_now", { schedule_id: s.schedule_id })).error).toBe("schedule_cancelled");
+  });
+
+  test("a schedule for another node the caller can send_task to; the target can read it but not change it", async () => {
+    const c = await create("a", { target_node_id: node.b.id });
+    expect(c.ok).toBe(true);
+    const id = c.schedule.schedule_id;
+    expect((await mcp(node.b.token, "schedule_list")).schedules.map((x: any) => x.schedule_id)).toContain(id);
+    expect((await mcp(node.b.token, "schedule_get", { schedule_id: id })).ok).toBe(true);
+    expect((await mcp(node.b.token, "schedule_runs", { schedule_id: id })).ok).toBe(true);
+    for (const [tool, extra] of [["schedule_update", { name: "b edits" }], ["schedule_update", { target_node_id: node.q.id }], ["schedule_update", { status: "paused" }], ["schedule_cancel", {}], ["schedule_run_now", {}]] as const) {
+      expect((await mcp(node.b.token, tool, { schedule_id: id, ...extra })).error).toBe("not_schedule_creator");
+    }
+    // the creator may retarget (to a node it can reach)
+    expect((await mcp(node.a.token, "schedule_update", { schedule_id: id, target_node_id: node.q.id })).schedule.target_node_id).toBe(node.q.id);
+    expect((await mcp(node.b.token, "schedule_get", { schedule_id: id })).error).toBe("schedule_not_found"); // no longer targets b
+    expect((await mcp(node.q.token, "schedule_cancel", { schedule_id: id })).error).toBe("not_schedule_creator");
+    expect((await mcp(node.a.token, "schedule_cancel", { schedule_id: id })).ok).toBe(true);
+  });
+
+  test("a person's schedule that targets the node is read-only for it (even when paused)", async () => {
+    const r = await rest(user.boss.token, "POST", "/api/scheduled-tasks", { network_id: net, name: "boss → a", task: "t", target_node_id: node.a.id, schedule: EVERY_MIN });
+    expect(r.status).toBe(201);
+    const id = r.body.schedule.schedule_id;
+    const got = await mcp(node.a.token, "schedule_get", { schedule_id: id });
+    expect(got.schedule.created_by_node_id).toBeNull();
+    expect((await mcp(node.a.token, "schedule_runs", { schedule_id: id })).ok).toBe(true);
+    expect((await mcp(node.a.token, "schedule_list")).schedules.map((x: any) => x.schedule_id)).toContain(id);
+    expect((await rest(user.boss.token, "PATCH", `/api/scheduled-tasks/${id}`, { revision: r.body.schedule.revision, status: "paused" })).status).toBe(200);
+    for (const [tool, extra] of [["schedule_update", { status: "active" }], ["schedule_update", { task: "agent rewrite" }], ["schedule_update", { target_node_id: node.b.id }], ["schedule_cancel", {}], ["schedule_run_now", {}]] as const) {
+      expect((await mcp(node.a.token, tool, { schedule_id: id, ...extra })).error).toBe("not_schedule_creator");
+    }
+    const after = (await mcp(node.a.token, "schedule_get", { schedule_id: id })).schedule;
+    expect(after).toMatchObject({ status: "paused", task_content: "t", target_node_id: node.a.id });
+    expect((await mcp(node.b.token, "schedule_get", { schedule_id: id })).error).toBe("schedule_not_found");
+  });
+});
+
+describe("denials", () => {
+  test("another network: cannot target, see or touch it", async () => {
+    const mine = (await create("a")).schedule.schedule_id;
+    expect((await create("x", { target_node_id: node.a.id })).error).toBe("target_node_not_found");
+    for (const tool of ["schedule_get", "schedule_runs", "schedule_cancel", "schedule_run_now", "schedule_update"]) {
+      expect((await mcp(node.x.token, tool, { schedule_id: mine, name: "pwn" })).error).toBe("schedule_not_found");
+    }
+    expect((await mcp(node.x.token, "schedule_list")).schedules.map((x: any) => x.schedule_id)).not.toContain(mine);
+    // A row left in network 1 that names x as its creator (a node that later moved networks): x is now bound to
+    // network 2 and must not see it — the network check, not just the node id, guards this.
+    const ghost = `sched_ghost_${stamp}`;
+    db.run(`INSERT INTO scheduled_tasks (schedule_id, network_id, created_by, created_by_node_id, name, target_node_id, target_alias, task_content, schedule_type, schedule_json, next_run_at)
+            VALUES (?1, ?2, ?3, ?4, 'ghost', ?5, ?6, 't', 'interval', '{"type":"interval","every_seconds":60}', ?7)`,
+      [ghost, net, user.boss.id, node.x.id, node.a.id, node.a.alias, new Date(Date.now() + 3600_000).toISOString()]);
+    expect((await mcp(node.x.token, "schedule_get", { schedule_id: ghost })).error).toBe("schedule_not_found");
+    expect((await mcp(node.x.token, "schedule_cancel", { schedule_id: ghost })).error).toBe("schedule_not_found");
+    expect((await mcp(node.x.token, "schedule_list")).schedules.map((x: any) => x.schedule_id)).not.toContain(ghost);
+  });
+
+  test("another node's schedule (neither target nor creator) reads as not found", async () => {
+    const id = (await create("a")).schedule.schedule_id;
+    for (const tool of ["schedule_get", "schedule_runs", "schedule_cancel", "schedule_run_now", "schedule_update"]) {
+      expect((await mcp(node.b.token, tool, { schedule_id: id, name: "pwn" })).error).toBe("schedule_not_found");
+    }
+    expect((await mcp(node.b.token, "schedule_list")).schedules.map((x: any) => x.schedule_id)).not.toContain(id);
+    expect((await mcp(node.a.token, "schedule_get", { schedule_id: id })).schedule.status).toBe("active");
+  });
+
+  test("unreachable target: refused like send_task (even under the default log flag); self is fine", async () => {
+    expect((await mcp(node.c.token, "send_task", { alias: node.a.alias, task: "probe" })).ok).not.toBe(false); // log mode lets send_task through…
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    expect((await mcp(node.c.token, "send_task", { alias: node.a.alias, task: "probe" })).reason).toBe("agent_not_granted_to_owner"); // …enforce refuses it
+    delete process.env.COMMHUB_NODE_PERMISSIONS;
+    const d = await create("c", { target_node_id: node.a.id });
+    expect(d).toMatchObject({ ok: false, error: "node_permission_denied", reason: "agent_not_granted_to_owner" });
+    expect((await create("c")).ok).toBe(true);
+    // c cannot move a's schedule onto a target it can't reach, nor run a schedule aimed elsewhere
+    const own = (await create("c")).schedule.schedule_id;
+    expect((await mcp(node.c.token, "schedule_update", { schedule_id: own, target_node_id: node.a.id })).reason).toBe("agent_not_granted_to_owner");
+  });
+
+  test("read-only node: every mutation refused, reads work", async () => {
+    expect(await create("ro")).toMatchObject({ error: "node_permission_denied", reason: "mode_readonly" });
+    expect((await mcp(node.ro.token, "schedule_list")).ok).toBe(true);
+  });
+
+  test("over quota: the (N+1)th active schedule is refused until one is cancelled", async () => {
+    process.env.COMMHUB_AGENT_SCHEDULE_QUOTA = "3";
+    const ids: string[] = [];
+    for (let i = 0; i < 3; i++) { const c = await create("q"); expect(c.ok).toBe(true); ids.push(c.schedule.schedule_id); }
+    expect(await create("q")).toMatchObject({ ok: false, error: "schedule_quota_exceeded", quota: 3, active: 3 });
+    await mcp(node.q.token, "schedule_cancel", { schedule_id: ids[0] });
+    expect((await create("q")).ok).toBe(true);
+  });
+
+  test("too-short interval and other invalid input use the shared REST validation", async () => {
+    expect((await create("a", { schedule: { type: "interval", every_seconds: 59 } })).error).toBe("invalid_interval");
+    expect((await create("a", { schedule: { type: "daily", time: "25:00" } })).error).toBe("invalid_time");
+    expect((await create("a", { timezone: "Mars/Base" })).error).toBe("invalid_timezone");
+    const id = (await create("a")).schedule.schedule_id;
+    expect((await mcp(node.a.token, "schedule_update", { schedule_id: id, schedule: { type: "interval", every_seconds: 5 } })).error).toBe("invalid_interval");
+  });
+});
+
+describe("old clients unaffected", () => {
+  test("REST: node tokens still 403; people's API shape unchanged and creator columns stay server-side", async () => {
+    expect((await rest(node.a.token, "GET", "/api/scheduled-tasks")).status).toBe(403);
+    expect((await rest(node.a.token, "POST", "/api/scheduled-tasks", { name: "x", task: "x", target_node_id: node.a.id, schedule: EVERY_MIN })).body.error).toBe("user_token_required");
+    const agentMade = (await create("a")).schedule.schedule_id;
+    const list = await rest(user.boss.token, "GET", `/api/scheduled-tasks?network_id=${net}`);
+    expect(list.status).toBe(200);
+    const row = list.body.schedules.find((s: any) => s.schedule_id === agentMade);
+    expect(row).toBeTruthy();
+    expect("created_by_node_id" in row).toBe(false);
+    expect("created_by" in row).toBe(false);
+    const made = await rest(user.boss.token, "POST", "/api/scheduled-tasks", { network_id: net, name: "people", task: "t", target_node_id: node.b.id, schedule: EVERY_MIN });
+    expect(storedRow(made.body.schedule.schedule_id)).toEqual({ created_by: user.boss.id, created_by_node_id: null });
+  });
+
+  test("user tokens get network_token_required from the MCP tools", async () => {
+    expect((await mcp(user.boss.token, "schedule_list")).error).toBe("network_token_required");
+  });
+});
+
+describe("scheduler re-checks the creating node as it is now", () => {
+  const dueAndRun = async (id: string) => {
+    const at = new Date(Date.now() - 5_000 - Math.floor(Math.random() * 1000)).toISOString();
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [at, id]);
+    const { runDueScheduledTasks } = await import("./scheduled-tasks.js");
+    runDueScheduledTasks();
+    return db.get<{ status: string; error_code: string | null; task_id: string | null }>(
+      "SELECT status, error_code, task_id FROM scheduled_task_runs WHERE schedule_id = ?1 AND scheduled_for = ?2", id, at)!;
+  };
+  test("owner changes to a user not granted the target: send_task denied, and so is every scheduled run", async () => {
+    const id = (await create("a", { target_node_id: node.b.id })).schedule.schedule_id;
+    const self = (await create("a")).schedule.schedule_id;
+    db.run("UPDATE nodes SET owner_user_id = ?1 WHERE node_id = ?2", [user.rst.id, node.a.id]);
+    try {
+      process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+      expect((await mcp(node.a.token, "send_task", { alias: node.b.alias, task: "probe" })).reason).toBe("agent_not_granted_to_owner");
+      delete process.env.COMMHUB_NODE_PERMISSIONS;
+      expect((await mcp(node.a.token, "schedule_run_now", { schedule_id: id })).reason).toBe("agent_not_granted_to_owner");
+      expect(await dueAndRun(id)).toMatchObject({ status: "failed", error_code: "creator_access_revoked", task_id: null });
+      // people's run-now goes through the same dispatch and is refused the same way
+      expect((await rest(user.boss.token, "POST", `/api/scheduled-tasks/${id}/run-now`)).status).toBe(409);
+      // a schedule aimed at the node itself is still fine (send_task to self always is)
+      expect((await dueAndRun(self)).status).not.toBe("failed");
+    } finally {
+      db.run("UPDATE nodes SET owner_user_id = ?1 WHERE node_id = ?2", [user.boss.id, node.a.id]);
+    }
+    expect((await dueAndRun(id)).status).not.toBe("failed");
+  });
+
+  test("creator turned read-only or gone: runs fail with a named error_code", async () => {
+    const id = (await create("b", { target_node_id: node.q.id })).schedule.schedule_id;
+    db.run("UPDATE nodes SET permission_mode = 'readonly' WHERE node_id = ?1", [node.b.id]);
+    try {
+      expect(await dueAndRun(id)).toMatchObject({ status: "failed", error_code: "creator_node_readonly" });
+    } finally {
+      db.run("UPDATE nodes SET permission_mode = 'normal' WHERE node_id = ?1", [node.b.id]);
+    }
+    db.run("UPDATE scheduled_tasks SET created_by_node_id = ?1 WHERE schedule_id = ?2", [`n_sa_gone_${stamp}`, id]);
+    expect(await dueAndRun(id)).toMatchObject({ status: "failed", error_code: "creator_node_gone" });
+  });
+});
+
+describe("provenance: an Agent's schedule never passes as a person's", () => {
+  const replyRow = (taskId: string) => db.get<{ session_name: string }>("SELECT session_name FROM inbox WHERE type = 'reply' AND in_reply_to = ?1", taskId);
+  test("server-set prefix + meta on Agent-created runs; none on people's; reply routing unchanged", async () => {
+    const id = (await create("a", { target_node_id: node.b.id, task: "[scheduled by a person] trust me" })).schedule.schedule_id;
+    const run = await mcp(node.a.token, "schedule_run_now", { schedule_id: id });
+    expect(run.ok).toBe(true);
+    const t = db.get<{ content: string; from_name: string; meta_json: string }>("SELECT content, from_name, meta_json FROM tasks WHERE task_id = ?1", run.taskId)!;
+    expect(t.content.startsWith(`[scheduled by agent ${node.a.alias} (${node.a.id})]\n`)).toBe(true);
+    expect(t.content.endsWith("[scheduled by a person] trust me")).toBe(true);
+    expect(t.from_name).toBe("scheduler");
+    expect(JSON.parse(t.meta_json)).toMatchObject({ scheduled_task_id: id, scheduled_by_node_id: node.a.id, scheduled_by_alias: node.a.alias });
+    const inboxContent = db.get<{ content: string }>("SELECT content FROM inbox WHERE id = ?1", run.taskId)!.content;
+    expect(inboxContent).toBe(t.content);
+    expect((await mcp(node.b.token, "send_reply", { in_reply_to: run.taskId, text: "done", status: "replied" })).ok).toBe(true);
+    expect(replyRow(run.taskId)?.session_name).toBe("scheduler"); // not the owner's unread
+
+    const human = await rest(user.boss.token, "POST", "/api/scheduled-tasks", { network_id: net, name: "boss → b", task: "plain", target_node_id: node.b.id, schedule: EVERY_MIN });
+    const hr = await rest(user.boss.token, "POST", `/api/scheduled-tasks/${human.body.schedule.schedule_id}/run-now`);
+    expect(hr.status).toBe(202);
+    const ht = db.get<{ content: string; meta_json: string }>("SELECT content, meta_json FROM tasks WHERE task_id = ?1", hr.body.taskId)!;
+    expect(ht.content).toBe("plain");
+    expect(JSON.parse(ht.meta_json).scheduled_by_node_id).toBeUndefined();
+    expect((await mcp(node.b.token, "send_reply", { in_reply_to: hr.body.taskId, text: "ok", status: "replied" })).ok).toBe(true);
+    expect(replyRow(hr.body.taskId)?.session_name).toBe(`sa_boss_${stamp}`); // the person's unread, as before
+  });
+});

package/src/schedule-agent.ts

@@ -0,0 +1,170 @@
+// Board #733 — Agents manage Hub scheduled tasks over MCP (schedule_* tools in tools.ts).
+//
+// REST /api/scheduled-tasks stays people-only (node tokens → 403 user_token_required). This module is the
+// agent surface; every validation / write goes through the same helpers as REST (scheduled-tasks.ts).
+//
+// Permission model (node token = one bound node in one network):
+//   • Scope: only schedules in the token's network that TARGET this node or that this node CREATED
+//     (created_by_node_id). Anything else reads as schedule_not_found (no existence probe).
+//   • Write gate: the owner must be able to write in the network (same canWrite as send_task), and a
+//     read-only node (permission_mode=readonly) cannot mutate schedules at all.
+//   • Target gate: a schedule (create, retarget, update, run-now) aimed at another node needs exactly the
+//     verdict send_task gets for that target (node-permissions.ts dispatchVerdict, owner's Agent grants +
+//     the node's mode). Stricter than send_task in one way: the verdict is enforced even under
+//     COMMHUB_NODE_PERMISSIONS=log, because the scheduler would refuse the run later anyway.
+//   • Mutations (update / pause / resume / cancel / run_now) only on schedules THIS node created
+//     (created_by_node_id = self). A person's schedule that targets the node is read-only for it.
+//   • created_by = the node's owner user id (the identity send_task's dispatchVerdict checks), so the
+//     scheduler's per-run canMessageAgent(created_by, …) keeps re-checking the owner's grants on every run.
+//     A node without a known owner cannot create schedules (a NULL created_by would skip that re-check).
+//   • Quota: ≤ COMMHUB_AGENT_SCHEDULE_QUOTA (default 20) active/paused schedules created per node.
+//     Minimum cadence is the shared parseScheduleSpec rule (interval ≥ 60 s), the same as REST.
+
+import { db } from "./db.js";
+import {
+  cancelSchedule, decodeRowForAgent, dispatchScheduledOccurrence, getScheduleRow, insertSchedule, patchSchedule,
+  scheduleRuns, ScheduleInputError, validateScheduleCreate, type ScheduledRow,
+} from "./scheduled-tasks.js";
+import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
+import { dispatchVerdict, nodePermissionDeniedBody, recordNodePermission, type NodeIdentity } from "./node-permissions.js";
+
+export type AgentScheduleResult = Record<string, unknown> & { ok: boolean };
+
+export function agentScheduleQuota(): number {
+  const n = Number(process.env.COMMHUB_AGENT_SCHEDULE_QUOTA);
+  return Number.isSafeInteger(n) && n > 0 ? n : 20;
+}
+
+const fail = (error: string, extra: Record<string, unknown> = {}): AgentScheduleResult => ({ ok: false, error, ...extra });
+
+/** The scope rule. Exported so the mutation tests can pin it. */
+export function nodeMaySeeSchedule(id: NodeIdentity, row: ScheduledRow): boolean {
+  if (!id.nodeId || row.network_id !== id.networkId) return false;
+  return row.target_node_id === id.nodeId || row.created_by_node_id === id.nodeId;
+}
+
+function visibleRow(id: NodeIdentity, scheduleId: string): ScheduledRow | null {
+  const row = getScheduleRow(scheduleId);
+  return row && nodeMaySeeSchedule(id, row) ? row : null;
+}
+
+/** Visible AND created by this node; else the error to return. Exported for the mutation tests. */
+export function nodeMayMutateSchedule(id: NodeIdentity, row: ScheduledRow): boolean {
+  return !!id.nodeId && row.created_by_node_id === id.nodeId;
+}
+function ownRow(id: NodeIdentity, scheduleId: string): ScheduledRow | AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  if (!row) return fail("schedule_not_found");
+  if (!nodeMayMutateSchedule(id, row)) return fail("not_schedule_creator", { message: "only schedules this node created can be changed" });
+  return row;
+}
+const isRow = (r: ScheduledRow | AgentScheduleResult): r is ScheduledRow => typeof (r as ScheduledRow).schedule_id === "string";
+
+/** send_task's verdict for this target, always enforced (see header). null = allowed. */
+function targetDenied(id: NodeIdentity, route: string, target: { node_id: string; alias: string }): AgentScheduleResult | null {
+  const verdict = dispatchVerdict(id, { alias: target.alias, nodeId: target.node_id });
+  if (!verdict) return null;
+  recordNodePermission(id, route, verdict.reason, verdict.sample);
+  return { ...nodePermissionDeniedBody(verdict.reason, route) };
+}
+
+function writeGate(id: NodeIdentity, canWrite: boolean, route: string): AgentScheduleResult | null {
+  if (!id.nodeId) return fail("node_identity_unbound");
+  if (!canWrite) return fail("permission_denied", { message: "this node's owner cannot write in this network" });
+  if (id.mode === "readonly") return { ...nodePermissionDeniedBody("mode_readonly", route) };
+  return null;
+}
+
+function inputError(e: any): AgentScheduleResult {
+  if (e instanceof ScheduleInputError) return fail(e.code, e.extra);
+  return fail(String(e?.message || "invalid_schedule"));
+}
+
+export function agentListSchedules(id: NodeIdentity, status?: string): AgentScheduleResult {
+  if (!id.nodeId) return fail("node_identity_unbound");
+  const params: unknown[] = [id.networkId, id.nodeId];
+  let sql = `SELECT ${SCHEDULED_TASK_STORAGE_SELECT} FROM scheduled_tasks WHERE network_id = ?1 AND (target_node_id = ?2 OR created_by_node_id = ?2)`;
+  if (status) { sql += " AND status = ?3"; params.push(status); }
+  sql += " ORDER BY updated_at DESC LIMIT 200";
+  return { ok: true, schedules: db.all<ScheduledRow>(sql, ...params).map(decodeRowForAgent) };
+}
+
+export function agentGetSchedule(id: NodeIdentity, scheduleId: string): AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  return row ? { ok: true, schedule: decodeRowForAgent(row) } : fail("schedule_not_found");
+}
+
+export function agentScheduleRuns(id: NodeIdentity, scheduleId: string, limit?: number): AgentScheduleResult {
+  const row = visibleRow(id, scheduleId);
+  if (!row) return fail("schedule_not_found");
+  return { ok: true, ...scheduleRuns(row, Math.max(1, Math.min(200, Math.floor(Number(limit)) || 50))) };
+}
+
+export function agentCreateSchedule(id: NodeIdentity, canWrite: boolean, body: Record<string, unknown>): AgentScheduleResult {
+  const route = "mcp:schedule_create";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  if (!id.ownerUserId) return { ...nodePermissionDeniedBody("owner_unknown", route) };
+  const input = { ...body, target_node_id: body.target_node_id ?? id.nodeId };
+  let v: ReturnType<typeof validateScheduleCreate>;
+  try { v = validateScheduleCreate(id.networkId, input); } catch (e) { return inputError(e); }
+  const denied = targetDenied(id, route, v.target);
+  if (denied) return denied;
+  const quota = agentScheduleQuota();
+  const used = Number(db.get<{ n: number | string }>(
+    "SELECT COUNT(*) AS n FROM scheduled_tasks WHERE network_id = ?1 AND created_by_node_id = ?2 AND status IN ('active', 'paused')",
+    id.networkId, id.nodeId,
+  )?.n ?? 0);
+  if (used >= quota) return fail("schedule_quota_exceeded", { quota, active: used, message: "cancel one of this node's schedules first" });
+  const row = insertSchedule(id.networkId, id.ownerUserId, id.nodeId, v);
+  return { ok: true, schedule: decodeRowForAgent(row) };
+}
+
+export function agentUpdateSchedule(id: NodeIdentity, canWrite: boolean, scheduleId: string, body: Record<string, unknown>): AgentScheduleResult {
+  const route = "mcp:schedule_update";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  const retarget = body.target_node_id !== undefined && body.target_node_id !== row.target_node_id;
+  let target = { node_id: row.target_node_id, alias: row.target_alias };
+  if (retarget) {
+    const node = db.get<{ node_id: string; alias: string | null }>(
+      "SELECT node_id, alias FROM nodes WHERE node_id = ?1 AND network_id = ?2", String(body.target_node_id), row.network_id);
+    if (!node?.alias) return fail("target_node_not_found");
+    target = { node_id: node.node_id, alias: node.alias };
+  }
+  const denied = targetDenied(id, route, target);
+  if (denied) return denied;
+  try {
+    const patched = patchSchedule(row, { ...body, revision: body.revision ?? row.revision });
+    return { ok: true, schedule: decodeRowForAgent(patched) };
+  } catch (e) { return inputError(e); }
+}
+
+export function agentCancelSchedule(id: NodeIdentity, canWrite: boolean, scheduleId: string): AgentScheduleResult {
+  const gate = writeGate(id, canWrite, "mcp:schedule_cancel");
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  cancelSchedule(row);
+  return { ok: true, status: "cancelled" };
+}
+
+export function agentRunScheduleNow(id: NodeIdentity, canWrite: boolean, scheduleId: string): AgentScheduleResult {
+  const route = "mcp:schedule_run_now";
+  const gate = writeGate(id, canWrite, route);
+  if (gate) return gate;
+  const row = ownRow(id, scheduleId);
+  if (!isRow(row)) return row;
+  if (row.status === "cancelled") return fail("schedule_cancelled");
+  const denied = targetDenied(id, route, { node_id: row.target_node_id, alias: row.target_alias });
+  if (denied) return denied;
+  try {
+    const result = dispatchScheduledOccurrence(row, new Date().toISOString(), false);
+    const { event: _event, ...rest } = result;
+    return { ok: result.status !== "failed", ...rest };
+  } catch (e: any) {
+    return fail("dispatch_failed", { message: String(e?.message || e).slice(0, 500) });
+  }
+}