@xyagent/cli 0.0.1

package/src-ext/runtime/hermes/handleRequest.mjs

@@ -0,0 +1,1257 @@
+/**
+ * handleRequest.mjs — hermes runtime D-C2.1
+ *
+ * 把 hermes handleRequest 逻辑提取为独立模块，以便单元测试。
+ *
+ * createHermesHandleRequest({ pre, log, gwId, usage, dispatchHandlerOptions, workspaceRpc? })
+ *   → async (request, ctx) => void
+ *
+ * 请求路由（三分支）：
+ *   1. request.request.__relayKind === "rpc" → workspaceRpc.dispatch → publishEvent response(body=JSON) + end → 结束
+ *   2. request.request.__kind === "agent.run.dispatch" → unifiedDispatchHandler（返回 true）→ 结束
+ *   3. 否则 → 原有 streamChat 旧路径（含 appendTurn）
+ *
+ * dispatchHandlerOptions:
+ *   relayUrl       string         relay 服务地址
+ *   bridgeToken    string         bridge 鉴权 token
+ *   producerFactory?  Function   注入 producer（测试用）
+ *   openclawInvoke?   Function   注入 openclawInvoke（测试用；若未注入则使用默认）
+ *   _backendOverride? Object     注入旧路径 backend（测试用）
+ *
+ * workspaceRpc:
+ *   可选，createHermesWorkspaceRpc 实例。默认由 handleRequest 内部实例化。
+ *   注入用于单测隔离文件系统。
+ */
+
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+import * as httpBackendMod from "./httpBackend.mjs";
+import * as commandBackendMod from "./commandBackend.mjs";
+import * as responsesBackendMod from "./responsesBackend.mjs";
+import { appendTurn, clearHistory, readHistory } from "./sessionStore.mjs";
+import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
+import { fetchAndBase64Encode } from "../_shared/fetchAndBase64Encode.mjs";
+import { relayObjectToBlock } from "../_shared/relayObjectToBlock.mjs";
+import { createHermesWorkspaceRpc } from "./workspaceRpc.mjs";
+import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
+import { createWorkspace as _defaultCreateWorkspace } from "../../core/createWorkspace.mjs";
+import {
+  classifySlashCommand,
+  emitAssistantText,
+} from "../_shared/slashCommandRouter.mjs";
+import { createInterruptGateway } from "../../core/interruptGateway.mjs";
+import { waitForRunResumed } from "../../core/interruptRunListener.mjs";
+import { listSessionsForRuntime, buildSessionLabel, buildSessionSubtitle } from "../_shared/sessionPicker.mjs";
+import {
+  buildRunStarted,
+  buildRunCompleted,
+  buildRunPaused,
+  buildBlockStarted,
+  buildBlockCompleted,
+  newBlockId,
+  newRunId,
+} from "../../../src-shared/envelope_builder.mjs";
+import { createHermesTodoTranslator } from "./todoTranslator.mjs";
+import { createActiveRunRegistry } from "../../core/activeRuns.mjs";
+
+// /v1/responses 端点选择：hermes-agent 自家实现，**仅**它支持；切上去 bridge
+// 才能拿 delegate_task 的真实返回值（chat/completions 上 _on_tool_progress
+// 过滤掉 tool.completed，api_server.py:751）。
+//
+// 启用规则：
+//   - pre.useResponsesApi === true            → 走 responsesBackend（强制 opt-in）
+//   - pre.useResponsesApi === false           → 走 httpBackend（强制 opt-out）
+//   - 未设 + apiBaseUrl 指向 localhost/127.0.0.1 → 默认 responsesBackend
+//                                                （本地 hermes-agent，大概率支持）
+//   - 未设 + 其它 → httpBackend（兼容 LM Studio/Ollama/vLLM 等）
+//
+// 失败时不自动 fallback —— 端点选错的话报错更清楚；用户改 HERMES_BRIDGE_USE_RESPONSES_API
+// env 即可显式切回 chat/completions。
+function _shouldUseResponsesApi(pre) {
+  if (typeof pre?.useResponsesApi === "boolean") return pre.useResponsesApi;
+  const envFlag = String(process.env.HERMES_BRIDGE_USE_RESPONSES_API || "").trim().toLowerCase();
+  if (envFlag === "1" || envFlag === "true" || envFlag === "yes") return true;
+  if (envFlag === "0" || envFlag === "false" || envFlag === "no") return false;
+  const url = String(pre?.apiBaseUrl || "");
+  return /\b(127\.0\.0\.1|localhost|::1)\b/.test(url);
+}
+
+// hermes-agent api_server.py 只在 tool.started 时发 event:hermes.tool.progress
+// 帧（line 751: `if event_type != "tool.started": return`），不发完成事件。
+// bridge 端要把这个**单向**信号补齐成 unified protocol 的 tool_use{started→completed}
+// + tool_result 闭环，server subagent_synth 才能给 delegate_task 之类的派生工具
+// 合成 subagent_ref（synth.go:34 defaultToolNames 已含 "delegate_task"）。
+//
+// 生成 synthetic tool_call_id —— hermes 不暴露真实 id，bridge 自造一个稳定字串
+// 即可，protocol 仅要求非空（go_relay/internal/protocol/unified/block.go:312）。
+function newSyntheticToolCallId() {
+  return "tcu_hermes_" + randomBytes(8).toString("hex");
+}
+
+const SYSTEM_PROMPT_DEFAULT =
+  "You are Hermes, a helpful assistant integrated with the agentlink platform.";
+
+/**
+ * 从 workspace_path（可含 ~ 前缀）中解析 profile 名和 hermesHome 绝对路径。
+ *
+ * workspace_path 形如：
+ *   /Users/alice/.hermes/profiles/deepseek32  → profileName="deepseek32"
+ *   ~/.hermes/profiles/gemini3pro             → profileName="gemini3pro"
+ *   ~/.hermes                                 → profileName="default"（root profile）
+ *   /Users/alice/.hermes                      → profileName="default"（root profile）
+ *
+ * align-runtime-default-workspace: 当归一化路径 === root ~/.hermes 时
+ * 返回 profileName="default"（不取 basename=".hermes"），
+ * 以与 readHermesWorkspaces 的 default entry 语义对齐。
+ *
+ * 返回 { profileName, profileHome } 或 null（不符合 profiles/* 路径结构时）。
+ *
+ * @param {string} workspacePath
+ * @returns {{ profileName: string, profileHome: string } | null}
+ */
+function _resolveWorkspacePathProfile(workspacePath) {
+  if (!workspacePath || typeof workspacePath !== "string") return null;
+  // expand ~ 前缀
+  const expanded = workspacePath.startsWith("~")
+    ? path.join(os.homedir(), workspacePath.slice(1))
+    : workspacePath;
+  const normalized = path.resolve(expanded);
+  if (!normalized) return null;
+
+  // align-runtime-default-workspace: root hermesHome（~/.hermes）→ profileName="default"
+  const hermesRoot = path.join(os.homedir(), ".hermes");
+  if (path.normalize(normalized) === path.normalize(hermesRoot)) {
+    return { profileName: "default", profileHome: hermesRoot };
+  }
+
+  const profileName = path.basename(normalized);
+  if (!profileName) return null;
+  return { profileName, profileHome: normalized };
+}
+
+/**
+ * @param {{
+ *   pre: {
+ *     backend: "http"|"command",
+ *     model: string,
+ *     apiKey?: string,
+ *     apiBaseUrl?: string,
+ *     command?: string,
+ *   },
+ *   log: { info, warn, error, child? },
+ *   gwId: string,
+ *   usage: { addCost, schedulePublish, setTokensAbsolute },
+ *   dispatchHandlerOptions: {
+ *     relayUrl: string,
+ *     bridgeToken: string,
+ *     producerFactory?: Function,
+ *     openclawInvoke?: Function,
+ *     _backendOverride?: Object,  // 仅测试用
+ *   },
+ *   profileHome: string  默认 profileHome（bridge 启动时由 pair state profileName 计算），
+ *                        无 workspace_path 时作为 fallback。不允许内部 fallback 到 process.env.HERMES_HOME。
+ *   workspaceRpc?: { dispatch(method: string, params: object): Promise<{ok:boolean, error?:string}> }
+ *                  可选，测试隔离用注入的 fake rpc，优先于 profileHome
+ *   _manageProfileGateway?: Function  可选，测试隔离用注入的 manageProfileGateway（模型 b per-conv 路由）
+ * }} opts
+ * @returns {(request: any, ctx: any) => Promise<void>}
+ */
+export function createHermesHandleRequest({ pre, log, gwId, usage, dispatchHandlerOptions, profileHome, workspaceRpc: injectedWorkspaceRpc, scanner, _manageProfileGateway, _createWorkspace }) {
+  // Workspace RPC handler：处理 identity.soul.set 等 gateway → bridge RPC 请求
+  // 优先级：injectedWorkspaceRpc（测试隔离）> profileHome（必填，来自 resolveProfileHome(gwId)）
+  // 不允许 fallback 到 process.env.HERMES_HOME 或无参兜底（核心不变量）
+  const workspaceRpc = injectedWorkspaceRpc ?? createHermesWorkspaceRpc({ hermesHome: profileHome, log });
+
+  // 确定旧路径使用的 backend（测试可通过 _backendOverride 注入）
+  const {
+    relayUrl,
+    bridgeToken,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke,
+    _backendOverride,
+  } = dispatchHandlerOptions ?? {};
+
+  // manageProfileGateway 能力：注入（测试隔离）或运行时懒加载（避免 import 循环）
+  // _manageProfileGateway 参数在构造时注入（测试 / index.mjs 生产路径）
+  let _resolvedManageProfileGateway = _manageProfileGateway ?? null;
+  let _gwModuleCache = null;
+  async function _gwModule() {
+    // 运行时动态加载 gatewayManager（避免 circular import）；缓存模块
+    if (!_gwModuleCache) _gwModuleCache = await import("./gatewayManager.mjs");
+    return _gwModuleCache;
+  }
+  async function _getManageProfileGateway() {
+    if (_resolvedManageProfileGateway) return _resolvedManageProfileGateway;
+    _resolvedManageProfileGateway = (await _gwModule()).manageProfileGateway;
+    return _resolvedManageProfileGateway;
+  }
+
+  // interrupt 闸门 — /resume picker 挂起/恢复
+  const interruptGateway = createInterruptGateway({ log });
+
+  // per-handler activeRuns 注册表 — 供 sessions.abort / chat.abort 分支使用
+  const activeRuns = createActiveRunRegistry({ log });
+
+  // 默认 openclawInvoke：调用 hermes backend.streamChat，把 chunk 翻译为统一格式
+  // 模型 b：每次 dispatch 按 workspace_path 解析 profile，确保对应 gateway 健康，
+  //         用该 profile 的 baseUrl + hermesHome（per-conversation routing）。
+  // Task 4.1: 加入 blocks 参数，支持 image + PDF attachment multimodal content
+  // run_id 由 unifiedDispatchHandler 透传 —— hermes 在 delegate_task 派生 subagent
+  // 时需要它作为 parent_run_id 挂到 child run.started/run.completed 上。
+  const defaultOpenclawInvoke = async ({ run_id: parentRunId, input, blocks = [], onChunk: _rawOnChunk, _fetchAndBase64Encode, thread_id, workspace_path }) => {
+    // ── 模型 b: per-conversation profile 路由 ────────────────────────────────
+    // 若 workspace_path 非空，按请求动态解析 profile，确保其 gateway 健康，
+    // 用该 profile 的 baseUrl + hermesHome。否则 fallback 到默认 profileHome。
+    let effectiveProfileHome = profileHome;  // 默认：bridge 启动时固定的 profileHome
+    let effectiveApiBaseUrl = pre.apiBaseUrl;  // 默认：bridge 启动时固定的 apiBaseUrl
+    let effectiveApiKey = pre.apiKey;  // 默认：bridge 启动时固定的 apiKey
+
+    const workspaceResolved = workspace_path ? _resolveWorkspacePathProfile(workspace_path) : null;
+    if (workspaceResolved) {
+      const { profileName, profileHome: reqProfileHome } = workspaceResolved;
+      let gwResult;
+      try {
+        const mgr = await _getManageProfileGateway();
+        gwResult = await mgr(profileName, reqProfileHome, { mode: "ensure", log });
+      } catch (err) {
+        // workspace_path 明确指定了 profile，但 gateway 起不来 —— **不回退默认 profile**，
+        // 否则会用错身份/凭证应答（串台）。直接抛错让上层走 response.failed，报错更诚实。
+        throw new Error(`hermes profile '${profileName}' gateway 启动异常：${err?.message || err}`);
+      }
+      if (gwResult?.ok && gwResult.baseUrl) {
+        effectiveProfileHome = reqProfileHome;
+        effectiveApiBaseUrl = gwResult.baseUrl + "/v1";
+        // bridge→gateway 鉴权必须用该 profile 自己的 API_SERVER_KEY（各 profile 不同）；
+        // 沿用默认 profile 的 key 会被目标 gateway 以 401 拒（串台 bug fix）。
+        const { readProfileEnvValue } = await _gwModule();
+        const profKey = readProfileEnvValue(reqProfileHome, "API_SERVER_KEY");
+        if (profKey) effectiveApiKey = profKey;
+        log.info?.("hermes.per_conv_profile.resolved", "per-conversation profile gateway ready", {
+          run_id: parentRunId, profileName, profileHome: reqProfileHome,
+          baseUrl: effectiveApiBaseUrl,
+        });
+      } else {
+        // 指定了 profile 但 gateway 未就绪 → 报错，不静默回退默认身份。
+        throw new Error(`hermes profile '${profileName}' gateway 未就绪：${gwResult?.error || "unknown"}`);
+      }
+    }
+    // ── 构造本次请求的 pre（可能是 per-profile override）────────────────────
+    const effectivePre = (effectiveApiBaseUrl !== pre.apiBaseUrl || effectiveApiKey !== pre.apiKey)
+      ? { ...pre, apiBaseUrl: effectiveApiBaseUrl, apiKey: effectiveApiKey }
+      : pre;
+    // ── 自动 attach 扫描器（fire-and-forget，不阻塞流式输出）─────────────
+    // scanner 由工厂注入（bootstrapAgentlinkTools.scanner）。每个 turn 一个新
+    // accumulator,按 `\n` 切完整行交给 scanner,扫到本机路径就异步走 attach_file。
+    // 包一层 onChunk 拦截 response.output_text.delta 喂 accumulator;包完所有
+    // text 都覆盖（包括 slash command 的 emitAssistantText 路径）。
+    const _acc = scanner?.createTurnAccumulator({ requestId: parentRunId });
+    const onChunk = _acc
+      ? async (event) => {
+          if (event && event.event === "response.output_text.delta" && typeof event.delta === "string") {
+            try { _acc.append(event.delta); } catch { /* swallow: 扫描器异常永远不破坏主流 */ }
+          }
+          return _rawOnChunk(event);
+        }
+      : _rawOnChunk;
+    try {
+    // ── Hermes slash command 拦截 ─────────────────────────────────────────
+    // hermes worker 之前直接把 /status /usage /model 等当 prompt 喂给 LLM,
+    // LLM 拿 cached_context 当问题, 回 "你这条消息没有实际问题" 的废话。
+    // 跟 codex/claude 一样, 在 bridge 层拦下来, 用 bridge 真实状态合成响应。
+    const slash = await classifySlashCommand(input, "hermes", {
+      model: pre?.model || null,
+      apiBaseUrl: pre?.apiBaseUrl || null,
+      backend: pre?.backend || null,
+      cwd: process.cwd(),
+      gwId,
+      threadId: thread_id || null,
+      version: pre?.version || null,
+      historyFn: async () => {
+        try { return await readHistory(gwId); } catch { return []; }
+      },
+      usageStats: typeof usage?.getStats === "function" ? usage.getStats() : null,
+    });
+    if (slash.kind === "client-reset") {
+      try { await clearHistory(gwId); } catch { /* ignore */ }
+      log.info?.("hermes.slash.clear",
+        "client-reset slash command, cleared session history",
+        { gwId, command: slash.command });
+      await emitAssistantText(onChunk, slash.ackText);
+      return;
+    }
+    if (slash.kind === "bridge-synth") {
+      log.info?.("hermes.slash.synth",
+        "bridge-synthesized slash response",
+        { gwId, command: slash.command });
+      await emitAssistantText(onChunk, slash.responseText);
+      return;
+    }
+
+    // ── /resume interrupt session picker (hermes) ───────────────────────────
+    if (slash.kind === "interrupt-session-pick") {
+      log.info?.("hermes.slash.resume_picker", "/resume: starting interrupt session picker", { thread_id, run_id: parentRunId });
+      const sessions = await listSessionsForRuntime("hermes");
+      if (sessions.length === 0) {
+        await emitAssistantText(onChunk, "暂无历史会话，直接开始新对话吧");
+        return;
+      }
+      const blockId = newBlockId();
+      const options = sessions.map((s) => ({ id: s.session_id, label: buildSessionLabel(s), description: buildSessionSubtitle(s) }));
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [
+          buildRunStarted(parentRunId),
+          buildBlockStarted(parentRunId, {
+            id: blockId, type: "interrupt", subtype: "question",
+            prompt: "选择要续接的历史会话", options, selection_mode: "single",
+          }),
+          buildRunPaused(parentRunId, [blockId]),
+        ],
+      });
+      const { promise } = interruptGateway.openRequest({ runId: parentRunId, blockId, interruptId: blockId });
+      const listenerPromise = (relayUrl && bridgeToken && thread_id)
+        ? waitForRunResumed({ relayUrl, bridgeToken, threadId: thread_id, runId: parentRunId, interruptId: blockId, log })
+            .then(({ value }) => interruptGateway.settle(blockId, value))
+            .catch((err) => log.warn?.("hermes.slash.resume_picker.listener_err", err?.message))
+        : Promise.resolve();
+      let decisionValue;
+      try {
+        decisionValue = await promise;
+      } catch {
+        return;
+      }
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [
+          buildBlockCompleted(parentRunId, { id: blockId, type: "interrupt", subtype: "question", prompt: "选择要续接的历史会话", status: "completed", value: decisionValue }),
+          buildRunCompleted(parentRunId, "end_turn"),
+        ],
+      });
+      // hermes 的 session 续接：选中的 session_id 对应 ~/.agentlink/hermes/sessions/<id>.json
+      // 下次 dispatch 时，hermes readHistory(sessionId) 会加载这个 session 的历史消息。
+      // 通过 gwId 作为 hermes 的 session key（hermes sessionStore 用 gwId 键）。
+      const selectedSessionId = decisionValue?.option_id ?? null;
+      if (selectedSessionId) {
+        log.info?.("hermes.slash.resume_picker.done", "hermes session selected, loading history on next turn", {
+          session_id: selectedSessionId,
+        });
+        // 把选中 session 的历史消息预加载到当前 gwId：实质上是把 selectedSessionId 的
+        // history 复制到 gwId session，以便下次 dispatch 能带上正确的上下文。
+        // 注意：这是 hermes-specific 的 resume 语义，不同于 claude --resume。
+        try {
+          const { readHistory: readHistoryFn, appendTurn: appendTurnFn } = await import("./sessionStore.mjs");
+          const history = await readHistoryFn(selectedSessionId);
+          // 以最后一条 user 消息为截断点，取整完整的 turn 对
+          if (history.length > 0) {
+            // 把 selectedSession 的历史写入 gwId session（替换，而非追加）
+            const { ensureRoot } = await import("./sessionStore.mjs");
+            const { promises: fsp } = await import("node:fs");
+            const nodePath = await import("node:path");
+            const nodeOs = await import("node:os");
+            const ROOT = nodePath.default.join(nodeOs.default.homedir(), ".agentlink", "hermes", "sessions");
+            await ensureRoot();
+            await fsp.writeFile(
+              nodePath.default.join(ROOT, `${gwId}.json`),
+              JSON.stringify({ messages: history }, null, 2),
+              "utf8",
+            );
+            log.info?.("hermes.slash.resume_picker.history_loaded", "history copied to current session", {
+              from: selectedSessionId, to: gwId, turns: Math.floor(history.length / 2),
+            });
+          }
+        } catch (err) {
+          log.warn?.("hermes.slash.resume_picker.history_err", "failed to load history for resumed session", {
+            session_id: selectedSessionId, err: err?.message,
+          });
+        }
+      }
+      await listenerPromise;
+      return;
+    }
+
+    // not-slash: 继续走 LLM 路径
+
+    const useResponses = _shouldUseResponsesApi(effectivePre);
+    let backendName = "httpBackend";
+    let backend;
+    if (_backendOverride) {
+      backend = _backendOverride;
+      backendName = "override";
+    } else if (effectivePre.backend === "command") {
+      backend = commandBackendMod;
+      backendName = "commandBackend";
+    } else if (useResponses) {
+      backend = responsesBackendMod;
+      backendName = "responsesBackend";
+    } else {
+      backend = httpBackendMod;
+      backendName = "httpBackend";
+    }
+    const doFetchAndBase64 = _fetchAndBase64Encode ?? fetchAndBase64Encode;
+    log.info("dispatch.debug.in", "hermes dispatch handling", {
+      run_id: parentRunId,
+      backend: backendName,
+      api_base_url: effectivePre.apiBaseUrl,
+      useResponsesApi_decision: useResponses,
+      useResponsesApi_envFlag: String(process.env.HERMES_BRIDGE_USE_RESPONSES_API || "(unset)"),
+      blocks_summary: (blocks ?? []).map((b) => {
+        const kind = b?.source?.kind ? `/${b.source.kind}` : "";
+        const mime = b?.mime ? `(${b.mime})` : "";
+        return `${b?.type ?? "?"}${kind}${mime}`;
+      }).join(",") || "(none)",
+      inputText_len: typeof input === "string" ? input.length : 0,
+    });
+
+    // Phase 5 (multimodal-attachment-llm-dispatch): relay_object blocks を
+    // relayObjectToBlock に通し、結果を OpenAI 互換形式（image_url / file）に変換する。
+    // hermes は ["text","image"] の caps（pdf は pdfjs fallback 経由）
+    const relayContentBlocks = [];
+    const relayBlocks = (blocks ?? []).filter(
+      (b) =>
+        (b?.type === "image" || b?.type === "attachment") &&
+        b?.source?.kind === "url" &&
+        b?.source?.url,
+    );
+    for (const block of relayBlocks) {
+      const result = await relayObjectToBlock(block, {
+        runtimeHint: "hermes",
+        modelCaps: ["text", "image"],  // hermes: image ok, pdf → text fallback
+        fetchAndBase64Encode: doFetchAndBase64,
+      });
+
+      if (result.error) {
+        // caps_mismatch / fetch_failed / size_exceeded → text fallback
+        const name = block?.name ?? block?.source?.media_type ?? "file";
+        relayContentBlocks.push({
+          type: "text",
+          text: `[${block?.type === "image" ? "image" : `file: ${name}`}] (encoding failed: ${result.error.message})`,
+        });
+        continue;
+      }
+
+      // relayObjectToBlock 結果を OpenAI 互換 content block に変換
+      switch (result.type) {
+        case "input_image":
+          // OpenAI image_url format: data URI
+          relayContentBlocks.push({
+            type: "image_url",
+            image_url: { url: `data:${result.source.media_type};base64,${result.source.data}` },
+          });
+          break;
+        case "input_file":
+          // OpenAI file format: data URI
+          relayContentBlocks.push({
+            type: "file",
+            file: {
+              filename: result.source.filename,
+              file_data: `data:${result.source.media_type};base64,${result.source.data}`,
+            },
+          });
+          break;
+        case "input_text":
+          // text fallback（document text extraction / binary description）
+          relayContentBlocks.push({ type: "text", text: result.text });
+          break;
+        default:
+          break;
+      }
+    }
+
+    // relay block を含む場合は content array、なければ string（向后兼容）
+    const hasMultimodal = relayContentBlocks.length > 0;
+    let userContent;
+    if (hasMultimodal) {
+      // array 格式：text block（可以为空字符串，OpenAI 允许）+ relay content blocks
+      const contentArray = [];
+      if (input) {
+        contentArray.push({ type: "text", text: input });
+      }
+      contentArray.push(...relayContentBlocks);
+      userContent = contentArray;
+    } else {
+      userContent = input;
+    }
+
+    // 构造消息（dispatch 路径不读本地 history，直接用 input 作单条 user 消息）
+    const messages = [
+      { role: "system", content: SYSTEM_PROMPT_DEFAULT },
+      { role: "user", content: userContent },
+    ];
+    log.info("dispatch.debug.built", "hermes user content ready", {
+      hasMultimodal,
+      relay_block_count: relayContentBlocks.length,
+      relay_block_types: relayContentBlocks.map((b) => b.type).join(","),
+      user_content_kind: Array.isArray(userContent) ? "array" : "string",
+      user_content_parts: Array.isArray(userContent) ? userContent.map((p) => p.type).join(",") : null,
+      backend: effectivePre.backend,
+      model: effectivePre.model,
+      apiBaseUrl: effectivePre.apiBaseUrl,
+    });
+    // AbortController — 供 sessions.abort / chat.abort RPC 中断本次流式
+    // dispatch 路径：sessionKey / runId 均为 parentRunId（unifiedDispatch 协议）
+    const ac = new AbortController();
+    const unregisterRun = activeRuns.register({
+      sessionKey: String(parentRunId ?? ""),
+      threadId: String(thread_id ?? ""),
+      runId: String(parentRunId ?? ""),
+      kill: (reason) => ac.abort(reason),
+    });
+    const stream = backend.streamChat(messages, {
+      apiBaseUrl: effectivePre.apiBaseUrl,
+      apiKey: effectivePre.apiKey,
+      command: effectivePre.command,
+      model: effectivePre.model,
+      hermesHome: effectiveProfileHome,  // per-conversation profile HERMES_HOME（模型 b）
+      signal: ac.signal,
+    });
+    log.info("dispatch.debug.stream_opened", "hermes backend.streamChat returned, awaiting chunks");
+    // Track open tool_use calls so we can synthesize a completed event when
+    // the stream ends (OpenAI tool_calls don't emit a per-call completion).
+    const openToolCalls = new Map(); // call_id → { name, argsAccum }
+
+    // todo translator：在 envelope_builder 之前拦截 todo 工具调用（Responses API 路径）
+    const todoTranslator = createHermesTodoTranslator(parentRunId);
+
+    // ── hermes subagent state machine ─────────────────────────────────────
+    //
+    // hermes-agent api_server.py 只发 `event: hermes.tool.progress` (tool.started)，
+    // 不发 tool.finished / 子 agent 完成事件。bridge 必须补齐两件事：
+    //
+    //   1. 每个 tool 的 tool_result —— 老实现把所有 progress 攒到 stream done
+    //      再一次性 flush，意味着用户要等整轮 LLM 输出结束才能看到任何 tool
+    //      结果。新实现「立即 flush」：下一个 tool.progress 到达时（或 done
+    //      时）就关闭上一个 tool，让 App 实时看到进度。
+    //
+    //   2. delegate_task 的子 run 生命周期 —— hermes 不开独立 session，bridge
+    //      为 delegate_task 合成一条 child run（run.started/run.completed 带
+    //      parent_run_id + extensions.openclaw.child_session_key），让
+    //      subagent_synth.synthChildRunTerminal 走标准 §9.1.4 时序在 child
+    //      run.completed 落地时发 subagent_ref.completed；delegate_task 之
+    //      后到达的工具进度（read / exec / ...）都挂在 child run 上，App 端
+    //      SubagentRefBlockView 可以通过 view.findRun(childRunId) 展开看子
+    //      agent 干了什么。
+    //
+    // hermes 不发嵌套信息 —— 后续 delegate_task 视为 sibling（关掉前一个
+    // subagent 再开新的）。
+    //
+    /** @type {null | {
+     *   childRunId: string,
+     *   parentCallId: string,
+     *   agent: string,
+     *   childSessionKey: string,
+     *   childTools: Array<{ name: string, label: string }>,
+     * }} */
+    let currentSubagent = null;
+    /** @type {null | { callId: string, name: string, label: string, runId: string }} */
+    let inflightTool = null;
+
+    // Immediate-flush: 关闭当前 inflightTool, 发它的 tool_result。call site:
+    //   - 下一个 hermes_tool_progress 到达时
+    //   - stream done / error 时
+    async function flushInflightTool(isError = false) {
+      if (!inflightTool) return;
+      const { callId, name, label, runId } = inflightTool;
+      inflightTool = null;
+      const summaryText = label || `${name} completed`;
+      if (currentSubagent && runId === currentSubagent.childRunId) {
+        currentSubagent.childTools.push({ name, label });
+      }
+      await onChunk({
+        event: "response.tool_result",
+        call_id: callId,
+        run_id: runId,
+        output: [{ type: "text", text: summaryText }],
+        is_error: isError,
+        summary: summaryText,
+      });
+    }
+
+    // 关闭当前 subagent：
+    //   1) 把 child tools 的摘要拼起来，加上 childSessionKey 做成 JSON
+    //      写入 delegate_task 的 tool_result.output（在 parent run 上发）。
+    //      → server synth.synthCompleted 抽 childSessionKey，挂到
+    //        pendingByChildKey，等 child run.completed。
+    //   2) 发 child run.completed 带 parent_run_id + extensions.openclaw.
+    //      child_session_key → server synth.synthChildRunTerminal 看到匹配
+    //      就发 subagent_ref.completed 到 parent run timeline。
+    async function closeCurrentSubagent(isError = false) {
+      if (!currentSubagent) return;
+      const sub = currentSubagent;
+      currentSubagent = null;
+      // 优先用 subagent_output 条目（Responses API 路径下子 agent 的实际答案）
+      // 否则按 childTools 拼摘要；都没有时给 fallback 文案。
+      const subagentOutputs = sub.childTools
+        .filter((t) => t.name === "subagent_output" && t.label)
+        .map((t) => t.label);
+      const summaryText = subagentOutputs.length > 0
+        ? subagentOutputs.join(" · ")
+        : (sub.childTools.length > 0
+            ? sub.childTools
+                .map((t) => (t.label ? `${t.name}: ${t.label}` : t.name))
+                .join(" · ")
+            : (isError ? "subagent failed" : "subagent completed"));
+      // delegate_task tool_result on PARENT run，output[0].text 是 JSON 串
+      // —— extractSummary 期望 JSON 格式才能抽 childSessionKey（synth.go:575）。
+      await onChunk({
+        event: "response.tool_result",
+        call_id: sub.parentCallId,
+        run_id: parentRunId,
+        output: [{
+          type: "text",
+          text: JSON.stringify({
+            summary: summaryText,
+            childSessionKey: sub.childSessionKey,
+            status: isError ? "failed" : "completed",
+          }),
+        }],
+        is_error: isError,
+        summary: summaryText,
+      });
+      // subagent_ref.completed —— 发给父 run，用同一 refBlockId（信号 2 路径）。
+      // 在 child run.completed 之前发出，App 可以在子 run 落地前先更新 subagent 卡片。
+      // 使用 sub（已赋值的局部变量），currentSubagent 已被置 null。
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [
+          buildBlockCompleted(parentRunId, {
+            id: sub.refBlockId,
+            type: "subagent_ref",
+            child_run_id: sub.childRunId,
+            spawn_tool_use_id: sub.parentCallId,
+            agent: sub.agent,
+            summary: summaryText,
+            status: isError ? "failed" : "completed",
+            stop_reason: isError ? "error" : "end_turn",
+          }),
+        ],
+      });
+      // child run.completed —— 用 __envelopes passthrough 直接构造,带
+      // parent_run_id + extensions.openclaw.child_session_key。
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [
+          buildRunCompleted(sub.childRunId, isError ? "error" : "end_turn", {
+            parentRunId,
+            extensions: { openclaw: { child_session_key: sub.childSessionKey } },
+          }),
+        ],
+      });
+    }
+
+    for await (const chunk of stream) {
+      if (chunk.kind === "delta") {
+        const text = chunk.text || "";
+        if (text) {
+          await onChunk({ event: "response.output_text.delta", delta: text });
+        }
+      } else if (chunk.kind === "thinking") {
+        const text = chunk.text || "";
+        if (text) {
+          await onChunk({ event: "response.reasoning_summary_text.delta", delta: text });
+        }
+      } else if (chunk.kind === "tool_use_start") {
+        const callId = String(chunk.call_id || "");
+        const name = String(chunk.name || "unknown");
+        if (callId) {
+          openToolCalls.set(callId, { name, argsAccum: "" });
+          await onChunk({ event: "response.tool_use.start", call_id: callId, name });
+        }
+      } else if (chunk.kind === "tool_use_args_delta") {
+        const callId = String(chunk.call_id || "");
+        const args = String(chunk.arguments || "");
+        if (callId && args) {
+          const tc = openToolCalls.get(callId);
+          if (tc) tc.argsAccum += args;
+          await onChunk({ event: "response.tool_use.arguments.delta", call_id: callId, delta: args });
+        }
+      } else if (chunk.kind === "hermes_tool_progress") {
+        // hermes-agent 内部 LLM 决策走 tool — 详见上面 state machine 注释。
+        const toolName = String(chunk.tool || "");
+        const label = String(chunk.label || "");
+        if (!toolName) continue;
+
+        // 1) 先 immediate-flush 上一个挂着的 tool（不论是父 tool 还是 child tool）
+        if (inflightTool) {
+          await flushInflightTool(false);
+        }
+
+        if (toolName === "delegate_task") {
+          // 2a) delegate_task —— 派生新 subagent
+          // 若已有未关闭的 subagent，先关掉（hermes 不发嵌套，按 sibling 处理）
+          if (currentSubagent) {
+            await closeCurrentSubagent(false);
+          }
+          const childRunId = newRunId();
+          const parentCallId = newSyntheticToolCallId();
+          const childSessionKey = "hermes:subagent:" + childRunId;
+          const inputObj = label ? { task: label } : {};
+          const argsJson = JSON.stringify(inputObj);
+          // subagent_ref.started 必须在 tool_use(delegate_task) **之前**发出。
+          // 原因：unifiedDispatchHandler 默认 flushPolicy size:1 来即发，每个 envelope
+          // 单独 POST，relay scanSDKSignals 单 batch 只看到 1 个 envelope。若 tool_use
+          // 先到，synth.synthStarted 立即兜底合成 subagent_ref（mint 另一个 child_run_id），
+          // 待我们的 subagent_ref{source=runtime} 后到时已经晚了 → 出现两张卡。
+          // 先发 subagent_ref → sdkModeByTool 写入持久 map → 后续 tool_use batch
+          // 命中 SDK 模式 → synth.synthStarted 跳过自合成。spec lifecycle 示例的
+          // (tool_use, run.started, subagent_ref) 顺序在 size:1 流式策略下不可用。
+          const refBlockId = newBlockId();
+          await onChunk({
+            event: "__envelopes",
+            envelopes: [
+              buildBlockStarted(parentRunId, {
+                id: refBlockId,
+                type: "subagent_ref",
+                child_run_id: childRunId,
+                spawn_tool_use_id: parentCallId,
+                agent: label || "delegate_task",
+                summary: "",
+              }),
+            ],
+          });
+          await onChunk({
+            event: "response.tool_use.start",
+            call_id: parentCallId, name: toolName, run_id: parentRunId,
+          });
+          if (argsJson && argsJson !== "{}") {
+            await onChunk({
+              event: "response.tool_use.arguments.delta",
+              call_id: parentCallId, delta: argsJson, run_id: parentRunId,
+            });
+          }
+          await onChunk({
+            event: "response.tool_use.completed",
+            call_id: parentCallId, name: toolName, input: inputObj, run_id: parentRunId,
+          });
+          // child run.started —— ingester 识别新 run；后续 child tool events
+          // 都挂在这个 run 上。spawnToolUseId 允许 relay synth SDK 模式
+          // 用 CLI 给的 run_id 而不自行 mint。
+          await onChunk({
+            event: "__envelopes",
+            envelopes: [
+              buildRunStarted(childRunId, {
+                parentRunId,
+                spawnToolUseId: parentCallId,
+                extensions: { openclaw: { child_session_key: childSessionKey } },
+              }),
+            ],
+          });
+          currentSubagent = {
+            childRunId,
+            parentCallId,
+            agent: label || "delegate_task",
+            childSessionKey,
+            childTools: [],
+            refBlockId,
+          };
+          // delegate_task 的 tool_result 等到 closeCurrentSubagent 时发；这里
+          // 不设 inflightTool（设了反而会被下一个 child tool 的 flush 误关）
+        } else {
+          // 2b) 普通工具（read / exec / recall / ...）—— 落在当前作用域（child
+          // run 若有 subagent active，否则 parent run）
+          const scopedRunId = currentSubagent ? currentSubagent.childRunId : parentRunId;
+          const callId = newSyntheticToolCallId();
+          const inputObj = label ? { task: label } : {};
+          const argsJson = JSON.stringify(inputObj);
+          await onChunk({
+            event: "response.tool_use.start",
+            call_id: callId, name: toolName, run_id: scopedRunId,
+            ...(currentSubagent ? { parent_tool_use_id: currentSubagent.parentCallId } : {}),
+          });
+          if (argsJson && argsJson !== "{}") {
+            await onChunk({
+              event: "response.tool_use.arguments.delta",
+              call_id: callId, delta: argsJson, run_id: scopedRunId,
+            });
+          }
+          await onChunk({
+            event: "response.tool_use.completed",
+            call_id: callId, name: toolName, input: inputObj, run_id: scopedRunId,
+            ...(currentSubagent ? { parent_tool_use_id: currentSubagent.parentCallId } : {}),
+          });
+          inflightTool = { callId, name: toolName, label, runId: scopedRunId };
+        }
+      } else if (chunk.kind === "tool_call_started") {
+        // Responses API 路径：tool.started 事件，arguments 完整、call_id 真实。
+        // 跟 hermes_tool_progress 分支的差别 ——
+        //   1) call_id 用 hermes-agent 真实下发的（不再 mint synthetic）
+        //   2) 不需要 inflightTool flush 机制（complete 会单独到达）
+        //   3) input 解析 arguments JSON，不仅是 label
+
+        // todo translator：在 envelope_builder 之前拦截 todo 工具调用
+        {
+          const intercepted = todoTranslator.intercept(chunk);
+          if (intercepted.length === 0) continue; // 静默丢弃（不应发生于 started）
+          if (intercepted[0] !== chunk) {
+            // translator 返回了 todo_list envelopes
+            try { await onChunk({ event: "__envelopes", envelopes: intercepted }); } catch { /* ignore */ }
+            continue;
+          }
+        }
+
+        const toolName = String(chunk.name || "");
+        const callId = String(chunk.call_id || "");
+        if (!toolName || !callId) continue;
+        let inputObj = {};
+        if (chunk.arguments) {
+          try { inputObj = JSON.parse(String(chunk.arguments)); } catch { inputObj = {}; }
+        }
+        log.info("hermes.tool_call_started", "responses tool start", {
+          tool_name: toolName, call_id: callId,
+          args_keys: Object.keys(inputObj).slice(0, 8),
+          is_delegate: toolName === "delegate_task",
+        });
+        if (toolName === "delegate_task") {
+          // 关掉前一个 subagent（sibling 处理）
+          if (currentSubagent) {
+            await closeCurrentSubagent(false);
+          }
+          const childRunId = newRunId();
+          const childSessionKey = "hermes:subagent:" + childRunId;
+          const argsJson = JSON.stringify(inputObj);
+          // task 描述：偏好 input.task / input.goal / input.prompt，否则截 JSON
+          const agentLabel = String(
+            inputObj?.task ?? inputObj?.goal ?? inputObj?.prompt ?? toolName,
+          ).slice(0, 80);
+          // subagent_ref.started 必须在 tool_use(delegate_task) **之前**发出。
+          // size:1 流式策略下 relay scanSDKSignals 单 batch 一个 envelope，
+          // 必须先把 SDK 信号塞进 sdkModeByTool，后续 tool_use batch 才会命中
+          // SDK 模式跳过自合成（同 hermes_tool_progress 分支注释）。
+          const refBlockIdResp = newBlockId();
+          await onChunk({
+            event: "__envelopes",
+            envelopes: [
+              buildBlockStarted(parentRunId, {
+                id: refBlockIdResp,
+                type: "subagent_ref",
+                child_run_id: childRunId,
+                spawn_tool_use_id: callId,
+                agent: agentLabel,
+                summary: "",
+              }),
+            ],
+          });
+          // tool_use(delegate_task) on PARENT run，call_id 沿用 hermes 真实下发
+          await onChunk({
+            event: "response.tool_use.start",
+            call_id: callId, name: toolName, run_id: parentRunId,
+          });
+          if (argsJson && argsJson !== "{}") {
+            await onChunk({
+              event: "response.tool_use.arguments.delta",
+              call_id: callId, delta: argsJson, run_id: parentRunId,
+            });
+          }
+          await onChunk({
+            event: "response.tool_use.completed",
+            call_id: callId, name: toolName, input: inputObj, run_id: parentRunId,
+          });
+          // child run.started（带 spawnToolUseId）
+          await onChunk({
+            event: "__envelopes",
+            envelopes: [
+              buildRunStarted(childRunId, {
+                parentRunId,
+                spawnToolUseId: callId,
+                extensions: { openclaw: { child_session_key: childSessionKey } },
+              }),
+            ],
+          });
+          currentSubagent = {
+            childRunId,
+            parentCallId: callId,
+            agent: agentLabel,
+            childSessionKey,
+            childTools: [],
+            refBlockId: refBlockIdResp,
+          };
+        } else {
+          // 普通工具 —— 落在当前作用域
+          const scopedRunId = currentSubagent ? currentSubagent.childRunId : parentRunId;
+          const argsJson = JSON.stringify(inputObj);
+          await onChunk({
+            event: "response.tool_use.start",
+            call_id: callId, name: toolName, run_id: scopedRunId,
+            ...(currentSubagent ? { parent_tool_use_id: currentSubagent.parentCallId } : {}),
+          });
+          if (argsJson && argsJson !== "{}") {
+            await onChunk({
+              event: "response.tool_use.arguments.delta",
+              call_id: callId, delta: argsJson, run_id: scopedRunId,
+            });
+          }
+          await onChunk({
+            event: "response.tool_use.completed",
+            call_id: callId, name: toolName, input: inputObj, run_id: scopedRunId,
+            ...(currentSubagent ? { parent_tool_use_id: currentSubagent.parentCallId } : {}),
+          });
+          // Responses API 配对到达 tool_call_completed —— 不用 inflightTool 攒着
+        }
+      } else if (chunk.kind === "tool_call_completed") {
+        // Responses API 路径：tool 真实返回值在这里到达。call_id 跟 started
+        // 配对。delegate_task 的 result 是 JSON 串，含 results[*].summary
+        // （子 agent 实际答案）—— 抽出来注入为 child run 的 text block。
+
+        // todo translator：静默丢弃 todo tool_call_completed
+        {
+          const intercepted = todoTranslator.intercept(chunk);
+          if (intercepted.length === 0) continue; // 静默丢弃
+        }
+
+        const toolName = String(chunk.name || "");
+        const callId = String(chunk.call_id || "");
+        const resultText = String(chunk.result || "");
+        const isError = !!chunk.is_error;
+        if (!callId) continue;
+        log.info("hermes.tool_call_completed", "responses tool complete", {
+          tool_name: toolName, call_id: callId,
+          result_len: resultText.length,
+          result_preview: resultText.slice(0, 200),
+          is_error: isError,
+          has_active_subagent: !!currentSubagent,
+        });
+        if (toolName === "delegate_task" && currentSubagent && currentSubagent.parentCallId === callId) {
+          // 解析 delegate_task 返回，把每个子任务的 summary 注入 child run
+          // —— 这是 chat/completions 端点看不到的"子 agent 答案"。
+          // 抽 child run 文本：delegate_tool.py:549-566 的 result entry 形状是
+          //   {task_index, status, summary, error?, ...}
+          // - status="completed" → summary 字段是子 agent 实际答案
+          // - status="failed"     → summary 通常为空，错误信息在 error 字段
+          // - status="error"      → 同上
+          // 任何一种都要往 child run 注入 text block 让 App 看见子 agent 状态，
+          // 否则 status=failed 时子 run 空白用户无所适从（这是 e2e 跑通时
+          // 实际遇到的 bug：subagent 异常退出 → bridge 把它默默吞了）。
+          function _subagentEntryText(r) {
+            const summary = String(r?.summary || "").trim();
+            if (summary) return summary;
+            const error = String(r?.error || "").trim();
+            if (error) return `(subagent failed: ${error})`;
+            const status = String(r?.status || "unknown");
+            return `(subagent ended status=${status} — no summary / error)`;
+          }
+          // 直接构造 child run 上的 text block —— 不走 translator 的
+          // text.blockState（那是给 parent run 文本累积用的，跟 child
+          // run 共用会串）。
+          // newBlockId 返回 blk_<26 Crockford Base32>，跟 server schema
+          // ^blk_[0-9A-HJKMNP-TV-Z]{26}$ 对齐；自造任意前缀会被 ingester 拒。
+          async function _emitChildText(text) {
+            const textBlockId = newBlockId();
+            await onChunk({
+              event: "__envelopes",
+              envelopes: [
+                buildBlockStarted(currentSubagent.childRunId, {
+                  id: textBlockId, type: "text",
+                  format: "plain", text: "",
+                }),
+                buildBlockCompleted(currentSubagent.childRunId, {
+                  id: textBlockId, type: "text",
+                  format: "plain", text,
+                }),
+              ],
+            });
+            currentSubagent.childTools.push({
+              name: "subagent_output",
+              label: text.slice(0, 80),
+            });
+          }
+          try {
+            const parsed = JSON.parse(resultText);
+            const results = Array.isArray(parsed?.results) ? parsed.results : [];
+            log.info("hermes.delegate_task.parsed", "delegate_task result parsed", {
+              results_count: results.length,
+              summaries: results.map((r) => String(r?.summary || "").slice(0, 60)),
+              statuses: results.map((r) => String(r?.status || "")),
+              errors: results.map((r) => String(r?.error || "").slice(0, 80)),
+            });
+            if (results.length === 0) {
+              // results 空 —— 整个 delegate_task 调用层失败（如配额拒批 /
+              // depth limit 触发）。retry text 兜底，让 App 看到错误而不是
+              // 完全静默。
+              await _emitChildText(`(delegate_task returned empty results: ${resultText.slice(0, 200)})`);
+            } else {
+              for (const r of results) {
+                await _emitChildText(_subagentEntryText(r));
+              }
+            }
+          } catch (err) {
+            // result 不是 JSON（极少见，可能是 hermes-agent 早期版本）——
+            // 当纯文本整体注入。
+            const text = resultText.trim() || "(delegate_task returned empty body)";
+            await _emitChildText(text);
+          }
+          // 关闭 subagent —— 发 delegate_task tool_result on parent + child run.completed
+          await closeCurrentSubagent(isError);
+        } else {
+          // 普通工具完成 —— 发 tool_result 带真实结果到对应作用域
+          const scopedRunId = currentSubagent && currentSubagent.parentCallId !== callId
+            ? currentSubagent.childRunId
+            : (currentSubagent && currentSubagent.parentCallId === callId ? parentRunId : parentRunId);
+          await onChunk({
+            event: "response.tool_result",
+            call_id: callId,
+            run_id: scopedRunId,
+            output: [{ type: "text", text: resultText }],
+            is_error: isError,
+            summary: resultText.length > 200 ? resultText.slice(0, 200) + "..." : resultText,
+            ...(currentSubagent && scopedRunId === currentSubagent.childRunId
+              ? { parent_tool_use_id: currentSubagent.parentCallId }
+              : {}),
+          });
+          if (currentSubagent && scopedRunId === currentSubagent.childRunId) {
+            currentSubagent.childTools.push({ name: toolName, label: resultText.slice(0, 60) });
+          }
+        }
+      } else if (chunk.kind === "done") {
+        // Synthesize tool_use.completed for any still-open tool calls before
+        // signaling completion. Parse accumulated argsAccum as JSON.
+        for (const [callId, tc] of openToolCalls) {
+          let parsedInput = {};
+          if (tc.argsAccum) {
+            try { parsedInput = JSON.parse(tc.argsAccum); } catch { /* leave {} */ }
+          }
+          await onChunk({
+            event: "response.tool_use.completed",
+            call_id: callId, name: tc.name, input: parsedInput,
+          });
+        }
+        openToolCalls.clear();
+        // Subagent_synth 期望 tool_result.completed 在 run.completed 之前到达：
+        //   1) 关掉最后一个挂着的 child tool（flush inflightTool）
+        //   2) 关掉当前 subagent —— 发 delegate_task tool_result + child run.completed
+        await flushInflightTool(false);
+        await closeCurrentSubagent(false);
+        await onChunk({ event: "response.completed" });
+      } else if (chunk.kind === "error") {
+        await flushInflightTool(true);
+        await closeCurrentSubagent(true);
+        await onChunk({
+          event: "response.failed",
+          error: { message: String(chunk.error || "hermes error") },
+        });
+      }
+    }
+    } finally {
+      // turn 结束:把 accumulator buffer 里剩余的尾巴扫一次。fire-and-forget,
+      // 不会阻塞 caller。早 return (slash command) 路径 buffer 为空,无副作用。
+      try { _acc?.flush(); } catch { /* swallow */ }
+      // 注销 activeRuns 注册，防止后续 abort RPC 命中已结束的 run
+      try { unregisterRun?.(); } catch { /* swallow */ }
+    }
+  };
+
+  // 注册 unifiedDispatchHandler
+  const unifiedHandler = createUnifiedDispatchHandler({
+    relayUrl,
+    bridgeToken,
+    log,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke ?? defaultOpenclawInvoke,
+    gatewayId: gwId, // 正文 agentlink-cos:// 图片引用解析（sign-get）
+  });
+
+  // workspaces.create 实现（可注入用于测试）
+  const createWorkspaceImpl = _createWorkspace ?? _defaultCreateWorkspace;
+
+  return async function handleRequest(request, ctx) {
+    // 步骤 0（最优先）：workspace RPC 分支
+    // 识别字段为 request.request.__relayKind === "rpc"（不是 __kind）
+    // 由服务端 RelayRuntimeRPC（legacy_types_export.go:292）设置
+    if (request?.request?.__relayKind === "rpc") {
+      const method = request.request.method;
+      const params = request.request.params ?? {};
+      let result;
+      try {
+        // workspaces.scan 走通用 scanWorkspacesByRuntime（hermes 第一版返空 list，
+        // 见 OpenSpec change workspaces-scan-rpc 决策 2）。绕过 hermes 自己的
+        // workspaceRpc.dispatch（它只认 identity.soul.set / memory.files.get）。
+        if (method === "workspaces.scan") {
+          result = await scanWorkspacesByRuntime({
+            runtimeKind: "hermes",
+            gatewayId: gwId,
+            params,
+          });
+        } else if (method === "workspaces.create") {
+          result = await createWorkspaceImpl({
+            runtime: "hermes",
+            name: params.name,
+          });
+        } else if (method === "sessions.abort" || method === "chat.abort") {
+          // 调用 activeRuns 注册表中断活跃 run
+          const { aborted, matched } = activeRuns.abort({
+            key: params.key ?? params.sessionKey ?? "",
+            runId: params.runId ?? "",
+          });
+          if (aborted === 0) {
+            result = { ok: true, aborted: 0, matched: [], status: "no-active-run" };
+          } else {
+            result = { ok: true, aborted, matched };
+          }
+        } else {
+          result = await workspaceRpc.dispatch(method, params);
+        }
+      } catch (err) {
+        result = { ok: false, error: err?.message ?? String(err) };
+      }
+      // 之前只发 `rpc.result` event,但 relay 端 `waitGatewayResponse` switch
+      // 里没这个 case → 落到 `end` 分支返回空 body,App 端 `_relayRpcPayload`
+      // 解析空 body 直接拿不到 `file` 字段(典型场景:用户修改 AI 身份后
+      // App 调 `memory.files.get` 拉新 SOUL.md,响应空 → identity 解析 null
+      // → 列表标题 fallback 回 "Hermes 设备",改名不生效)。
+      //
+      // 改成发 `response` event 带 JSON body,relay 的 case "response" 会把
+      // body 原样回给 App;workspaceRpc 同时返回 ok/error/file 等字段,App
+      // 的 `_relayRpcPayload` 按 {ok:true, ...} 协议解出 file。
+      const bodyJson = JSON.stringify(result);
+      await ctx.publishEvent({
+        event: "response",
+        statusCode: 200,
+        contentType: "application/json; charset=utf-8",
+        body: bodyJson,
+      });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    // 步骤 1：优先走 unified dispatch
+    const handled = await unifiedHandler(request, ctx);
+    if (handled) return;
+
+    // 步骤 2：旧路径 — 与 index.mjs 原有逻辑一致
+    const userText = extractUserText(request);
+    if (!userText) {
+      log.warn("turn.skip", "no user text in request", { requestId: ctx.requestId });
+      await ctx.publishEvent({ event: "error", error: "empty user input" });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+    const turnStartedAt = Date.now();
+
+    // 拼历史
+    const history = await readHistory(gwId);
+    const messages = [
+      { role: "system", content: SYSTEM_PROMPT_DEFAULT },
+      ...history,
+      { role: "user", content: userText },
+    ];
+
+    await ctx.publishEvent({ event: "start" });
+
+    const backend = _backendOverride ?? (pre.backend === "command" ? commandBackendMod : httpBackendMod);
+    // AbortController — 旧路径同样支持 sessions.abort / chat.abort RPC 中断
+    const acLegacy = new AbortController();
+    const unregisterLegacy = activeRuns.register({
+      sessionKey: request?.sessionKey ?? "",
+      threadId: request?.request?.thread_id ?? "",
+      runId: request?.sessionKey ?? "",
+      kill: (reason) => acLegacy.abort(reason),
+    });
+    const stream = backend.streamChat(messages, {
+      apiBaseUrl: pre.apiBaseUrl,
+      apiKey: pre.apiKey,
+      command: pre.command,
+      model: pre.model,
+      hermesHome: profileHome,  // per-profile HERMES_HOME 透传给 command backend
+      signal: acLegacy.signal,
+    });
+
+    let fullText = "";
+    let errored = false;
+    let lastError = null;
+    for await (const chunk of stream) {
+      switch (chunk.kind) {
+        case "delta": {
+          const text = chunk.text || "";
+          if (!text) break;
+          fullText += text;
+          await ctx.publishEvent({
+            event: "chunk",
+            data: JSON.stringify({ type: "response.output_text.delta", delta: text }),
+          });
+          break;
+        }
+        case "usage": {
+          const u = chunk.usage || null;
+          if (!u) break;
+          const cached = Number(u?.prompt_tokens_details?.cached_tokens || 0);
+          usage.setTokensAbsolute({
+            input: Number(u.prompt_tokens || 0),
+            cached_input: cached,
+            output: Number(u.completion_tokens || 0),
+          });
+          break;
+        }
+        case "done":
+          if (chunk.fullText) fullText = chunk.fullText;
+          break;
+        case "error":
+          errored = true;
+          lastError = String(chunk.error || "unknown");
+          break;
+      }
+    }
+
+    if (errored) {
+      await ctx.publishEvent({
+        event: "error", error: lastError || "hermes turn failed",
+      });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    await ctx.publishEvent({
+      event: "chunk",
+      data: JSON.stringify({ type: "response.output_text.done", text: fullText }),
+    });
+    await ctx.publishEvent({ event: "end" });
+
+    // 持久化历史（dispatch 路径不调此处）
+    await appendTurn(gwId, userText, fullText).catch((err) => {
+      log.warn("hermes.history.persist.err", "history write failed", {
+        err: err?.message,
+      });
+    });
+
+    usage.addCost({ turns: 1, duration_ms: Date.now() - turnStartedAt });
+    usage.schedulePublish("hermes.turn_end");
+    unregisterLegacy();
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function extractUserText(request) {
+  const input = request?.request?.input;
+  if (typeof input === "string") return input.trim();
+  if (Array.isArray(input)) return collectTextFromItems(input).trim();
+  if (input && typeof input === "object") {
+    if (typeof input.text === "string") return input.text.trim();
+    if (input.content !== undefined) return collectTextFromAny(input.content).trim();
+  }
+  if (typeof request?.clientPreviewText === "string") {
+    return request.clientPreviewText.trim();
+  }
+  return "";
+}
+
+function collectTextFromAny(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return collectTextFromItems(value);
+  if (value && typeof value === "object" && typeof value.text === "string") return value.text;
+  return "";
+}
+
+function collectTextFromItems(items) {
+  const parts = [];
+  for (const item of items) {
+    if (typeof item === "string") { parts.push(item); continue; }
+    if (!item || typeof item !== "object") continue;
+    if (item.role && String(item.role).toLowerCase() !== "user") continue;
+    if (typeof item.text === "string") { parts.push(item.text); continue; }
+    if (item.content !== undefined) {
+      const t = collectTextFromAny(item.content);
+      if (t) parts.push(t);
+    }
+  }
+  return parts.join("\n\n");
+}