cs-bots 0.1.1 → 0.7.4

package/src/kernel.js

@@ -27,11 +27,14 @@ import { createRequire } from 'node:module'
 import { existsSync } from 'node:fs'
 
 const HOST_LLM = '@deepseek-ai/dsh-llm'
+const HOST_AGENT = '@deepseek-ai/dsh-agent'
 
 /** @type {Function | null} */
 let _createUserMessage = null
 /** @type {Error | null} */
 let _loadError = null
+/** 宿主模块缓存：`spec → module | Error`（同一个 spec 只解析一次，失败也缓存）。 */
+const _hostModules = new Map()
 
 /**
  * 探测 dsh 安装锚点（按可靠性排序）。
@@ -60,13 +63,23 @@ function dshAnchors() {
 }
 
 /**
- * 惰性加载宿主的 `createUserMessage`。
- * @returns {Function}
- * @throws {Error} 所有锚点都失败时（**带排查提示**，不静默）
+ * 惰性加载一个宿主包（**通用版**）。
+ *
+ * 为什么不用静态 import：官方包只存在于 dsh 安装目录（本机
+ * `/home/ubuntu/.npm-global/lib/node_modules/@deepseek-ai/dsh/node_modules/`），
+ * 而 plugin 的 profile `node_modules/@deepseek-ai/` 只有 cosmokit 与 schemastery
+ * ——**解析不到**任何 dsh 子包（2026-11-09 实测）。所以必须从锚点 `createRequire`。
+ *
+ * 结果按 spec 缓存：同一个 spec 只解析一次，**失败也缓存**（避免反复重试空转）。
+ *
+ * @param {string} spec 包名（如 `@deepseek-ai/dsh-agent`）
+ * @returns {unknown} 模块导出
+ * @throws {Error} 所有锚点都失败时（带排查提示，不静默）
  */
-function loadCreateUserMessage() {
-  if (_createUserMessage) return _createUserMessage
-  if (_loadError) throw _loadError
+export function loadHostModule(spec) {
+  const cached = _hostModules.get(spec)
+  if (cached instanceof Error) throw cached
+  if (cached !== undefined) return cached
 
   const tried = []
   for (const anchor of dshAnchors()) {
@@ -74,22 +87,45 @@ function loadCreateUserMessage() {
       // 文件锚点需先存在，createRequire 才不会因怪路径抛错
       if (anchor.startsWith('/') && !existsSync(anchor)) continue
       const req = createRequire(anchor)
-      const mod = req(HOST_LLM)
-      const fn = mod?.createUserMessage
-      if (typeof fn === 'function') {
-        _createUserMessage = fn
-        return fn
+      const mod = req(spec)
+      if (mod !== undefined) {
+        _hostModules.set(spec, mod)
+        return mod
       }
-      tried.push(`${anchor}: 已解析但无 createUserMessage 导出`)
+      tried.push(`${anchor}: 已解析但模块为空`)
     } catch (error) {
       tried.push(`${anchor}: ${error?.code ?? error?.message ?? error}`)
     }
   }
-  _loadError = new Error(
-    `cs-bots kernel: 无法解析宿主包 ${HOST_LLM}。\n` +
+  const err = new Error(
+    `cs-bots kernel: 无法解析宿主包 ${spec}。\n` +
       `  已知锚点尝试：\n    ${tried.join('\n    ')}\n` +
       `  对策：设 CS_BOTS_DSH_ROOT=<dsh 安装目录>，或用 \`dsh --profile <p>\` 启动（宿主会暴露解析锚）。`,
   )
+  _hostModules.set(spec, err)
+  throw err
+}
+
+/**
+ * 惰性加载宿主的 `createUserMessage`。
+ * @returns {Function}
+ * @throws {Error} 所有锚点都失败时（**带排查提示**，不静默）
+ */
+function loadCreateUserMessage() {
+  if (_createUserMessage) return _createUserMessage
+  if (_loadError) throw _loadError
+
+  try {
+    const mod = /** @type {any} */ (loadHostModule(HOST_LLM))
+    const fn = mod?.createUserMessage
+    if (typeof fn === 'function') {
+      _createUserMessage = fn
+      return fn
+    }
+  } catch (error) {
+    _loadError = /** @type {Error} */ (error)
+  }
+  _loadError = _loadError ?? new Error(`cs-bots kernel: 已解析 ${HOST_LLM} 但没有 createUserMessage 导出`)
   throw _loadError
 }
 
@@ -209,10 +245,25 @@ export function listAgents(ctx) {
 // ── 投递（唤醒）─────────────────────────────────────────────────────────────
 
 /**
- * 消息来源标记 —— 官方 `UserMessage.source` 需要它。
- * 未经标识的消息在会话日志里无法追溯，故统一走这里。
+ * 消息来源标记 —— 官方 `UserMessage.source` 需要它。未经标识的消息在会话日志里
+ * 无法追溯，故统一走这里。
+ *
+ * ## ⚠️ 这里踩过一个坐实的坑（2026-11-09）
+ * 原来写的是 `{ kind: 'plugin', name: 'cs-bots' }`。看起来「很官方」，实际上
+ * **v4 格式明令拒收 `kind:'plugin'`**（`dsh-session-format-v3-to-v4/lib/index.js:126`）：
+ *
+ *     if (... source["kind"] === "plugin") throw new SessionFormatError(
+ *       "format v4 message requires a producer-owned source kind")
+ *
+ * 'plugin' 是 **v3 时代的「包装写法」**，只允许出现在**历史回放**里由迁移层
+ * 改写成 `plugin:<name>`；**新建消息**必须直接给「生产者自己的 kind」。
+ * 后果：cs-bots 每次唤醒投递都被宿主在准入处拒收，而 `followup()` 早已返回
+ * ok —— 于是任务静默卡在「进行中」，页面看不到任何异常。
+ *
+ * 取值与迁移层的映射**逐字对齐**（`producerKind()`：非已发布同名生产者 →
+ * `plugin:<name>`），这样新建的消息与历史回放后的形状完全一致。
  */
-const SOURCE = { kind: 'plugin', name: 'cs-bots' }
+const SOURCE = { kind: 'plugin:cs-bots' }
 
 /**
  * 构造一条可投递的用户消息。**不投递**，只构造（便于幂等键先记账再发送）。
@@ -289,6 +340,116 @@ export function steer(ctx, sessionId, text) {
 
 // ── 会话创建（**唯一能指定 cwd 的路径**）──────────────────────────────────────
 
+/**
+ * 组装「Agent 级 setup 回调」—— 把 preset 的工具面挂上去。
+ *
+ * ## 为什么必须自己拼（2026-11-09 复核，源码级证据链）
+ *
+ * 官方 `agents.create(options)` 只透传 `AgentOptions`，而
+ * `AgentOptions`（`dsh-agent/lib/types/runtime-types.d.ts:27-36`）**没有
+ * tools/preset 字段**；preset 挂载完全发生在 `setup` 回调里：
+ *   1. `dsh-api-session-controller/lib/index.js:264-278` 的 `composeAgent(presetId)`
+ *      才是官方唯一的装配入口 —— 它返回
+ *      `{ agentPreset, setup: async (agentCtx) => { installModelSelection(agentCtx); await presets.mount(agentCtx, resolvedId) } }`
+ *   2. `dsh-agent-loop/lib/index.js:1574-1576` 在 `initializeAgent` 里真正调用
+ *      `setup?.(agent.ctx, agent)`；`:543` 证实 `agent.ctx` 带 scope（`mount` 的前置条件）
+ *   3. `dsh-agent-preset-registry/lib/index.js:702-711` 的 `mount()` → `retain` + `bind(ctx, generation)`
+ *      **这一步才挂载工具面**
+ *
+ * cs-bots 走的 `agents.create({ sessionId, meta, agentOptions })` 这条窄接口
+ * **从不传 `setup`** ⇒ preset 从未被挂载 ⇒ Bot 只有 cs-bots 自己注册的
+ * `bot_*` 工具，**没有 read / exec / web_fetch 等任何宿主能力**。
+ * 这就是「Bot 说它没有文件读写能力」的根因（用户：「无法调用工具会失去很多功能」）。
+ *
+ * ## 降级策略（沿用本文件「绝不阻塞启动」纪律）
+ *   - 缺 `agentPresets` 服务 → 退化成只装 model selection（官方同款降级，见 ①）
+ *   - 缺宿主包 / `mount` 抛错 → warn + 返回 setup 的降级版，**不抛**
+ *     （「没挂上工具面」仍然好过「会话建不起来」）
+ *
+ * @param {object} ctx
+ * @param {string | undefined} presetId 调用方显式给的 preset；不给则用宿主默认
+ * @param {(msg: string) => void} [warn] 告警出口（缺省静默）
+ * @returns {Promise<{ setup?: (agentCtx: object) => Promise<void>, agentPreset?: string }>}
+ */
+export async function composePresetSetup(ctx, presetId, warn = () => {}) {
+  /** @type {(agentCtx: object) => Promise<void>} */
+  let setup = async () => {}
+  let agentPreset
+
+  // ① 惰性取宿主的 installModelSelection（复用 loadHostModule 的锚点机制）
+  //    注意：不能静态 import —— profile 的 node_modules/@deepseek-ai/ 解析不到
+  //    dsh 子包（实测 ERR_MODULE_NOT_FOUND），必须从锚点 createRequire。
+  let installModelSelection = null
+  try {
+    const mod = /** @type {any} */ (loadHostModule(HOST_AGENT))
+    installModelSelection = typeof mod?.installModelSelection === 'function' ? mod.installModelSelection : null
+  } catch (error) {
+    warn(`cs-bots: 无法解析 ${HOST_AGENT}（model-selection 兜底将缺失）：${error?.message ?? error}`)
+  }
+
+  /** 安全装 model selection：任何异常都只 warn，绝不向上抛（见下方 mount 同纪律）。 */
+  const safeInstall = async (agentCtx) => {
+    if (!installModelSelection) return
+    try {
+      installModelSelection(agentCtx)
+    } catch (error) {
+      warn(`cs-bots: installModelSelection 失败（不影响工具面挂载）：${error?.message ?? error}`)
+    }
+  }
+
+  const presets = service(ctx, 'agentPresets')
+  if (!presets || typeof presets.mount !== 'function') {
+    // 官方同款降级：只有 model selection，没有 preset 工具面
+    if (installModelSelection) setup = safeInstall
+    warn('cs-bots: agentPresets 服务不可用 —— Bot 将只挂 model selection，不会挂 preset 工具面')
+    return { setup: installModelSelection ? setup : undefined }
+  }
+
+  // ② resolve → 拿到真实 id（未给则用宿主默认；官方 `composeAgent` 同款）
+  let resolvedId
+  try {
+    const resolved = await presets.resolve(presetId)
+    resolvedId = /** @type {any} */ (resolved)?.id
+  } catch (error) {
+    // 请求的 preset 不可用（未知 / 已下架）⇒ 回落**宿主默认**。
+    // ⚠️ 回落目标必须是 `presets.defaultId`，不能是 `presetId` —— 那等于拿同一个
+    //    坏值再 resolve 一次，必然再失败（2026-11-09 测试 P4 揪出来的真 bug：
+    //    上一版写 `presetId ?? presets.defaultId`，presetId 非空所以永远不回落）。
+    const fallback = presets.defaultId
+    warn(
+      `cs-bots: preset ${JSON.stringify(presetId ?? null)} 不可用（${error?.message ?? error}）`
+      + `，回落到宿主默认 ${JSON.stringify(fallback ?? null)}`,
+    )
+    if (typeof fallback === 'string' && fallback) {
+      try {
+        const resolved = await presets.resolve(fallback)
+        resolvedId = /** @type {any} */ (resolved)?.id
+      } catch (err) {
+        warn(`cs-bots: 连默认 preset ${JSON.stringify(fallback)} 都 resolve 不了，跳过挂载：${err?.message ?? err}`)
+      }
+    }
+  }
+  if (typeof resolvedId !== 'string' || !resolvedId) {
+    warn('cs-bots: preset resolve 返回的 id 无效，跳过挂载')
+    return { setup: installModelSelection ? safeInstall : undefined }
+  }
+  agentPreset = resolvedId
+
+  // ③ 真正拼 setup：installModelSelection + presets.mount
+  //    两步必须**各自独立兜底**：installModelSelection 抛错（宿主版本不匹配、
+  //    agentCtx 形状不符）时绝不允许连带跳过 mount —— 那等于把整个工具面也丢了。
+  //    纪律：会话必须建得起来，挂不上的部分如实 warn。
+  setup = async (agentCtx) => {
+    await safeInstall(agentCtx)
+    try {
+      await presets.mount(agentCtx, resolvedId)
+    } catch (error) {
+      warn(`cs-bots: preset ${resolvedId} mount 失败（会话仍可用，但工具面未挂上）：${error?.message ?? error}`)
+    }
+  }
+  return { setup, agentPreset }
+}
+
 /**
  * 创建一个 root Agent 会话，**可指定工作目录**。
  *
@@ -310,27 +471,132 @@ export async function createSession(ctx, options) {
   if (!agents || typeof agents.create !== 'function') {
     throw new Error('cs-bots kernel: agents.create 不可用（宿主未提供 agents 服务）')
   }
-  const { sessionId, cwd, parentAgent, agentPreset, agentOptions, signal } = options ?? {}
+  const { sessionId, cwd, parentAgent, agentPreset, agentOptions, signal, warn } = options ?? {}
   if (!sessionId) throw new Error('cs-bots kernel: createSession 需要 sessionId')
 
+  // ── preset 装配（2026-11-09 修复「Bot 没有任何工具」）──────────────────────
+  // 必须走 setup 回调，理由见 composePresetSetup 的注释（源码级证据链）。
+  // 先 resolve，再拿它回填 meta.agentPreset —— 这样落盘的 preset 与会话真正
+  // 挂载的 preset **是同一个**（官方 composeAgent 也是先 resolve 再写 meta）。
+  const composition = await composePresetSetup(ctx, agentPreset, warn)
+
   const meta = {}
   if (cwd) meta.cwd = cwd
-  if (agentPreset) meta.agentPreset = agentPreset
+  const effectivePreset = composition.agentPreset ?? agentPreset
+  if (effectivePreset) meta.agentPreset = effectivePreset
   if (parentAgent) meta.parentSession = parentAgent.id
 
-  return agents.create({
+  // ── 模型选择（2026-11-09 修复「bot has no provider/model」）───────────────
+  // 官方 agent-loop 在每一步 preStep 都会 `this.model.current()`，
+  // 得到 undefined 就直接抛 `agent "X" has no provider/model`。
+  // 官方 Web UI 建会话时由 session-controller 记录一次 model selection；
+  // 我们走 agents.create 这条窄接口，**没有人替我们记录** ⇒ 必须自己带上。
+  // 取值优先级：调用方显式给 > 宿主的全局默认（agentDefaultModel.currentSelection()）。
+  const route = agentOptions ?? defaultModelSelection(ctx)
+
+  const handle = await agents.create({
     sessionId,
     ...(parentAgent ? { parentAgent } : {}),
     ...(Object.keys(meta).length ? { meta } : {}),
-    ...(agentOptions ? { agentOptions } : {}),
+    ...(route ? { agentOptions: route } : {}),
+    ...(composition.setup ? { setup: composition.setup } : {}),
     ...(signal ? { signal } : {}),
   })
+
+  // ── 挂进工作区（2026-11-09 修复「左侧栏未分组」）─────────────────────────
+  // 官方把会话归组进 Workspace（`workspaceRegistry`），attachSession 的
+  // 前置条件是「会话 header 的 cwd 与 workspace.path 完全相同」。
+  // 我们建会话时正好指定了 cwd，所以这里补上「建/复用 workspace + attach」，
+  // 否则会话永远落在「未分组」里（2026-11-09 现场：bot-6b654c19… 就是）。
+
+  // 注意顺序：attach 必须在会话创建之后（attach 要读会话 header 的 cwd）。
+  if (cwd) {
+    try {
+      await attachToWorkspace(ctx, cwd, pickSessionId(handle, sessionId))
+    } catch {
+      /* 工作区挂载是「锦上添花」：失败不影响会话可用（只是仍显示未分组） */
+    }
+  }
+  return handle
+}
+
+/**
+ * 宿主全局默认模型（`agentDefaultModel.currentSelection()`）。
+ * 缺失/异常一律返回 undefined —— 不因拿不到默认模型就让建会话失败。
+ * @param {object} ctx
+ * @returns {{ provider: string, model: string, reasoningEffort?: string } | undefined}
+ */
+function defaultModelSelection(ctx) {
+  try {
+    const svc = service(ctx, 'agentDefaultModel')
+    if (!svc || typeof svc.currentSelection !== 'function') return undefined
+    const sel = svc.currentSelection()
+    if (!sel || typeof sel.provider !== 'string' || typeof sel.model !== 'string') return undefined
+    if (sel.provider === '' || sel.model === '') return undefined
+    return {
+      provider: sel.provider,
+      model: sel.model,
+      ...(sel.reasoningEffort === undefined ? {} : { reasoningEffort: sel.reasoningEffort }),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** 从 AgentHandle 里取 session id（宿主可能返回 { agent } / { sessionId } / 字符串）。 */
+function pickSessionId(handle, fallback) {
+  if (typeof handle === 'string' && handle) return handle
+  const id = handle?.agent?.id ?? handle?.sessionId ?? handle?.id
+  return typeof id === 'string' && id ? id : fallback
+}
+
+/**
+ * 把会话挂到「路径 = 该会话 cwd」的工作区（不存在则先建）。
+ *
+ * 官方契约（`dsh-workspace/lib/index.js`）：
+ *   - `workspaceRegistry.create(path)` 建（同路径已存在时会复用，返回 created=false）
+ *   - `workspace.attachSession(sessionId)` 挂，前提是会话 cwd === workspace.path
+ *   - 两个方法都可能不存在（老宿主）⇒ 全程 try/catch，静默降级
+ *
+ * @param {object} ctx
+ * @param {string} cwd 已存在的绝对目录
+ * @param {string} sessionId
+ * @returns {Promise<boolean>} 是否挂上
+ */
+export async function attachToWorkspace(ctx, cwd, sessionId) {
+  const registry = service(ctx, 'workspaceRegistry')
+  if (!registry || typeof sessionId !== 'string' || !sessionId) return false
+  let workspace
+  try {
+    if (typeof registry.resolveByPath === 'function') {
+      workspace = await registry.resolveByPath(cwd)
+    }
+  } catch {
+    workspace = undefined
+  }
+  if (!workspace) {
+    if (typeof registry.create !== 'function') return false
+    const out = await registry.create(cwd) // 官方可能返回 { workspace, created } 或直接返回 workspace
+    workspace = out?.workspace ?? out
+  }
+  if (!workspace || typeof workspace.attachSession !== 'function') return false
+  await workspace.attachSession(sessionId)
+  return true
 }
 
 /**
  * 在既有持久会话上恢复 Agent（重启后复活会话用）。
+ *
+ * ⚠️ resume 也必须传 `setup`（2026-11-09 同源修复）。
+ * 官方 resume 路径同样装配 preset：`dsh-api-session-controller/lib/index.js:364-370`
+ * 传的是 `setup: this.reuseSetup(composition)`，其中 `reuseSetup`（382-397）
+ * 除了 installModelSelection + mount，还会在 preset 变化时 append
+ * `agent-preset/selected` 事件。**不传 setup 的 resume 出来的 Agent 同样没有工具面**
+ * —— 存量 Bot 光靠「复活」不会自动长出 read/exec，必须在这里补挂。
+ *
  * @param {object} ctx
- * @param {{ resumeSessionId: string, signal?: AbortSignal }} options
+ * @param {{ resumeSessionId: string, signal?: AbortSignal, agentPreset?: string,
+ *           agentOptions?: object, warn?: (msg: string) => void }} options
  * @returns {Promise<object>} AgentHandle
  */
 export async function resumeSession(ctx, options) {
@@ -338,9 +604,22 @@ export async function resumeSession(ctx, options) {
   if (!agents || typeof agents.resume !== 'function') {
     throw new Error('cs-bots kernel: agents.resume 不可用')
   }
-  const { resumeSessionId, signal } = options ?? {}
+  const { resumeSessionId, signal, agentOptions, agentPreset, warn } = options ?? {}
   if (!resumeSessionId) throw new Error('cs-bots kernel: resumeSession 需要 resumeSessionId')
-  return agents.resume({ resumeSessionId, ...(signal ? { signal } : {}) })
+  // 2026-11-09 同源修复：**存量会话**从来没有记录过模型选择（当时走的是不带
+  // agentOptions 的创建路径），复活后依然 `model.current() === undefined`，
+  // 下一次唤醒照样炸 `has no provider/model`。所以复活也要给兜底路由：
+  // 调用方显式给 > 会话自己已记录的 > 宿主全局默认（由宿主负责，我们只在
+  // 前两者都没有时才传，避免把用户后来改过的会话级选择覆盖回默认值）。
+  const route = agentOptions ?? defaultModelSelection(ctx)
+  // preset 装配：与 createSession 同源（见 composePresetSetup 的注释）。
+  const composition = await composePresetSetup(ctx, agentPreset, warn)
+  return agents.resume({
+    resumeSessionId,
+    ...(route ? { agentOptions: route } : {}),
+    ...(composition.setup ? { setup: composition.setup } : {}),
+    ...(signal ? { signal } : {}),
+  })
 }
 
 // ── HTTP 路由注册 ───────────────────────────────────────────────────────────
@@ -433,6 +712,100 @@ export function restrictTools(agent, names) {
   }
 }
 
+// ── LLM 请求拦截（复杂度路由唯一需要的宿主触点）──────────────────────────────
+
+/**
+ * 注册一条 `llm/stream` 瀑布拦截（**接口 v1，2026-11-04 新增**）。
+ *
+ * 官方语义一手依据：
+ *   - 调用点：`dsh-llm/lib/index.js:2397`
+ *     `this.ctx.waterfall(this, 'llm/stream', options, () => this.adapterStream(...))`
+ *   - 签名：`'llm/stream'(this: LlmRuntime, options: GenerateOptions,
+ *     next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>`
+ *   - 官方插件用法样板：`dsh-session-checkpoint-policy/lib/index.js:61`
+ *     `ctx.on('llm/stream', (options, next) => { ... return next() })`
+ *
+ * ⚠️ `options` 是**冻结的**（`dsh-agent-loop/lib/index.js:1286` 处 `Object.freeze`）：
+ *    处理函数只能读、不能写；想让下游知道点什么，必须走旁路通道
+ *    （本平台用 `globalThis[Symbol.for('cs-myfree.routing.hints.v1')]`）。
+ *
+ * ⚠️ handler 必须**同步返回 `next()`**（那是 AsyncIterable，不是 Promise），
+ *    所以本函数不做任何 await，也不包 async。
+ *
+ * 缺 `ctx.on`（测试替身/更老宿主）时返回 `false`，调用方按降级处理，**不抛**。
+ *
+ * @param {object} ctx
+ * @param {(options: object, next: Function) => any} handler
+ * @returns {boolean} 是否注册成功
+ */
+export function onLlmStream(ctx, handler) {
+  if (!ctx || typeof ctx.on !== 'function') return false
+  if (typeof handler !== 'function') return false
+  try {
+    ctx.on('llm/stream', handler)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ── 会话元数据（谱系）──────────────────────────────────────────────────────
+
+/**
+ * 读一个会话的**谱系元数据**（接口 v1，2026-11-04 新增）。
+ *
+ * 为什么需要（授权泄漏修复）：官方 `spawn_teammate` 生成的子会话**不在 cs-bots 的
+ * roster 注册表里**，但宿主 session header 带谱系字段。没有这条信息，平台只能把
+ * 「不是 Bot 的会话」当成主对话 ⇒ 官方子智能体反而拿到 `paid_allowed`（越权付费）。
+ *
+ * 一手依据（宿主源码，已核验）：
+ *   - `dsh-session/lib/index.js:1340` `Session.header`（公开属性，deep-frozen）；
+ *   - `dsh-session/lib/index.js:1823-1827` header 由 `meta` 组装，含
+ *     `parentSession` / `origin`（子代理为 `'subagent'`）/ `delegationDepth` / `agentPreset`；
+ *   - `dsh-session/lib/index.js:1980` `sessions.get(id)` ⇒ Session。
+ *
+ * 纪律：
+ *   - **只取白名单四个字段**并转成纯数据（绝不把宿主对象/header 引用漏给业务层）；
+ *   - 服务缺失、无此会话、任何抛错 ⇒ `null`（调用方据此 fail-closed，**本函数绝不抛**）；
+ *   - 返回 `{}` 表示「会话存在但没有任何谱系字段」= 可确认是顶层会话（主对话）。
+ *
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @returns {{ origin?: string, parentSession?: string, delegationDepth?: number,
+ *             agentPreset?: string } | null}
+ */
+export function sessionMeta(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId === '') return null
+  const sessions = service(ctx, 'sessions')
+  if (!sessions || typeof sessions.get !== 'function') return null
+  let header
+  try {
+    header = sessions.get(sessionId)?.header
+  } catch {
+    return null
+  }
+  if (!header || typeof header !== 'object') return null
+
+  /** @type {{ origin?: string, parentSession?: string, delegationDepth?: number, agentPreset?: string }} */
+  const meta = {}
+  try {
+    if (typeof header.origin === 'string' && header.origin !== '') meta.origin = header.origin
+    if (typeof header.parentSession === 'string' && header.parentSession !== '') {
+      meta.parentSession = header.parentSession
+    }
+    if (typeof header.delegationDepth === 'number' && Number.isFinite(header.delegationDepth)) {
+      meta.delegationDepth = header.delegationDepth
+    }
+    if (typeof header.agentPreset === 'string' && header.agentPreset !== '') {
+      meta.agentPreset = header.agentPreset
+    }
+  } catch {
+    // 代理陷阱/只读失败等 ⇒ 视为拿不到元数据（调用方 fail-closed）
+    return null
+  }
+  return meta
+}
+
 // ── 状态目录 ────────────────────────────────────────────────────────────────
 
 /**
@@ -478,3 +851,242 @@ export function defaultPreset(ctx) {
     return undefined
   }
 }
+
+// ── 会话内容读取（需求2：任务详情里直接看对话，不必跳走）──────────────────────
+
+/**
+ * 读一个会话的历史事件，转成「人类可读的对话片段」。
+ *
+ * 为什么需要它（2026-11-08 用户反馈）：
+ *   「任务栏页面指派 bot 后，无法追踪任务进度，无法看到产出物，
+ *     没有跳转对话也没有对话内容查看」
+ *   ⇒ 跳转会话（openSession）只能把人带到会话界面，**看不到这个任务相关的对话**；
+ *     人想看「Bot 到底干了什么」，必须能在任务详情里直接读。
+ *
+ * 数据来源：官方 `ctx.sessionPersistence`（durable 事件日志，**真相源**）。
+ * 为什么不用 live Agent 的内存：进程重启后 live 注册表是空的，但磁盘上的会话仍在——
+ * 用持久化层读才能保证「重启后照样能看历史」。
+ *
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @param {{ limit?: number, offset?: number }} [options]
+ *   - `limit`：最多返回多少条**消息片段**（默认 40；取**末尾**的，因为人关心最近发生了什么）
+ * @returns {Promise<{
+ *   ok: boolean, sessionId?: string, messages?: object[], total?: number,
+ *   reason?: string, available?: boolean,
+ * }>}
+ */
+export async function readSessionMessages(ctx, sessionId, options = {}) {
+  if (typeof sessionId !== 'string' || sessionId === '') {
+    return { ok: false, reason: 'missing-session-id', available: true }
+  }
+  const persistence = service(ctx, 'sessionPersistence')
+  if (!persistence || typeof persistence.open !== 'function') {
+    return {
+      ok: false,
+      available: false,
+      reason: 'sessionPersistence 不可用（宿主未装配持久化层）——无法读取会话历史',
+    }
+  }
+
+  let handle
+  try {
+    // access: 'read' —— 只读打开，绝不抢所有权（会话可能正在被 live agent 使用）
+    handle = await persistence.open(sessionId, 'read')
+  } catch (error) {
+    return {
+      ok: false,
+      available: true,
+      reason: `打开会话失败：${error?.message ?? error}`,
+    }
+  }
+
+  try {
+    const result = await handle.read(0)
+    const events = Array.isArray(result?.events) ? result.events : []
+    const messages = eventsToMessages(events)
+    const limit = Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : 40
+    // 取末尾 limit 条：人关心的是「最近在干什么」，不是开场白
+    const tail = messages.length > limit ? messages.slice(-limit) : messages
+    return {
+      ok: true,
+      sessionId,
+      messages: tail,
+      total: messages.length,
+      truncated: messages.length > limit,
+    }
+  } catch (error) {
+    return { ok: false, available: true, reason: `读取会话事件失败：${error?.message ?? error}` }
+  } finally {
+    try {
+      await handle.close?.()
+    } catch {
+      /* 关闭失败不影响已读到的数据 */
+    }
+  }
+}
+
+/**
+ * 会话的「水位」：最新事件序号 + 最新事件时间 + 是否已有用户消息。
+ *
+ * ## 为什么要它（2026-11-09「投递成功但执行者不动」）
+ *   `dispatcher` 只记 `sent`（= 我们把消息交给了宿主），这不等于「执行者真的开始了
+ *   一个回合」。现场就出现过：wake 记 `sent`，而会话 `turns: 0 / steps: 0`、
+ *   事件文件还停在几天前 —— 任务卡在「进行中」，页面上看不到任何异常。
+ *
+ *   要判「它到底动没动」，最可靠、成本最低的依据就是**会话事件水位**：
+ *   投递后一段时间内，如果 seq 没有增长、也没有新的 `user/message`，
+ *   那这条输入就是没被消费。这就是 superagent `inputsRead` 那一层的最小实现。
+ *
+ * 只读打开（`access:'read'`），绝不抢会话所有权。
+ *
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @returns {Promise<{ ok: boolean, available?: boolean, seq?: number, lastAt?: number,
+ *                     userMessages?: number, reason?: string }>}
+ */
+export async function readSessionWatermark(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId === '') {
+    return { ok: false, reason: 'missing-session-id', available: true }
+  }
+  const persistence = service(ctx, 'sessionPersistence')
+  if (!persistence || typeof persistence.open !== 'function') {
+    return { ok: false, available: false, reason: 'sessionPersistence 不可用' }
+  }
+  let handle
+  try {
+    handle = await persistence.open(sessionId, 'read')
+  } catch (error) {
+    return { ok: false, available: true, reason: `打开会话失败：${error?.message ?? error}` }
+  }
+  try {
+    const result = await handle.read(0)
+    const events = Array.isArray(result?.events) ? result.events : []
+    let seq = -1
+    let lastAt
+    let userMessages = 0
+    for (const ev of events) {
+      if (!ev || typeof ev !== 'object') continue
+      if (Number.isFinite(ev.seq) && ev.seq > seq) seq = ev.seq
+      if (Number.isFinite(ev.time)) lastAt = ev.time
+      if (ev.type === 'user/message') userMessages += 1
+    }
+    return { ok: true, available: true, seq, lastAt, userMessages }
+  } catch (error) {
+    return { ok: false, available: true, reason: `读取会话事件失败：${error?.message ?? error}` }
+  } finally {
+    try { await handle.close?.() } catch { /* 关闭失败不影响已读到的数据 */ }
+  }
+}
+
+/**
+ * 把官方 SessionEvent 转成人类可读的消息片段。
+ *
+ * 只保留**有对话价值**的事件类型：用户消息、助手文本、工具调用（摘要）、工具结果（摘要）。
+ * 其余事件（会话元数据、内存写入等）一律跳过——它们对「看 Bot 干了什么」没有帮助，
+ * 塞进来只会让人淹没在噪声里。
+ *
+ * 每条输出统一形状：`{ role, kind, text, at?, toolName? }`
+ *   - role: 'user' | 'assistant' | 'tool'
+ *   - kind: 'text' | 'tool-call' | 'tool-result' | 'reasoning'
+ *
+ * @param {object[]} events
+ * @returns {object[]}
+ */
+export function eventsToMessages(events) {
+  const out = []
+  for (const ev of events) {
+    if (!ev || typeof ev !== 'object') continue
+    // 官方 SessionEvent 的形状是 `{ type, seq, time, data }` —— 内容在 `data` 里。
+    // 早期实现只读 `ev.content`，结果对**任何真实会话**都产出空数组（需求2「看不到对话内容」
+    // 的真因）。这里同时兼容两种形状，避免新旧数据各有盲区。
+    const type = ev.type
+    const at = typeof ev.time === 'number' ? ev.time : undefined
+    const data = (ev.data && typeof ev.data === 'object') ? ev.data : {}
+
+    const pushBlocks = (role, blocks) => {
+      if (!Array.isArray(blocks)) return
+      for (const b of blocks) {
+        if (!b || typeof b !== 'object') continue
+        if (b.type === 'text' && typeof b.text === 'string' && b.text.trim()) {
+          out.push({ role, kind: 'text', text: b.text, at })
+        } else if (b.type === 'reasoning' && typeof b.text === 'string' && b.text.trim()) {
+          out.push({ role: 'assistant', kind: 'reasoning', text: b.text.slice(0, 2000), at })
+        } else if (b.type === 'tool-call' || b.type === 'toolCall') {
+          out.push({ role: 'assistant', kind: 'tool-call', toolName: String(b.name ?? b.toolName ?? '?'), text: summarizeInput(b.input ?? b.arguments), at })
+        }
+      }
+    }
+
+    // 用户消息（含 system/developer 注入的「用户侧」文本，人看任务上下文需要）
+    if (type === 'user/message' || type === 'user-message') {
+      pushBlocks('user', data.content ?? ev.content ?? data.message?.content ?? ev.message?.content)
+      continue
+    }
+
+    // 助手消息：内容在 data.message.content
+    if (type === 'assistant/message' || type === 'assistant-message') {
+      const msg = data.message ?? ev.message ?? {}
+      pushBlocks('assistant', msg.content ?? data.content ?? ev.content)
+      continue
+    }
+
+    // 工具调用：data.name + data.arguments（顶层事件，不嵌在 assistant 消息里）
+    if (type === 'tool/call' || type === 'tool-call' || type === 'toolCall') {
+      const name = data.name ?? data.toolName ?? ev.name
+      const summary = summarizeInput(data.arguments ?? data.input ?? ev.arguments)
+      // 既没名字也没入参 ⇒ 对「看 Bot 干了什么」毫无信息量，跳过而不是画一个空壳
+      if (!name && !summary) continue
+      out.push({
+        role: 'assistant',
+        kind: 'tool-call',
+        toolName: String(name ?? '?'),
+        text: summary,
+        at,
+      })
+      continue
+    }
+
+    // 工具结果：data.message.content
+    if (type === 'tool/result' || type === 'tool-result' || type === 'toolResult') {
+      const msg = data.message ?? ev.message ?? {}
+      const text = blocksToText(msg.content ?? data.content ?? ev.content ?? ev.result)
+      const name = msg.toolName ?? data.name ?? ev.toolName
+      if (text) {
+        out.push({
+          role: 'tool',
+          kind: 'tool-result',
+          ...(typeof name === 'string' && name ? { toolName: name } : {}),
+          text: text.length > 1500 ? `${text.slice(0, 1500)}\u2026` : text,
+          at,
+        })
+      }
+      continue
+    }
+  }
+  return out
+}
+
+/** 工具入参压成一行摘要（对象转 JSON，超长截断）。 */
+function summarizeInput(input) {
+  if (input === undefined || input === null) return ''
+  let summary = ''
+  try {
+    summary = typeof input === 'string' ? input : JSON.stringify(input)
+  } catch {
+    summary = ''
+  }
+  return summary && summary.length > 500 ? `${summary.slice(0, 500)}\u2026` : summary
+}
+
+/** 把 content blocks 拍平成一段文本（只取 text 类型块）。 */
+function blocksToText(content) {
+  if (typeof content === 'string') return content.trim()
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const b of content) {
+    if (typeof b === 'string') parts.push(b)
+    else if (b && typeof b === 'object' && typeof b.text === 'string') parts.push(b.text)
+  }
+  return parts.join('\n').trim()
+}