@menghuan1918/dsh-apollo 0.4.0 → 0.5.0

package/src/settings.js

@@ -1,46 +1,47 @@
 /**
  * dsh-apollo —— 设置装配（src/settings.js）。
  *
- * 本文件负责两件「必须等到服务可用才能做」的事，以及一次性的旧配置迁移：
+ * 0.5.0 起 Apollo 不再注册任何 HTTP 路由：子代理能力/模型/路由探针与
+ * `/apollo/api/*` 别名由 dsh-better-subagent 拥有，compact 诊断由
+ * dsh-better-compact 拥有。重复注册同一 `(kind, path)` 会让 webServer 抛错，
+ * 所以这里必须保持“零路由”。
  *
- * 1. **只读能力路由**：`ctx.inject(['webServer'])` → 注册
- *    `/apollo/api/capabilities`（处理器与探针在 `src/panel.js`，一处注册避免
- *    webServer 的重复 (kind,path) 抛错）。headless 组合没有 webServer 就自然
- *    跳过，面板装配照常返回。
+ * 本文件只做三件需要等服务的事情：
+ *
+ * 1. **反代部署标志**：`installOwnsHostTap`（`src/owns-host.js`）在行配置
+ *    `declareOwnsHost: true` 时注入 index boot 全局。
  *
  * 2. **行配置页面策略**：`ctx.inject(['settings'])` → 在本插件实例上登记
- *    `configure({ auto: false }, ctx.fiber)`：本行自带配置页（浏览器半边的
- *    `plugins.row.config`）就是它唯一的编辑入口，不需要 DSH 再按 schema 自动
- *    生成一页。策略随本行的 effect 生命周期增删。
+ *    `configure({ auto: false }, ctx.fiber)`：本行自带的最小配置页就是唯一
+ *    编辑入口，不需要 DSH 再按 schema 自动生成一页。策略随本行的 effect
+ *    生命周期增删。
  *
  * 3. **旧 eng.json / atlas.json 一次性只读导入**：DSH 0.2 起设置就是正式
- *    Config（volatile，见 `src/config.js`），落盘由 configEditor 写进活动
- *    profile 的 cordis.patch.yml；`<dshHome>/eng.json` 与旧名 `atlas.json`
- *    不再被写入（**只读**），但第一次装配时会把里面的 `exitGuard` 搬进正式
- *    配置，之后旧的读取路径（预设本地守卫）即使被删也不丢开关。
+ *    Config（volatile，见 `src/config.js`）。`<dshHome>/eng.json` 与旧名
+ *    `atlas.json` 不再被写入（**只读**），但第一次装配时会把里面的
+ *    `exitGuard` 搬进正式配置。0.5.0 后这个 `exitGuard` 是 **job/通用守卫**
+ *    的开关；同一个初值再由迁移模块复制到 dsh-better-subagent 的
+ *    `childExitGuard`（旧组合开关拆成两个可独立配置的开关）。
  *
  *    迁移规则：
- *      - 只在 `settings` 服务可用、且 Loader 已把所有 entry 装配完（本行 fiber
- *        进入 active，`describe()` 才认得它）之后跑一次；
- *      - **当前 profile 显式给出的值优先**：`exitGuard` 已存在于用户层（哪怕是
- *        显式 `false`）时不覆盖——判断「存在」而不是「等于」，与 dsh-settings
- *        的 override 语义一致；
- *      - 值已经与生效值相同（等于 schema 默认）时不写盘，避免制造无意义的
- *        profile 覆盖层；
+ *      - 只在 `settings` 服务可用、且 Loader 已把所有 entry 装配完（本行
+ *        fiber 进入 active，`describe()` 才认得它）之后跑一次；
+ *      - **当前 profile 显式给出的值优先**：`exitGuard` 已存在于用户层（哪怕
+ *        是显式 `false`）时不覆盖；
+ *      - 值已经与生效值相同（等于 schema 默认）时不写盘；
  *      - 旧文件永不改写、永不删除；导入失败只告警，不影响插件装载。
  *
  * 持久化与生效：写入经 `settings.update`（= configEditor 校验完整候选后落盘 +
- * Loader 调和）。因为 `exitGuard` 是 volatile 字段，写入不会重挂本行，运行中的
- * 消费方（预设守卫、CLI 路由）下一次读取即拿到新值。
+ * Loader 调和）。因为 `exitGuard` 是 volatile 字段，写入不会重挂本行。
  *
- * 零第三方依赖：只用 node 内置模块 + 本包 `src/config.js`。
+ * 零第三方依赖：只用 node 内置模块 + 本包 `src/config.js` / `src/owns-host.js`。
  */
 
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { ENTRY_ID } from './config.js'
 import { resolveDshHome } from './dsh-home.js'
-import { installOwnsHostTap, registerCapabilitiesRoute } from './panel.js'
+import { installOwnsHostTap } from './owns-host.js'
 
 /** 旧配置文件名，按优先级排列（新名优先，旧名只读回退）。 */
 export const LEGACY_FILES = Object.freeze(['eng.json', 'atlas.json'])
@@ -126,13 +127,13 @@ function loaderOf(ctx) {
  * 调用方保证「只调用一次」；本函数自身也幂等（用户层已有该字段就不写）。
  * @param ctx - 已注入 `settings` 的上下文。
  * @param env - 读取 DSH_HOME 的进程环境（测试注入点）。
- * @returns `{ imported, reason, file?, patch? }`（不抛错，失败信息只用于日志）。
+ * @returns `{ imported, reason, file?, patch? }`（不抛错以外的失败信息只用于日志）。
  */
 export async function importLegacyConfig(ctx, env = process.env) {
   const legacy = readLegacyDocument(env)
   if (legacy === undefined) return { imported: false, reason: 'absent' }
   const settings = ctx.settings
-  if (typeof settings?.describe !== 'function' || typeof settings.update !== 'function') {
+  if (typeof settings?.describe !== 'function' || typeof settings?.update !== 'function') {
     return { imported: false, reason: 'unavailable', file: legacy.file }
   }
   // Loader 装配完成后 describe() 才认得出本行（fiber 必须 active）。
@@ -150,25 +151,24 @@ export async function importLegacyConfig(ctx, env = process.env) {
 }
 
 /**
- * 装配设置侧：延迟注册只读能力路由、登记行配置页面策略、一次性导入旧配置。
+ * 装配设置侧：安装反代部署 tap、登记行配置页面策略、一次性导入旧配置。
  *
  * 由宿主行（`src/index.js` 的 `apply`）调用。所有动作都延迟到服务出现时进行：
  * 没有 webServer / settings 的组合里本函数安静返回，插件其余部分照常工作。
  * @param ctx - 插件上下文。
  * @param config - 行配置（可能含 volatile 引用）。
- * @param options - 注入点（测试用）：`env`、`route`（探针依赖，透传
- *   {@link registerCapabilitiesRoute}）。
+ * @param options - 注入点（测试用）：`env`。
+ * @returns `{ legacyImport }`：旧配置导入结束时 resolve 的 Promise（失败也
+ *   resolve，错误只记日志）。迁移模块用它保证先导入、再读取来源。
  */
 export function mountSettings(ctx, config, options = {}) {
   const env = options.env ?? process.env
 
-  // 反代部署标志：宿主行只调 mountSettings 时也必须装上（否则设置镜像降级 memory）。
+  // 反代部署标志：宿主行只调 mountSettings 时也必须装上。
   installOwnsHostTap(ctx, config)
 
-  ctx.inject(['webServer'], (webCtx) => {
-    registerCapabilitiesRoute(webCtx, () => config, options.route)
-  })
-
+  let settle
+  const legacyImport = new Promise((resolve) => { settle = resolve })
   let started = false
   ctx.inject(['settings'], (settingsCtx) => {
     // 行配置页面策略：本行自带配置页，不需要自动生成的一页。
@@ -178,7 +178,10 @@ export function mountSettings(ctx, config, options = {}) {
     } catch (error) {
       settingsCtx.logger?.warn?.(`apollo-settings: settings page policy was not registered: ${error instanceof Error ? error.message : String(error)}`)
     }
-    if (started) return
+    if (started) {
+      settle()
+      return
+    }
     started = true
     void importLegacyConfig(settingsCtx, env).then((result) => {
       if (result.imported) {
@@ -186,6 +189,7 @@ export function mountSettings(ctx, config, options = {}) {
       }
     }, (error) => {
       settingsCtx.logger?.warn?.(`apollo-settings: legacy config import skipped: ${error instanceof Error ? error.message : String(error)}`)
-    })
+    }).finally(settle)
   })
+  return { legacyImport }
 }

package/presets/eng/plugins/wait-subagent/index.js

@@ -1,233 +0,0 @@
-/**
- * `wait_subagent` tool — explicit wait for continuable children to settle.
- *
- * Preset-local plugin for the eng preset (resolved relative to this preset's
- * directory). Continuable subagents live in the `subagents` registry, not the
- * `jobs` registry, so the only settlement signal is the scoped `subagent/end`
- * event. The tool takes an ARRAY of durable child ids (`subagent_id`), awaits
- * them all concurrently (duplicates deduped, order preserved), and returns one
- * SHORT line per id (done + stopReason).
- *
- * The children's content is none of this tool's business: the subagent manager
- * unconditionally delivers a settlement notice to the parent BEFORE
- * `subagent/end` fires (dispose order: notifySettlement() →
- * observer.settle()), carrying the one-line account and the closing message.
- * A busy parent is steered, so the notice sits in the pending next-step queue
- * and reaches the model right after this tool result — exactly once, per
- * child, by the framework. Earlier designs returned the child's final message
- * here AND spliced the duplicate notice (and any mid-run `report`) out of the
- * parent inbox; that coupled this plugin to `agent.inbox` internals and to
- * the `subagent-report` source kind, which upstream removed in
- * 0.1.2-alpha.4 (bidirectional `send_message` replaced `report`). Returning
- * "done" lines and leaving delivery to the framework has no such coupling.
- * Mid-run messages the child sends (`send_message`, source kind
- * `agent-message`) likewise stay in place.
- *
- * `timeout_ms` is ONE shared window over the whole batch (all timers start at
- * the same instant), matching the semantics same-message parallel calls had.
- * Values below MIN_TIMEOUT_MS (15 minutes) are raised to it: short polling
- * waits only burned turns, since a finishing child notifies the parent anyway.
- * An id that is not a direct child fails the whole call fast — nobody is
- * waited for — keeping the contract the single-id version had. A child
- * dispatched moments ago may not have started its first turn yet: its status
- * is not `running` and no settlement exists. Returning early with a "not
- * running" note there (the pre-grace behavior) ended the turn before the
- * child even started and forced a re-wait on the next turn — session audit
- * 2f5dd618. Instead, a not-yet-started child gets a startup grace window
- * (START_GRACE_MS): the tool keeps waiting while the child spins up,
- * settles, the optional timeout elapses, or the grace expires without the
- * child ever starting (only then a retryable informational line).
- *
- * Zero imports on purpose: the module loads from the preset directory, where
- * Node's upward node_modules walk never reaches the harness install, so bare
- * package imports would fail. Everything needed comes from the context.
- */
-
-export const name = 'tool-wait-subagent'
-
-export const inject = ['tools', 'subagents', 'agents']
-
-/** Grace window for a just-dispatched child that has not started running yet. */
-const START_GRACE_MS = 30_000
-
-/** Floor for a caller-supplied timeout_ms (15 minutes). */
-const MIN_TIMEOUT_MS = 15 * 60_000
-
-/** Status polling interval while waiting for a not-yet-started child. */
-const POLL_MS = 250
-
-export function apply(ctx) {
-  /** childId -> { time, info } — latest settlement observed since mount. */
-  const settled = new Map()
-  /** childId -> finish(info) callbacks awaiting settlement. */
-  const waiters = new Map()
-
-  ctx.on('subagent/end', (info) => {
-    const id = info && info.id
-    if (typeof id !== 'string') return
-    settled.set(id, { time: Date.now(), info })
-    const list = waiters.get(id)
-    if (list !== undefined) {
-      waiters.delete(id)
-      for (const finish of [...list]) finish({ kind: 'settled', info })
-    }
-  })
-
-  ctx.tools.register({
-    name: 'wait_subagent',
-    description: 'Wait for direct subagents (from subagent or subagent_fork) to finish their current turn. Pass every id in subagent_id; all are awaited together and each gets one done line, while its closing message arrives as the settlement notice right after. Use it when your next step needs the results, instead of messaging the child to check on it. Not for bash jobs (use job_output).',
-    parameters: {
-      type: 'object',
-      properties: {
-        subagent_id: {
-          type: 'array',
-          items: { type: 'string' },
-          minItems: 1,
-          description: 'Durable ids returned by subagent or subagent_fork.',
-        },
-        timeout_ms: {
-          type: 'integer',
-          description: 'Optional shared wait window in ms; values below 900000 (15 minutes) are raised to 900000. Omit to wait until every child settles.',
-        },
-      },
-      required: ['subagent_id'],
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    isConcurrencySafe: () => true,
-    async execute(args, exec) {
-      // Dedupe preserving input order; the schema already enforces a
-      // non-empty array, the guard below only covers malformed direct calls.
-      const ids = [...new Set(Array.isArray(args.subagent_id) ? args.subagent_id : [])]
-      if (ids.length === 0) return 'subagent_id must be a non-empty array of subagent ids.'
-      const parent = exec.agent
-      if (parent === undefined) throw new Error('wait_subagent requires a calling agent (exec.agent was undefined)')
-
-      // Verify every id is one of this agent's direct children — fail fast,
-      // waiting for nobody (the contract the single-id version had).
-      let entries
-      try {
-        entries = await ctx.subagents.listChildren(parent.id, exec.signal)
-      } catch (error) {
-        return 'listChildren failed: ' + (error && error.message ? error.message : String(error))
-      }
-      const known = new Set(entries.map((entry) => entry.id))
-      const unknown = ids.filter((id) => !known.has(id))
-      if (unknown.length > 0) {
-        return `unknown subagent ${unknown.map((id) => `"${id}"`).join(', ')}: not a direct child of this agent (list_agents shows your children; only depth-1 children can be awaited).`
-      }
-
-      const statusOf = (id) => {
-        const agent = ctx.agents.get(id)
-        return agent === undefined ? 'ready' : agent.status === 'running' ? 'running' : 'idle'
-      }
-
-      /** Settlement line: short done line; content belongs to the framework notice. */
-      const doneLine = (id, info) => `subagent ${id} done (${info && info.stopReason ? info.stopReason : 'completed'}); its closing message follows as the settlement notice.`
-
-      const startedAt = Date.now()
-      const capMs = typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? Math.max(args.timeout_ms, MIN_TIMEOUT_MS) : undefined
-
-      /**
-       * Wait for one child. Resolves with {kind:'settled',info} |
-       * {kind:'timedOut'} | {kind:'aborted'} | {kind:'notStarted'}. The
-       * per-id machinery (settled fast path, waiter registration, timeout
-       * timer, startup-grace poller) is the single-id logic of old,
-       * unchanged; Promise.all over ids gives the concurrent batch.
-       */
-      const waitOne = (id) => {
-        // Fast path: the child is not running and a settlement is already on
-        // record — resolve immediately (the notice was already delivered when
-        // the child settled, so it is in the conversation history).
-        if (statusOf(id) !== 'running') {
-          const hit = settled.get(id)
-          if (hit !== undefined) return Promise.resolve({ kind: 'settled', info: hit.info })
-        }
-
-        return new Promise((resolve) => {
-          let done = false
-          let timer
-          let poller
-          const finish = (value) => {
-            if (done) return
-            done = true
-            if (poller !== undefined) clearInterval(poller)
-            const list = waiters.get(id)
-            if (list !== undefined) {
-              const index = list.indexOf(finish)
-              if (index >= 0) list.splice(index, 1)
-              if (list.length === 0) waiters.delete(id)
-            }
-            if (timer !== undefined) clearTimeout(timer)
-            if (exec.signal !== undefined) exec.signal.removeEventListener('abort', onAbort)
-            resolve(value)
-          }
-          const onAbort = () => finish({ kind: 'aborted' })
-
-          const list = waiters.get(id) ?? []
-          list.push(finish)
-          waiters.set(id, list)
-          // All ids share startedAt, so one capMs value is one shared window.
-          if (capMs !== undefined) timer = setTimeout(() => finish({ kind: 'timedOut' }), capMs)
-          if (exec.signal !== undefined) {
-            if (exec.signal.aborted) {
-              finish({ kind: 'aborted' })
-              return
-            }
-            exec.signal.addEventListener('abort', onAbort, { once: true })
-          }
-
-          // Startup grace: a freshly dispatched child sits between spawn and
-          // its first turn (status not `running`, no settlement yet). Keep the
-          // wait alive while it spins up; once `running`, only `subagent/end`
-          // (the listener above) resolves us. If the grace expires without the
-          // child ever starting or settling, fall back to a retryable note
-          // instead of the old misleading "is not running" early return.
-          poller = setInterval(() => {
-            if (done) return
-            const hit = settled.get(id)
-            if (hit !== undefined) {
-              finish({ kind: 'settled', info: hit.info })
-              return
-            }
-            if (statusOf(id) !== 'running' && Date.now() - startedAt >= START_GRACE_MS) {
-              finish({ kind: 'notStarted' })
-            }
-          }, POLL_MS)
-
-          // Re-check: the child may have settled between the fast path above
-          // and waiter registration. Only a settlement AFTER this wait started
-          // counts as a live result.
-          const hit = settled.get(id)
-          if (hit !== undefined && hit.time >= startedAt) finish({ kind: 'settled', info: hit.info })
-        })
-      }
-
-      const outcomes = await Promise.all(ids.map((id) => waitOne(id)))
-
-      // Every waiter shares one abort signal, so an interruption either
-      // aborts the whole batch or lands after some children already settled.
-      // Collapse the all-aborted case into one line; mixed cases keep
-      // per-id lines so the settled ones are not lost.
-      if (outcomes.length > 0 && outcomes.every((outcome) => outcome.kind === 'aborted')) {
-        return `wait for ${ids.length} subagent${ids.length === 1 ? '' : 's'} was aborted by user interruption; the children may still be running.`
-      }
-
-      const lines = outcomes.map((outcome, index) => {
-        const id = ids[index]
-        if (outcome.kind === 'aborted') return `wait for subagent ${id} was aborted by user interruption; the child may still be running.`
-        if (outcome.kind === 'timedOut') return `timed out waiting for subagent ${id}; it is still running. You will be notified when it finishes — you can wait_subagent it again or continue with other work.`
-        if (outcome.kind === 'notStarted') {
-          return `subagent ${id} has not started after ${Math.round(START_GRACE_MS / 1000)}s (status: ${statusOf(id)}). It may still be spinning up — call wait_subagent again, or continue with other work; you will be notified when it finishes.`
-        }
-        // Real settlement: short done line; the framework's settlement notice
-        // (already delivered to the parent inbox before `subagent/end`)
-        // carries the closing message — nothing to consume or deduplicate.
-        return doneLine(id, outcome.info)
-      })
-      return lines.join('\n')
-    },
-  })
-}

package/presets/eng/plugins/wait-subagent/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "dsh-preset-eng-wait-subagent",
-  "private": true,
-  "type": "module",
-  "main": "index.js",
-  "version": "0.1.0"
-}

package/src/cli/claude.js

@@ -1,166 +0,0 @@
-/**
- * Claude Code CLI 适配：纯命令构造 + `--print --output-format stream-json` 事件流解析。
- * 只产出 argv 与 stdin 正文并翻译事件；spawn/管道/stderr/中断由父 adapter 的
- * `ctx.subprocess` 掌握（stdin 取 `{data: input}`）。不 import 任何 DSH 包。
- *
- * 实测依据（Claude Code 2.1.300，新建 + `--resume` 各一轮真实跑通）：
- * - `--print` 不给位置参数 prompt 时正文从 stdin 读，所以 argv 里没有 prompt；
- * - `stream-json` 必须配 `--verbose` 才是完整事件流；
- * - `--permission-prompts none` = 没人回答权限提问、会被提问的一律自动拒绝，
- *   正是无人值守管道要的语义（`--permission-mode` 仍决定其余判定）；
- * - 续接用 `--resume <SESSION_ID>`；**不传** `--no-session-persistence`，否则会话
- *   不落盘、下一轮无法续接；
- * - claude **没有** cwd 选项（`--add-dir` 只是追加可写目录），工作目录由进程 cwd
- *   决定，故本模块接受并忽略 `cwd`，交给父 adapter 的 spawn `cwd`；`profile` 是
- *   codex 专属概念，同样忽略。
- *
- * 事件语义：
- * - `system`（hook_started / hook_response / init）都带 `session_id`，且前两者出现在
- *   `init` **之前**——故 remoteId 在「第一个带 session_id 的 system 事件」就回报；
- * - `assistant` → `message.content[]` 里 `type === 'text'` 的块拼成正文；`tool_use` /
- *   `thinking` 块**绝不**当作正文；带 `parent_tool_use_id` 的是子代理消息，也不计入；
- * - `result` → 唯一权威收尾：`subtype === 'success' && is_error !== true` 才算成功；
- *   `result` 字段是最终答复文本（覆盖累积值），`usage` 是整轮用量。
- */
-
-import { normalizeUsage, requireEnum, requireEffort, requireId, requirePrompt, requireText, sanitizeError } from './jsonl.js'
-
-/** `claude --permission-mode` 的实测取值（`claude --help`）。 */
-const PERMISSION_MODES = ['acceptEdits', 'auto', 'bypassPermissions', 'manual', 'dontAsk', 'plan']
-
-/**
- * 构造一轮 `claude --print` 调用。
- *
- * @param {object} spec
- * @param {string} [spec.executable='claude'] - 可执行名或绝对路径。
- * @param {string} [spec.cwd] - 接受但忽略：claude 无 cwd 选项，请用 spawn 的 cwd。
- * @param {string} [spec.model] - `--model`，别名（sonnet/opus…）或全名。
- * @param {string} [spec.effort] - `--effort`，实测取值 low/medium/high/xhigh/max。
- * @param {string} [spec.profile] - 接受但忽略：codex 专属概念。
- * @param {string} [spec.permissionMode] - `--permission-mode`。
- * @param {string} [spec.remoteId] - 已有 session id 时走 `--resume <id>`。
- * @param {string} spec.prompt - 正文，经 stdin 送入。
- * @returns {{argv: string[], input: string}}
- */
-export function buildCommand({ executable = 'claude', model, effort, permissionMode, remoteId, prompt } = {}) {
-  const argv = [requireText(executable, 'executable'), '--print', '--output-format', 'stream-json', '--verbose']
-  if (model !== undefined) argv.push('--model', requireText(model, 'model'))
-  if (effort !== undefined) argv.push('--effort', requireEffort(effort))
-  if (permissionMode !== undefined) argv.push('--permission-mode', requireEnum(permissionMode, PERMISSION_MODES, 'permissionMode'))
-  // 无人值守：任何权限提问都自动拒绝，而不是挂起等一个永远不会来的回答。
-  argv.push('--permission-prompts', 'none')
-  if (remoteId !== undefined) argv.push('--resume', requireId(remoteId, 'remoteId'))
-  // 正文走 stdin（`--print` 无位置参数时读 stdin），argv 里不出现 prompt。
-  return { argv, input: requirePrompt(prompt) }
-}
-
-/**
- * 创建一个有状态的 claude 事件解析器（一轮子进程一个）。
- *
- * @returns {{push: (event: unknown) => ({remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined), finish: () => {text: string, remoteId?: string, usage?: object}}}
- */
-export function createParser() {
-  let remoteId
-  let text = ''
-  let usage
-  let completed = false
-  let failure
-
-  /** 失败时优先用 provider 给的错误正文，否则退化成 subtype/api_error_status。 */
-  function describeResultFailure(event) {
-    const label = typeof event.subtype === 'string' && event.subtype !== '' ? event.subtype : 'error'
-    const detail = typeof event.result === 'string' && event.result !== '' ? event.result
-      : Array.isArray(event.errors) ? event.errors.filter((item) => typeof item === 'string').slice(0, 3).join('; ') : ''
-    const status = event.api_error_status === undefined ? '' : ` (api_error_status=${event.api_error_status})`
-    return sanitizeError(detail === '' ? `claude result ${label}${status}` : `claude result ${label}${status}: ${detail}`)
-  }
-
-  return {
-    /**
-     * 投喂一个已解析的事件。
-     * @param {unknown} event - `readJsonLines` 产出的单个事件。
-     * @returns {{remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined}
-     *   本次事件产生的动作；无动作返回 undefined。
-     *   `error` 是**信息性**的：只有 `finish()` 抛错才代表这一轮失败。
-     */
-    push(event) {
-      if (event === null || typeof event !== 'object') return undefined
-      switch (event.type) {
-        case 'system': {
-          if (typeof event.session_id !== 'string' || event.session_id === '') return undefined
-          // 只回报一次；实测 hook_started 早于 init，因此这里通常是最早的时机。
-          if (remoteId !== undefined) return undefined
-          remoteId = event.session_id
-          return { remoteId }
-        }
-        case 'assistant': {
-          // 子代理（Task 工具）的消息带 parent_tool_use_id，不能混进主答复。
-          if (typeof event.parent_tool_use_id === 'string' && event.parent_tool_use_id !== '') return undefined
-          const message = event.message
-          if (message === null || typeof message !== 'object' || !Array.isArray(message.content)) return undefined
-          const chunk = message.content
-            .filter((block) => block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
-            .map((block) => block.text)
-            .join('')
-          if (chunk === '') return undefined
-          // 覆盖式：一条 assistant 事件就是一条完整消息，最后一条才是最终答复。
-          text = chunk
-          return { text }
-        }
-        case 'result': {
-          const mapped = mapClaudeUsage(event.usage)
-          if (mapped !== undefined) usage = mapped
-          const succeeded = event.subtype === 'success' && event.is_error !== true
-          if (succeeded) {
-            completed = true
-            if (typeof event.result === 'string' && event.result !== '') text = event.result
-          } else {
-            failure ??= describeResultFailure(event)
-          }
-          return {
-            ...(mapped === undefined ? {} : { usage: mapped }),
-            ...(succeeded ? { completed: true } : { error: failure }),
-            ...(succeeded && typeof event.result === 'string' && event.result !== '' ? { text: event.result } : {}),
-          }
-        }
-        default:
-          // user（工具结果）/ stream_event / 未来新增事件：无语义动作。
-          return undefined
-      }
-    },
-
-    /**
-     * 收流。失败或缺少 `result` 都抛错——「流结束了」不等于「回合成功了」。
-     * 幂等：可重复调用，不改变状态。
-     * @returns {{text: string, remoteId?: string, usage?: object}}
-     */
-    finish() {
-      if (failure !== undefined) throw new Error(`claude 回合失败：${failure}`)
-      if (!completed) throw new Error('claude 流在收到成功的 result 事件之前结束')
-      return {
-        text,
-        ...(remoteId === undefined ? {} : { remoteId }),
-        ...(usage === undefined ? {} : { usage }),
-      }
-    },
-  }
-}
-
-/**
- * 把 claude 的整轮用量映射成 DSH TokenUsage。
- *
- * Anthropic 的 `input_tokens` 本来就**不含**缓存（另给 `cache_read_input_tokens` /
- * `cache_creation_input_tokens`），与 DSH 约定一致，无需扣减；
- * `output_tokens_details.thinking_tokens` 映射为 reasoning。
- */
-function mapClaudeUsage(raw) {
-  if (raw === null || typeof raw !== 'object') return undefined
-  const details = raw.output_tokens_details
-  return normalizeUsage({
-    inputTokens: raw.input_tokens,
-    outputTokens: raw.output_tokens,
-    cacheReadTokens: raw.cache_read_input_tokens,
-    cacheWriteTokens: raw.cache_creation_input_tokens,
-    reasoningTokens: details !== null && typeof details === 'object' ? details.thinking_tokens : undefined,
-  })
-}