@sleep2agi/commhub-server 0.9.0-preview.115 → 0.9.0-preview.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.115",
+  "version": "0.9.0-preview.116",
   "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/agent-teams-http.test.ts

@@ -0,0 +1,323 @@
+// #764:Agent 团队 —— GET/POST/PATCH/DELETE /api/networks/:id/agent-teams[/:team_id] + PUT …/nodes/:node_id/agent-team。
+// HTTP 集成测试(真实 Bun.serve,私有端口,临时库;PG 阶梯里用同一个文件跑真 PostgreSQL)。
+//
+// 夹具(全是占位名):网络 owner;成员 ownerA(管「平台」子树)、ownerB(管「运维」,和平台是兄弟)、member;
+// 节点 n1..n3(owner 建),nodeTok 是 n1 的节点令牌;另一个网络 NET2(owner2)有自己的团队和节点。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-teams-"));
+let BASE = "";
+let hub: any = null;
+const PW = "AgentTeamsPassw0rd!xyz";
+let NET = "";
+let NET2 = "";
+const U: Record<string, { token: string; id: string }> = {};
+const T: Record<string, string> = {};
+let NODE_TOKEN = "";
+const N = { n1: "node_at_1", n2: "node_at_2", n3: "node_at_3", x1: "node_at_x1" };
+let before: Record<string, string> = {};
+
+async function raw(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  return { status: res.status, text: await res.text() };
+}
+async function send(token: string, method: string, path: string, body?: unknown) {
+  const r = await raw(token, method, path, body);
+  let json: any = null;
+  try { json = JSON.parse(r.text); } catch {}
+  return { status: r.status, body: json };
+}
+const tok = (who: string) => (who === "node" ? NODE_TOKEN : U[who].token);
+const create = (who: string, name: string, parent_id?: string | null, net = NET) => send(tok(who), "POST", `/api/networks/${net}/agent-teams`, { name, parent_id });
+const patch = (who: string, id: string, body: unknown, net = NET) => send(tok(who), "PATCH", `/api/networks/${net}/agent-teams/${id}`, body);
+const del = (who: string, id: string) => send(tok(who), "DELETE", `/api/networks/${NET}/agent-teams/${id}`);
+const assign = (who: string, node: string, team_id: string | null, net = NET) => send(tok(who), "PUT", `/api/networks/${net}/nodes/${node}/agent-team`, { team_id });
+const teams = async (who = "owner") => (await send(tok(who), "GET", `/api/networks/${NET}/agent-teams`)).body.teams as any[];
+const team = async (id: string) => (await teams()).find((t) => t.id === id);
+const teamOf = async (node: string) => (await teams()).find((t) => t.members.some((m: any) => m.node_id === node))?.id ?? null;
+const denied = (r: { status: number; body: any }) => { expect(r.status).toBe(403); expect(r.body.error).toBe("agent_team_scope_denied"); };
+const snapshot = async () => ({
+  departments: (await raw(U.owner.token, "GET", `/api/networks/${NET}/departments`)).text,
+  humans: (await raw(U.owner.token, "GET", `/api/networks/${NET}/humans`)).text,
+  node: (await raw(U.owner.token, "GET", `/api/nodes/${N.n1}/config`)).text,
+});
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const stamp = Date.now();
+  const a = register(`at_owner_${stamp}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const b = register(`at_owner2_${stamp}`, PW, undefined, "Owner2");
+  U.owner2 = { token: b.token!, id: b.user!.user_id };
+  NET2 = b.network_id!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  for (const k of ["ownerA", "ownerB", "member"]) {
+    const username = `at_${k}_${stamp}`;
+    expect((await send(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    U[k] = { token: login.body.token, id: login.body.user.user_id };
+  }
+  db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", ["平台负责人", U.ownerA.id]);
+  for (const [alias, id] of [["示例节点一", N.n1], ["示例节点二", N.n2], ["示例节点三", N.n3]]) {
+    const t = createNetworkTokenForNode(U.owner.id, NET, alias, id);
+    expect(t.error ?? null).toBe(null);
+    if (id === N.n1) NODE_TOKEN = t.token!;
+  }
+  expect(createNetworkTokenForNode(U.owner2.id, NET2, "外网节点", N.x1).error ?? null).toBe(null);
+  db.run("UPDATE nodes SET display_name = ?1 WHERE node_id = ?2", ["节点一号", N.n1]);
+  // 成员默认「只看授权 Agent」:ownerA 看得见 n1、n2(看不见 n3),ownerB 看得见 n2、n3。
+  const grant = (k: string, ids: string[]) => send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U[k].id}/agent-grants`, { agent_access: "granted", grants: ids.map((node_id) => ({ node_id })) });
+  expect((await grant("ownerA", [N.n1, N.n2])).status).toBe(200);
+  expect((await grant("ownerB", [N.n2, N.n3])).status).toBe(200);
+  before = await snapshot();
+}, 60_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#764 CRUD (network owner)", () => {
+  test("empty tree, then create roots and children", async () => {
+    expect(await teams()).toEqual([]);
+    const p = await create("owner", "平台");
+    expect(p.status).toBe(201);
+    T.plat = p.body.team.id;
+    T.ops = (await create("owner", "运维")).body.team.id;
+    T.api = (await create("owner", "接口", T.plat)).body.team.id;
+    T.web = (await create("owner", "前端", T.plat)).body.team.id;
+    const t = await team(T.api);
+    expect(t).toMatchObject({ id: T.api, name: "接口", parent_id: T.plat, lead: null, owner: null, members: [] });
+  });
+  test("validation: empty name 400, duplicate sibling 409, unknown parent 400, wrong method 405", async () => {
+    expect((await create("owner", "  ")).body.error).toBe("invalid_team_name");
+    const dup = await create("owner", "接口", T.plat);
+    expect(dup.status).toBe(409); expect(dup.body.error).toBe("team_name_taken");
+    expect((await create("owner", "接口", T.ops)).status).toBe(201); // 不同上级可以同名
+    expect((await create("owner", "x", "team_nope")).body.error).toBe("parent_not_found");
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/agent-teams`, {})).status).toBe(405);
+  });
+  test("rename, sort, lead, owner; GET shows display names", async () => {
+    expect((await patch("owner", T.plat, { name: "平台组", sort: 5, lead_node_id: N.n1, owner_user_id: U.ownerA.id })).status).toBe(200);
+    expect((await patch("owner", T.ops, { owner_user_id: U.ownerB.id })).status).toBe(200);
+    const t = await team(T.plat);
+    expect(t.name).toBe("平台组"); expect(t.sort).toBe(5);
+    expect(t.lead).toEqual({ node_id: N.n1, alias: "示例节点一", display_name: "节点一号" });
+    expect(t.owner).toEqual({ user_id: U.ownerA.id, display_name: "平台负责人" });
+    expect((await team(T.ops)).owner).toEqual({ user_id: U.ownerB.id, display_name: "" });
+    const nope = await patch("owner", T.plat, { lead_node_id: "node_nope" });
+    expect(nope.status).toBe(404); expect(nope.body.error).toBe("node_not_found");
+    expect((await patch("owner", T.plat, { owner_user_id: U.owner2.id })).body.error).toBe("owner_not_member");
+    expect((await patch("owner", T.plat, {})).body.error).toBe("empty_patch");
+  });
+  test("cycle rejected (self and descendant)", async () => {
+    for (const p of [T.plat, T.api]) {
+      const r = await patch("owner", T.plat, { parent_id: p });
+      expect(r.status).toBe(400); expect(r.body.error).toBe("team_cycle");
+    }
+    expect((await team(T.plat)).parent_id).toBe(null);
+  });
+  test("delete with children rejected; leaf delete clears memberships", async () => {
+    const r = await del("owner", T.plat);
+    expect(r.status).toBe(409); expect(r.body.error).toBe("team_has_children"); expect(r.body.children).toBe(2);
+    const tmp = (await create("owner", "临时", T.ops)).body.team.id;
+    expect((await assign("owner", N.n3, tmp)).status).toBe(200);
+    expect(await teamOf(N.n3)).toBe(tmp);
+    expect((await del("owner", tmp)).status).toBe(200);
+    expect(await teamOf(N.n3)).toBe(null);
+    expect((await del("owner", tmp)).status).toBe(404);
+  });
+});
+
+describe("#764 membership set / move / clear", () => {
+  test("set, move, clear", async () => {
+    const r = await assign("owner", N.n2, T.api);
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ ok: true, node_id: N.n2, team_id: T.api });
+    expect((await team(T.api)).members).toEqual([{ node_id: N.n2, alias: "示例节点二", display_name: null }]);
+    expect((await assign("owner", N.n2, T.ops)).status).toBe(200);
+    expect(await teamOf(N.n2)).toBe(T.ops);
+    expect((await team(T.api)).members).toEqual([]);
+    expect((await assign("owner", N.n2, null)).status).toBe(200);
+    expect(await teamOf(N.n2)).toBe(null);
+    expect((await assign("owner", N.n2, "team_nope")).body.error).toBe("team_not_found");
+    expect((await assign("owner", "node_nope", T.api)).status).toBe(404);
+  });
+});
+
+describe("#764 subtree owner vs sibling owner", () => {
+  test("ownerA manages the 平台 subtree", async () => {
+    expect((await patch("ownerA", T.plat, { name: "平台", lead_node_id: N.n2 })).status).toBe(200);
+    const c = await create("ownerA", "网关", T.api);
+    expect(c.status).toBe(201);
+    T.gw = c.body.team.id;
+    expect((await patch("ownerA", T.gw, { parent_id: T.web })).status).toBe(200); // 子树内挪动
+    expect((await patch("ownerA", T.web, { owner_user_id: U.ownerA.id })).status).toBe(200); // 下级的 owner 可以换
+    expect((await assign("ownerA", N.n1, T.gw)).status).toBe(200);
+    expect((await assign("ownerA", N.n1, T.api)).status).toBe(200);
+    expect((await assign("ownerA", N.n1, null)).status).toBe(200);
+    expect((await del("ownerA", T.gw)).status).toBe(200);
+  });
+  test("ownerA cannot change its own team's owner, move it out, delete it, or create a root", async () => {
+    denied(await patch("ownerA", T.plat, { owner_user_id: U.ownerA.id }));
+    denied(await patch("ownerA", T.plat, { parent_id: T.ops }));
+    denied(await patch("ownerA", T.api, { parent_id: T.ops })); // 挪出子树
+    denied(await patch("ownerA", T.api, { parent_id: null }));
+    denied(await del("ownerA", T.plat));
+    denied(await create("ownerA", "根"));
+  });
+  test("sibling owner (ownerB) denied on the 平台 subtree", async () => {
+    denied(await patch("ownerB", T.plat, { name: "抢" }));
+    denied(await patch("ownerB", T.api, { lead_node_id: N.n3 }));
+    denied(await create("ownerB", "插", T.plat));
+    denied(await del("ownerB", T.web));
+    denied(await assign("ownerB", N.n3, T.api));
+    expect((await assign("owner", N.n3, T.api)).status).toBe(200);
+    denied(await assign("ownerB", N.n3, T.ops)); // 从别人的子树拉走
+    denied(await assign("ownerB", N.n3, null));
+    expect(await teamOf(N.n3)).toBe(T.api);
+    expect((await assign("ownerB", N.n2, T.ops)).status).toBe(200); // 自己子树里可以
+  });
+});
+
+describe("#764 read-only callers", () => {
+  test("plain member and node token: GET ok, every write denied", async () => {
+    for (const who of ["member", "node"]) {
+      expect((await send(tok(who), "GET", `/api/networks/${NET}/agent-teams`)).status).toBe(200);
+      denied(await create(who, "x"));
+      denied(await create(who, "x", T.plat));
+      denied(await patch(who, T.plat, { name: "x" }));
+      denied(await del(who, T.web));
+      denied(await assign(who, N.n1, T.plat));
+    }
+    expect((await teams("node")).find((t) => t.id === T.plat).lead.node_id).toBe(N.n2);
+  });
+  test("agent-restricted member does not see ungranted nodes", async () => {
+    const t = (await teams("member")).find((x) => x.id === T.plat);
+    expect(t.lead).toBe(null);
+    expect((await teams("member")).every((x) => x.members.length === 0)).toBe(true);
+  });
+});
+
+describe("#764 restricted subtree owner: invisible nodes are the same as missing ones", () => {
+  test("cannot set an invisible lead; cannot assign an invisible node; 404 identical to a nonexistent node", async () => {
+    expect((await assign("owner", N.n3, null)).status).toBe(200);
+    const leadHidden = await raw(U.ownerA.token, "PATCH", `/api/networks/${NET}/agent-teams/${T.api}`, { lead_node_id: N.n3 });
+    const leadMissing = await raw(U.ownerA.token, "PATCH", `/api/networks/${NET}/agent-teams/${T.api}`, { lead_node_id: "node_nope" });
+    expect(leadHidden.status).toBe(404);
+    expect(leadHidden.text).toBe(leadMissing.text);
+    expect((await team(T.api)).lead).toBe(null);
+    const putHidden = await raw(U.ownerA.token, "PUT", `/api/networks/${NET}/nodes/${N.n3}/agent-team`, { team_id: T.api });
+    const putMissing = await raw(U.ownerA.token, "PUT", `/api/networks/${NET}/nodes/node_nope/agent-team`, { team_id: T.api });
+    expect(putHidden.status).toBe(404);
+    expect(putHidden.text).toBe(putMissing.text.replace("node_nope", N.n3));
+    expect(await teamOf(N.n3)).toBe(null);
+    // 能看见的节点照常可设
+    const ok = await patch("ownerA", T.api, { lead_node_id: N.n1 });
+    expect(ok.status).toBe(200); expect(ok.body.team.lead.node_id).toBe(N.n1);
+  });
+  test("PATCH response never echoes an invisible lead", async () => {
+    expect((await patch("owner", T.web, { lead_node_id: N.n3 })).status).toBe(200);
+    const r = await patch("ownerA", T.web, { name: "前端组" });
+    expect(r.status).toBe(200);
+    expect(r.body.team.lead).toBe(null);
+    expect(JSON.stringify(r.body)).not.toContain(N.n3);
+  });
+  test("owner_not_member is only reported after the permission check", async () => {
+    denied(await patch("ownerA", T.plat, { owner_user_id: "user_nope" }));
+    denied(await patch("ownerB", T.plat, { owner_user_id: "user_nope" }));
+    denied(await patch("member", T.plat, { owner_user_id: "user_nope" }));
+  });
+});
+
+describe("#764 network owner (not a Hub admin)", () => {
+  test("owner2 manages its own network's teams end to end", async () => {
+    expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", U.owner2.id)?.role).not.toBe("admin");
+    const c = await create("owner2", "外网根", null, NET2);
+    expect(c.status).toBe(201);
+    const id = c.body.team.id;
+    const child = (await create("owner2", "外网子", id, NET2)).body.team.id;
+    expect((await patch("owner2", child, { name: "外网子组", lead_node_id: N.x1, owner_user_id: U.owner2.id }, NET2)).status).toBe(200);
+    expect((await assign("owner2", N.x1, child, NET2)).status).toBe(200);
+    expect((await assign("owner2", N.x1, null, NET2)).status).toBe(200);
+    expect((await send(U.owner2.token, "DELETE", `/api/networks/${NET2}/agent-teams/${child}`)).status).toBe(200);
+    expect((await send(U.owner2.token, "DELETE", `/api/networks/${NET2}/agent-teams/${id}`)).status).toBe(200);
+  });
+});
+
+describe("#764 cross-network", () => {
+  test("foreign network's ids are not usable here", async () => {
+    const foreign = (await create("owner2", "外网团队", null, NET2)).body.team.id;
+    expect((await patch("owner", foreign, { name: "x" })).status).toBe(404);
+    expect((await del("owner", foreign)).status).toBe(404);
+    expect((await create("owner", "x", foreign)).body.error).toBe("parent_not_found");
+    expect((await patch("owner", T.api, { parent_id: foreign })).body.error).toBe("parent_not_found");
+    expect((await assign("owner", N.n1, foreign)).body.error).toBe("team_not_found");
+    expect((await assign("owner", N.x1, T.api)).status).toBe(404);
+    expect((await patch("owner", T.api, { lead_node_id: N.x1 })).status).toBe(404);
+    expect((await assign("owner2", N.x1, T.api, NET2)).body.error).toBe("team_not_found");
+    // 非成员 / 别的网络的节点令牌
+    expect((await send(U.owner2.token, "GET", `/api/networks/${NET}/agent-teams`)).status).toBe(403);
+    expect((await send(NODE_TOKEN, "GET", `/api/networks/${NET2}/agent-teams`)).status).toBe(403);
+    expect((await (await send(U.owner2.token, "GET", `/api/networks/${NET2}/agent-teams`)).body.teams).length).toBe(1);
+  });
+});
+
+describe("#764 node delete cleans up", () => {
+  test("deleting a node removes its membership and nulls the lead", async () => {
+    expect((await assign("owner", N.n2, T.plat)).status).toBe(200);
+    expect((await send(U.owner.token, "DELETE", `/api/nodes/${N.n2}`)).status).toBe(200);
+    expect(await teamOf(N.n2)).toBe(null);
+    expect((await team(T.plat)).lead).toBe(null);
+    expect(db.get("SELECT 1 AS x FROM network_agent_team_members WHERE node_id = ?1", N.n2) ?? null).toBe(null);
+    expect(db.get("SELECT 1 AS x FROM network_agent_teams WHERE lead_node_id = ?1", N.n2) ?? null).toBe(null);
+  });
+});
+
+describe("#764 network deletion removes team rows", () => {
+  const rowsIn = (net: string) => ({
+    teams: db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_agent_teams WHERE network_id = ?1", net)!.n,
+    members: db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_agent_team_members WHERE network_id = ?1", net)!.n,
+  });
+  const seed = async (who: string) => {
+    const r = register(`at_${who}_${Date.now()}`, PW, undefined, who);
+    U[who] = { token: r.token!, id: r.user!.user_id };
+    const team_id = (await create(who, "将删", null, r.network_id!)).body.team.id;
+    db.run("INSERT INTO network_agent_team_members (network_id, node_id, team_id) VALUES (?1, ?2, ?3)", [r.network_id!, `node_gone_${who}`, team_id]);
+    expect(rowsIn(r.network_id!)).toEqual({ teams: 1, members: 1 });
+    return r.network_id!;
+  };
+  test("Hub admin deleting an empty network (NETWORK_CLEANUP_TABLES)", async () => {
+    const net = await seed("owner3");
+    const r = await send(U.owner.token, "DELETE", `/api/networks/${net}`);
+    expect(r.status).toBe(200);
+    expect(r.body.cleaned.network_agent_teams).toBe(1);
+    expect(r.body.cleaned.network_agent_team_members).toBe(1);
+    expect(rowsIn(net)).toEqual({ teams: 0, members: 0 });
+  });
+  test("owner deleting its own network", async () => {
+    const net = await seed("owner4");
+    expect((await send(U.owner4.token, "DELETE", `/api/networks/${net}`)).status).toBe(200);
+    expect(rowsIn(net)).toEqual({ teams: 0, members: 0 });
+  });
+});
+
+describe("#764 existing endpoints unchanged", () => {
+  test("departments / humans / node config byte-identical after all team operations", async () => {
+    const after = await snapshot();
+    expect(after.departments).toBe(before.departments);
+    expect(after.humans).toBe(before.humans);
+    expect(after.node).toBe(before.node);
+  });
+});

package/src/agent-teams.ts

@@ -0,0 +1,222 @@
+// Agent 团队(看板 #764,父卡 #750):Agent(节点)自己的组织树,和人的部门树(network_departments)完全独立。
+//
+// 只增:两张新表。network_agent_teams = 团队(多层,同一上级下不重名);network_agent_team_members = 节点归哪个团队
+// (一个节点最多一个团队;行存在 = 在这个团队)。nodes / 部门表一概不动,已有接口的响应不变。
+//
+// 权限(每次请求按 owner_user_id 现算,不存展开结果):
+//   网络 owner / admin、Hub 管理员:全部;
+//   团队的 owner_user_id:管这个团队的子树 —— 改名 / 排序 / 设 lead、在子树里建子团队、在子树里挪动、把节点放进 / 移出子树;
+//     但不能改自己那个团队的 owner,也不能把它挪出去(这两样要求「上级也在我的范围里」);
+//   其他成员、节点令牌:只读。viewer 当 owner 也不获得写权限。
+// 读的时候 JOIN nodes:节点删了,它的归属 / lead 自然消失;删节点的两条路径另外调 clearNodeFromAgentTeams 真删行。
+
+import { db } from "./db.js";
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS network_agent_teams (
+    network_id    TEXT NOT NULL,
+    team_id       TEXT NOT NULL,
+    name          TEXT NOT NULL,
+    parent_id     TEXT,
+    lead_node_id  TEXT,
+    owner_user_id TEXT,
+    sort          INTEGER NOT NULL DEFAULT 0,
+    created_by    TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (network_id, team_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_network_agent_teams_parent ON network_agent_teams(network_id, parent_id);
+  CREATE TABLE IF NOT EXISTS network_agent_team_members (
+    network_id TEXT NOT NULL,
+    node_id    TEXT NOT NULL,
+    team_id    TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (network_id, node_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_network_agent_team_members_team ON network_agent_team_members(network_id, team_id);
+`);
+
+export const AGENT_TEAM_SCOPE_DENIED = "agent_team_scope_denied";
+const MAX_DEPTH = 10;
+const MAX_TEAMS = 500;
+const NAME_MAX = 40;
+
+type Row = { team_id: string; name: string; parent_id: string | null; lead_node_id: string | null; owner_user_id: string | null; sort: number; created_at: string; updated_at: string };
+type Fail = { ok: false; status: number; error: string };
+const fail = (status: number, error: string): Fail => ({ ok: false, status, error });
+const nil = (v: unknown) => v === undefined || v === null || v === "";
+
+function rows(networkId: string): Row[] {
+  return db.all<Row>(
+    "SELECT team_id, name, parent_id, lead_node_id, owner_user_id, sort, created_at, updated_at FROM network_agent_teams WHERE network_id = ?1 ORDER BY sort, created_at, team_id",
+    networkId,
+  );
+}
+function one(networkId: string, id: unknown): Row | null {
+  if (typeof id !== "string") return null;
+  return rows(networkId).find((r) => r.team_id === id) ?? null;
+}
+function parentOf(networkId: string): Map<string, string | null> {
+  return new Map(rows(networkId).map((r) => [r.team_id, r.parent_id]));
+}
+/** id 和它的全部上级(从自己往上)。 */
+function chain(parent: Map<string, string | null>, id: string | null): string[] {
+  const out: string[] = [];
+  let cur = id;
+  while (cur && parent.has(cur) && !out.includes(cur)) { out.push(cur); cur = parent.get(cur) ?? null; }
+  return out;
+}
+function height(parent: Map<string, string | null>, id: string): number {
+  let h = 1;
+  for (const [c, p] of parent) if (p === id && c !== id) h = Math.max(h, 1 + height(parent, c));
+  return h;
+}
+const isMember = (networkId: string, userId: string) =>
+  !!db.get("SELECT user_id FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
+type Hidden = (n: NodeRef) => boolean;
+/** 写路径用同一个可见性判据:不在本网络、或调用者看不见(只看授权 Agent)→ 一律当不存在(同一个 404,不能拿来探测)。 */
+function visibleNode(networkId: string, nodeId: unknown, hidden: Hidden): boolean {
+  if (typeof nodeId !== "string") return false;
+  const n = db.get<NodeRef>("SELECT node_id, alias, display_name FROM nodes WHERE network_id = ?1 AND node_id = ?2", networkId, nodeId);
+  return !!n && !hidden(n);
+}
+const publicTeam = (networkId: string, id: string, hidden: Hidden) => listAgentTeams(networkId, hidden).find((t) => t.id === id)!;
+const cleanName = (raw: unknown): string | null => {
+  if (typeof raw !== "string") return null;
+  const n = raw.trim();
+  return n && [...n].length <= NAME_MAX ? n : null;
+};
+function nameTaken(networkId: string, parentId: string | null, name: string, except?: string): boolean {
+  return rows(networkId).some((r) => r.parent_id === parentId && r.name === name && r.team_id !== except);
+}
+
+/** userId 能管的团队:他当 owner 的团队及全部下级(owner 不在本网络 / 是 viewer → 空)。 */
+export function ownedScope(networkId: string, userId: string): Set<string> {
+  const role = db.get<{ role: string | null }>("SELECT role FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId)?.role;
+  const out = new Set<string>();
+  if (!role || role === "viewer") return out;
+  const all = rows(networkId);
+  const parent = new Map(all.map((r) => [r.team_id, r.parent_id]));
+  const owned = new Set(all.filter((r) => r.owner_user_id === userId).map((r) => r.team_id));
+  for (const r of all) if (chain(parent, r.team_id).some((id) => owned.has(id))) out.add(r.team_id);
+  return out;
+}
+
+type NodeRef = { node_id: string; alias: string | null; display_name: string | null };
+/** 整棵树 + 每个团队的成员 / lead / owner。hidden(node) = true 的节点不出现(只看授权 Agent 的成员)。 */
+export function listAgentTeams(networkId: string, hidden: Hidden) {
+  const nodes = new Map(db.all<NodeRef>("SELECT node_id, alias, display_name FROM nodes WHERE network_id = ?1", networkId).map((n) => [n.node_id, n]));
+  const people = new Map(db.all<{ user_id: string; username: string; display_name: string | null }>(
+    "SELECT u.user_id, u.username, u.display_name FROM network_members m JOIN users u ON u.user_id = m.user_id WHERE m.network_id = ?1", networkId,
+  ).map((u) => [u.user_id, !u.display_name || u.display_name === u.username ? "" : u.display_name])); // 同 requirements-people 的显示名规则
+  const seen = (id: string | null) => (id && nodes.has(id) && !hidden(nodes.get(id)!) ? nodes.get(id)! : null);
+  const members = new Map<string, NodeRef[]>();
+  for (const m of db.all<{ node_id: string; team_id: string }>("SELECT node_id, team_id FROM network_agent_team_members WHERE network_id = ?1 ORDER BY node_id", networkId)) {
+    const n = seen(m.node_id);
+    if (n) members.set(m.team_id, [...(members.get(m.team_id) ?? []), n]);
+  }
+  return rows(networkId).map((r) => ({
+    id: r.team_id, name: r.name, parent_id: r.parent_id, sort: r.sort,
+    lead: seen(r.lead_node_id),
+    owner: r.owner_user_id && people.has(r.owner_user_id) ? { user_id: r.owner_user_id, display_name: people.get(r.owner_user_id)! } : null,
+    members: members.get(r.team_id) ?? [],
+    created_at: r.created_at, updated_at: r.updated_at,
+  }));
+}
+
+/** scope = null 表示全管;否则是调用者能管的团队集合。 */
+export function createAgentTeam(networkId: string, actor: string, scope: Set<string> | null, hidden: Hidden, body: Record<string, unknown>) {
+  const name = cleanName(body.name);
+  if (!name) return fail(400, "invalid_team_name");
+  const parentId = nil(body.parent_id) ? null : body.parent_id;
+  if (parentId !== null && !one(networkId, parentId)) return fail(400, "parent_not_found");
+  if (scope && (parentId === null || !scope.has(parentId as string))) return fail(403, AGENT_TEAM_SCOPE_DENIED);
+  if (chain(parentOf(networkId), parentId as string | null).length + 1 > MAX_DEPTH) return fail(400, "team_too_deep");
+  if (nameTaken(networkId, parentId as string | null, name)) return fail(409, "team_name_taken");
+  if (rows(networkId).length >= MAX_TEAMS) return fail(400, "too_many_teams");
+  const id = `team_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  const sort = rows(networkId).filter((r) => r.parent_id === parentId).length;
+  db.run("INSERT INTO network_agent_teams (network_id, team_id, name, parent_id, sort, created_by) VALUES (?1, ?2, ?3, ?4, ?5, ?6)", [networkId, id, name, parentId, sort, actor]);
+  return { ok: true as const, team: publicTeam(networkId, id, hidden) };
+}
+
+export function updateAgentTeam(networkId: string, id: string, scope: Set<string> | null, hidden: Hidden, body: Record<string, unknown>) {
+  const cur = one(networkId, id);
+  if (!cur) return fail(404, "team_not_found");
+  // 子树 owner:团队本身要在范围里;改 owner / 挪动还要求它的上级也在范围里(不能改自己那个团队的 owner、不能挪出去)。
+  if (scope && !scope.has(id)) return fail(403, AGENT_TEAM_SCOPE_DENIED);
+  const parentInScope = !scope || (cur.parent_id !== null && scope.has(cur.parent_id));
+  const next = { ...cur };
+  let touched = false;
+  if (body.name !== undefined) {
+    const n = cleanName(body.name);
+    if (!n) return fail(400, "invalid_team_name");
+    next.name = n; touched = true;
+  }
+  if (body.parent_id !== undefined) {
+    const p = nil(body.parent_id) ? null : body.parent_id;
+    if (p !== null && !one(networkId, p)) return fail(400, "parent_not_found");
+    if (scope && (!parentInScope || p === null || !scope.has(p as string))) return fail(403, AGENT_TEAM_SCOPE_DENIED);
+    const parent = parentOf(networkId);
+    if (p !== null && chain(parent, p as string).includes(id)) return fail(400, "team_cycle");
+    if (chain(parent, p as string | null).length + height(parent, id) > MAX_DEPTH) return fail(400, "team_too_deep");
+    next.parent_id = p as string | null; touched = true;
+  }
+  if (body.sort !== undefined) {
+    if (!Number.isInteger(body.sort)) return fail(400, "invalid_sort");
+    next.sort = body.sort as number; touched = true;
+  }
+  if (body.lead_node_id !== undefined) {
+    const l = nil(body.lead_node_id) ? null : body.lead_node_id;
+    if (l !== null && !visibleNode(networkId, l, hidden)) return fail(404, "node_not_found");
+    next.lead_node_id = l as string | null; touched = true;
+  }
+  if (body.owner_user_id !== undefined) {
+    const o = nil(body.owner_user_id) ? null : body.owner_user_id;
+    if (!parentInScope) return fail(403, AGENT_TEAM_SCOPE_DENIED); // 先判权限,再判成员:没权限的人不能借此探测谁是成员
+    if (o !== null && (typeof o !== "string" || !isMember(networkId, o))) return fail(400, "owner_not_member");
+    next.owner_user_id = o as string | null; touched = true;
+  }
+  if (!touched) return fail(400, "empty_patch");
+  if ((next.name !== cur.name || next.parent_id !== cur.parent_id) && nameTaken(networkId, next.parent_id, next.name, id)) return fail(409, "team_name_taken");
+  db.run(
+    "UPDATE network_agent_teams SET name = ?3, parent_id = ?4, sort = ?5, lead_node_id = ?6, owner_user_id = ?7, updated_at = datetime('now') WHERE network_id = ?1 AND team_id = ?2",
+    [networkId, id, next.name, next.parent_id, next.sort, next.lead_node_id, next.owner_user_id],
+  );
+  return { ok: true as const, team: publicTeam(networkId, id, hidden) };
+}
+
+/** 只删没有子团队的团队;成员归属同一事务清掉(节点变回未分配)。 */
+export function deleteAgentTeam(networkId: string, id: string, scope: Set<string> | null) {
+  const cur = one(networkId, id);
+  if (!cur) return fail(404, "team_not_found");
+  if (scope && (cur.parent_id === null || !scope.has(cur.parent_id))) return fail(403, AGENT_TEAM_SCOPE_DENIED);
+  const children = rows(networkId).filter((r) => r.parent_id === id).length;
+  if (children) return { ...fail(409, "team_has_children"), children };
+  db.transaction(() => {
+    db.run("DELETE FROM network_agent_teams WHERE network_id = ?1 AND team_id = ?2", [networkId, id]);
+    db.run("DELETE FROM network_agent_team_members WHERE network_id = ?1 AND team_id = ?2", [networkId, id]);
+  });
+  return { ok: true as const, deleted: id };
+}
+
+/** 节点归一个团队(null = 未分配)。子树 owner:目标团队、节点当前的团队(有的话)都要在范围里。 */
+export function setNodeAgentTeam(networkId: string, nodeId: string, scope: Set<string> | null, hidden: Hidden, teamId: unknown) {
+  if (!visibleNode(networkId, nodeId, hidden)) return fail(404, "node_not_found");
+  const target = nil(teamId) ? null : teamId;
+  if (target !== null && !one(networkId, target)) return fail(400, "team_not_found");
+  const current = db.get<{ team_id: string }>("SELECT team_id FROM network_agent_team_members WHERE network_id = ?1 AND node_id = ?2", networkId, nodeId)?.team_id ?? null;
+  if (scope && ((target === null && current === null) || (target !== null && !scope.has(target as string)) || (current !== null && !scope.has(current)))) return fail(403, AGENT_TEAM_SCOPE_DENIED);
+  db.transaction(() => {
+    db.run("DELETE FROM network_agent_team_members WHERE network_id = ?1 AND node_id = ?2", [networkId, nodeId]);
+    if (target !== null) db.run("INSERT INTO network_agent_team_members (network_id, node_id, team_id) VALUES (?1, ?2, ?3)", [networkId, nodeId, target]);
+  });
+  return { ok: true as const, node_id: nodeId, team_id: target as string | null };
+}
+
+/** 节点删除时调用:清掉它的团队归属,指向它的 lead 置空。 */
+export function clearNodeFromAgentTeams(nodeId: string): void {
+  db.run("DELETE FROM network_agent_team_members WHERE node_id = ?1", [nodeId]);
+  db.run("UPDATE network_agent_teams SET lead_node_id = NULL WHERE lead_node_id = ?1", [nodeId]);
+}

package/src/auth.ts

@@ -5,7 +5,7 @@ import { db, generateId, hashPassword, verifyPassword, hashToken, generateToken,
 import { WEAK_PASSWORDS } from "./password-dict.js";
 import { checkNodeTokenClaim, legacyNodeHolder } from "./node-token-ownership.js";
 import { NETWORK_REST_COLUMNS, NETWORK_REST_SELECT, sqlColumns } from "./rest-projections.js";
-import { deleteAgentGrants, isAgentRestricted } from "./agent-access.js"; import { deleteTaskGrantsForMember, NEW_MEMBER_TASK_ACCESS, type TaskAccessMode } from "./task-access.js"; // 一行两个 import:文档钉着 auth.ts 的行号
+import { deleteAgentGrants, isAgentRestricted } from "./agent-access.js"; import { deleteTaskGrantsForMember, newMemberTaskAccess, type TaskAccessMode } from "./task-access.js"; // 一行两个 import:文档钉着 auth.ts 的行号
 
 // Round-6 A1 hardening — dummy hash for username-enumeration timing
 // close. We compute ONE scrypt hash of a throwaway password and reuse
@@ -514,7 +514,7 @@ export function deleteNetwork(userId: string, networkId: string): { ok: boolean;
     // single-network user to "ambiguous" or auto-resolve writes INTO the
     // deleted network. Remove memberships with the network.
     db.run("DELETE FROM network_members WHERE network_id = ?1", [networkId]);
-    deleteNetworkAgentGroups(networkId); deleteDepartmentsForNetwork(networkId); // #2144, #419 (one line: docs pin auth.ts line numbers)
+    deleteNetworkAgentGroups(networkId); deleteDepartmentsForNetwork(networkId); for (const t of AGENT_TEAM_TABLES) if (tableExists(t)) db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [networkId]); // #2144, #419, #764 (one line: docs pin auth.ts line numbers)
   });
   return { ok: true };
 }
@@ -749,8 +749,8 @@ export function usernameCollidesWithAgent(networkId: string, userId: string): bo
 export function addNetworkMember(networkId: string, userId: string, role: string, invitedBy?: string, opts: { agentAccess?: "all" | "granted"; taskAccess?: TaskAccessMode } = {}): { ok: boolean; error?: string } {
   if (!MEMBER_ROLES.has(role)) return { ok: false, error: "invalid role" };
   const agentAccess = opts.agentAccess === "all" ? "all" : "granted";
-  // 任务范围:新成员默认 NEW_MEMBER_TASK_ACCESS(task-access.ts 一处定义)。
-  const taskAccess: TaskAccessMode = opts.taskAccess === "all" || opts.taskAccess === "scoped" ? opts.taskAccess : NEW_MEMBER_TASK_ACCESS;
+  // 任务范围:显式传值优先;否则 newMemberTaskAccess(role)(#746:member/viewer 'scoped',admin 'all')。
+  const taskAccess: TaskAccessMode = opts.taskAccess === "all" || opts.taskAccess === "scoped" ? opts.taskAccess : newMemberTaskAccess(role);
   if (!db.get("SELECT 1 FROM users WHERE user_id = ?1", userId)) return { ok: false, error: "user not found" };
   const existing = db.get<any>("SELECT 1 FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
   if (existing) return { ok: false, error: "user already a member" };
@@ -816,7 +816,7 @@ export function joinByInvite(inviteCode: string, userId: string): { ok: boolean;
   if (usernameCollidesWithAgent(invite.network_id, userId)) return { ok: false, error: "username_collides_with_agent_alias" };
   // Add member + increment used count
   db.run("INSERT INTO network_members (network_id, user_id, role, invited_by, agent_access, task_access) VALUES (?1, ?2, ?3, ?4, 'granted', ?5)",
-    [invite.network_id, userId, invite.role, invite.created_by, NEW_MEMBER_TASK_ACCESS]);
+    [invite.network_id, userId, invite.role, invite.created_by, newMemberTaskAccess(invite.role)]);
   db.run("UPDATE network_invites SET used_count = used_count + 1 WHERE invite_code = ?1", [inviteCode]);
   // 受限成员不能持有网络令牌(resolveToken 会拒),别签一个用不了的。
   if (isAgentRestricted(userId, invite.network_id)) return { ok: true, network_id: invite.network_id, role: invite.role };
@@ -953,6 +953,7 @@ const NETWORK_CONTENT_CHECKS: Array<[label: string, sql: string]> = [
   ["pending_node_create_requests", "SELECT COUNT(*) AS cnt FROM node_create_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
   ["pending_node_start_requests", "SELECT COUNT(*) AS cnt FROM node_start_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
 ];
+const AGENT_TEAM_TABLES = ["network_agent_teams", "network_agent_team_members"]; // #764
 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",
@@ -962,6 +963,8 @@ const NETWORK_CLEANUP_TABLES = [
   "network_tags",
   // 组织架构(board #419):部门是网络本身的元数据。
   "network_departments",
+  // Agent 团队(#764):Agent 自己的组织树,同样是网络元数据。
+  ...AGENT_TEAM_TABLES,
 ];
 
 function tableExists(name: string): boolean {

package/src/db.ts

@@ -1648,6 +1648,9 @@ try { db.exec("CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_creator_node ON sc
 // success in between re-arms the alert.
 try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN failure_alert_at TEXT"); } catch {}
 try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN failure_alert_key TEXT"); } catch {}
+// Board #757 — one warning per continuous target-offline episode. The scheduler
+// clears this as soon as the target session is online again; older Hubs ignore it.
+try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN offline_alert_at TEXT"); } catch {}
 
 // RFC-036 / B4 — owner-authorized edits of node-host managed schedules.
 // This is intentionally separate from Hub scheduled_tasks: these rows are

package/src/department-heads-http.test.ts

@@ -55,7 +55,8 @@ beforeAll(async () => {
     expect((await send(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
     const login = await send("", "POST", "/api/auth/login", { username, password: PW });
     U[k] = { token: login.body.token, id: login.body.user.user_id };
-    if (scoped && role !== "admin") expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U[k].id}/task-grants`, { task_access: "scoped" })).status).toBe(200);
+    // #746 起新成员默认就是 scoped;allMember 显式放宽到 'all'(模拟升级前的老成员)。
+    if (role !== "admin") expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U[k].id}/task-grants`, { task_access: scoped ? "scoped" : "all" })).status).toBe(200);
   };
   await add("admin", "admin");
   for (const k of ["head", "parentHead", "member", "be", "sales"]) await add(k, "member");

package/src/requirements-comment-http.test.ts

@@ -58,6 +58,8 @@ beforeAll(async () => {
   const mk = async (username: string, role: string) => {
     expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
     const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    // #746 起新成员默认 scoped;这里的 member / viewer 模拟老成员('all'),scoped 那位下面再收窄。
+    expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${login.body.user.user_id}/task-grants`, { task_access: "all" })).status).toBe(200);
     return { token: login.body.token as string, id: login.body.user.user_id as string };
   };
   const stamp = Date.now();