@xyagent/cli 0.0.1

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

@@ -0,0 +1,142 @@
+// Codex 桥接入口 — long-poll worker 模式。
+//
+// 与 claude bridge 思路相同:每条 user message 拉到后,起一次 codex mcp 子进程
+// 跑完 turn 即退出,以避免长生命周期 SSE 订阅。
+//
+// 关键差异:codex 走 MCP stdio,需要先 initialize → tools/call codex(prompt) →
+// 监听 notifications/codex/event → mcp 子进程会保持运行直到 codex 自己结束 turn,
+// 我们在 task_complete 通知到达后主动 close 子进程。
+//
+// 转译规则:codex notification 的 params.msg 直接序列化成 native event,
+// msg.type 已经对齐服务端 codex adapter 的 EventType 枚举(session_configured /
+// agent_message_delta / task_started / ...);因此 native event 形如
+//   { event: "chunk", data: JSON.stringify(msg) }
+// 服务端 codex adapter 直接吃这条 chunk 的 data 字段(stream-json line)。
+
+import process from "node:process";
+import path from "node:path";
+
+import { createSessionSlot, SESSION_STATES } from "../../core/sessionSlot.mjs";
+import { createRelayWorker } from "../../core/relayWorker.mjs";
+import { bootstrapAgentlinkTools } from "../../core/agentlinkToolsBootstrap.mjs";
+import { installAutoTunnel } from "../../core/autoTunnelWiring.mjs";
+import { resolveSession } from "../../core/pairCodeClient.mjs";
+import { createUsageReporter } from "../../core/usageReporter.mjs";
+import { runWorkerWithRevokeHandling } from "../../core/bridgeSelfUninstall.mjs";
+import { codexPreflight } from "./preflight.mjs";
+import { createCodexHandleRequest } from "./handleRequest.mjs";
+
+
+export async function runCodexBridge({ options, positional, log }) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+
+  // 1. preflight
+  const pre = codexPreflight({ log });
+  if (!pre.ok) {
+    process.stderr.write(`codex preflight failed: ${pre.error}\n`);
+    if (pre.hint) process.stderr.write(`${pre.hint}\n`);
+    process.exit(65);
+  }
+
+  // 2. resolve session
+  let gwId, relayBase, bridgeToken;
+  try {
+    const r = await resolveSession({ runtime: "codex", options, log });
+    gwId = r.gwId;
+    relayBase = r.relayUrl;
+    bridgeToken = r.bridgeToken;
+    log.info("bridge.preflight.pass", "codex runtime entry reached", {
+      cwd, relay: relayBase, gw_id: gwId, source: r.source, has_bridge_token: !!bridgeToken,
+    });
+  } catch (err) {
+    process.stderr.write(`${err?.message || err}\n`);
+    process.exit(65);
+  }
+  if (!bridgeToken) {
+    process.stderr.write("缺少 bridge_token,请重新运行 agentlink pair <code> -r codex\n");
+    process.exit(65);
+  }
+
+  const sessLog = log.child({ gw: gwId });
+  const worker = createRelayWorker({
+    relayUrl: relayBase, gwId, bridgeToken, runtime: "codex", log: sessLog,
+  });
+  installAutoTunnel({ relayUrl: relayBase, log: sessLog });
+
+  let lastRequestId = null;
+  const usage = createUsageReporter({
+    runtime: "codex", log: sessLog,
+    publishEvent: (event) => {
+      if (!lastRequestId) return Promise.resolve(false);
+      return worker.publishEvent(lastRequestId, event);
+    },
+  });
+  usage.setContextWindow(272_000);
+
+  const slot = createSessionSlot({ log: sessLog, name: "codex" });
+  slot.transition(SESSION_STATES.READY, "worker-ready");
+
+  // agentlinkToolsServer + discovery 文件(见 claude/index.mjs 同段注释)
+  let toolsLifecycle = null;
+  try {
+    toolsLifecycle = await bootstrapAgentlinkTools({
+      runtime: "codex", gwId, relayUrl: relayBase, bridgeToken,
+      worker, log: sessLog, version: pre?.version || "",
+      getLastRequestId: () => lastRequestId,
+    });
+  } catch (err) {
+    sessLog.warn("agentlink_tools.bootstrap.failed",
+      "agentlink tools server failed to start; continuing without tools", { err: err?.message });
+  }
+
+  const shuttingDownRef = { current: false };
+  let shuttingDown = false;
+  async function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    shuttingDownRef.current = true;
+    sessLog.info("bridge.shutdown", "shutting down", { reason });
+    worker.stop(reason);
+    try { usage.dispose(); } catch {}
+    if (toolsLifecycle?.stop) {
+      try { await toolsLifecycle.stop(); } catch {}
+    }
+  }
+  process.once("SIGINT", () => { void shutdown("SIGINT").then(() => process.exit(0)); });
+  process.once("SIGTERM", () => { void shutdown("SIGTERM").then(() => process.exit(0)); });
+
+  // ---- handler:每条 in-flight 请求一次完整 turn ----
+  // D-C2.2.3: 替换内联 handleRequest，改为 createCodexHandleRequest 工厂函数
+  const _handleRequestImpl = createCodexHandleRequest({
+    pre,
+    cwd,
+    log: sessLog,
+    usage,
+    shuttingDownRef,
+    bridgeCtx: {
+      version: pre?.version || "",
+      gwId,
+      model: null, // codex 模型由 ~/.codex/config.toml 决定, bridge 没主动读
+    },
+    dispatchHandlerOptions: {
+      relayUrl: relayBase,
+      bridgeToken,
+    },
+    scanner: toolsLifecycle?.scanner ?? null,
+  });
+
+  async function handleRequest(request, ctx) {
+    lastRequestId = ctx.requestId;
+    return _handleRequestImpl(request, ctx);
+  }
+
+  sessLog.info("bridge.loop.entered", "codex worker entering long-poll loop", {
+    gw_id: gwId, cwd, version: pre.version || "", mcp_subcommand: pre.mcpSubcommand,
+  });
+  // 双向解绑：收到 App 端 deleteContact 触发的 HTTP 404 时自动清状态 + 卸 plist。
+  await runWorkerWithRevokeHandling({
+    worker, handler: handleRequest, runtime: "codex", log: sessLog,
+  });
+}
+
+// helpers 已移入 handleRequest.mjs

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

@@ -0,0 +1,155 @@
+// mcpConfigAdapter.mjs — Codex 的 MCP server 配置注入器。
+//
+// Codex 读 ~/.codex/config.toml,具体:
+//
+//   [mcp_servers.<name>]
+//   command = "node"
+//   args    = [...]
+//
+// 跟 Claude 不同:Codex 配置文件用 TOML,需要文档级 round-trip
+// (vendored smol-toml)。smol-toml 不保留注释,但只会把我们改的 section
+// 重写,用户其它 section/keys 通过 parse->merge->stringify 路径保留。
+//
+// 操作要求(spec.md Codex MCP server registration):
+//   - 通过 vendored smol-toml round-trip
+//   - non-destructive(其它 mcp_servers / 其它 sections / 其它 keys 都保留)
+//   - idempotent(args 数组 + command 与 desired 完全相等就不重写)
+//   - versioned
+
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOML = await import(
+  path.join(__dirname, "../../../src-shared/vendor/smol-toml/dist/index.js")
+);
+
+export const fileExtension = "toml";
+
+const SERVER_NAME = "agentlink";
+
+function configPath() {
+  return path.join(os.homedir(), ".codex", "config.toml");
+}
+
+export async function read() {
+  return await fs.readFile(configPath(), "utf8");
+}
+
+export async function register({ args, log } = {}) {
+  const cfgPath = configPath();
+  const desired = {
+    command: "node",
+    args: args.slice(),
+  };
+
+  let raw = "";
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  let cfg = {};
+  if (raw.trim().length > 0) {
+    try {
+      cfg = TOML.parse(raw);
+    } catch (err) {
+      // 解析失败别盲目覆盖 —— 抛出去让 caller backup + log + 决定怎么办。
+      const e = new Error(`codex config.toml parse failed: ${err.message}`);
+      e.kind = "parse_failed";
+      throw e;
+    }
+  }
+  if (!cfg.mcp_servers || typeof cfg.mcp_servers !== "object") {
+    cfg.mcp_servers = {};
+  }
+  const current = cfg.mcp_servers[SERVER_NAME];
+  if (tomlEqual(current, desired)) {
+    return { changed: false, configPath: cfgPath, mode: "noop_idempotent" };
+  }
+  cfg.mcp_servers[SERVER_NAME] = desired;
+
+  // 确保 ~/.codex/ 存在(用户可能从来没装过 codex)
+  await fs.mkdir(path.dirname(cfgPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(cfgPath, TOML.stringify(cfg), { mode: 0o600 });
+  log?.info?.("mcp.fanout.codex.write", "wrote agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function deregister({ log } = {}) {
+  const cfgPath = configPath();
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { changed: false, configPath: cfgPath, mode: "noop_no_config" };
+    }
+    throw err;
+  }
+  let cfg;
+  try {
+    cfg = TOML.parse(raw);
+  } catch {
+    return { changed: false, configPath: cfgPath, mode: "noop_parse_failed" };
+  }
+  if (!cfg?.mcp_servers || !(SERVER_NAME in cfg.mcp_servers)) {
+    return { changed: false, configPath: cfgPath, mode: "noop_not_registered" };
+  }
+  delete cfg.mcp_servers[SERVER_NAME];
+  await fs.writeFile(cfgPath, TOML.stringify(cfg), { mode: 0o600 });
+  log?.info?.("mcp.fanout.codex.delete", "removed agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function status() {
+  const cfgPath = configPath();
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { installed: true, registered: false, configPath: cfgPath, reason: "no_config_file" };
+    }
+    return { installed: false, registered: false, error: err.message };
+  }
+  let cfg;
+  try { cfg = TOML.parse(raw); }
+  catch { return { installed: true, registered: false, configPath: cfgPath, reason: "parse_failed" }; }
+  const entry = cfg?.mcp_servers?.[SERVER_NAME];
+  if (!entry) {
+    return { installed: true, registered: false, configPath: cfgPath };
+  }
+  return {
+    installed: true,
+    registered: true,
+    configPath: cfgPath,
+    version: extractAgentlinkVersion(entry.args),
+  };
+}
+
+function tomlEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.command !== b.command) return false;
+  if (!Array.isArray(a.args) || !Array.isArray(b.args)) return false;
+  if (a.args.length !== b.args.length) return false;
+  for (let i = 0; i < a.args.length; i++) {
+    if (a.args[i] !== b.args[i]) return false;
+  }
+  return true;
+}
+
+function extractAgentlinkVersion(args) {
+  if (!Array.isArray(args)) return null;
+  const idx = args.indexOf("--agentlink-version");
+  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
+  return null;
+}

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

@@ -0,0 +1,305 @@
+// Codex 模型列表扫描器。
+//
+// 背景：codex CLI 二进制（native, Rust）里嵌了一份结构化 JSON 清单，每项形如：
+//   {
+//     "slug": "gpt-5.4",
+//     "description": "Latest frontier agentic coding model.",
+//     ...
+//   }
+// 这就是交互式 TUI `/model` picker 的数据源。
+//
+// 策略：
+//   1. 扫描 codex native binary，提取所有 slug + description 配对
+//   2. 读 ~/.codex/config.toml 的顶层 `model` 字段，标记"当前默认"
+//   3. 完全动态 —— 跟着 codex CLI 升级自动带来新清单
+//
+// 扫不到（codex 未装 / 二进制定位失败 / 读取错误）→ 返回空列表。
+//
+// 跨平台：
+//   - 二进制路径按 platform+arch 计算 npm 包 target-triple，定位 vendor 下的 native binary
+//   - 若找不到 vendor 结构（自定义 build 等），回退到 which 能找到的任何二进制
+//   - strings 扫描跨 PE/ELF/Mach-O（ASCII 字符串明文）
+
+import { promises as fs, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+const cache = new Map(); // key -> { at, result }
+
+/**
+ * 返回 { models: [ { id, label, hint }, ... ], default: "<slug>" | null }。
+ * default 取自 `~/.codex/config.toml` 的顶层 model 字段。
+ */
+export async function listCodexModels() {
+  const bin = await resolveCodexBinary();
+  const cfgPath = path.join(os.homedir(), ".codex", "config.toml");
+  const binStat = bin ? await safeStat(bin) : null;
+  const cfgStat = await safeStat(cfgPath);
+  const cacheKey = `${bin || ""}:${binStat?.mtimeMs ?? 0}:${cfgStat?.mtimeMs ?? 0}`;
+  const hit = cache.get(cacheKey);
+  if (hit) return hit.result;
+
+  // 1. 扫二进制拿全量 slug + description
+  let scanned = [];
+  if (bin) {
+    try {
+      scanned = await scanCodexBinaryForModels(bin);
+    } catch {
+      scanned = [];
+    }
+  }
+
+  // 2. 读 config.toml 的当前默认 model（可选，仅用于标记）
+  let defaultModel = null;
+  if (cfgStat) {
+    const raw = await readTextSafe(cfgPath);
+    if (raw) defaultModel = parseDefaultModel(raw);
+  }
+
+  const models = composeModels(scanned, defaultModel);
+  const result = { models, default: defaultModel };
+  cache.set(cacheKey, { at: Date.now(), result });
+  return result;
+}
+
+// ── Compose ───────────────────────────────────────────────────────────────
+
+function composeModels(scanned, defaultModel) {
+  // 保留扫描顺序（codex 二进制内 JSON 顺序 = picker 展示顺序）。若 defaultModel
+  // 匹配某条，提到最前。每条返回 raw description + isDefault 标志，
+  // 由 App 端根据 locale 决定最终展示文案（国际化在 UI 层做）。
+  const out = [];
+  let defaultItem = null;
+  for (const m of scanned) {
+    const base = {
+      id: m.slug,
+      label: prettyLabel(m.slug),
+      hint: m.description || "",
+    };
+    if (defaultModel && m.slug === defaultModel) {
+      defaultItem = { ...base, isDefault: true };
+    } else {
+      out.push(base);
+    }
+  }
+  if (defaultItem) return [defaultItem, ...out];
+
+  // defaultModel 不在 scanned 里（用户手配了 codex 不认识的 id）—— 仍展示
+  if (defaultModel && !scanned.some((m) => m.slug === defaultModel)) {
+    return [
+      { id: defaultModel, label: prettyLabel(defaultModel), hint: "", isDefault: true },
+      ...out,
+    ];
+  }
+  return out;
+}
+
+function prettyLabel(id) {
+  // gpt-5.4 → "GPT-5.4"；gpt-5.2-codex → "GPT-5.2 Codex"；o3 → "o3"
+  if (/^o\d/i.test(id)) return id;
+  if (id.startsWith("gpt-")) {
+    const rest = id.slice(4);
+    return "GPT-" + rest
+      .split("-")
+      .map((seg, i) => i === 0 ? seg : (seg ? seg[0].toUpperCase() + seg.slice(1) : seg))
+      .join(" ");
+  }
+  return id;
+}
+
+// ── Binary scanning ───────────────────────────────────────────────────────
+
+/**
+ * 扫 codex 二进制，提取所有 `"slug": "...", "description": "..."` 配对。
+ * JSON blob 跨行，slug 和 description 之间可能夹着别的字段 —— 我们只靠
+ * "紧邻出现"假设（实测 codex 内这两者在同一 object 内相邻）。
+ */
+async function scanCodexBinaryForModels(binPath) {
+  const CHUNK = 1 << 20;
+  // codex 二进制里每个 model 的 JSON object 大约 800-1200 字节（含 reasoning
+  // levels / visibility / shell_type 等字段），OVERLAP 要覆盖一整个 object
+  const OVERLAP = 4096;
+  const fd = await fs.open(binPath, "r");
+  try {
+    const buf = Buffer.alloc(CHUNK);
+    // 匹配同一 model object 内的 slug + description + visibility 三元组。
+    //   - id 限定在 [A-Za-z0-9._-]，防止匹配到非模型字符串
+    //   - 中间段用 `(?:(?!"slug":)[\s\S]){0,N}?` 非贪婪 + 禁止跨对象（另一个 slug）
+    //   - visibility 是 codex 的 picker 过滤依据：list / hide
+    const RE = /"slug":\s*"([A-Za-z0-9._-]{1,64})"(?:(?!"slug":)[\s\S]){0,2000}?"description":\s*"([^"\\]{0,500})"(?:(?!"slug":)[\s\S]){0,2000}?"visibility":\s*"([a-z]+)"/g;
+    const seen = new Map(); // slug -> { description, visibility }
+    let position = 0;
+    let carry = "";
+    while (true) {
+      const { bytesRead } = await fd.read(buf, 0, CHUNK, position);
+      if (bytesRead === 0) break;
+      const hay = carry + buf.slice(0, bytesRead).toString("latin1");
+      RE.lastIndex = 0;
+      for (const m of hay.matchAll(RE)) {
+        const slug = m[1];
+        if (seen.has(slug)) continue;
+        seen.set(slug, { description: m[2], visibility: m[3] });
+      }
+      carry = hay.slice(-OVERLAP);
+      position += bytesRead;
+    }
+    // 只保留 picker 展示的（visibility=list），对齐 codex TUI 的 /model 菜单
+    const out = [];
+    for (const [slug, meta] of seen) {
+      if (!looksLikeModelId(slug)) continue;
+      if (meta.visibility !== "list") continue;
+      out.push({ slug, description: meta.description });
+    }
+    return out;
+  } finally {
+    await fd.close();
+  }
+}
+
+function looksLikeModelId(slug) {
+  if (slug.length < 2) return false;
+  // 典型 id: gpt-5.4 / gpt-5-codex / o3 / o4-mini / claude-* 等 —— 都含小写和数字
+  if (!/[a-z]/.test(slug)) return false;
+  if (!/\d/.test(slug)) return false;
+  return true;
+}
+
+// ── Default-model extraction from config.toml ─────────────────────────────
+
+function parseDefaultModel(text) {
+  // 只抓顶层 `model = "..."`（第一个出现且在 section header 之前的）
+  const lines = text.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.replace(/^\s+|\s+$/g, "");
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("[")) return null; // 遇到 section header 就停
+    const m = line.match(/^model\s*=\s*["']([^"']+)["']/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// ── Binary resolution ─────────────────────────────────────────────────────
+//
+// 布局（@openai/codex npm 包）：
+//   <codex.js 所在 bin>/codex.js              (node script entry)
+//   上溯至 @openai/codex/package.json
+//   → <pkg root>/node_modules/@openai/codex-<triple>/vendor/<triple>/codex/<codex|codex.exe>
+//
+// 若 codex 是自定义 build / 通过其他方式安装，这里走不通，就回退到 which 到的文件。
+
+async function resolveCodexBinary() {
+  const scriptPath = findCodexInPath();
+  if (!scriptPath) return null;
+  const real = await safeRealpath(scriptPath);
+  if (!real) return null;
+
+  // 若 realpath 本身就是 native binary（big，非 .js）—— 直接用
+  const st = await safeStat(real);
+  if (st && st.isFile() && st.size > 1024 * 1024 && !real.endsWith(".js")) {
+    return real;
+  }
+
+  // 否则尝试从 @openai/codex 包布局里找 vendor native
+  const vendor = await locateVendorNative(real);
+  if (vendor) return vendor;
+
+  // 兜底：返回脚本路径（扫描会失败，但不报错）
+  return real;
+}
+
+function findCodexInPath() {
+  const pathDirs = (process.env.PATH || "").split(process.platform === "win32" ? ";" : ":");
+  const candidates = process.platform === "win32"
+    ? ["codex.exe", "codex.cmd", "codex.bat", "codex"]
+    : ["codex"];
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    for (const name of candidates) {
+      const p = path.join(dir, name);
+      try {
+        if (fsExistsSync(p)) return p;
+      } catch {}
+    }
+  }
+  // 兜底：which / where
+  const which = process.platform === "win32" ? "where" : "which";
+  const r = spawnSync(which, ["codex"], { encoding: "utf8" });
+  if (r.status === 0) {
+    const first = (r.stdout || "").split(/\r?\n/).map((s) => s.trim()).find(Boolean);
+    if (first && fsExistsSync(first)) return first;
+  }
+  return null;
+}
+
+async function locateVendorNative(codexJsRealPath) {
+  // 上溯找到 @openai/codex 包根（含 package.json）
+  let dir = path.dirname(codexJsRealPath);
+  let pkgRoot = null;
+  for (let i = 0; i < 6; i++) {
+    if (fsExistsSync(path.join(dir, "package.json"))) {
+      try {
+        const pkg = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
+        if (pkg.name === "@openai/codex") { pkgRoot = dir; break; }
+      } catch {}
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (!pkgRoot) return null;
+
+  const plat = resolvePlatformMapping();
+  if (!plat) return null;
+  const binName = process.platform === "win32" ? "codex.exe" : "codex";
+  // npm package 名用 node-platform 后缀（如 codex-darwin-arm64），
+  // 但 vendor 子目录用 target-triple（如 aarch64-apple-darwin）—— 不一样
+  const vendorBin = path.join(
+    pkgRoot, "node_modules", "@openai", `codex-${plat.pkgSuffix}`,
+    "vendor", plat.triple, "codex", binName,
+  );
+  if (!fsExistsSync(vendorBin)) return null;
+  const st = await safeStat(vendorBin);
+  if (!st || !st.isFile() || st.size < 1024 * 1024) return null;
+  return vendorBin;
+}
+
+/**
+ * 返回 { triple, pkgSuffix }。对齐 @openai/codex/bin/codex.js 里的
+ * PLATFORM_PACKAGE_BY_TARGET：key 是 target-triple（vendor 目录名），
+ * value 是 @openai/codex-<suffix> 的 npm 包名后缀。
+ */
+function resolvePlatformMapping() {
+  const { platform, arch } = process;
+  if (platform === "linux" || platform === "android") {
+    if (arch === "x64")   return { triple: "x86_64-unknown-linux-musl", pkgSuffix: "linux-x64" };
+    if (arch === "arm64") return { triple: "aarch64-unknown-linux-musl", pkgSuffix: "linux-arm64" };
+  } else if (platform === "darwin") {
+    if (arch === "x64")   return { triple: "x86_64-apple-darwin", pkgSuffix: "darwin-x64" };
+    if (arch === "arm64") return { triple: "aarch64-apple-darwin", pkgSuffix: "darwin-arm64" };
+  } else if (platform === "win32") {
+    if (arch === "x64")   return { triple: "x86_64-pc-windows-msvc", pkgSuffix: "win32-x64" };
+    if (arch === "arm64") return { triple: "aarch64-pc-windows-msvc", pkgSuffix: "win32-arm64" };
+  }
+  return null;
+}
+
+// ── fs helpers ─────────────────────────────────────────────────────────────
+
+function fsExistsSync(p) {
+  try { return existsSync(p); } catch { return false; }
+}
+
+async function safeStat(p) {
+  try { return await fs.stat(p); } catch { return null; }
+}
+
+async function safeRealpath(p) {
+  try { return await fs.realpath(p); } catch { return null; }
+}
+
+async function readTextSafe(p) {
+  try { return await fs.readFile(p, "utf8"); } catch { return null; }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * planNotificationHandler.mjs — Codex turn/plan/updated → todo_list block translator
+ *
+ * 按 translator-spec.md D2 决策实现：
+ *   - 首次 handlePlanUpdated：发 content_block.started
+ *   - 后续调用：发 content_block.delta（复用 block.id）
+ *   - complete()：发 content_block.completed
+ *   - 未收过通知时 complete() 是 no-op
+ */
+
+import {
+  buildBlockStarted,
+  buildBlockCompleted,
+  buildBlockDelta,
+  newBlockId,
+} from "../../../src-shared/envelope_builder.mjs";
+import { buildTodoItems } from "../_shared/todoTranslatorUtils.mjs";
+
+/**
+ * 创建 Codex plan notification handler。
+ *
+ * @param {{ runId: string, onEnvelopes: (envs: object[]) => void }} opts
+ * @returns {{ handlePlanUpdated(payload: object): void, complete(): void }}
+ */
+export function createCodexPlanHandler({ runId, onEnvelopes }) {
+  let blockId = null;
+  let lastItems = null;
+
+  return {
+    /**
+     * 处理 turn/plan/updated 通知 payload。
+     * 第一次：发 started；后续：发 delta。
+     *
+     * @param {{ turnId: string|null, explanation?: string|null, plan: Array<{step: string, status: string}> }} payload
+     */
+    handlePlanUpdated(payload) {
+      const rawPlan = Array.isArray(payload?.plan) ? payload.plan : [];
+      const items = buildTodoItems(rawPlan);
+      lastItems = items;
+
+      if (blockId === null) {
+        // 首次调用：生成 block.id，发 started
+        blockId = newBlockId();
+        const block = { id: blockId, type: "todo_list", items };
+        onEnvelopes([buildBlockStarted(runId, block)]);
+      } else {
+        // 后续调用：发 delta（复用 block.id）
+        onEnvelopes([buildBlockDelta(runId, blockId, { todo_items_replace: items })]);
+      }
+    },
+
+    /**
+     * 发出 content_block.completed（若从未收到过 handlePlanUpdated 则 no-op）。
+     */
+    complete() {
+      if (blockId === null) return; // no-op
+      const block = { id: blockId, type: "todo_list", items: lastItems ?? [] };
+      onEnvelopes([buildBlockCompleted(runId, block)]);
+    },
+  };
+}