cs-bots 0.8.0 → 0.9.1

package/src/teams.js

@@ -64,7 +64,10 @@ export const DEFAULT_TEAM_ADMIN_POLICY = 'open'
 const HUMAN_IDS = Object.freeze(['ui', 'user', 'person'])
 
 /** 合法动作（含 setPolicy：策略变更本身也是要留痕的事件）。 */
-const ACTIONS = Object.freeze(['create', 'addMember', 'removeMember', 'setRole', 'close', 'note', 'setPolicy', 'attachRoom'])
+const ACTIONS = Object.freeze(['create', 'addMember', 'removeMember', 'setRole', 'close', 'note', 'setPolicy', 'attachRoom', 'route'])
+
+/** 跨团队路由的最大 hop 数（>3 拒绝）。 */
+const ROUTE_MAX_HOP = 3
 
 /** 结构化错误。 */
 export class TeamError extends Error {
@@ -192,6 +195,12 @@ export function createTeams(ctx, config = {}) {
     if (rows.length === 0) { diagnostics.hydratedFrom = 'empty'; return }
     let skipped = 0
     for (const ev of rows) {
+      // route 事件是**审计记录**，不是团队状态变更 —— 没有 id/rev，仍要进 events
+      // 供 listRoutes 查询；只有团队状态变更事件才需要 id + rev 去重。
+      if (ev?.action === 'route') {
+        events.push(clone(ev))
+        continue
+      }
       if (!ev || typeof ev.id !== 'string' || !ev.after) { skipped += 1; continue }
       const current = entries.get(ev.id)
       if (current && Number.isFinite(ev.rev) && ev.rev <= current.rev) { skipped += 1; continue }
@@ -282,7 +291,7 @@ export function createTeams(ctx, config = {}) {
    */
   function create(input = {}) {
     assertAlive('create')
-    const { name, type, purpose, memberIds, leadId, adminPolicy, by, now } = input ?? {}
+    const { name, type, purpose, memberIds, leadId, adminPolicy, by, now, kind, nativeTeamId } = input ?? {}
     const nameNorm = requireString(name, 'name', 'create')
     if (nameNorm.length > 120) throw new TeamError(`teams.create：name ≤120 字符（收到 ${nameNorm.length}）`, 'TEAM_BAD_FIELD', { field: 'name' })
     const teamType = type ?? 'big'
@@ -301,18 +310,40 @@ export function createTeams(ctx, config = {}) {
       throw new TeamError(`teams.create：leadId ${lead} 不能同时出现在 memberIds 中（会形成自引用）`, 'TEAM_BAD_FIELD', { field: 'memberIds' })
     }
 
+    // ── kind：人类/智能体（服务层强制推导，防止伪造）─────────────────────────
+    // 由执行者身份（author）硬推导：HUMAN_IDS ⇒ 'human'，其他 ⇒ 'agent'。
+    // 显式传 kind 但与推导矛盾 ⇒ 抛 TEAM_KIND_MISMATCH（不许伪造 Boss 建的团队）。
+    const derivedKind = HUMAN_IDS.includes(author) ? 'human' : 'agent'
+    if (kind !== undefined && kind !== null && kind !== derivedKind) {
+      throw new TeamError(
+        `teams.create：kind=${JSON.stringify(kind)} 与执行者身份矛盾（执行者 ${author} ⇒ '${derivedKind}'）——不许伪造`,
+        'TEAM_KIND_MISMATCH',
+        { author, derivedKind, requested: kind },
+      )
+    }
+    const teamKind = derivedKind
+
     idCounter += 1
     const id = `team-${idCounter}`
     /** @type {Record<string, unknown>} */
     const rec = {
-      id, rev: 1, name: nameNorm, type: teamType, purpose: purpose ?? '',
+      id, rev: 1, name: nameNorm, type: teamType, kind: teamKind, purpose: purpose ?? '',
       leadId: lead, members,
+      // ── t-39 第2批 C：绑定 DSH 原生 team ──
+      // cs-bots 团队（teams.jsonl）与 DSH 原生 team（agentTeams）是**两套人模型**，
+      // 没有任何自动交集（原生 TeamId = root session id，跟我们的 team-N 毫无关系）
+      // ⇒ 必须显式绑定。这个字段是「Boss 在这个 cs-bots 房间发言时，该同步给哪个
+      // 原生团队」的唯一依据。
+      //
+      // 为什么从 cs-bots 侧配：原生侧**没有**「列出所有原生 team」的接口，
+      // 只有 `tryMembership(agent)`（从某个成员反查它所属团队）⇒ 反向枚举不可行。
+      nativeTeamId: typeof nativeTeamId === 'string' && nativeTeamId.length > 0 ? nativeTeamId : null,
       adminPolicy: policy,
       status: 'open',
       createdAt: at, createdBy: author, updatedAt: at, updatedBy: author,
     }
     commit('create', at, author, null, rec)
-    info(`[cs-bots/teams] 团队 ${id}（${nameNorm}，${teamType}）创建 by ${author}`)
+    info(`[cs-bots/teams] 团队 ${id}（${nameNorm}，${teamType}，${teamKind}）创建 by ${author}`)
     return clone(rec)
   }
 
@@ -502,6 +533,209 @@ export function createTeams(ctx, config = {}) {
     return clone(next)
   }
 
+  // ── A. 跨团队路由（t-39 第2批 · bot_team_route 的服务层本体）────────────────
+
+  /**
+   * 解析并校验一条跨团队路由目标 —— **只做决定，不做投递**。
+   *
+   * 为什么拆开：投递要 dispatcher（wakes.jsonl / dedup / 背压），而 dispatcher 挂在
+   * `src/tools.js` 的组装层（`s.dispatcher`）。若把投递塞进 TeamsService，本服务就得
+   * 反向依赖 dispatcher —— 两个域服务互指会让装配顺序变成硬约束。所以这里只回答
+   * 「路由到谁」，投递由工具层完成，语义边界清晰。
+   *
+   * 失败一律**返回可读的 refused**，不抛裸错 —— 契约要求 `{ok:false, decision:'refused',
+   * reason}` 而不是异常（异常在工具层会被包成 `tool-crashed`，理由就丢了）。
+   *
+   * @param {{ fromTeam?: string, toTeam?: string, toBot?: string,
+   *           taskId: string, text?: string, hop?: number, by: string }} input
+   * @returns {{ ok: true, decision: 'accepted', to: { kind: 'team'|'bot', id: string,
+   *            leadId: string, name: string }, hop: number, dedupKey: string,
+   *            fromTeam: string }
+   *          | { ok: false, decision: 'refused', reason: string, to?: object, hop?: number }}
+   */
+  function resolveRoute(input = {}) {
+    assertAlive('resolveRoute')
+    const { fromTeam, toTeam, toBot, taskId, hop, by } = input ?? {}
+    const author = requireString(by, 'by', 'resolveRoute')
+
+    // ── 参数校验：全部**可读拒绝** ──
+    if (typeof taskId !== 'string' || taskId.trim() === '') {
+      return { ok: false, decision: 'refused', reason: 'ROUTE_TASK_ID_REQUIRED' }
+    }
+    if (!toTeam && !toBot) {
+      return { ok: false, decision: 'refused', reason: 'ROUTE_TARGET_REQUIRED' }
+    }
+    if (toTeam && toBot) {
+      return { ok: false, decision: 'refused', reason: 'ROUTE_TARGET_AMBIGUOUS' }
+    }
+
+    // ── hop 计数：>3 拒绝（环路防护第一道闸）──
+    const hopCount = Number.isFinite(Number(hop)) ? Math.max(0, Math.trunc(Number(hop))) : 0
+    if (hopCount > ROUTE_MAX_HOP) {
+      return { ok: false, decision: 'refused', reason: 'ROUTE_HOP_EXCEEDED', hop: hopCount }
+    }
+
+    // ── 解析目标团队 / 目标 lead ──
+    let targetTeamId = null
+    let targetLeadId = null
+    let targetName = null
+
+    if (toTeam) {
+      const team = entries.get(toTeam)
+      if (!team) return { ok: false, decision: 'refused', reason: 'ROUTE_TARGET_NOT_FOUND', hop: hopCount }
+      targetTeamId = team.id
+      targetLeadId = team.leadId ?? null
+      targetName = team.name
+    } else {
+      // toBot：必须**属于**某个 cs-bots 团队（leadId 或成员），否则无法确定唤醒谁
+      for (const t of entries.values()) {
+        if (t.leadId === toBot || (Array.isArray(t.members) && t.members.includes(toBot))) {
+          targetTeamId = t.id
+          targetLeadId = t.leadId ?? null
+          targetName = t.name
+          break
+        }
+      }
+      if (!targetTeamId) {
+        return { ok: false, decision: 'refused', reason: 'ROUTE_TARGET_NOT_FOUND', hop: hopCount }
+      }
+    }
+
+    // 目标团队必须有人可唤 —— 契约：**只唤 leadId**，不 wake 全部成员
+    if (!targetLeadId) {
+      return {
+        ok: false,
+        decision: 'refused',
+        reason: 'ROUTE_NO_LEAD',
+        to: { kind: toTeam ? 'team' : 'bot', id: targetTeamId, name: targetName },
+        hop: hopCount,
+      }
+    }
+
+    const fromKey = fromTeam ?? author
+
+    // 去重键：交给 dispatcher 的 dedupKey 机制（不自己造一套）。
+    // **不含 hop** —— 这样同一 (from→to, taskId) 的重复路由会命中 dispatcher 的
+    // IdempotencySet 而被判 skipped，正是「A→B→A→B 第 3 跳被拒」的实现路径。
+    const dedupKey = `route:${fromKey}:${targetTeamId}:${taskId}`
+
+    return {
+      ok: true,
+      decision: 'accepted',
+      to: { kind: toTeam ? 'team' : 'bot', id: targetTeamId, leadId: targetLeadId, name: targetName },
+      hop: hopCount,
+      dedupKey,
+      fromTeam: fromKey,
+    }
+  }
+
+  /**
+   * **一条龙路由**：决定 → 投递 → 留痕。工具层（`bot_team_route`）与 HTTP 层
+   * （`POST /teams/route`）**共用这一个方法**。
+   *
+   * 为什么必须共用：两条路各写一遍，行为就会漂 —— 工具层去重了、HTTP 层没去重，
+   * 或者一边先投后记、一边先记后投。契约要求「跨团队路由」只有一套语义，
+   * 所以序列编排只能有一处。
+   *
+   * 依赖注入：`dispatcher` 由调用方传入（TeamsService 不反向依赖 dispatcher，
+   * 否则两个域服务互指，装配顺序变成硬约束）。
+   *
+   * @param {{ fromTeam?: string, toTeam?: string, toBot?: string, taskId?: string,
+   *           text?: string, hop?: number, by: string, now?: number,
+   *           dispatcher: object }} input
+   * @returns {object} `{ok, decision, to, hop, wake, reason?, taskId}` —— DecisionKind 语义
+   */
+  function deliverRoute(input = {}) {
+    assertAlive('deliverRoute')
+    const { dispatcher, taskId: rawTaskId, by, now, text, hop } = input ?? {}
+    const author = requireString(by, 'by', 'deliverRoute')
+
+    // taskId 缺省生成：页面上的「发协作请求」不一定挂任务（Boss 只是想跨团队喊一句）。
+    // 每轮生成独立 id ⇒ 不会被 dispatcher 误判重（同一轮重发才判重，由调用方复用同一 id）。
+    const taskId = typeof rawTaskId === 'string' && rawTaskId.trim() !== ''
+      ? rawTaskId.trim()
+      : `route-${normalizeNow(now, 'deliverRoute')}`
+
+    const decision = resolveRoute({ ...input, taskId, by: author })
+    if (!decision.ok) return { ...decision, taskId }
+
+    if (!dispatcher || typeof dispatcher.notify !== 'function') {
+      return { ok: false, decision: 'refused', reason: 'ROUTE_NO_DISPATCHER', to: decision.to, hop: decision.hop, taskId }
+    }
+
+    // 投递：只唤对方 leadId；dedupKey 交给 dispatcher（不自己造去重）；
+    // teamId 让 byTeam() 能按团队聚合唤醒成本。
+    const wakeText = text ?? `[cs-bots 跨团队路由] ${decision.fromTeam} → ${decision.to.id}`
+      + `（lead=${decision.to.leadId}, hop=${decision.hop}, task=${taskId}）`
+    const wake = dispatcher.notify({
+      target: decision.to.leadId,
+      reason: 'room-message',
+      dedupKey: decision.dedupKey,
+      text: wakeText,
+      teamId: decision.to.id,
+    })
+
+    // 留痕在投递之后（投递已有 dedupKey 记在 wakes.jsonl；这里记的是「路由决策」本身）。
+    // 落盘失败**必须显式报错**，不能吞 —— 「投了没记」会让环路统计漏跳。
+    try {
+      recordRoute({ to: decision.to, fromTeam: decision.fromTeam, taskId, text, hop: decision.hop, by: author, now, wake })
+    } catch (recordError) {
+      return {
+        ok: false, decision: 'refused', reason: 'ROUTE_RECORD_FAILED',
+        message: recordError?.message ?? String(recordError),
+        to: decision.to, hop: decision.hop, wake, taskId,
+      }
+    }
+
+    return { ok: true, decision: 'delivered', to: decision.to, hop: decision.hop, wake, taskId }
+  }
+
+  /**
+   * 把已经做出的路由决定**落盘留痕**（intent-first：先记后投）。
+   *
+   * 顺序不可颠倒：`记了没投` 是可见可重试的；`投了没记` 则绕过限额/审计，
+   * 让环路防护统计不到这一跳 —— 那正是要防的。
+   * @param {{ to: object, fromTeam: string, taskId: string, text?: string, hop: number,
+   *           by: string, now?: number, wake?: object }} input
+   */
+  function recordRoute(input = {}) {
+    assertAlive('recordRoute')
+    const { to, fromTeam, taskId, text, hop, by, now, wake } = input ?? {}
+    const author = requireString(by, 'by', 'recordRoute')
+    const at = normalizeNow(now, 'recordRoute')
+    const rec = {
+      toKind: to?.kind ?? 'team',
+      toId: to?.id ?? null,
+      toLeadId: to?.leadId ?? null,
+      toName: to?.name ?? null,
+      fromTeam: fromTeam ?? null,
+      taskId,
+      text: text ?? '',
+      hop: Number(hop ?? 0),
+      wake: wake ?? null,
+      at,
+    }
+    if (!appendJsonl(jsonlPath, { action: 'route', at, by: author, before: null, after: rec })) {
+      throw new TeamError(`teams.recordRoute：事件追加失败（${jsonlPath}）—— 拒绝「投了没记」`, 'TEAM_APPEND_FAILED', { action: 'route' })
+    }
+    events.push({ action: 'route', at, by: author, before: null, after: clone(rec) })
+    info(`[cs-bots/teams] route ${rec.fromTeam} → ${rec.toId}（lead=${rec.toLeadId}, hop=${rec.hop}, task=${taskId}）by ${author}`)
+    return clone(rec)
+  }
+
+  /**
+   * 查 route 审计记录（按 toId / taskId / fromTeam 过滤）。
+   * @param {{ toId?: string, fromTeam?: string, taskId?: string }} [query]
+   */
+  function listRoutes(query = {}) {
+    assertAlive('listRoutes')
+    let rows = events.filter((e) => e.action === 'route').map((e) => ({ ...e.after, by: e.by, at: e.at }))
+    if (query?.toId !== undefined && query?.toId !== null) rows = rows.filter((r) => r.toId === query.toId)
+    if (query?.fromTeam !== undefined && query?.fromTeam !== null) rows = rows.filter((r) => r.fromTeam === query.fromTeam)
+    if (query?.taskId !== undefined && query?.taskId !== null) rows = rows.filter((r) => r.taskId === query.taskId)
+    return clone(rows)
+  }
+
   // ── API：读 ────────────────────────────────────────────────────────────────
 
   function list(query = {}) {
@@ -513,6 +747,113 @@ export function createTeams(ctx, config = {}) {
     return clone(rows.map((r) => (r.adminPolicy ? r : { ...r, adminPolicy: DEFAULT_TEAM_ADMIN_POLICY })))
   }
 
+  /**
+   * 按房间 id 反查绑定它的团队（t-39 第2批 C）。
+   *
+   * 用途：Boss 在 cs-bots 团队的议事厅发言 ⇒ 知道该同步给哪个原生 team。
+   * 一个房间只可能被一个团队绑定（`attachRoom` 是 CAS 单值覆盖）。
+   *
+   * @param {string} roomId
+   * @returns {object|null} 团队记录（含 `nativeTeamId`），没绑定 ⇒ null
+   */
+  function findByRoom(roomId) {
+    assertAlive('findByRoom')
+    if (typeof roomId !== 'string' || roomId.length === 0) return null
+    for (const t of entries.values()) {
+      if (t.roomId === roomId) return get(t.id)
+    }
+    return null
+  }
+
+  /**
+   * **发言同步给 DSH 原生 team 的 Lead**（t-39 第2批 C · Boss 体验 item 5）。
+   *
+   * ### 为什么要这个
+   * Boss 在 cs-bots 团队的议事厅发言，原生 team 的 Lead 感知不到 —— 因为两套
+   * 团队模型是**分离的**（cs-bots `teams.jsonl` vs DSH `agentTeam`），消息不会自动
+   * 跨过去。这个方法负责把这条链补上。
+   *
+   * ### 链路（lead 批准的实现方向，2026-11-11）
+   *   Boss 在 cs-bots 房间发言 → `findByRoom(roomId)` 反查绑定团队
+   *   → 取该团队的 `nativeTeamId` → 投递给原生 team 的 Lead。
+   *
+   * **为什么投递 target = nativeTeamId 就是投递给 Lead**：
+   * DSH 原生 `TeamId` 就是 root session id（`TeamId(id: SessionId|string)`，
+   * 且 `tryMembership(agent).root.id === membership.id`）。所以原生 team 的 Lead
+   * 会话 id 就等于这个 TeamId。投递 root = 投递 Lead，走的是 root 路径，**合法**。
+   *
+   * ### 为什么用 dispatcher 而不是 agentTeams.sendMessage
+   * 官方 `sendMessage(caller, ...)` 需要 Lead 身份的 `Agent` 作为凭证，且校验
+   * Lead→child 边 —— 队友不能给 Lead 发消息。cs-bots 是 root session，用
+   * `dispatcher.followup(root)` 投递是 root 路径，不冒充任何人。
+   *
+   * ### 诚实原则（硬要求）
+   * 同步失败**绝不**返回 `ok:false`，也**绝不**假装成功：
+   * `{ ok: true, synced: false, reason }` —— 房间消息本身已经成功落盘，
+   * 同步是附加动作，失败必须可见但不影响消息。
+   *
+   * reason 取值（给前端 A 的确定形状）：
+   *   - `NATIVE_TEAM_NOT_FOUND`  房间没绑任何 cs-bots 团队
+   *   - `NATIVE_TEAM_NOT_BOUND`  团队存在但 `nativeTeamId` 为 null（要先配置绑定）
+   *   - `SYNC_DISPATCHER_UNAVAILABLE`  装配层没注入 dispatcher
+   *   - `SYNC_DEDUP_HIT`  这条消息之前已同步过（幂等，不算新同步也不算失败）
+   *   - `SYNC_DELIVERY_FAILED`  投递失败（dispatcher 返回 failed）
+   *   - `SYNCED`  同步成功
+   *
+   * @param {{ roomId: string, messageId?: string, text?: string, by: string,
+   *           dispatcher: object }} input
+   * @returns {{ ok: true, synced: boolean, reason: string,
+   *            teamId?: string, nativeTeamId?: string, leadId?: string, wake?: object }}
+   */
+  function syncToNativeLead(input = {}) {
+    assertAlive('syncToNativeLead')
+    const { roomId, messageId, text, by, dispatcher } = input ?? {}
+    requireString(by, 'by', 'syncToNativeLead')
+
+    // ① 反查房间属于哪个 cs-bots 团队（一个房间只可能被一个团队绑定）
+    const team = findByRoom(roomId)
+    if (!team) {
+      return { ok: true, synced: false, reason: 'NATIVE_TEAM_NOT_FOUND', detail: '房间未绑定任何 cs-bots 团队' }
+    }
+
+    // ② 团队有没有绑定 DSH 原生 team —— 这是同步的唯一依据
+    if (!team.nativeTeamId) {
+      return {
+        ok: true, synced: false, reason: 'NATIVE_TEAM_NOT_BOUND',
+        teamId: team.id, detail: '团队未绑定 DSH 原生 team，请先在团队详情里配置 nativeTeamId',
+      }
+    }
+
+    // ③ dispatcher 在不在（缺失 ⇒ 无法投递，但不是消息本身的错）
+    if (!dispatcher || typeof dispatcher.notify !== 'function') {
+      return {
+        ok: true, synced: false, reason: 'SYNC_DISPATCHER_UNAVAILABLE',
+        teamId: team.id, nativeTeamId: team.nativeTeamId,
+      }
+    }
+
+    // ④ 投递给原生 team 的 Lead（root session id == nativeTeamId）
+    //    dedupKey 用消息 id —— 同一消息重复 post 不会重复同步（幂等）。
+    const dedupKey = `lead-sync:${messageId ?? roomId}:${team.id}`
+    const wake = dispatcher.notify({
+      target: team.nativeTeamId,
+      reason: 'room-message',
+      dedupKey,
+      text: `[cs-bots 团队发言同步] 「${team.name}」房间新消息：${String(text ?? '').slice(0, 200)}`,
+      teamId: team.id,
+    })
+
+    // ⑤ 诚实汇报：只有真的发出去才算 synced:true
+    const leadId = team.nativeTeamId
+    if (wake?.ok === true && wake?.result === 'sent') {
+      return { ok: true, synced: true, reason: 'SYNCED', teamId: team.id, nativeTeamId: leadId, leadId, wake }
+    }
+    if (wake?.ok === true && wake?.result === 'skipped') {
+      return { ok: true, synced: false, reason: 'SYNC_DEDUP_HIT', teamId: team.id, nativeTeamId: leadId, leadId, wake }
+    }
+    return { ok: true, synced: false, reason: 'SYNC_DELIVERY_FAILED', teamId: team.id, nativeTeamId: leadId, leadId, wake }
+  }
+
   function get(id) {
     assertAlive('get')
     const t = entries.get(id)
@@ -548,8 +889,16 @@ export function createTeams(ctx, config = {}) {
     // 契约 §3：把「议事厅」绑到团队上。api.js 的 ensureTeamRoom 会调它；
     // 不导出 ⇒ 房间建好了但团队记不住 roomId，重启后自动配厅就永远重配一遍。
     attachRoom,
+    // 契约 t-39：跨团队路由（只决定 + 留痕，投递由工具层用 dispatcher 完成）
+    resolveRoute,
+    recordRoute,
+    listRoutes,
+    // 一条龙：工具层与 HTTP 层共用的唯一序列编排
+    deliverRoute,
     list,
     get,
+    findByRoom,
+    syncToNativeLead,
     stats,
     replay,
     diagnostics: () => clone(diagnostics),

package/src/tools.js

@@ -94,6 +94,18 @@ const DEFS = [
         priority: { type: 'number', description: '优先级（数值越大越先）' },
         dueAt: { type: 'number', description: '截止时间（epoch ms）' },
         sourceSeq: { type: 'string', description: '幂等键：同键重复创建只产生一条' },
+        source: {
+          type: 'string',
+          enum: ['human', 'ai'],
+          description: '谁下的令：human=人（Boss）/ ai=智能体。不传则按调用者身份自动推断。',
+        },
+        channel: {
+          type: 'string',
+          enum: ['user', 'session', 'external'],
+          description:
+            '从哪个入口下的令（t-40 需求①）：user=用户在页面手工建 / session=会话里产出 / '
+            + 'external=外部渠道接入（预留）。不传则按 source 推断（人→user，智能体→session）。',
+        },
         expectedComplexity: {
           type: 'string',
           enum: ['T0', 'T1', 'T2', 'T3'],
@@ -144,7 +156,9 @@ const DEFS = [
   },
   {
     name: 'bot_task_list',
-    description: '列出 cs-bots 任务板上的任务。默认不含已删除（tombstone）；传 status 可只看某状态。',
+    description:
+      '列出 cs-bots 任务板上的任务。默认不含已删除（tombstone）；传 status 可只看某状态；'
+      + '传 source / channel 可按「谁下的令 / 从哪个入口下的令」筛选（t-40 需求①）。',
     parameters: {
       type: 'object',
       properties: {
@@ -153,12 +167,46 @@ const DEFS = [
           enum: ['pending', 'in_progress', 'completed', 'blocked', 'deleted'],
           description: '只看该状态',
         },
+        source: { type: 'string', enum: ['human', 'ai'], description: '只看该来源（人 / 智能体）' },
+        channel: {
+          type: 'string',
+          enum: ['user', 'session', 'external'],
+          description: '只看该渠道（用户手工 / 会话产出 / 外部接入）',
+        },
       },
       additionalProperties: false,
     },
     run: (s, a) => {
       if (!s.board) return failure('board-unavailable')
-      return success({ tasks: s.board.list(a?.status ? { status: a.status } : {}) })
+      // 只把**给了的**过滤条件传下去：给 undefined 会命中 `!== null` 分支造成误筛
+      const opts = {}
+      if (a?.status) opts.status = a.status
+      if (a?.source) opts.source = a.source
+      if (a?.channel) opts.channel = a.channel
+      return success({ tasks: s.board.list(opts) })
+    },
+  },
+  {
+    name: 'bot_task_room',
+    description:
+      '给任务开一个议事厅（群聊房间）。**长任务在建任务时就自动有了**，本工具用于：' +
+      '① 短任务按需开（Boss：「短任务默认不建房间，防止房间爆炸，需要时再建」）；' +
+      '② 长任务的议事厅丢了/想补一个。幂等：已有就复用，不会重复建。' +
+      '需要任务有负责人（没负责人就没有团队可挂）。',
+    parameters: {
+      type: 'object',
+      properties: { id: { type: 'string', description: '任务 id' } },
+      required: ['id'],
+      additionalProperties: false,
+    },
+    run: async (s, a, exec) => {
+      if (typeof s.openTaskRoom !== 'function') return failure('task-room-unavailable', { hint: '后端未注入 openTaskRoom' })
+      try {
+        const r = await s.openTaskRoom(String(a.id ?? ''), callerOf(exec))
+        return r.ok ? success(r) : failure('task-room-failed', { message: r.reason })
+      } catch (error) {
+        return failure(error?.code ?? 'task-room-failed', { message: String(error?.message ?? error) })
+      }
     },
   },
   {
@@ -428,6 +476,31 @@ const DEFS = [
       return success({ bots: [...live, ...retired] })
     },
   },
+  {
+    name: 'bot_roster_purge',
+    description:
+      '把**已退役**的 Bot 从注册表里真正清掉（retire 只是标记，记录会一直留着）。' +
+      '**只能清已退役的**：在役 Bot 一律拒绝。**不删工作目录、不杀会话** —— ' +
+      '只移除注册表记录，cwd 里的产物原样保留。清理动作在审计流里留档，可追溯。' +
+      'allRetired:true 一次清干净；或用 ids 指定。（**官方 roster 没有这个能力**）',
+    parameters: {
+      type: 'object',
+      properties: {
+        allRetired: { type: 'boolean', description: '清全部已退役的 Bot（与 ids 二选一）' },
+        ids: { type: 'array', items: { type: 'string' }, description: '指定要清的 Bot id 列表' },
+        reason: { type: 'string', description: '清理原因（写进审计流）' },
+      },
+      additionalProperties: false,
+    },
+    run: (s, a, exec) => {
+      if (!s.roster) return failure('roster-unavailable')
+      try {
+        return success(s.roster.purge({ ids: a.ids, allRetired: a.allRetired, reason: a.reason, byId: callerOf(exec) }))
+      } catch (error) {
+        return failure(error?.code ?? 'ROSTER_PURGE_FAILED', { message: String(error?.message ?? error) })
+      }
+    },
+  },
   {
     name: 'bot_roster_manage',
     description:
@@ -1132,7 +1205,7 @@ const DEFS = [
   },
   {
     name: 'bot_teams_add',
-    description: '向团队添加成员（需带 expectedRev 做 CAS）。',
+    description: '向团队添加成员（需带 expectedRev 做 CAS）。若该团队已绑定房间（roomId），自动把成员拉进房间。',
     parameters: {
       type: 'object',
       properties: {
@@ -1146,7 +1219,18 @@ const DEFS = [
     run: (s, a, exec) => {
       if (!s.teams) return failure('teams-unavailable')
       try {
-        return success({ team: s.teams.addMember({ ...a, by: callerOf(exec) }) })
+        const team = s.teams.addMember({ ...a, by: callerOf(exec) })
+        // ── ③ bot_teams_add 补 attachRoom：若团队有 roomId，自动拉人进房间（失败不阻断主流程）──
+        // 参照 api.js:1555 附近的逻辑：只回报 roomError，不让它把「加入团队成功」变成失败。
+        let roomError
+        if (team.roomId && s.room) {
+          try {
+            s.room.join({ roomId: team.roomId, sessionId: a.memberId, byId: callerOf(exec) })
+          } catch (e) {
+            roomError = `room.join 失败（${e?.code ?? 'room-join-failed'}）：${e?.message ?? String(e)}`
+          }
+        }
+        return success({ team, roomError })
       } catch (error) {
         return failure(error?.code ?? 'teams-add-failed', { message: error?.message ?? String(error) })
       }
@@ -1223,6 +1307,41 @@ const DEFS = [
       }
     },
   },
+  // ── A. bot_team_route（t-39 第2批 · 跨团队定向路由）─────────────────────────
+  {
+    name: 'bot_team_route',
+    description:
+      '跨团队定向路由：把任务/消息路由给另一个团队或某个 Bot 所在团队的 lead。' +
+      '只唤醒对方 leadId，不唤醒全部成员。先落 route 事件再投递（intent-first）。' +
+      '失败一律返回可读的 {ok:false, decision:"refused", reason}，绝不静默。',
+    parameters: {
+      type: 'object',
+      properties: {
+        fromTeam: { type: 'string', description: '发送方团队 id（可选；缺省按执行者会话 id 推导）' },
+        toTeam: { type: 'string', description: '目标团队 id' },
+        toBot: { type: 'string', description: '目标 Bot 的会话 id（toTeam 与 toBot 二选一）' },
+        taskId: {
+          type: 'string',
+          description: '关联任务 id（可选；缺省自动生成 route-<时间戳>——页面「发协作请求」不一定挂任务）。'
+            + '同一轮重发请复用同一 taskId，否则会被当成新路由（去重键含 taskId）',
+        },
+        text: { type: 'string', description: '要投递的正文内容' },
+        hop: { type: 'number', description: '当前跳数（>3 拒绝；缺省 0）' },
+      },
+      additionalProperties: false,
+    },
+    run: (s, a, exec) => {
+      if (!s.teams) return failure('teams-unavailable')
+      // 唯一的序列编排在 `teams.deliverRoute()`（决定 → 投递 → 留痕）。
+      // 工具层与 `POST /teams/route` 共用它 —— 两路各写一遍行为就会漂
+      // （一边去重了、一边没去重；一边先投后记、一边先记后投）。
+      return s.teams.deliverRoute({
+        ...a,
+        by: callerOf(exec),
+        dispatcher: s.dispatcher,
+      })
+    },
+  },
 ]