cs-bots 0.7.5 → 0.9.0

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'])
+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)
   }
 
@@ -474,6 +505,239 @@ export function createTeams(ctx, config = {}) {
 
   // ── API：读 ────────────────────────────────────────────────────────────────
 
+  /**
+   * 给团队挂上一个房间（契约 §3：团队自动配议事厅）。
+   *
+   * 幂等：同一个 roomId 再调一次 ⇒ 直接返回现有团队（rev 不变）。
+   * 房间已经存在、只是想补关联时**不重复写事件** —— 否则 `/teams` 反复保存
+   * 会把事件流刷成一条重复行，rev 也跟着虚增，页面上的「谁改了团队」就失真了。
+   * @param {{ id: string, expectedRev?: number, roomId: string, by: string, now?: number }} input
+   */
+  function attachRoom(input = {}) {
+    assertAlive('attachRoom')
+    const { id, expectedRev, roomId, by, now } = input ?? {}
+    const author = requireString(by, 'by', 'attachRoom')
+    const at = normalizeNow(now, 'attachRoom')
+    const room = requireString(roomId, 'roomId', 'attachRoom')
+    const current = cas(id, expectedRev, 'attachRoom')
+    if (current.roomId === room) {
+      return clone(current) // 幂等：已关联同一房间，不重复落事件
+    }
+    const next = clone(current)
+    next.rev = current.rev + 1
+    next.roomId = room
+    next.updatedAt = at
+    next.updatedBy = author
+    commit('attachRoom', at, author, clone(current), next)
+    info(`[cs-bots/teams] 团队 ${id} 关联房间 ${room}（by ${author}）`)
+    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 = {}) {
     assertAlive('list')
     let rows = [...entries.values()]
@@ -483,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)
@@ -515,8 +886,19 @@ export function createTeams(ctx, config = {}) {
     note,
     close,
     setPolicy,
+    // 契约 §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

@@ -30,7 +30,8 @@ function success(payload) {
  * 从宿主上下文取本平台的域服务。
  * @param {object} ctx
  * @returns {{ board?: object, roster?: object, room?: object, memory?: object, dispatcher?: object,
- *   todo?: object, scratch?: object, prompts?: object, discipline?: object, suggest?: object }}
+ *   todo?: object, scratch?: object, prompts?: object, discipline?: object, suggest?: object,
+ *   phaseWrite?: (taskId: string, patch: object) => object }}
  */
 function servicesOf(ctx) {
   return getServices(ctx)
@@ -258,6 +259,80 @@ const DEFS = [
     },
   },
 
+  // ── 阶段产出物（契约 §2.4，纯增量）──────────────────────────────────────────
+  {
+    name: 'bot_task_phase',
+    description:
+      '边做边交阶段产出物：每完成一个阶段就调用一次，带上这一阶段交出的文件路径/链接。' +
+      '【重要】不要等到整条任务做完才汇报 —— 阶段产物是给 Boss 点开就能看到的东西，' +
+      '分阶段交付（doing = 正在做这一阶段 / done = 这一阶段交完 / blocked = 卡在这一阶段）。' +
+      '需要 B 侧的 `services.phaseWrite(taskId, patch)` 能力；后端未注入时返回 failure，' +
+      '不会静默成功。',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '任务 id' },
+        index: { type: 'number', description: '阶段下标（从 0 开始，必填；越界会被后端拒）' },
+        state: {
+          type: 'string',
+          enum: ['doing', 'done', 'blocked'],
+          description: '该阶段状态（默认 done）',
+        },
+        artifacts: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '这一阶段交出的文件路径/URL（可为空数组，表示「这一阶段没产出物」）',
+        },
+        note: { type: 'string', description: '一句话说明' },
+        expectedRev: { type: 'number', description: '当前任务 rev（可选，CAS）' },
+      },
+      required: ['id', 'index'],
+      additionalProperties: false,
+    },
+    run: (s, a, exec) => {
+      // 契约 §2.4：阶段写入能力由 B 侧 installApi 挂到 services.phaseWrite。
+      // 拿不到就是拿不到 —— **绝不静默成功**，返回 failure 让调用方看见。
+      const phaseWrite = s?.phaseWrite
+      if (typeof phaseWrite !== 'function') {
+        return failure('phase-unavailable', {
+          hint: '后端未就绪：services.phaseWrite 未注入（应由 api.js 挂载）。'
+            + '请稍后重试；或先用 bot_task_update 交付总产出物。',
+        })
+      }
+      if (typeof a?.id !== 'string' || a.id === '') {
+        return failure('bad-argument', { field: 'id', hint: 'id 必填' })
+      }
+      const index = a?.index
+      if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
+        return failure('bad-argument', { field: 'index', hint: 'index 必填，且必须是 >=0 的整数' })
+      }
+      const state = a?.state === undefined ? 'done' : a.state
+      if (state !== 'doing' && state !== 'done' && state !== 'blocked') {
+        return failure('bad-argument', { field: 'state', hint: 'state 只允许 doing | done | blocked' })
+      }
+      try {
+        // `by` 由调用者身份得出（事实留痕，不猜）；`expectedRev` 若给了就带上做 CAS。
+        const res = phaseWrite(a.id, {
+          index,
+          state,
+          artifacts: a?.artifacts,
+          note: a?.note,
+          by: callerOf(exec),
+          expectedRev: a?.expectedRev,
+        })
+        if (!res || typeof res !== 'object') {
+          return failure('phase-write-failed', { message: 'phaseWrite 返回了非法结果' })
+        }
+        return res
+      } catch (error) {
+        // 写不进 task-meta.jsonl 必须让模型看见（不许吞）
+        return failure(error?.code ?? 'phase-write-failed', {
+          message: error?.message ?? String(error),
+        })
+      }
+    },
+  },
+
   // ── 唤醒桥（Dispatcher）────────────────────────────────────────────────────
   {
     name: 'bot_wake',
@@ -1057,7 +1132,7 @@ const DEFS = [
   },
   {
     name: 'bot_teams_add',
-    description: '向团队添加成员（需带 expectedRev 做 CAS）。',
+    description: '向团队添加成员（需带 expectedRev 做 CAS）。若该团队已绑定房间（roomId），自动把成员拉进房间。',
     parameters: {
       type: 'object',
       properties: {
@@ -1071,7 +1146,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) })
       }
@@ -1148,6 +1234,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,
+      })
+    },
+  },
 ]