@xyagent/cli 1.0.0 → 1.1.1

package/src-ext/runtime/_shared/jsonMcpConfigAdapter.mjs

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const SERVER_NAME = "agentlink";
+
+export function createJsonMcpConfigAdapter({ resolvePath, readServers, writeServers, desiredEntry }) {
+  async function read() {
+    return await fs.readFile(resolvePath(), "utf8");
+  }
+
+  async function register({ args, log } = {}) {
+    const configPath = resolvePath();
+    const config = await readConfig(configPath);
+    const servers = readServers(config);
+    const desired = desiredEntry(args || []);
+    if (JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(desired)) {
+      return { changed: false, configPath, mode: "noop_idempotent" };
+    }
+    servers[SERVER_NAME] = desired;
+    writeServers(config, servers);
+    await writeConfig(configPath, config);
+    log?.info?.("mcp.fanout.json.write", "wrote agentlink MCP entry", { configPath });
+    return { changed: true, configPath };
+  }
+
+  async function deregister() {
+    const configPath = resolvePath();
+    let config;
+    try {
+      config = await readConfig(configPath, { requireExisting: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") return { changed: false, configPath, mode: "noop_no_config" };
+      throw error;
+    }
+    const servers = readServers(config);
+    if (!(SERVER_NAME in servers)) return { changed: false, configPath, mode: "noop_not_registered" };
+    delete servers[SERVER_NAME];
+    writeServers(config, servers);
+    await writeConfig(configPath, config);
+    return { changed: true, configPath };
+  }
+
+  async function status() {
+    const configPath = resolvePath();
+    try {
+      const config = await readConfig(configPath, { requireExisting: true });
+      return { installed: true, registered: SERVER_NAME in readServers(config), configPath };
+    } catch (error) {
+      if (error?.code === "ENOENT") return { installed: true, registered: false, configPath };
+      return { installed: true, registered: false, configPath, error: error?.message };
+    }
+  }
+
+  return { read, register, deregister, status };
+}
+
+async function readConfig(configPath, { requireExisting = false } = {}) {
+  try {
+    const raw = await fs.readFile(configPath, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch (error) {
+    if (error?.code === "ENOENT" && !requireExisting) return {};
+    throw error;
+  }
+}
+
+async function writeConfig(configPath, config) {
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}

package/src-ext/runtime/_shared/ndjsonProcess.mjs

@@ -0,0 +1,141 @@
+import { spawn, spawnSync } from "node:child_process";
+import readline from "node:readline";
+
+const VERSION_PROBE_TIMEOUT_MS = 5_000;
+const MAX_STDERR_CHARS = 8_000;
+export const PROCESS_TERMINATION_GRACE_MS = 3_000;
+// 子进程连续无任何 stdout/stderr 输出超过该上限视为卡死：kill 进程树并抛错，
+// 由 dispatch 层上报 run.failed —— 否则 run 永久 running，客户端只能无限转圈。
+export const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60_000;
+
+function signalProcessTree(child, signal) {
+  if (!child?.pid) return;
+  if (process.platform === "win32") {
+    const args = ["/pid", String(child.pid), "/t"];
+    if (signal === "SIGKILL") args.push("/f");
+    spawnSync("taskkill", args, { windowsHide: true, stdio: "ignore" });
+    return;
+  }
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try { child.kill(signal); } catch {}
+  }
+}
+
+export function probeBinary(binary) {
+  const result = spawnSync(binary, ["--version"], {
+    encoding: "utf8",
+    timeout: VERSION_PROBE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      error: result.error?.code === "ENOENT" ? `找不到 ${binary}` : String(result.stderr || result.error || "version probe failed").trim(),
+      hint: `请先安装 ${binary}，并确认它在 PATH 中。`,
+    };
+  }
+  return { ok: true, version: String(result.stdout || result.stderr || "").trim().split(/\r?\n/)[0] };
+}
+
+export async function runNdjsonProcess({
+  binary,
+  args,
+  cwd,
+  env,
+  parseEvent,
+  onChunk,
+  onSession,
+  onProcess,
+  terminationGraceMs = PROCESS_TERMINATION_GRACE_MS,
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+}) {
+  const childEnv = env ? { ...process.env, ...env } : process.env;
+  const child = spawn(binary, args, {
+    cwd,
+    env: childEnv,
+    shell: false,
+    windowsHide: true,
+    detached: process.platform !== "win32",
+    // stdin 必须是 EOF：留 pipe 不关闭会让子进程（如 opencode run）等 stdin
+    // 读到 EOF 才开始干活 → 永久卡死（手动跑是 TTY 不受影响，headless 必挂）。
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let exited = false;
+  let aborted = false;
+  let timedOut = false;
+  let forceTimer = null;
+  const killTree = () => {
+    signalProcessTree(child, "SIGTERM");
+    forceTimer = setTimeout(() => {
+      if (!exited) signalProcessTree(child, "SIGKILL");
+    }, terminationGraceMs);
+    forceTimer.unref?.();
+  };
+  const terminate = () => {
+    if (exited || aborted) return;
+    aborted = true;
+    killTree();
+  };
+  // 空闲看门狗：任何 stdout/stderr 输出都会重置；超时视为子进程卡死。
+  let idleTimer = null;
+  const armIdleTimer = () => {
+    if (!idleTimeoutMs) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (exited || aborted || timedOut) return;
+      timedOut = true;
+      killTree();
+    }, idleTimeoutMs);
+    idleTimer.unref?.();
+  };
+  armIdleTimer();
+  onProcess?.({ pid: child.pid, terminate });
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      exited = true;
+      if (forceTimer) clearTimeout(forceTimer);
+      if (idleTimer) clearTimeout(idleTimer);
+      resolve({ code, signal });
+    });
+  });
+  let stderr = "";
+  let structuredError = "";
+  let reportedFailure = false;
+  child.stdout.on("data", armIdleTimer);
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    armIdleTimer();
+    stderr = (stderr + chunk).slice(-MAX_STDERR_CHARS);
+  });
+
+  const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let event;
+    try { event = JSON.parse(line); }
+    catch { continue; }
+    const eventError = event?.error?.message || event?.message?.error?.message;
+    if (eventError) structuredError = String(eventError);
+    const sessionId = event.sessionID || event.session_id;
+    if (sessionId) onSession?.(String(sessionId));
+    const chunks = parseEvent(event);
+    for (const chunk of Array.isArray(chunks) ? chunks : (chunks ? [chunks] : [])) {
+      if (chunk?.event === "response.failed") reportedFailure = true;
+      await onChunk(chunk);
+    }
+  }
+
+  const exit = await exitPromise;
+  if (aborted) return { aborted: true, exit };
+  if (timedOut) {
+    throw new Error(`${binary} 连续 ${Math.round(idleTimeoutMs / 1000)}s 无输出，判定卡死，已超时终止`);
+  }
+  if (exit.code !== 0) {
+    if (reportedFailure) return;
+    throw new Error(structuredError || stderr.trim() || `${binary} exited with code ${exit.code ?? "unknown"}${exit.signal ? ` (${exit.signal})` : ""}`);
+  }
+  return { aborted: false, exit };
+}

package/src-ext/runtime/_shared/resolveWorkspaceCwd.mjs

@@ -0,0 +1,47 @@
+/**
+ * resolveWorkspaceCwd.mjs — headless NDJSON runtime 的 spawn cwd 解析。
+ *
+ * 与 claude/codex handleRequest 的解析链对齐：
+ *   1. workspace_path 非空 → expandHome + existsSync → 用它（线程绑定工作区）
+ *   2. workspace_path 给定但无效/目录不存在 → 稳定失败，绝不 fallback
+ *   3. workspace_path 未给 → 默认工作区
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+
+import { expandHome } from "../../core/pathExpand.mjs";
+
+/**
+ * @param {{
+ *   workspacePath?: string | null,
+ *   fallbackWorkspace: string,
+ *   runtime: string,
+ *   log?: { info?: Function, warn?: Function },
+ * }} opts
+ * @returns {{ cwd: string, source: "workspace_path" | "default" }}
+ */
+export function resolveWorkspaceCwd({ workspacePath, fallbackWorkspace, runtime, log }) {
+  const requested = typeof workspacePath === "string" ? workspacePath.trim() : "";
+  if (requested) {
+    const resolved = expandHome(requested);
+    const requestedAbsolute = path.isAbsolute(requested) || requested === "~" || requested.startsWith("~/");
+    if (requestedAbsolute && path.isAbsolute(resolved)) {
+      let isDirectory = false;
+      try { isDirectory = statSync(resolved).isDirectory(); } catch {}
+      if (isDirectory) {
+        log?.info?.(`${runtime}.spawn.cwd.workspace`, "using workspace_path as cwd", { cwd: resolved });
+        return { cwd: resolved, source: "workspace_path" };
+      }
+    }
+    log?.warn?.(`${runtime}.spawn.cwd.unavailable`, "requested workspace context is unavailable", {
+      requested: true,
+    });
+    const error = new Error(`${runtime}: requested workspace context is unavailable`);
+    error.code = "workspace_context_unavailable";
+    throw error;
+  }
+  const fallback = path.resolve(fallbackWorkspace);
+  log?.info?.(`${runtime}.spawn.cwd.default`, "no workspace_path, using default workspace", { cwd: fallback });
+  return { cwd: fallback, source: "default" };
+}

package/src-ext/runtime/_shared/slashCommandRouter.mjs

@@ -115,6 +115,16 @@ export async function classifySlashCommand(input, runtime, bridgeCtx) {
     // 命中（用户自定义 ~/.claude/commands / skill 命令）→ 透传真跑；
     // 未命中 → __default__ 合成提示，避免英文 "Unknown command" 直出。
     const bare = command.slice(1);
+    // system/init 在部分 Claude/Node 组合下会复用 CLI 进程级缓存，刚创建的
+    // workspace command 即使 forceFresh 也可能暂时缺席。磁盘 marker 是这里的
+    // 权威兜底，且只检查由 SLASH_RE 限定过的安全文件名。
+    const workspaceCommand = ctx?.cwd
+      ? join(ctx.cwd, ".claude", "commands", `${bare}.md`)
+      : null;
+    const userCommand = join(homedir(), ".claude", "commands", `${bare}.md`);
+    if ((workspaceCommand && existsSync(workspaceCommand)) || existsSync(userCommand)) {
+      return { kind: "passthrough", command };
+    }
     const hitKnown = (init) => {
       const known = Array.isArray(init?.slash_commands) ? init.slash_commands : [];
       return known.some((c) => String(c).toLowerCase() === bare);

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

@@ -24,8 +24,8 @@ import { probeClaudeSystemInit } from "../_shared/cliExec.mjs";
 import { normalizeClaudeLine, createLineStreamParser } from "./stdoutParser.mjs";
 import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
 import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
-import { expandHome } from "../../core/pathExpand.mjs";
 import { ensureDefaultWorkspace, defaultWorkspacePath } from "../../core/defaultWorkspace.mjs";
+import { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
 import { createWorkspace as _defaultCreateWorkspace } from "../../core/createWorkspace.mjs";
 import { createClaudeTodoTranslator } from "./todoTranslator.mjs";
 import { createAskUserQuestionTranslator, aggregateAnswers, buildOptionMaps } from "./askUserQuestionTranslator.mjs";
@@ -257,38 +257,22 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
 
   // 默认 openclawInvoke：spawn claude --print 子进程，解析 stdout，翻译事件
   // Task 3.5: 加入 blocks 参数（来自 dispatch payload），透传给 writeUserMessage 以支持多模态
-  // workspace-aware cwd: 若 workspace_path 非空且目录存在，spawn 用它作 cwd；
-  // 否则 fallback 到 defaultWorkspace（不再用工厂 cwd，修 service 模式 "/" bug）。
-  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, session_key = null, 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
-    //   注：factory cwd 不再作为兜底（保留作显式 --cwd 入口）
+  // workspace-aware cwd：显式 workspace_path 必须是可用绝对目录；缺失时才使用
+  // defaultWorkspace（不再用工厂 cwd，修 service 模式 "/" bug）。
+  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, resume_session_id: resumeSessionIDFromRelay = null, session_key = null, onChunk: _rawOnChunk }) => {
+    // v2 workspace_path 是强约束：不可用时稳定失败，不得退回默认目录。
+    // route shell 未带 workspace_path 时继续使用原默认工作区。
     let spawnCwd;
-    let cwdFallback = null;
 
     const { existsSync } = await import("node:fs");
 
     if (reqWorkspacePath && typeof reqWorkspacePath === "string" && reqWorkspacePath.trim()) {
-      const resolved = expandHome(reqWorkspacePath.trim());
-      if (existsSync(resolved)) {
-        spawnCwd = resolved;
-        log.info?.("claude.spawn.cwd.workspace", "using workspace_path as cwd", {
-          cwd: resolved, source: "workspace_path",
-        });
-      } else {
-        // workspace_path 给定但不存在 → fallback 到默认工作区，fallback 可观测
-        spawnCwd = await ensureDefaultWorkspace("claude");
-        cwdFallback = {
-          actual_cwd: spawnCwd,
-          requested_cwd: reqWorkspacePath,
-          reason: `workspace_path '${reqWorkspacePath}' does not exist after expand, falling back to default workspace`,
-        };
-        log.warn?.("claude.spawn.cwd.not_found", "workspace_path does not exist, falling back to default workspace", {
-          workspace_path: reqWorkspacePath, fallback_cwd: spawnCwd,
-        });
-      }
+      ({ cwd: spawnCwd } = resolveWorkspaceCwd({
+        workspacePath: reqWorkspacePath,
+        fallbackWorkspace: cwd,
+        runtime: "claude",
+        log,
+      }));
     } else {
       // 未给 workspace_path → 用默认工作区（lazy ensure，兜底 service 模式 "/" bug）
       spawnCwd = await ensureDefaultWorkspace("claude");
@@ -320,14 +304,6 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
         }
       : _rawOnChunk;
 
-    // fallback 可观测：workspace_path 给定但不存在时，emit run.started 含 cwd_fallback
-    if (cwdFallback) {
-      await onChunk({
-        event: "__envelopes",
-        envelopes: [buildRunStarted(run_id, { options: { cwd_fallback: cwdFallback } })],
-      });
-    }
-
     // approval 模式资源（在 try 块外声明，以便 finally 块访问）
     let _approvalPermServer = null;
     let _approvalMcpConfigPath = null;
@@ -977,6 +953,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
                     });
                     resumeHandle.child.once("error", () => resolve(-1));
                   });
+                  await resumeParser.drain();
 
                   // 新 session_id 写入 threadSessionMap
                   if (resumeCode === 0 && resumeSawNonSynthetic && resumePendingSessionId && thread_id) {
@@ -1036,6 +1013,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
         });
         handle.child.once("error", () => resolve(-1));
       });
+      await parser.drain();
       childExited = true;
       unregister();
 
@@ -1048,7 +1026,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
     }
 
     // 第一次尝试：用现有 session_id（如果有）
-    let resumeSessionId = thread_id ? threadSessionMap.get(thread_id) : null;
+    let resumeSessionId = thread_id ? threadSessionMap.get(thread_id) || resumeSessionIDFromRelay : resumeSessionIDFromRelay;
     let result = await attemptOnce({ resumeSessionId, isRetry: false });
 
     // 兜底 1：spawn 失败直接报。

package/src-ext/runtime/claude/stdoutParser.mjs

@@ -258,6 +258,10 @@ export function normalizeClaudeLine(line) {
 export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit = 1 << 20 }) {
   const decoder = new TextDecoder("utf-8");
   let buf = "";
+  // stdout 的 data 回调是同步的，但 onObject 会异步发布 relay envelope。
+  // 必须串行排队并允许调用方在 child exit 后 drain，否则 run.completed 可能
+  // 越过仍在途的 delta，relay 按状态机拒绝后 App 就永久停在 streaming。
+  let pending = Promise.resolve();
   const pLog = log ? log.child({ comp: "stdout" }) : null;
 
   function feedLine(line) {
@@ -281,13 +285,12 @@ export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit =
     pLog?.debug("stdout.line.parsed", "line parsed", {
       type: obj.type || "", has_message: !!obj.message,
     });
-    try { onObject(obj); }
-    catch (err) {
+    pending = pending.then(() => onObject(obj)).catch((err) => {
       pLog?.error("error.caught", "onObject threw", {
         where: "stdoutParser.onObject",
         err: err?.message || String(err),
       });
-    }
+    });
   }
 
   return {
@@ -316,6 +319,8 @@ export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit =
         buf = "";
       }
     },
+    /** 等待已解析行的异步 onObject 全部按输入顺序处理完。 */
+    drain() { return pending; },
   };
 }
 

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

@@ -0,0 +1,41 @@
+
+import { runHeadlessCliBridge } from "../_shared/headlessCliBridge.mjs";
+import { recordBridgedSession } from "../_shared/bridgedSessionLedger.mjs";
+import { probeBinary, runNdjsonProcess } from "../_shared/ndjsonProcess.mjs";
+import { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
+import { translateClaudeSchemaEvent } from "../_shared/claudeSchemaEvent.mjs";
+
+export function codeBuddyPreflight() {
+  const result = probeBinary("codebuddy");
+  if (!result.ok) result.hint = "请先安装 CodeBuddy Code CLI，并完成账号登录。";
+  return result;
+}
+
+export function buildCodeBuddyArgs({ input, sessionId }) {
+  const args = ["--print", String(input || ""), "--output-format", "stream-json", "--dangerously-skip-permissions"];
+  if (sessionId) args.push("--resume", sessionId);
+  return args;
+}
+
+export function createCodeBuddyInvoke({ fallbackWorkspace, log, runProcess = runNdjsonProcess }) {
+  const sessions = new Map();
+  return async ({ thread_id, input, workspace_path, resume_session_id, onChunk, onProcess }) => {
+    const { cwd } = resolveWorkspaceCwd({ workspacePath: workspace_path, fallbackWorkspace, runtime: "codebuddy", log });
+    await runProcess({
+      binary: "codebuddy",
+      args: buildCodeBuddyArgs({ input, sessionId: sessions.get(thread_id) || resume_session_id || null }),
+      cwd,
+      parseEvent: translateClaudeSchemaEvent,
+      onChunk,
+      onProcess,
+      onSession: (id) => {
+        sessions.set(thread_id, id);
+        recordBridgedSession("codebuddy", id); // 打标：桥接产生的 CLI 会话，导入时跳过
+      },
+    });
+  };
+}
+
+export async function runCodeBuddyBridge({ options, log }) {
+  return runHeadlessCliBridge({ runtime: "codebuddy", options, log, preflight: codeBuddyPreflight, createInvoke: createCodeBuddyInvoke });
+}

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

@@ -24,9 +24,9 @@ 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 { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
 import { mapCodexMsg } from "./eventMapper.mjs";
 import { createCodexPlanHandler } from "./planNotificationHandler.mjs";
 import {
@@ -227,34 +227,18 @@ export function createCodexHandleRequest({ pre, cwd, log, usage, shuttingDownRef
   // 默认 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）
+  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, resume_session_id: resumeSessionIDFromRelay = null, onChunk: _rawOnChunk }) => {
+    // v2 workspace_path 是强约束：不可用时稳定失败，不得退回默认目录。
+    // route shell 未带 workspace_path 时继续使用原默认工作区。
     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,
-        });
-      }
+      ({ cwd: spawnCwd } = resolveWorkspaceCwd({
+        workspacePath: reqWorkspacePath,
+        fallbackWorkspace: cwd,
+        runtime: "codex",
+        log,
+      }));
     } else {
       spawnCwd = await ensureDefaultWorkspace("codex");
       log.info?.("codex.spawn.cwd.default", "no workspace_path, using default workspace", {
@@ -275,14 +259,6 @@ export function createCodexHandleRequest({ pre, cwd, log, usage, shuttingDownRef
         }
       : _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。
@@ -404,7 +380,9 @@ export function createCodexHandleRequest({ pre, cwd, log, usage, shuttingDownRef
     // 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;
+    // An imported workspace can seed the first turn from relay. Once this
+    // bridge has captured a local session, that active mapping always wins.
+    let priorCodexThreadId = thread_id ? threadCodexIdMap.get(thread_id) || resumeSessionIDFromRelay : resumeSessionIDFromRelay;
     mcp = thread_id ? threadMcpMap.get(thread_id) : null;
     let mcpIsNew = false;
     if (!mcp) {

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

@@ -0,0 +1,46 @@
+
+import { runHeadlessCliBridge } from "../_shared/headlessCliBridge.mjs";
+import { recordBridgedSession } from "../_shared/bridgedSessionLedger.mjs";
+import { probeBinary, runNdjsonProcess } from "../_shared/ndjsonProcess.mjs";
+import { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
+
+export function cursorPreflight() {
+  const result = probeBinary("cursor-agent");
+  if (!result.ok) result.hint = "请安装 Cursor Agent CLI，并执行 cursor-agent login 完成登录。";
+  return result;
+}
+
+export function translateCursorEvent(event) {
+  if (event?.type !== "assistant") return null;
+  const content = Array.isArray(event.message?.content) ? event.message.content : [];
+  return content
+    .filter((item) => item?.type === "text" && item.text)
+    .map((item) => ({ event: "response.output_text.delta", delta: String(item.text) }));
+}
+
+export function createCursorInvoke({ fallbackWorkspace, log, runProcess = runNdjsonProcess }) {
+  const sessions = new Map();
+  return async ({ thread_id, input, workspace_path, resume_session_id, onChunk, onProcess }) => {
+    const { cwd } = resolveWorkspaceCwd({ workspacePath: workspace_path, fallbackWorkspace, runtime: "cursor", log });
+    const args = ["-p", "--output-format", "stream-json", "--stream-partial-output", "--trust", "--workspace", cwd];
+    const prior = sessions.get(thread_id) || resume_session_id;
+    if (prior) args.push("--resume", prior);
+    args.push(String(input || ""));
+    await runProcess({
+      binary: "cursor-agent",
+      args,
+      cwd,
+      parseEvent: translateCursorEvent,
+      onChunk,
+      onProcess,
+      onSession: (id) => {
+        sessions.set(thread_id, id);
+        recordBridgedSession("cursor", id); // 打标：桥接产生的 CLI 会话，导入时跳过
+      },
+    });
+  };
+}
+
+export async function runCursorBridge({ options, log }) {
+  return runHeadlessCliBridge({ runtime: "cursor", options, log, preflight: cursorPreflight, createInvoke: createCursorInvoke });
+}

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

@@ -0,0 +1,15 @@
+import os from "node:os";
+import path from "node:path";
+
+import { createJsonMcpConfigAdapter } from "../_shared/jsonMcpConfigAdapter.mjs";
+
+export const fileExtension = "json";
+
+const adapter = createJsonMcpConfigAdapter({
+  resolvePath: () => path.join(os.homedir(), ".cursor", "mcp.json"),
+  readServers: (config) => config.mcpServers || (config.mcpServers = {}),
+  writeServers: (config, servers) => { config.mcpServers = servers; },
+  desiredEntry: (args) => ({ command: "node", args: [...args] }),
+});
+
+export const { read, register, deregister, status } = adapter;

package/src-ext/runtime/deepagents/preflight.mjs

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+const DEEPAGENTS_COMMAND = "agentlink-deepagents";
+const DEEPAGENTS_STATUS_URL = "http://127.0.0.1:2024/agentlink/v1/status";
+const DEEPAGENTS_STATUS_TIMEOUT_MS = 1_500;
+
+function commandInstalled(spawnImpl) {
+  const lookup = process.platform === "win32" ? "where" : "which";
+  const result = spawnImpl(lookup, [DEEPAGENTS_COMMAND], {
+    encoding: "utf8",
+    timeout: DEEPAGENTS_STATUS_TIMEOUT_MS,
+  });
+  return !result.error && result.status === 0;
+}
+
+function mountedInCurrentProject(projectDir) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(projectDir, "langgraph.json"), "utf8"));
+    return String(config?.http?.app || "").toLowerCase().includes("agentlink");
+  } catch {
+    return false;
+  }
+}
+
+async function statusReachable(fetchImpl) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEEPAGENTS_STATUS_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(DEEPAGENTS_STATUS_URL, { signal: controller.signal });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** DeepAgents 由独立 sidecar 承载，不属于 npm_cli bridge。 */
+export async function deepagentsPreflight({
+  fetchImpl = globalThis.fetch,
+  spawnImpl = spawnSync,
+  projectDir = process.cwd(),
+} = {}) {
+  if (commandInstalled(spawnImpl)) return { ok: true, source: "command" };
+  if (mountedInCurrentProject(projectDir)) return { ok: true, source: "langgraph_config" };
+  if (typeof fetchImpl === "function" && await statusReachable(fetchImpl)) {
+    return { ok: true, source: "status" };
+  }
+  return {
+    ok: false,
+    error: "DeepAgents sidecar 未安装或未启动",
+    hint: "请安装 deepagents-sdk，并在 langgraph.json 挂载 AgentLink app，或启动 agentlink-deepagents。",
+  };
+}