@xyagent/cli 0.0.1

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

@@ -0,0 +1,1152 @@
+/**
+ * handleRequest.mjs — codex runtime D-C2.2
+ *
+ * 把 codex handleRequest 逻辑提取为独立模块，以便单元测试。
+ *
+ * createCodexHandleRequest({ pre, cwd, log, usage, shuttingDownRef, dispatchHandlerOptions })
+ *   → async (request, ctx) => void
+ *
+ * 路由：
+ *   1. request.__kind == "agent.run.dispatch" → unifiedDispatchHandler（返回 true）→ 结束
+ *   2. 否则 → 原有 MCP stdio 旧路径
+ *
+ * dispatchHandlerOptions:
+ *   relayUrl          string         relay 服务地址
+ *   bridgeToken       string         bridge 鉴权 token
+ *   producerFactory?  Function       注入 producer（测试用）
+ *   openclawInvoke?   Function       注入 openclawInvoke（测试用；若未注入则使用默认）
+ *   _mcpClientFactory? Function      注入 MCP 客户端工厂（测试用，覆盖旧路径）
+ */
+
+import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
+import { collectCodexCustomCommands as _defaultCollectCodexCustomCommands } from "./codexCustomCommandsCollector.mjs";
+import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
+import { createMcpStdioClient } from "../../core/mcpStdioClient.mjs";
+import { createActiveRunRegistry } from "../../core/activeRuns.mjs";
+import { BoundedMap } from "../../core/boundedMap.mjs";
+import { expandHome } from "../../core/pathExpand.mjs";
+import { createWorkspace as _defaultCreateWorkspace } from "../../core/createWorkspace.mjs";
+import { ensureDefaultWorkspace } from "../../core/defaultWorkspace.mjs";
+import { mapCodexMsg } from "./eventMapper.mjs";
+import { createCodexPlanHandler } from "./planNotificationHandler.mjs";
+import {
+  classifySlashCommand,
+  emitAssistantText,
+} from "../_shared/slashCommandRouter.mjs";
+import { createInterruptGateway } from "../../core/interruptGateway.mjs";
+import { createApprovalGateway } from "../../core/approvalGateway.mjs";
+import { attachElicitationHandler } from "./elicitationHandler.mjs";
+import { writeCodexTrust } from "../../core/codexTrust.mjs";
+import { waitForRunResumed } from "../../core/interruptRunListener.mjs";
+import { listSessionsForRuntime, buildSessionLabel, buildSessionSubtitle } from "../_shared/sessionPicker.mjs";
+import {
+  buildRunStarted,
+  buildRunCompleted,
+  buildRunPaused,
+  buildBlockStarted,
+  buildBlockCompleted,
+  newBlockId,
+} from "../../../src-shared/envelope_builder.mjs";
+
+const TURN_HARD_TIMEOUT_MS = 10 * 60_000;
+
+/**
+ * codex notification msg 翻译为 onChunk 期望格式。
+ * 翻译规则:
+ *   agent_message_delta              → response.output_text.delta
+ *   agent_reasoning(_delta|_section_break|_raw_content)
+ *                                    → response.reasoning_summary_text.delta
+ *   exec_command_begin               → response.tool_use.start + completed (一次性，因 codex
+ *                                       的 command 在 begin 事件就有完整 input)
+ *   exec_command_end                 → response.tool_result
+ *   task_complete/task_completed/... → response.completed
+ *   error                            → response.failed
+ *   其他                             → null (忽略)
+ *
+ * codex 没有 subagent 概念 (单一 agent + tool calls)，所以无 parent_tool_use_id。
+ *
+ * 返回单个 chunk 或一组 chunk 数组——为支持 exec_command_begin 一次产 start+completed
+ * 两个事件，签名兼容数组返回。
+ */
+export function translateCodexMsgToChunk(msg) {
+  if (!msg || typeof msg.type !== "string") return null;
+  switch (msg.type) {
+    case "agent_message_content_delta":
+      // codex 0.130.0+: streaming text fragments arrive under msg.delta (single-token chars).
+      // 53 fragments per ~10s turn (实测), 必须接;否则用户看不到流式打字。
+      return { event: "response.output_text.delta", delta: String(msg.delta ?? "") };
+    case "agent_message_delta":
+      // Legacy event name (codex <0.130). msg.content 是完整文本。
+      return { event: "response.output_text.delta", delta: String(msg.content || "") };
+    case "agent_message":
+      // 完成态汇总 — content_delta 已流过整段, 此处不重复发, 否则 app 会看到双倍文本。
+      // 仅在 phase 标识为 "final" 时再考虑 (codex 默认 phase="commentary")
+      return null;
+    case "agent_reasoning":
+    case "agent_reasoning_delta":
+    case "agent_reasoning_section_break":
+    case "agent_reasoning_raw_content": {
+      // 字段在 codex 协议里可能是 msg.text 或 msg.content（参考 eventMapper.mjs:44-46）
+      const text = typeof msg.text === "string"
+        ? msg.text
+        : (typeof msg.content === "string" ? msg.content : "");
+      if (!text) return null;
+      return { event: "response.reasoning_summary_text.delta", delta: text };
+    }
+    case "exec_command_begin": {
+      const callId = String(msg.call_id || "");
+      const input = {
+        command: msg.command || "",
+        ...(msg.cwd ? { cwd: msg.cwd } : {}),
+      };
+      return [
+        { event: "response.tool_use.start", call_id: callId, name: "bash", input },
+        { event: "response.tool_use.completed", call_id: callId, name: "bash", input },
+      ];
+    }
+    case "exec_command_end": {
+      const callId = String(msg.call_id || "");
+      const exitCode = typeof msg.exit_code === "number" ? msg.exit_code : null;
+      const stdout = typeof msg.stdout === "string" ? msg.stdout : "";
+      const stderr = typeof msg.stderr === "string" ? msg.stderr : "";
+      const isError = exitCode != null && exitCode !== 0;
+      const summaryParts = [];
+      if (stdout) summaryParts.push(stdout.slice(-1500));
+      if (stderr) summaryParts.push(`STDERR:\n${stderr.slice(-500)}`);
+      return {
+        event: "response.tool_result",
+        call_id: callId,
+        output: [{ type: "text", format: "plain", text: summaryParts.join("\n") }],
+        is_error: isError,
+        summary: exitCode != null ? `exit=${exitCode}` : undefined,
+      };
+    }
+    case "task_complete":
+    case "task_completed":
+    case "session_ended":
+    case "shutdown":
+      return { event: "response.completed" };
+    case "error":
+      return {
+        event: "response.failed",
+        error: { message: String(msg.message || msg.error || "codex error") },
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * @param {{
+ *   pre: { ok: boolean, mcpSubcommand: string },
+ *   cwd: string,
+ *   log: { info, warn, error, child? },
+ *   usage: { addCost, schedulePublish },
+ *   shuttingDownRef: { current: boolean },
+ *   dispatchHandlerOptions: {
+ *     relayUrl: string,
+ *     bridgeToken: string,
+ *     producerFactory?: Function,
+ *     openclawInvoke?: Function,
+ *     _mcpClientFactory?: Function,  // 仅测试用
+ *   },
+ * }} opts
+ * @returns {(request: any, ctx: any) => Promise<void>}
+ */
+export function createCodexHandleRequest({ pre, cwd, log, usage, shuttingDownRef, bridgeCtx, dispatchHandlerOptions, scanner, _createWorkspace, _collectCodexCustomCommands }) {
+  const {
+    relayUrl,
+    bridgeToken,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke,
+    _mcpClientFactory,
+  } = dispatchHandlerOptions ?? {};
+  // bridge 状态(codex CLI 版本 / gw_id / model), 供 slash 路由器 bridge-synth
+  // 分支引用(/help /status /cost /model — codex MCP 全不识别 slash, 必须 bridge 合成)。
+  const codexCliVersion = bridgeCtx?.version || pre?.version || null;
+  const codexGwId = bridgeCtx?.gwId || null;
+  const codexModel = bridgeCtx?.model || null;
+
+  // MCP 客户端工厂（可被测试注入）
+  const mkMcpClient = _mcpClientFactory ?? (({ command, args, cwd: mcpCwd, log: mcpLog }) =>
+    createMcpStdioClient({ command, args, cwd: mcpCwd, log: mcpLog })
+  );
+
+  // agentlink thread_id → codex internal threadId 缓存（结构化输出抽出来的）。
+  // Codex MCP 暴露两个 tool：
+  //   - `codex {prompt}` 开新会话，返回 `{threadId, content}`
+  //   - `codex-reply {threadId, prompt}` 用现成的 threadId 续接 —— **但 codex
+  //     MCP server 要求 session 还在同一个 MCP 进程的内存里**（实测：从另一个
+  //     MCP 进程发 codex-reply 直接返回 isError + "Session not found"）。
+  // 所以续接必须配合 **long-lived MCP per agentlink-thread**：第一次给某
+  // thread dispatch 时 spawn MCP + 调 codex 拿 threadId 缓存；后续同 thread
+  // 复用这个 MCP client 调 codex-reply。
+  const threadCodexIdMap = new BoundedMap({ maxSize: 5_000, ttlMs: 7 * 24 * 60 * 60 * 1000 }); // audit: LRU+TTL
+  // interrupt 闸门 — /resume picker 挂起/恢复
+  const interruptGateway = createInterruptGateway({ log });
+  // 审批闸门 — codex elicitation/create（工具/命令需用户确认）经此收敛到 App
+  // （兼容无 child 方法的注入 log，如部分测试桩）
+  const approvalGateway = createApprovalGateway({
+    log: typeof log?.child === "function" ? log : { ...log, child: () => log },
+  });
+  // activeRuns 注册表：per-turn 登记 in-flight requestId，供 sessions.abort 精确 cancel。
+  // kill 语义 = 发 notifications/cancelled，不杀 MCP 子进程（会话保留）。
+  const activeRuns = createActiveRunRegistry({ log });
+
+  // agentlink thread_id → 长寿命 MCP client（per-thread 复用），死了从 map 里清掉。
+  const threadMcpMap = new Map();
+  // agentlink thread_id → 最近一次 session_configured payload(model / permission_profile /
+  // approval_policy / mcp_servers / cwd / sandbox / reasoning_effort 等)。供 /permissions
+  // /approvals /mcp /status 等 slash 合成响应时引用真实状态(而不是空模板)。
+  // 在 MCP onNotification("codex/event") 里捕获(msg.type === "session_configured")。
+  const threadSessionConfigured = new BoundedMap({ maxSize: 5_000, ttlMs: 7 * 24 * 60 * 60 * 1000 }); // audit: LRU+TTL
+  // agentlink thread_id → 最近一次 token_count.rate_limits payload。Codex MCP 每轮
+  // 跑完会发 `event_msg.token_count` 携带 5h(primary) + weekly(secondary) 额度,
+  // 结构跟 claude 的 rate_limits 一致 — primary.{used_percent, window_minutes:300,
+  // resets_at(unix秒)} / secondary.{used_percent, window_minutes:10080, resets_at} /
+  // credits / plan_type。/usage 合成时用这份, 同时也写盘到本地最近一次 jsonl
+  // (~/.codex/sessions/...)做 fallback(bridge 重启后还能读到上次结果)。
+  const threadRateLimits = new BoundedMap({ maxSize: 5_000, ttlMs: 7 * 24 * 60 * 60 * 1000 }); // audit: LRU+TTL
+
+  function evictMcp(threadId, mcpRef, reason) {
+    const cur = threadMcpMap.get(threadId);
+    if (cur === mcpRef) {
+      // audit 修复：仅删 map 引用时旧 mcp 对象的 pending/notifHandlers 仍被
+      // 闭包持有；显式 close 释放（进程已退场景 close 幂等无害）。
+      try { mcpRef.close?.(reason); } catch { /* already closed */ }
+      threadMcpMap.delete(threadId);
+      threadCodexIdMap.delete(threadId);
+      threadSessionConfigured.delete(threadId);
+      threadRateLimits.delete(threadId);
+      log.warn?.("codex.mcp.evicted", "long-lived MCP removed from cache", {
+        thread_id: threadId, reason,
+      });
+    }
+  }
+
+  // 默认 openclawInvoke：起 MCP stdio 子进程，监听 codex/event notification
+  // Task 5.1: 加入 blocks 参数（默认 []），支持 image + PDF attachment inline URL
+  // align-runtime-default-workspace: 加入 workspace_path 参数，解析链同 claude
+  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, onChunk: _rawOnChunk }) => {
+    // per-request cwd 解析（align-runtime-default-workspace）:
+    //   1. workspace_path 非空 → expandHome + existsSync → 用它
+    //   2. workspace_path 给定但不存在 → fallback 到 defaultWorkspace，emit cwd_fallback
+    //   3. workspace_path 未给 → 直接用 defaultWorkspace（修 service 模式 "/" bug）
+    let spawnCwd;
+    let cwdFallback = null;
+
+    const { existsSync: fsExistsSync } = await import("node:fs");
+
+    if (reqWorkspacePath && typeof reqWorkspacePath === "string" && reqWorkspacePath.trim()) {
+      const resolved = expandHome(reqWorkspacePath.trim());
+      if (fsExistsSync(resolved)) {
+        spawnCwd = resolved;
+        log.info?.("codex.spawn.cwd.workspace", "using workspace_path as cwd", {
+          cwd: resolved, source: "workspace_path",
+        });
+      } else {
+        spawnCwd = await ensureDefaultWorkspace("codex");
+        cwdFallback = {
+          actual_cwd: spawnCwd,
+          requested_cwd: reqWorkspacePath,
+          reason: `workspace_path '${reqWorkspacePath}' does not exist after expand, falling back to default workspace`,
+        };
+        log.warn?.("codex.spawn.cwd.not_found", "workspace_path does not exist, falling back to default workspace", {
+          workspace_path: reqWorkspacePath, fallback_cwd: spawnCwd,
+        });
+      }
+    } else {
+      spawnCwd = await ensureDefaultWorkspace("codex");
+      log.info?.("codex.spawn.cwd.default", "no workspace_path, using default workspace", {
+        cwd: spawnCwd, source: "default_workspace",
+      });
+    }
+
+    // 自动 attach 扫描器: 拦 response.output_text.delta 喂 accumulator, fire-and-forget。
+    // codex 是 single-token streaming, accumulator 按 \n 切完整行触发 scan, 路径
+    // 自然落在完整行里被识别。scanner 由工厂注入。
+    const _acc = scanner?.createTurnAccumulator({ requestId: run_id });
+    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;
+
+    // fallback 可观测：workspace_path 给定但不存在时，emit run.started 含 cwd_fallback
+    if (cwdFallback) {
+      await onChunk({
+        event: "__envelopes",
+        envelopes: [buildRunStarted(run_id, { options: { cwd_fallback: cwdFallback } })],
+      });
+    }
+
+    // audit 修复：unsubEvent/mcp 提升声明——turn 中任何异常此前会跳过
+    // try 尾部的清理（listener 累积 → 下一轮事件翻倍；__currentRun 悬空 →
+    // elicitation 发往旧 run）。清理统一挪进 finally。
+    let mcp = null;
+    let unsubEvent = null;
+    try {
+    // ── Slash command 拦截（bridge 层）─────────────────────────────────────
+    // codex MCP `tools/call codex {prompt:"/help"}` **不识别任何 slash 命令**——
+    // 全部当 prompt 喂给 LLM,LLM 用自然语言"假装"完成命令(最危险的是
+    // `/clear` 答"已清除上下文"但 codex 内部 threadId 一字未动,用户被误导)。
+    //
+    // 因此 codex 这边 bridge 必须截下所有 slash:
+    //   - /clear → 删 threadCodexIdMap + 关 MCP 进程, 下一条消息 fresh session
+    //   - /help /status /cost /model /usage /version → bridge 用已有信息合成
+    //     等价输出(不调 MCP, 避免 LLM 介入)
+    //   - 其它 unknown slash → 友好提示
+    const cachedSessionCfg = thread_id ? threadSessionConfigured.get(thread_id) || null : null;
+    const slash = await classifySlashCommand(input, "codex", {
+      version: codexCliVersion,
+      cwd,
+      gwId: codexGwId,
+      threadId: thread_id || null,
+      sessionId: thread_id ? threadCodexIdMap.get(thread_id) || null : null,
+      // 优先用 session_configured 里的真实 model(codex MCP 启动时返回),
+      // 退回到 bridgeCtx 里的 fallback model(目前是 null)。
+      model: cachedSessionCfg?.model || codexModel,
+      // 整段 session_configured payload, 给 /permissions /approvals /mcp 用
+      sessionConfigured: cachedSessionCfg,
+      // 最近一次 token_count.rate_limits, 给 /usage 用
+      rateLimits: thread_id ? threadRateLimits.get(thread_id) || null : null,
+    });
+    if (slash.kind === "client-reset") {
+      if (thread_id) {
+        threadCodexIdMap.delete(thread_id);
+        const mcpRef = threadMcpMap.get(thread_id);
+        if (mcpRef) {
+          // 关掉当前 MCP 进程,下一轮 spawn 新的 = 新 codex session,
+          // 跟用户对"清除上下文"的期望一致。
+          try { mcpRef.close?.("slash-clear"); } catch {}
+          evictMcp(thread_id, mcpRef, "slash-clear");
+        }
+        log.info?.("codex.slash.clear",
+          "client-reset slash command, dropped codex threadId + closed MCP",
+          { thread_id, command: slash.command });
+      }
+      await emitAssistantText(onChunk, slash.ackText);
+      return;
+    }
+    if (slash.kind === "bridge-synth") {
+      log.info?.("codex.slash.synth",
+        "bridge-synthesized slash response (codex MCP can't dispatch slash)",
+        { thread_id, command: slash.command });
+      await emitAssistantText(onChunk, slash.responseText);
+      return;
+    }
+
+    // ── /resume interrupt session picker (codex) ────────────────────────────
+    if (slash.kind === "interrupt-session-pick") {
+      log.info?.("codex.slash.resume_picker", "/resume: starting interrupt session picker", { thread_id, run_id });
+      // 默认只列「当前工作区」(spawnCwd) 下的历史会话；跨项目会话不再混入。
+      const sessions = await listSessionsForRuntime("codex", { filterCwd: spawnCwd });
+      if (sessions.length === 0) {
+        log.info?.("codex.slash.resume_picker.empty", "/resume: no sessions in current workspace", { thread_id, cwd: spawnCwd });
+        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(run_id),
+          buildBlockStarted(run_id, {
+            id: blockId, type: "interrupt", subtype: "question",
+            prompt: "选择要续接的历史会话", options, selection_mode: "single",
+          }),
+          buildRunPaused(run_id, [blockId]),
+        ],
+      });
+      // 非阻塞：发完 interrupt + run.paused 立即 return 释放 worker；
+      // resume 由 relay stream 监听器异步处理（见 claude handleRequest 同款）。
+      if (relayUrl && bridgeToken && thread_id) {
+        waitForRunResumed({ relayUrl, bridgeToken, threadId: thread_id, runId: run_id, interruptId: blockId, log })
+          .then(async ({ value }) => {
+            const decisionValue = value;
+            await onChunk({
+              event: "__envelopes",
+              envelopes: [
+                buildBlockCompleted(run_id, { id: blockId, type: "interrupt", subtype: "question", prompt: "选择要续接的历史会话", status: "completed", value: decisionValue }),
+                buildRunCompleted(run_id, "end_turn"),
+              ],
+            });
+            // codex 的 session resume 与 claude 不同（走 codex-reply threadId），
+            // 磁盘 session resume 暂无等价路径，仅记录供后续集成。
+            const selectedSessionId = decisionValue?.option_id ?? null;
+            if (selectedSessionId) {
+              log.info?.("codex.slash.resume_picker.done", "codex session selected (pending resume integration)", {
+                thread_id, session_id: selectedSessionId,
+              });
+            }
+          })
+          .catch((err) => log.warn?.("codex.slash.resume_picker.listener_err", err?.message));
+      }
+      return;
+    }
+
+    if (slash.kind === "unsupported") {
+      log.info?.("codex.slash.unsupported",
+        "unsupported slash command, replying with hint",
+        { thread_id, command: slash.command });
+      await emitAssistantText(onChunk, slash.hintText);
+      return;
+    }
+    // not-slash：继续走 MCP 路径
+
+    // Task 5.3: 使用 buildCodexPromptWithAttachments 构造包含 image/PDF 引导语的 prompt
+    // P0#29: codex MCP 工具只收纯文本 prompt，远程 URL 模型"看"不到（fetch 拿到的
+    // 是二进制，进不了多模态上下文）→ 先把 image URL 下载成本地临时文件，
+    // prompt 引导 codex 用 view_image 工具查看本地路径。下载失败回退 URL 行为。
+    const localizedBlocks = await localizeImageBlocksForCodex(blocks, { log });
+    const promptWithAttachments = buildCodexPromptWithAttachments(input, localizedBlocks);
+    let priorCodexThreadId = thread_id ? threadCodexIdMap.get(thread_id) : null;
+    mcp = thread_id ? threadMcpMap.get(thread_id) : null;
+    let mcpIsNew = false;
+    if (!mcp) {
+      // P0#27: codex 按 ~/.codex/config.toml 的 projects 信任决定沙箱模式；
+      // 默认工作区（ensureDefaultWorkspace 建出）从未写过信任 → untrusted →
+      // read-only 沙箱 + 命令被拒。配对进来的工作区都是用户显式导入/创建的，
+      // spawn 前幂等补写 trust_level=trusted。
+      // 测试注入 _mcpClientFactory 时跳过（不碰真实 ~/.codex/config.toml）。
+      try {
+        if (!_mcpClientFactory) await writeCodexTrust(spawnCwd);
+      } catch (trustErr) {
+        log.warn?.("codex.trust.write_failed", "writeCodexTrust failed (continuing)", {
+          cwd: spawnCwd, err: trustErr?.message || String(trustErr),
+        });
+      }
+      mcp = mkMcpClient({
+        command: "codex",
+        args: [pre.mcpSubcommand],
+        cwd: spawnCwd,  // align-runtime-default-workspace: 用解析后的 spawnCwd
+        log,
+      });
+      mcpIsNew = true;
+      if (thread_id) {
+        threadMcpMap.set(thread_id, mcp);
+        // MCP 进程意外死亡 → 从 cache 清掉，下次 dispatch 会重 spawn
+        try {
+          mcp.setExitHandler(({ code, signal }) => {
+            evictMcp(thread_id, mcp, `mcp.exit code=${code} signal=${signal}`);
+          });
+        } catch { /* setExitHandler 不存在的话忽略 */ }
+      }
+    }
+
+    let turnComplete = false;
+    let lastChunkError = null;
+
+    // plan notification handler：处理 turn/plan/updated → todo_list block 翻译
+    // 每次 openclawInvoke 独立实例（每个 run 独立），符合 D3 的 block.id 复用策略
+    const planHandler = createCodexPlanHandler({
+      runId: run_id,
+      onEnvelopes: async (envs) => {
+        try { await onChunk({ event: "__envelopes", envelopes: envs }); } catch { /* ignore */ }
+      },
+    });
+
+    // 每轮重新订阅 codex/event —— 闭包里捕获本轮的 turnComplete/onChunk。
+    // 关键：turn 结束时 unsubscribe 这个 listener，否则下一轮 listener 会叠加，
+    // 一个事件触发多次 chunk → App 端文本翻倍。
+    unsubEvent = mcp.onNotification("codex/event", async (params) => {
+      const msg = params?.msg;
+      if (!msg || typeof msg !== "object") return;
+
+      // 捕获 session_configured: 含 model / permission_profile / approval_policy /
+      // mcp_servers / sandbox / reasoning_effort / cwd / session_id, 后续 slash
+      // 合成(/permissions /approvals /mcp /sandbox 等)从这里读真实状态。
+      // 捕获 token_count → rate_limits(5h + weekly 配额),供 /usage 用
+      if (msg.type === "token_count" && msg.rate_limits && thread_id) {
+        threadRateLimits.set(thread_id, {
+          ...msg.rate_limits,
+          captured_at: new Date().toISOString(),
+        });
+      }
+
+      if (msg.type === "session_configured" && thread_id) {
+        threadSessionConfigured.set(thread_id, {
+          session_id: msg.session_id || null,
+          thread_id_codex: msg.thread_id || null,
+          model: msg.model || null,
+          model_provider_id: msg.model_provider_id || null,
+          approval_policy: msg.approval_policy || null,
+          approvals_reviewer: msg.approvals_reviewer || null,
+          permission_profile: msg.permission_profile || null,
+          active_permission_profile: msg.active_permission_profile || null,
+          cwd: msg.cwd || null,
+          reasoning_effort: msg.reasoning_effort || null,
+          mcp_servers: msg.mcp_servers || null,
+          rollout_path: msg.rollout_path || null,
+          captured_at: new Date().toISOString(),
+        });
+      }
+
+      // 先检测 turn 结束信号
+      if (msg.type === "task_complete" || msg.type === "task_completed" ||
+          msg.type === "session_ended" || msg.type === "shutdown") {
+        turnComplete = true;
+      }
+      // turn_aborted: codex 收到 notifications/cancelled 后发此事件，表示 turn 已真停。
+      // 置 turnComplete=true 使主循环退出；同时配合下方 `if (toolError && !turnComplete)`
+      // 护栏，确保被 cancel 的 tools/call 迟到 reject 不触发 response.failed。
+      if (msg.type === "turn_aborted") {
+        turnComplete = true;
+        abortedByTurnAborted = true;
+      }
+      if (msg.type === "error") {
+        lastChunkError = String(msg.message || msg.error || "codex error");
+      }
+
+      // turn/plan/updated 通知：交给 planHandler 处理（不透传为普通 chunk）
+      if (msg.type === "turn/plan/updated") {
+        const mapped = mapCodexMsg(msg);
+        if (mapped?.kind === "plan_updated") {
+          planHandler.handlePlanUpdated(mapped.payload);
+        }
+        return;
+      }
+
+      const chunk = translateCodexMsgToChunk(msg);
+      if (chunk) {
+        const chunks = Array.isArray(chunk) ? chunk : [chunk];
+        for (const c of chunks) {
+          try { await onChunk(c); } catch { /* ignore */ }
+        }
+      }
+    });
+
+    // long-lived MCP：只在第一次 spawn 时 initialize，后续 turn 复用已经
+    // initialized 的 client。mcp.initialize 自己有 `if (initialized) return`
+    // 兜底，这里加 if(mcpIsNew) 主要是为了不在 reuse 路径上多打 init log。
+    if (mcpIsNew) {
+      try {
+        await mcp.initialize({ capabilities: {} });
+      } catch (err) {
+        const msg = err?.message || String(err);
+        log.error?.("mcp.initialize.failed", "handshake failed", { err: msg });
+        await onChunk({ event: "response.failed", error: { message: `mcp init failed: ${msg}` } });
+        try { unsubEvent(); } catch {}
+        try { mcp.close("init-failed"); } catch {}
+        if (thread_id) evictMcp(thread_id, mcp, "init-failed");
+        return;
+      }
+    }
+
+    // P0#27/#16: codex elicitation/create（命令/工具需用户确认）→ App 审批弹窗。
+    // 此前 handler 从未注册，codex 的确认请求悬空超时 → 工具直接失败。
+    // 编排与 /resume picker 一致：interrupt(approval) block + run.paused →
+    // 等 relay run.resumed（App 决策）→ blockCompleted + settle 闸门。
+    if (mcpIsNew) {
+      try {
+        attachElicitationHandler({
+          mcp,
+          approvalGateway,
+          log,
+          onApprovalRequest: (info) => {
+            const cur = mcp.__currentRun;
+            if (!cur || !relayUrl || !bridgeToken || !cur.thread_id) {
+              log.warn?.("codex.approval.no_context",
+                "elicitation arrived without run context; auto-reject", {
+                  request_id: info?.request_id || "",
+                });
+              approvalGateway.settle(info.request_id, "reject", "no-run-context");
+              return;
+            }
+            const blockId = newBlockId();
+            const message =
+              (typeof info?.tool_input?.message === "string" && info.tool_input.message.trim())
+                ? info.tool_input.message.trim()
+                : "Codex 请求执行需要确认的操作";
+            void cur.onChunk({
+              event: "__envelopes",
+              envelopes: [
+                buildBlockStarted(cur.run_id, {
+                  id: blockId,
+                  type: "interrupt",
+                  subtype: "approval",
+                  prompt: message,
+                }),
+                buildRunPaused(cur.run_id, [blockId]),
+              ],
+            });
+            waitForRunResumed({
+              relayUrl,
+              bridgeToken,
+              threadId: cur.thread_id,
+              runId: cur.run_id,
+              interruptId: blockId,
+              log,
+            }).then(async ({ value }) => {
+              const approved =
+                value?.approved === true ||
+                (typeof value?.option_id === "string" &&
+                  value.option_id !== "" && value.option_id !== "reject");
+              await cur.onChunk({
+                event: "__envelopes",
+                envelopes: [
+                  buildBlockCompleted(cur.run_id, {
+                    id: blockId,
+                    type: "interrupt",
+                    subtype: "approval",
+                    prompt: message,
+                    status: "completed",
+                    value,
+                  }),
+                ],
+              });
+              approvalGateway.settle(
+                info.request_id,
+                approved ? "approve" : "reject",
+                typeof value?.reason === "string" ? value.reason : "",
+              );
+            }).catch((err) => {
+              log.warn?.("codex.approval.listener_err", "run.resumed listener error", {
+                request_id: info?.request_id || "",
+                err: err?.message || String(err),
+              });
+              approvalGateway.settle(info.request_id, "reject", "listener-error");
+            });
+          },
+        });
+      } catch (attachErr) {
+        log.warn?.("codex.approval.attach_failed", "attachElicitationHandler failed", {
+          err: attachErr?.message || String(attachErr),
+        });
+      }
+    }
+
+    let toolError = null;
+    let toolResult = null;
+    // turn_aborted 标志：收到 codex/event turn_aborted 时置 true，用于 turn 结束后
+    // emit「已停止本次回复」文案（类比 claude runtime 的 abortedByRpc 收尾行为）。
+    let abortedByTurnAborted = false;
+    // 续接：缓存命中 → codex-reply（带 threadId 续会话），否则 codex（开新会话）。
+    // 第一次会 cache codex 返回的 threadId；同一 MCP 进程后续轮直接 reply。
+    let callName = priorCodexThreadId ? "codex-reply" : "codex";
+    let callArgs = priorCodexThreadId
+      ? { threadId: priorCodexThreadId, prompt: promptWithAttachments }
+      : { prompt: promptWithAttachments };
+    if (priorCodexThreadId) {
+      log.info?.("codex.session.resume", "resuming codex thread", {
+        agentlink_thread: thread_id, codex_thread: priorCodexThreadId,
+      });
+    }
+
+    // executeCall 包装：codex-reply 在 MCP server 还活着但 session 失效时
+    // （理论上不该发生，但兜底）返回 isError + "Session not found"，
+    // 自动回退到全新 `codex` 调用。
+    //
+    // 改用 callWithId 以持有 requestId，供 activeRuns.register 的 kill 函数
+    // 调用 mcp.cancel(requestId) 发 notifications/cancelled 真停当前 turn。
+    async function executeCall() {
+      let lastErr = null;
+      for (let attempt = 0; attempt < 2; attempt++) {
+        let res;
+        try {
+          // callWithId 暴露 requestId，供 cancel(requestId) 精确取消当前 turn。
+          // mcp 由 _mcpClientFactory 注入，真实路径已是 mcpStdioClient（有 callWithId）；
+          // 若注入的 mock 未实现 callWithId，降级到 call() 并注册空 kill（无 cancel 能力）。
+          let promise;
+          let unregisterRun;
+          if (typeof mcp.callWithId === "function") {
+            const callResult = mcp.callWithId("tools/call", { name: callName, arguments: callArgs });
+            promise = callResult.promise;
+            const requestId = callResult.requestId;
+            // turn 开始前登记 activeRun：
+            //   kill = () => mcp.cancel(requestId)（发 cancelled，不杀子进程）
+            // turn 结束（turnComplete 或 turn_aborted）时 unregister。
+            unregisterRun = activeRuns.register({
+              sessionKey: thread_id,
+              threadId: thread_id,
+              runId: run_id,
+              kill: () => mcp.cancel(requestId),
+            });
+          } else {
+            // 降级路径：旧 mock 或不支持 callWithId 的客户端
+            promise = mcp.call("tools/call", { name: callName, arguments: callArgs });
+            unregisterRun = activeRuns.register({
+              sessionKey: thread_id,
+              threadId: thread_id,
+              runId: run_id,
+              kill: () => { /* no cancel capability in fallback mode */ },
+            });
+          }
+          try {
+            res = await promise;
+          } catch (err) {
+            lastErr = err;
+            unregisterRun();
+            return { res: null, err };
+          }
+          unregisterRun();
+        } catch (err) {
+          lastErr = err;
+          return { res: null, err };
+        }
+        if (res?.isError === true) {
+          const txt = Array.isArray(res.content)
+            ? res.content.filter((b) => b?.type === "text").map((b) => b.text).join("\n")
+            : "tool returned isError";
+          // Session not found → 清缓存，重试 codex（开新会话）
+          if (callName === "codex-reply" && /session not found/i.test(txt) && attempt === 0) {
+            log.warn?.("codex.session.invalid",
+              "codex-reply rejected with Session not found; falling back to fresh codex",
+              { agentlink_thread: thread_id, codex_thread: callArgs.threadId, err: txt });
+            if (thread_id) threadCodexIdMap.delete(thread_id);
+            callName = "codex";
+            callArgs = { prompt: promptWithAttachments };
+            priorCodexThreadId = null;
+            continue;
+          }
+          return { res, err: new Error(`codex tool error: ${txt}`) };
+        }
+        return { res, err: null };
+      }
+      return { res: null, err: lastErr || new Error("codex retry exhausted") };
+    }
+
+    // elicitation handler 是 per-MCP 一次性挂载的，审批要回到「当前 turn」的
+    // run 上下文 —— 每轮 tools/call 前登记，turn 结束清除。
+    mcp.__currentRun = { thread_id, run_id, onChunk };
+    const callPromise = executeCall()
+      .then(({ res, err }) => {
+        toolResult = res;
+        if (err) toolError = err;
+      });
+
+    // 等 turn 完成（task_complete notification / tools/call 返回 / 硬超时 / shutdown）
+    const startedAt = Date.now();
+    while (!turnComplete && !shuttingDownRef?.current && !toolError) {
+      if (Date.now() - startedAt > TURN_HARD_TIMEOUT_MS) {
+        log.warn?.("codex.turn.hard_timeout", "turn exceeded hard timeout", {
+          elapsed_ms: Date.now() - startedAt,
+        });
+        await onChunk({ event: "response.failed", error: { message: "codex turn hard timeout" } });
+        break;
+      }
+      await sleep(200);
+    }
+    await callPromise;
+
+    if (toolError && !turnComplete) {
+      const errMsg = toolError?.message || String(toolError);
+      await onChunk({ event: "response.failed", error: { message: `tools/call failed: ${errMsg}` } });
+    }
+
+    // turn_aborted 收尾：emit 「已停止本次回复」 assistant text chunk
+    // 类比 claude runtime 的 abortedByRpc 收尾（让 App 看到明确的停止文案）。
+    if (abortedByTurnAborted) {
+      await onChunk({ event: "response.output_text.delta", delta: "已停止本次回复" });
+      log.info?.("codex.abort.finalized", "turn aborted by cancel, emitted stop notice", {
+        thread_id, run_id,
+      });
+    }
+
+    // 从 tool result 抽取 codex threadId 缓存起来，下次同 agentlink thread
+    // 来 dispatch 时走 codex-reply。结构化输出按 MCP outputSchema 形状走
+    // structuredContent；老版本 codex 可能放在 content[].text 的 JSON 里，
+    // 这里两种都兜一下。已有缓存（同 MCP 复用）时跳过，避免每轮覆盖。
+    if (thread_id && toolResult && !toolError && !threadCodexIdMap.has(thread_id)) {
+      const sc = toolResult.structuredContent;
+      let codexThreadId = sc && typeof sc.threadId === "string" ? sc.threadId : null;
+      if (!codexThreadId && Array.isArray(toolResult.content)) {
+        for (const item of toolResult.content) {
+          if (item?.type === "text" && typeof item.text === "string") {
+            try {
+              const parsed = JSON.parse(item.text);
+              if (parsed && typeof parsed.threadId === "string") {
+                codexThreadId = parsed.threadId;
+                break;
+              }
+            } catch { /* not JSON, ignore */ }
+          }
+        }
+      }
+      if (codexThreadId) {
+        threadCodexIdMap.set(thread_id, codexThreadId);
+        log.info?.("codex.session.captured",
+          "captured codex threadId for resume", {
+            agentlink_thread: thread_id, codex_thread: codexThreadId,
+          });
+      } else {
+        log.warn?.("codex.session.no_thread_id",
+          "tools/call returned no threadId — next turn will start a new session",
+          { agentlink_thread: thread_id });
+      }
+    }
+
+    // plan handler complete()：发 content_block.completed（若有未关闭的 plan block）
+    // 在 response.completed 之前调用（unifiedDispatchHandler 会在我们返回后追加 run.completed）
+    planHandler.complete();
+
+    // **关键**：long-lived MCP 模式下 turn 结束 **只 unsubscribe listener**，
+    // 不能 close MCP —— 否则同 agentlink thread 下一轮还得重 spawn，
+    // codex 内存 session 又丢了，跟没续接一样。
+    // MCP 子进程的真正 cleanup 走 setExitHandler / bridge shutdown。
+    } finally {
+      try { _acc?.flush(); } catch { /* swallow */ }
+      // 清理统一在 finally：异常路径同样生效
+      if (mcp?.__currentRun?.run_id === run_id) mcp.__currentRun = null;
+      try { unsubEvent?.(); } catch { /* already unsubscribed */ }
+    }
+  };
+
+  // 注册 unifiedDispatchHandler
+  const unifiedHandler = createUnifiedDispatchHandler({
+    relayUrl,
+    bridgeToken,
+    log,
+    producerFactory,
+    openclawInvoke: injectedOpenclawInvoke ?? defaultOpenclawInvoke,
+    gatewayId: codexGwId, // 正文 agentlink-cos:// 图片引用解析（sign-get）
+  });
+
+  // workspaces.create 实现（可注入用于测试）
+  const createWorkspaceImpl = _createWorkspace ?? _defaultCreateWorkspace;
+  // codex 自定义命令收集器（可注入用于测试）
+  const collectCodexCustomCommandsImpl = _collectCodexCustomCommands ?? _defaultCollectCodexCustomCommands;
+
+  return async function handleRequest(request, ctx) {
+    // 步骤 0（最优先）：relay-rpc 分支。
+    if (request?.request?.__relayKind === "rpc") {
+      const method = request.request.method;
+      const params = request.request.params ?? {};
+      let result;
+      try {
+        if (method === "__runtime.customCommands") {
+          // codex 自定义命令来自 ~/.codex/prompts/*.md，无需 probe
+          const commands = await collectCodexCustomCommandsImpl();
+          result = { commands };
+        } else if (method === "workspaces.scan") {
+          // workspaces.scan 走通用 scanWorkspacesByRuntime（codex runtime 读
+          // ~/.codex/sessions/*.jsonl 首行 cwd field，dedupe 后返回）。
+          result = await scanWorkspacesByRuntime({
+            runtimeKind: "codex",
+            gatewayId: codexGwId,
+            params,
+          });
+        } else if (method === "workspaces.create") {
+          result = await createWorkspaceImpl({
+            runtime: "codex",
+            name: params.name,
+          });
+        } else if (method === "sessions.abort" || method === "chat.abort") {
+          // codex abort 真实实现（codex-abort-via-cancelled）：
+          //   1. activeRuns.abort 找到匹配的 in-flight run，调用 kill()
+          //   2. kill() = mcp.cancel(requestId)，发 notifications/cancelled 给 codex MCP server
+          //   3. codex 发 turn_aborted 事件，主循环 turnComplete 置位，turn 自然收尾
+          //   4. MCP 子进程不被 kill，threadCodexIdMap 保留，下条消息可续接
+          // aborted=0 时返回 no-active-run（不报错，方便 App 幂等重试）。
+          const { aborted, matched } = activeRuns.abort({
+            key: params.key ?? params.sessionKey ?? "",
+            runId: params.runId ?? "",
+          });
+          if (aborted >= 1) {
+            result = { ok: true, aborted, matched };
+          } else {
+            result = { ok: true, aborted: 0, matched: [], status: "no-active-run" };
+          }
+        } else {
+          result = { ok: false, error: `unknown rpc method: ${method}` };
+        }
+      } catch (err) {
+        result = { ok: false, error: err?.message ?? String(err) };
+      }
+      await ctx.publishEvent({
+        event: "response",
+        statusCode: 200,
+        contentType: "application/json; charset=utf-8",
+        body: JSON.stringify(result),
+      });
+      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;
+    }
+
+    await ctx.publishEvent({ event: "start" });
+
+    const mcp = mkMcpClient({
+      command: "codex",
+      args: [pre.mcpSubcommand],
+      cwd,
+      log,
+    });
+
+    let turnComplete = false;
+    let lastError = null;
+
+    mcp.onNotification("codex/event", (params) => {
+      const msg = params?.msg;
+      if (!msg || typeof msg !== "object" || typeof msg.type !== "string") return;
+      try {
+        const data = JSON.stringify(msg);
+        void ctx.publishEvent({ event: "chunk", data });
+      } catch (err) {
+        log.warn?.("codex.notify.serialize", "failed to stringify msg", {
+          err: err?.message || String(err), type: msg.type,
+        });
+      }
+      if (msg.type === "task_complete" || msg.type === "task_completed" ||
+          msg.type === "session_ended" || msg.type === "shutdown") {
+        turnComplete = true;
+      }
+      if (msg.type === "error") {
+        lastError = String(msg.message || msg.error || "codex error");
+      }
+    });
+
+    try {
+      await mcp.initialize({ capabilities: {} });
+    } catch (err) {
+      const msg = err?.message || String(err);
+      log.error?.("mcp.initialize.failed", "handshake failed", { err: msg });
+      await ctx.publishEvent({ event: "error", error: `mcp init failed: ${msg}` });
+      await ctx.publishEvent({ event: "end" });
+      try { mcp.close("init-failed"); } catch {}
+      return;
+    }
+
+    let toolError = null;
+    const callPromise = mcp
+      .call("tools/call", { name: "codex", arguments: { prompt: userText } })
+      .catch((err) => { toolError = err; });
+
+    const startedAt = Date.now();
+    while (!turnComplete && !shuttingDownRef?.current && !toolError) {
+      if (Date.now() - startedAt > TURN_HARD_TIMEOUT_MS) {
+        log.warn?.("codex.turn.hard_timeout", "turn exceeded hard timeout", {
+          requestId: ctx.requestId, elapsed_ms: Date.now() - startedAt,
+        });
+        lastError = "turn hard timeout";
+        break;
+      }
+      await sleep(200);
+    }
+    await callPromise;
+
+    if (toolError) {
+      const msg = toolError?.message || String(toolError);
+      log.warn?.("codex.tool.fail", "tools/call codex errored", { err: msg });
+      await ctx.publishEvent({ event: "error", error: `tools/call failed: ${msg}` });
+    } else if (lastError) {
+      await ctx.publishEvent({ event: "error", error: lastError });
+    }
+    await ctx.publishEvent({ event: "end" });
+
+    try { mcp.close("turn-end"); } catch {}
+
+    usage.addCost({ turns: 1, duration_ms: Date.now() - startedAt });
+    usage.schedulePublish("codex.turn_end");
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+/**
+ * buildCodexPromptWithAttachments — Phase 5 (multimodal-attachment-llm-dispatch)
+ *
+ * codex MCP prompt 参数为字符串类型（无多模态 content array）。
+ * N/A for base64 fetch path — codex uses string prompt only; attachment content
+ * is represented as URL references or descriptions inline in the prompt text.
+ *
+ * attachment_kind ベースの4種 dispatch（relayObjectToBlock 相当のロジックを string に inline）：
+ * - image   → [image] <URL>（base64 fetch は不可。codex は fetch tool で取得する）
+ * - document → [file: <name>] <URL>（PDF: URL inline）
+ * - text    → [file: <name>] <URL>（text-like: URL inline）
+ * - binary  → [file: <name>] (type: <mime>, size: <size>) — binary content
+ *
+ * 後方互換：attachment_kind がない場合は block.type + mime から推断。
+ *
+ * @param {string} input - 用户原始文字 prompt
+ * @param {any[]} blocks - dispatch payload blocks 数组
+ * @returns {string} 构造后的 prompt 字符串
+ */
+// P0#29: image URL block → 本地临时文件。codex 的 view_image 工具只认本地路径，
+// 这是 codex 路径上让模型真正"看到"图片的唯一通道（MCP prompt 无多模态入参）。
+// 单图上限 15MB、15s 超时；任何失败都不阻塞——保留原 block，prompt 回退 URL 行。
+const CODEX_IMG_MAX_BYTES = 15 * 1024 * 1024;
+export async function localizeImageBlocksForCodex(blocks = [], { log, _fetchImpl } = {}) {
+  const { mkdtemp, writeFile } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const path = await import("node:path");
+  const doFetch = _fetchImpl || fetch;
+
+  const imageIdx = (blocks ?? [])
+    .map((b, i) => ({ b, i }))
+    .filter(({ b }) => b?.type === "image" && b?.source?.kind === "url" && b?.source?.url);
+  if (imageIdx.length === 0) return blocks;
+
+  let dir = null;
+  const out = [...blocks];
+  for (const { b, i } of imageIdx) {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 15000);
+      const resp = await doFetch(b.source.url, { signal: controller.signal });
+      clearTimeout(timer);
+      if (!resp.ok) throw new Error(`http_${resp.status}`);
+      const buf = Buffer.from(await resp.arrayBuffer());
+      if (buf.length > CODEX_IMG_MAX_BYTES) throw new Error(`too_large_${buf.length}`);
+      if (!dir) dir = await mkdtemp(path.join(tmpdir(), "agentlink-codex-img-"));
+      const mime = String(b.source?.media_type || "").toLowerCase();
+      const ext = mime.includes("jpeg") || mime.includes("jpg") ? ".jpg"
+        : mime.includes("webp") ? ".webp"
+        : mime.includes("gif") ? ".gif"
+        : ".png";
+      const file = path.join(dir, `img-${i}${ext}`);
+      await writeFile(file, buf);
+      out[i] = { ...b, source: { ...b.source, local_path: file } };
+      log?.info?.("codex.image.localized", "image downloaded for view_image", {
+        index: i, bytes: buf.length, path: file,
+      });
+    } catch (err) {
+      log?.warn?.("codex.image.localize_failed", "image download failed; falling back to URL line", {
+        index: i, err: err?.message || String(err),
+      });
+    }
+  }
+  return out;
+}
+
+export function buildCodexPromptWithAttachments(input, blocks = []) {
+  const relayBlocks = (blocks ?? []).filter(
+    (b) =>
+      (b?.type === "image" || b?.type === "attachment") &&
+      b?.source?.kind === "url" &&
+      b?.source?.url,
+  );
+
+  if (relayBlocks.length === 0) return input;
+
+  const imageParts = [];
+  const fileParts = [];
+
+  for (const block of relayBlocks) {
+    const kind = _resolveAttachmentKind(block);
+    const url = block.source.url;
+    const name = block.name ?? "file";
+    const mime = block.source?.media_type ?? block.mime ?? "application/octet-stream";
+    const size = block.size ?? null;
+
+    if (kind === "image") {
+      // P0#29: 本地化成功 → 给本地路径（配合 view_image 引导语）；失败回退 URL。
+      const localPath = block.source?.local_path;
+      imageParts.push(`[image] ${localPath || url}`);
+    } else if (kind === "binary") {
+      const sizeDesc = size != null ? `${size} bytes` : "unknown size";
+      fileParts.push(`[file: ${name}] (type: ${mime}, size: ${sizeDesc}) — binary content`);
+    } else {
+      // document / text → URL inline
+      fileParts.push(`[file: ${name}] ${url}`);
+    }
+  }
+
+  const parts = [];
+
+  // 引导语。图片若已本地化（local_path），必须明确指示用 view_image 查看——
+  // 这是 codex 把图片载入多模态上下文的唯一方式；不引导的话模型会拿 shell
+  // 工具去 cat/curl 二进制然后开始幻觉 (P0#29)。
+  const hasLocalImage = relayBlocks.some(
+    (b) => _resolveAttachmentKind(b) === "image" && b.source?.local_path,
+  );
+  if (imageParts.length > 0 && fileParts.length > 0) {
+    parts.push(hasLocalImage
+      ? "你收到了以下图片和文件。图片是本地文件路径，请先用 view_image 工具逐张查看，再结合内容回答："
+      : "你收到了以下图片和文件，请结合内容回答：");
+  } else if (imageParts.length > 0) {
+    parts.push(hasLocalImage
+      ? "你收到了以下图片（本地文件路径）。请先用 view_image 工具逐张查看，再结合图片内容回答："
+      : "你收到了以下图片，请结合图片内容回答：");
+  } else {
+    parts.push("你收到了以下文件，请结合内容回答：");
+  }
+
+  parts.push(...imageParts, ...fileParts);
+
+  if (input) {
+    parts.push("---");
+    parts.push(input);
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * attachment_kind を推断（relayObjectToBlock.mjs の resolveAttachmentKind と同じロジック）。
+ * codex は relayObjectToBlock を async でインポートせず同期で動く必要があるため、
+ * ここでは同期コピーを保持する。
+ */
+// keep in sync with relayObjectToBlock.mjs:resolveAttachmentKind (lines 50-65)
+function _resolveAttachmentKind(block) {
+  const kind = block?.source?.attachment_kind;
+  if (kind && kind !== "file") return kind;
+
+  const mime = block?.source?.media_type ?? block?.mime ?? "";
+  if (block?.type === "image" || mime.startsWith("image/")) return "image";
+  if (mime === "application/pdf") return "document";
+  if (
+    mime.startsWith("text/") ||
+    mime === "application/json" ||
+    mime === "application/yaml" ||
+    mime === "application/x-yaml" ||   // CR-005: align with relayObjectToBlock.mjs
+    mime === "application/xml" ||
+    mime.startsWith("application/typescript") ||
+    /^text\/x-/.test(mime)
+  ) return "text";
+  return "binary";
+}
+
+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");
+}