@leo000001/codex-mcp 2.1.1 → 2.1.3

package/dist/index.js

@@ -197,8 +197,8 @@ function tryResolveNodeScriptFromShim(shimPath, codexCommand, exists, readFile,
 // src/utils/codex-executable.ts
 import { accessSync, constants, existsSync as existsSync2, statSync } from "fs";
 import path2 from "path";
-var CODEX_MCP_DEFAULT_CODEX_COMMAND = "CODEX_MCP_DEFAULT_CODEX_COMMAND";
-var CODEX_MCP_DEFAULT_CODEX_PATH = "CODEX_MCP_DEFAULT_CODEX_PATH";
+var CODEX_MCP_COMMAND = "CODEX_MCP_COMMAND";
+var CODEX_MCP_PATH = "CODEX_MCP_PATH";
 var AUTO_CODEX_COMMANDS = ["codex", "codex-internal"];
 var _resolved;
 var WINDOWS_SUPPORTED_EXTENSIONS = [".com", ".exe", ".bat", ".cmd"];
@@ -263,33 +263,33 @@ function looksLikePath(value) {
   return value.includes("/") || value.includes("\\");
 }
 function resolveDefaultCodexExecutable(env = process.env) {
-  const envPathRaw = env[CODEX_MCP_DEFAULT_CODEX_PATH]?.trim();
-  const envCommandRaw = env[CODEX_MCP_DEFAULT_CODEX_COMMAND]?.trim();
+  const envPathRaw = env[CODEX_MCP_PATH]?.trim();
+  const envCommandRaw = env[CODEX_MCP_COMMAND]?.trim();
   const envPath = envPathRaw ? normalizeMaybeQuotedToken(envPathRaw) : void 0;
   const envCommand = envCommandRaw ? normalizeMaybeQuotedToken(envCommandRaw) : void 0;
   if (envPath && envCommand) {
     throw new Error(
-      `Cannot set both ${CODEX_MCP_DEFAULT_CODEX_PATH} and ${CODEX_MCP_DEFAULT_CODEX_COMMAND}. Use one or the other.`
+      `Cannot set both ${CODEX_MCP_PATH} and ${CODEX_MCP_COMMAND}. Use one or the other.`
     );
   }
   if (envPath) {
     const resolvedPath = path2.resolve(envPath);
     if (!existsSync2(resolvedPath)) {
-      throw new Error(`${CODEX_MCP_DEFAULT_CODEX_PATH}="${envPath}" \u2014 file does not exist.`);
+      throw new Error(`${CODEX_MCP_PATH}="${envPath}" \u2014 file does not exist.`);
     }
     if (!isExecutableFile(resolvedPath)) {
-      throw new Error(`${CODEX_MCP_DEFAULT_CODEX_PATH}="${envPath}" \u2014 not an executable file.`);
+      throw new Error(`${CODEX_MCP_PATH}="${envPath}" \u2014 not an executable file.`);
     }
     return { command: resolvedPath, isPath: true, source: "env_path" };
   }
   if (envCommand) {
     if (looksLikePath(envCommand)) {
       throw new Error(
-        `${CODEX_MCP_DEFAULT_CODEX_COMMAND}="${envCommand}" looks like a path. Use ${CODEX_MCP_DEFAULT_CODEX_PATH} for filesystem paths.`
+        `${CODEX_MCP_COMMAND}="${envCommand}" looks like a path. Use ${CODEX_MCP_PATH} for filesystem paths.`
       );
     }
     if (!commandExistsOnPath(envCommand, env)) {
-      throw new Error(`${CODEX_MCP_DEFAULT_CODEX_COMMAND}="${envCommand}" was not found in PATH.`);
+      throw new Error(`${CODEX_MCP_COMMAND}="${envCommand}" was not found in PATH.`);
     }
     return { command: envCommand, isPath: false, source: "env_command" };
   }
@@ -311,17 +311,17 @@ function checkDefaultCodexExecutableAvailability() {
   const label = info.isPath ? "path" : "command";
   switch (info.source) {
     case "env_path":
-      console.error(`[codex-executable] Using ${CODEX_MCP_DEFAULT_CODEX_PATH}: ${info.command}`);
+      console.error(`[codex-executable] Using ${CODEX_MCP_PATH}: ${info.command}`);
       break;
     case "env_command":
-      console.error(`[codex-executable] Using ${CODEX_MCP_DEFAULT_CODEX_COMMAND}: ${info.command}`);
+      console.error(`[codex-executable] Using ${CODEX_MCP_COMMAND}: ${info.command}`);
       break;
     case "auto_detect":
       console.error(`[codex-executable] Auto-detected ${label}: ${info.command}`);
       break;
     case "default":
       console.error(
-        `[codex-executable] No codex found on PATH; falling back to "${info.command}". Set ${CODEX_MCP_DEFAULT_CODEX_COMMAND} or ${CODEX_MCP_DEFAULT_CODEX_PATH} to configure.`
+        `[codex-executable] No codex found on PATH; falling back to "${info.command}". Set ${CODEX_MCP_COMMAND} or ${CODEX_MCP_PATH} to configure.`
       );
       break;
   }
@@ -372,6 +372,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["THREAD_FORK_RESUME_FAILED"] = "THREAD_FORK_RESUME_FAILED";
   ErrorCode2["PROTOCOL_PARSE_ERROR"] = "PROTOCOL_PARSE_ERROR";
   ErrorCode2["WRITE_QUEUE_DROPPED"] = "WRITE_QUEUE_DROPPED";
+  ErrorCode2["EXEC_NOT_SUPPORTED"] = "EXEC_NOT_SUPPORTED";
   ErrorCode2["INTERNAL"] = "INTERNAL";
   return ErrorCode2;
 })(ErrorCode || {});
@@ -391,7 +392,7 @@ var DEFAULT_TERMINAL_CLEANUP_MS = 5 * 60 * 1e3;
 var CLEANUP_INTERVAL_MS = 6e4;
 
 // src/app-server/client.ts
-var CLIENT_VERSION = true ? "2.1.1" : "0.0.0-dev";
+var CLIENT_VERSION = true ? "2.1.3" : "0.0.0-dev";
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var STARTUP_REQUEST_TIMEOUT = 9e4;
 var MAX_WRITE_QUEUE_BYTES = 5 * 1024 * 1024;
@@ -413,6 +414,9 @@ var AppServerClient = class extends EventEmitter {
   get destroyed() {
     return this._destroyed;
   }
+  get supportsTurnOverrides() {
+    return true;
+  }
   /**
    * Spawn codex app-server and perform initialization handshake.
    */
@@ -1001,12 +1005,13 @@ var SessionManager = class {
       const turnStartResult = await client.turnStart(turnParams);
       const startedTurnId = extractTurnId(turnStartResult);
       if (startedTurnId) session.activeTurnId = startedTurnId;
-      if (resolvedCwd) session.cwd = resolvedCwd;
+      const canOverride = client.supportsTurnOverrides;
+      if (resolvedCwd && canOverride) session.cwd = resolvedCwd;
       if (overrides?.model) session.model = overrides.model;
       if (overrides?.approvalPolicy) {
         session.approvalPolicy = overrides.approvalPolicy;
       }
-      if (overrides?.sandbox) {
+      if (overrides?.sandbox && canOverride) {
         session.sandbox = overrides.sandbox;
       }
     } catch (err) {
@@ -1558,10 +1563,14 @@ var SessionManager = class {
       switch (method) {
         case Methods.THREAD_STARTED: {
           const thread = isRecord(p.thread) ? p.thread : void 0;
+          const notifiedThreadId = normalizeOptionalString(p.threadId) ?? normalizeOptionalString(thread?.id);
+          if (notifiedThreadId && notifiedThreadId !== session.threadId) {
+            session.threadId = notifiedThreadId;
+          }
           pushEvent(session.eventBuffer, "progress", {
             method,
             ...p,
-            threadId: normalizeOptionalString(p.threadId) ?? normalizeOptionalString(thread?.id),
+            threadId: notifiedThreadId,
             status: normalizeOptionalString(thread?.status)
           });
           break;
@@ -2808,6 +2817,7 @@ var ERROR_CODE_HINTS = {
   ["THREAD_FORK_RESUME_FAILED" /* THREAD_FORK_RESUME_FAILED */]: "Forked thread could not resume in new process. Retry fork from current source session.",
   ["PROTOCOL_PARSE_ERROR" /* PROTOCOL_PARSE_ERROR */]: "Non-JSON or malformed app-server line. Check shell/profile noise and transport health.",
   ["WRITE_QUEUE_DROPPED" /* WRITE_QUEUE_DROPPED */]: "stdin backpressure overflow. Reduce burst size and re-run in smaller turns.",
+  ["EXEC_NOT_SUPPORTED" /* EXEC_NOT_SUPPORTED */]: "Operation not supported in exec mode. Features like threadFork and threadResume require app-server mode.",
   ["INTERNAL" /* INTERNAL */]: "Unexpected server-side failure. Inspect logs and retry safely."
 };
 function asTextResource(uri, text, mimeType) {
@@ -2917,6 +2927,7 @@ function buildGotchasText() {
     "- Default response mode is `minimal`; use `full` if you need full raw event payloads.",
     "- respond_* uses monotonic cursor handling: `max(cursor, sessionLastCursor)`.",
     "- If `cursorResetTo` is present, your cursor is stale (old events were evicted); restart from that value.",
+    "- **Poll frequency guidance**: Adapt poll interval to task complexity and previous poll results. For `running` sessions, start at 2 minutes and increase for long tasks. Only poll frequently (~1s) when `waiting_approval`. Do NOT high-frequency poll \u2014 it wastes tokens and provides no benefit.",
     "",
     "## Approval behavior",
     "",
@@ -2950,6 +2961,13 @@ function buildGotchasText() {
     "",
     "- codex-mcp does not hard-code a strict concurrent-session cap.",
     "- Practical limit depends on machine resources and child-process load.",
+    "",
+    "## Exec fallback mode",
+    "",
+    "- When the codex binary does not support `app-server`, codex-mcp falls back to `exec` mode (`codex exec --json`).",
+    "- Check `codex-mcp:///server-info` `clientMode` field to detect which mode is active.",
+    "- **Exec mode supports multi-turn**: first turn uses `codex exec`, subsequent turns use `codex exec resume <threadId>` for context continuity.",
+    "- **Exec mode limitations**: no approval/user-input interactions, `threadFork`/`threadResume` throw `EXEC_NOT_SUPPORTED`. `sandbox`/`profile`/`cwd`/`outputSchema` overrides only apply on the first turn (exec resume does not support `-s`/`-p`/`-C`/`--output-schema`).",
     ""
   ].join("\n");
 }
@@ -3130,6 +3148,7 @@ function registerResources(server, deps) {
             name: "codex-mcp",
             version: deps.version,
             codexCliVersion: getCodexCliVersion(),
+            clientMode: deps.clientMode ?? "app-server",
             node: process.version,
             platform: process.platform,
             arch: process.arch,
@@ -3221,7 +3240,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.1.1" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.1.3" : "0.0.0-dev";
 function formatErrorMessage(err) {
   const message = err instanceof Error ? err.message : String(err);
   const m = /^Error \[([A-Z_]+)\]:\s*(.*)$/.exec(message);
@@ -3240,13 +3259,17 @@ function toStructuredContent(value) {
   }
   return { value };
 }
-function createServer(serverCwd) {
-  const sessionManager = new SessionManager();
+function createServer(serverCwd, options) {
+  const sessionManager = new SessionManager(options);
   const server = new McpServer({
     name: "codex-mcp",
     version: SERVER_VERSION
   });
-  registerResources(server, { version: SERVER_VERSION, sessionManager });
+  registerResources(server, {
+    version: SERVER_VERSION,
+    sessionManager,
+    clientMode: options?.clientMode
+  });
   const publicSessionInfoSchema = z.object({
     sessionId: z.string(),
     status: z.enum(["running", "idle", "waiting_approval", "error", "cancelled"]),
@@ -3585,9 +3608,10 @@ function createServer(serverCwd) {
 
 POLLING FREQUENCY: Do NOT poll every turn. Codex tasks take minutes, not seconds.
 - Treat pollInterval as a minimum hint, not a fixed schedule.
-- "running": never poll faster than 120000ms (2 minutes); use longer intervals for longer tasks.
+- "running": sleep at least 2 minutes between polls; increase for complex tasks. Do NOT high-frequency poll \u2014 it wastes tokens and provides no benefit.
 - "waiting_approval": poll about every 1000ms and respond quickly to actions[].
 - When status is "idle"/"error"/"cancelled": stop polling, the session is done.
+- Adapt interval based on task complexity and whether the previous poll returned new events.
 
 poll: events since cursor. Default maxEvents=${POLL_DEFAULT_MAX_EVENTS}.
 
@@ -3685,6 +3709,595 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
   return server;
 }
 
+// src/app-server/detect.ts
+import { spawn as spawn2 } from "child_process";
+var DETECTION_TIMEOUT_MS = 5e3;
+async function detectClientMode(codexCommand, codexIsPath = false, env = process.env) {
+  const override = env.CODEX_MCP_MODE;
+  if (override === "app-server" || override === "exec") {
+    return override;
+  }
+  try {
+    const supported = await probeAppServer(codexCommand, codexIsPath, env);
+    return supported ? "app-server" : "exec";
+  } catch {
+    return "exec";
+  }
+}
+function probeAppServer(codexCommand, codexIsPath, env) {
+  return new Promise((resolve) => {
+    const invocation = resolveCodexInvocation(["app-server", "--help"], {
+      env,
+      codexCommand,
+      codexIsPath
+    });
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    let stdout = "";
+    let stderr = "";
+    const proc = spawn2(invocation.cmd, invocation.args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      windowsHide: true
+    });
+    proc.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", () => {
+      settle(false);
+    });
+    proc.on("exit", (code) => {
+      if (code === 0) {
+        settle(true);
+      } else {
+        const combined = (stdout + stderr).toLowerCase();
+        const isUnknown = combined.includes("unknown") || combined.includes("unrecognized") || combined.includes("not found") || combined.includes("no such subcommand");
+        settle(!isUnknown && combined.includes("app-server"));
+      }
+    });
+    const timer = setTimeout(() => {
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+      }
+      settle(false);
+    }, DETECTION_TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+  });
+}
+
+// src/app-server/exec-client.ts
+import { spawn as spawn3 } from "child_process";
+import { writeFileSync, mkdtempSync } from "fs";
+import { EventEmitter as EventEmitter2 } from "events";
+import { randomUUID as randomUUID2 } from "crypto";
+import { tmpdir } from "os";
+import { join } from "path";
+import { StringDecoder as StringDecoder2 } from "string_decoder";
+var FORCE_KILL_TIMEOUT_MS = 5e3;
+function camelCaseItemType(snakeType) {
+  return snakeType.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function transformItem(item) {
+  const result = { ...item };
+  if (typeof result.type === "string") {
+    result.type = camelCaseItemType(result.type);
+  }
+  return result;
+}
+function isRetryableError(event) {
+  const msg = typeof event.message === "string" ? event.message : "";
+  return /reconnect/i.test(msg) || /\d+\/\d+/.test(msg);
+}
+function sandboxPolicyToMode(policy) {
+  switch (policy.type) {
+    case "readOnly":
+      return "read-only";
+    case "workspaceWrite":
+      return "workspace-write";
+    case "dangerFullAccess":
+      return "danger-full-access";
+    case "externalSandbox":
+      console.error(
+        `[exec-client] SandboxPolicy type "externalSandbox" cannot be mapped to exec -s flag; using thread-level sandbox`
+      );
+      return void 0;
+    default:
+      return void 0;
+  }
+}
+var EXEC_EVENT_TO_METHOD = {
+  // Agent message deltas
+  agent_message_delta: Methods.AGENT_MESSAGE_DELTA,
+  agent_message_content_delta: Methods.AGENT_MESSAGE_DELTA,
+  // Command execution
+  exec_command_output_delta: Methods.COMMAND_OUTPUT_DELTA,
+  command_output_delta: Methods.COMMAND_OUTPUT_DELTA,
+  terminal_interaction: Methods.COMMAND_TERMINAL_INTERACTION,
+  // File changes
+  file_change_output_delta: Methods.FILE_CHANGE_OUTPUT_DELTA,
+  // Reasoning
+  reasoning_content_delta: Methods.REASONING_TEXT_DELTA,
+  reasoning_raw_content_delta: Methods.REASONING_TEXT_DELTA,
+  agent_reasoning_delta: Methods.REASONING_TEXT_DELTA,
+  agent_reasoning_raw_content_delta: Methods.REASONING_TEXT_DELTA,
+  reasoning_summary_delta: Methods.REASONING_SUMMARY_DELTA,
+  agent_reasoning_section_break: Methods.REASONING_SUMMARY_PART_ADDED,
+  // Plan
+  plan_delta: Methods.PLAN_DELTA,
+  plan_update: Methods.TURN_PLAN_UPDATED,
+  // Turn-level
+  turn_diff: Methods.TURN_DIFF_UPDATED,
+  diff_update: Methods.TURN_DIFF_UPDATED,
+  // MCP
+  mcp_tool_call_begin: Methods.MCP_TOOL_PROGRESS,
+  mcp_tool_call_end: Methods.MCP_TOOL_PROGRESS,
+  mcp_startup_update: Methods.MCP_TOOL_PROGRESS,
+  mcp_startup_complete: Methods.MCP_TOOL_PROGRESS,
+  // Model routing
+  model_reroute: Methods.MODEL_REROUTED,
+  // Thread/session events
+  thread_name_updated: Methods.THREAD_NAME_UPDATED,
+  token_count: Methods.THREAD_TOKEN_USAGE_UPDATED,
+  session_configured: Methods.SESSION_CONFIGURED,
+  // Item lifecycle (in case exec emits these outside the dot-notation variants)
+  item_started: Methods.ITEM_STARTED,
+  item_completed: Methods.ITEM_COMPLETED,
+  raw_response_item: Methods.RAW_RESPONSE_ITEM_COMPLETED,
+  // Stream errors — map to error method so retryable detection can handle it
+  stream_error: Methods.ERROR,
+  // Legacy turn lifecycle (v1 wire format used by older CLIs)
+  // These are critical for exec fallback since it targets CLIs without app-server.
+  task_started: Methods.TURN_STARTED,
+  task_complete: Methods.TURN_COMPLETED,
+  turn_aborted: Methods.TURN_COMPLETED
+};
+var ExecClient = class extends EventEmitter2 {
+  _destroyed = false;
+  process = null;
+  spawnOpts = null;
+  // Thread/turn state
+  threadId = null;
+  /** Real thread ID from CLI (received via thread.started event). Used for exec resume. */
+  realThreadId = null;
+  turnId = null;
+  turnCount = 0;
+  threadStartParams = null;
+  lastAgentMessageText = "";
+  turnCompleted = false;
+  // Handlers
+  notificationHandler = null;
+  serverRequestHandler = null;
+  // Stdout buffer for JSONL parsing
+  buffer = "";
+  decoder = new StringDecoder2("utf8");
+  get destroyed() {
+    return this._destroyed;
+  }
+  get supportsTurnOverrides() {
+    return this.turnCount <= 1 || this.realThreadId == null;
+  }
+  async start(opts) {
+    if (this._destroyed) throw new Error("Client destroyed");
+    this.spawnOpts = opts;
+    return { userAgent: "codex-exec" };
+  }
+  async threadStart(params) {
+    if (this._destroyed) throw new Error("Client destroyed");
+    this.threadStartParams = params;
+    this.threadId = `exec_thread_${randomUUID2().slice(0, 12)}`;
+    return { thread: { id: this.threadId } };
+  }
+  async threadFork(_params) {
+    throw new Error(
+      `Error [${"EXEC_NOT_SUPPORTED" /* EXEC_NOT_SUPPORTED */}]: threadFork is not supported in exec mode`
+    );
+  }
+  async threadResume(_params) {
+    throw new Error(
+      `Error [${"EXEC_NOT_SUPPORTED" /* EXEC_NOT_SUPPORTED */}]: threadResume is not supported in exec mode`
+    );
+  }
+  async threadBackgroundTerminalsClean(_params) {
+    return {};
+  }
+  async turnStart(params) {
+    if (this._destroyed) throw new Error("Client destroyed");
+    if (!this.threadId) throw new Error("No thread started");
+    this.killProcess();
+    this.turnCount++;
+    this.turnId = `exec_turn_${randomUUID2().slice(0, 12)}`;
+    this.lastAgentMessageText = "";
+    this.turnCompleted = false;
+    this.buffer = "";
+    this.decoder = new StringDecoder2("utf8");
+    const prompt = params.input.filter((i) => i.type === "text").map((i) => i.text).join("\n");
+    const images = params.input.filter((i) => i.type === "localImage").map((i) => i.path);
+    const isResume = this.turnCount > 1 && this.realThreadId != null;
+    if (this.turnCount > 1 && !this.realThreadId) {
+      console.error(
+        "[exec-client] No realThreadId available for resume; falling back to fresh exec (context will be lost)"
+      );
+      this.emitNotification(Methods.ERROR, {
+        threadId: this.threadId,
+        turnId: this.turnId,
+        error: "exec mode: multi-turn context unavailable (CLI did not provide thread ID). This turn runs without prior context.",
+        willRetry: true
+        // non-terminal: session continues, just without context
+      });
+    }
+    const args = isResume ? this.buildResumeArgs(prompt, params, images) : this.buildExecArgs(prompt, params, images);
+    const executable = getDefaultCodexExecutable();
+    const invocation = resolveCodexInvocation(args, {
+      codexCommand: executable.command,
+      codexIsPath: executable.isPath
+    });
+    const proc = spawn3(invocation.cmd, invocation.args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env },
+      detached: process.platform !== "win32",
+      windowsHide: process.platform === "win32"
+    });
+    this.process = proc;
+    proc.stdin?.end();
+    proc.stdout.on("data", (chunk) => this.onData(chunk));
+    proc.stderr.on("data", (chunk) => {
+      console.error(`[exec-client stderr] ${chunk.toString().trimEnd()}`);
+    });
+    proc.on("error", (err) => {
+      if (!this._destroyed) {
+        this.emit("error", err);
+      }
+    });
+    proc.on("exit", (code, signal) => {
+      if (this.turnId && !this._destroyed && !this.turnCompleted) {
+        if (code !== 0 && code !== null) {
+          this.emitNotification(Methods.ERROR, {
+            threadId: this.threadId,
+            turnId: this.turnId,
+            error: { message: `exec process exited with code ${code}` },
+            willRetry: false
+          });
+        }
+      }
+      if (!this._destroyed) {
+        this.emit("exit", code, signal);
+      }
+      this.process = null;
+    });
+    const turnId = this.turnId;
+    return { turn: { id: turnId } };
+  }
+  async turnInterrupt(_params) {
+    this.killProcess();
+  }
+  onNotification(handler) {
+    this.notificationHandler = handler;
+  }
+  onServerRequest(handler) {
+    this.serverRequestHandler = handler;
+  }
+  respondToServer(_id, _result) {
+  }
+  respondErrorToServer(_id, _code, _message) {
+  }
+  async destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    const proc = this.process;
+    if (proc && !proc.killed) {
+      const alreadyExited = proc.exitCode !== null;
+      proc.stdin?.end();
+      this.killProcess();
+      const forceKill = setTimeout(() => {
+        if (proc && !proc.killed && proc.exitCode === null) {
+          if (process.platform === "win32" && proc.pid) {
+            try {
+              spawn3("taskkill", ["/PID", String(proc.pid), "/T", "/F"], {
+                stdio: "ignore",
+                windowsHide: true
+              });
+            } catch {
+            }
+          } else {
+            try {
+              if (proc.pid) process.kill(-proc.pid, "SIGKILL");
+              else proc.kill("SIGKILL");
+            } catch {
+            }
+          }
+        }
+      }, FORCE_KILL_TIMEOUT_MS);
+      forceKill.unref();
+      if (!alreadyExited) {
+        await new Promise((resolve) => {
+          proc.on("exit", () => {
+            clearTimeout(forceKill);
+            resolve();
+          });
+          const fallback = setTimeout(resolve, FORCE_KILL_TIMEOUT_MS + 1e3);
+          fallback.unref();
+        });
+      }
+    }
+    this.process = null;
+    this.removeAllListeners();
+  }
+  // ── Private helpers ─────────────────────────────────────────────
+  /**
+   * Build args for the first turn: `codex exec "<prompt>" --json --skip-git-repo-check [flags]`.
+   * No --ephemeral so the session persists for subsequent resume turns.
+   */
+  buildExecArgs(prompt, params, images) {
+    const args = ["exec", prompt, "--json", "--skip-git-repo-check"];
+    const model = params.model ?? this.threadStartParams?.model ?? this.spawnOpts?.model;
+    if (model) args.push("-m", model);
+    let effectiveSandbox;
+    if (params.sandboxPolicy) {
+      effectiveSandbox = sandboxPolicyToMode(params.sandboxPolicy);
+    }
+    if (!effectiveSandbox) {
+      effectiveSandbox = this.threadStartParams?.sandbox ?? this.spawnOpts?.sandbox;
+    }
+    if (effectiveSandbox) args.push("-s", effectiveSandbox);
+    if (this.spawnOpts?.profile) args.push("-p", this.spawnOpts.profile);
+    const cwd = params.cwd ?? this.threadStartParams?.cwd;
+    if (cwd) args.push("-C", cwd);
+    for (const img of images) args.push("-i", img);
+    const approvalPolicy = params.approvalPolicy ?? this.threadStartParams?.approvalPolicy ?? this.spawnOpts?.approvalPolicy;
+    if (approvalPolicy) args.push("-c", `approval_policy=${approvalPolicy}`);
+    if (params.outputSchema && Object.keys(params.outputSchema).length > 0) {
+      try {
+        const tmpDir = mkdtempSync(join(tmpdir(), "codex-mcp-schema-"));
+        const schemaPath = join(tmpDir, "output-schema.json");
+        writeFileSync(schemaPath, JSON.stringify(params.outputSchema));
+        args.push("--output-schema", schemaPath);
+      } catch (err) {
+        console.error(
+          `[exec-client] Failed to write output schema to temp file: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    const configs = {
+      ...this.spawnOpts?.config,
+      ...this.threadStartParams?.config
+    };
+    for (const [key, value] of Object.entries(configs)) {
+      const serialized = typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+      args.push("-c", `${key}=${serialized}`);
+    }
+    return args;
+  }
+  /**
+   * Build args for subsequent turns: `codex exec resume <threadId> "<prompt>" --json [flags]`.
+   * Resumes the persisted session for multi-turn context continuity.
+   * Note: exec resume only supports -m, -c, -i, --json, --skip-git-repo-check.
+   *       -s, -p, -C are NOT supported and inherit from the first turn's session.
+   */
+  buildResumeArgs(prompt, params, images) {
+    const args = [
+      "exec",
+      "resume",
+      this.realThreadId,
+      prompt,
+      "--json",
+      "--skip-git-repo-check"
+    ];
+    if (params.sandboxPolicy) {
+      console.error(
+        "[exec-client] sandbox override ignored in resume mode (exec resume does not support -s)"
+      );
+    }
+    if (params.cwd) {
+      console.error(
+        "[exec-client] cwd override ignored in resume mode (exec resume does not support -C)"
+      );
+    }
+    if (params.outputSchema && Object.keys(params.outputSchema).length > 0) {
+      console.error(
+        "[exec-client] outputSchema ignored in resume mode (exec resume does not support --output-schema)"
+      );
+    }
+    const model = params.model ?? this.threadStartParams?.model ?? this.spawnOpts?.model;
+    if (model) args.push("-m", model);
+    for (const img of images) args.push("-i", img);
+    const approvalPolicy = params.approvalPolicy ?? this.threadStartParams?.approvalPolicy ?? this.spawnOpts?.approvalPolicy;
+    if (approvalPolicy) args.push("-c", `approval_policy=${approvalPolicy}`);
+    const configs = {
+      ...this.spawnOpts?.config,
+      ...this.threadStartParams?.config
+    };
+    for (const [key, value] of Object.entries(configs)) {
+      const serialized = typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+      args.push("-c", `${key}=${serialized}`);
+    }
+    return args;
+  }
+  onData(chunk) {
+    this.buffer += this.decoder.write(chunk);
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed[0] !== "{") continue;
+      try {
+        const event = JSON.parse(trimmed);
+        this.handleExecEvent(event);
+      } catch {
+        console.error(`[exec-client] Failed to parse JSONL: ${trimmed.slice(0, 200)}`);
+      }
+    }
+  }
+  /**
+   * Transform exec JSONL event into app-server notification and dispatch.
+   */
+  handleExecEvent(event) {
+    const type = event.type;
+    switch (type) {
+      case "thread.started": {
+        const cliThreadId = event.thread_id;
+        if (cliThreadId) {
+          this.threadId = cliThreadId;
+          this.realThreadId = cliThreadId;
+        }
+        this.emitNotification(Methods.THREAD_STARTED, {
+          thread: { id: this.threadId }
+        });
+        return;
+      }
+      case "turn.started":
+        this.emitNotification(Methods.TURN_STARTED, {
+          turn: { id: this.turnId, status: "inProgress" }
+        });
+        return;
+      case "item.started": {
+        const item = event.item;
+        if (item) {
+          this.emitNotification(Methods.ITEM_STARTED, {
+            threadId: this.threadId,
+            turnId: this.turnId,
+            item: transformItem(item)
+          });
+        }
+        return;
+      }
+      case "item.completed": {
+        const item = event.item;
+        if (item) {
+          const transformed = transformItem(item);
+          if (transformed.type === "agentMessage" && typeof transformed.text === "string") {
+            this.lastAgentMessageText = transformed.text;
+          }
+          this.emitNotification(Methods.ITEM_COMPLETED, {
+            threadId: this.threadId,
+            turnId: this.turnId,
+            item: transformed
+          });
+        }
+        return;
+      }
+      case "turn.completed": {
+        const turnId = this.turnId ?? "";
+        this.turnCompleted = true;
+        this.emitNotification(Methods.TURN_COMPLETED, {
+          threadId: this.threadId,
+          turn: {
+            id: turnId,
+            status: "completed",
+            output: this.lastAgentMessageText || void 0,
+            usage: event.usage
+          }
+        });
+        this.turnId = null;
+        return;
+      }
+      case "turn.failed": {
+        const turnId = this.turnId ?? "";
+        const error = event.error;
+        this.turnCompleted = true;
+        this.emitNotification(Methods.TURN_COMPLETED, {
+          threadId: this.threadId,
+          turn: {
+            id: turnId,
+            status: "failed",
+            error: error ?? { message: "Turn failed" }
+          }
+        });
+        this.turnId = null;
+        return;
+      }
+      case "error": {
+        const willRetry = isRetryableError(event);
+        this.emitNotification(Methods.ERROR, {
+          threadId: this.threadId,
+          turnId: this.turnId,
+          error: event.message ?? event.error,
+          willRetry
+        });
+        return;
+      }
+      default:
+        break;
+    }
+    const mappedMethod = EXEC_EVENT_TO_METHOD[type];
+    if (mappedMethod) {
+      if (type === "task_started") {
+        const turnId = event.turn_id ?? this.turnId;
+        if (turnId) this.turnId = turnId;
+        this.emitNotification(Methods.TURN_STARTED, {
+          turn: { id: this.turnId, status: "inProgress" }
+        });
+      } else if (type === "task_complete") {
+        const turnId = this.turnId ?? "";
+        this.turnCompleted = true;
+        this.emitNotification(Methods.TURN_COMPLETED, {
+          threadId: this.threadId,
+          turn: {
+            id: turnId,
+            status: "completed",
+            output: this.lastAgentMessageText || void 0
+          }
+        });
+        this.turnId = null;
+      } else if (type === "turn_aborted") {
+        const turnId = this.turnId ?? "";
+        this.turnCompleted = true;
+        this.emitNotification(Methods.TURN_COMPLETED, {
+          threadId: this.threadId,
+          turn: {
+            id: turnId,
+            status: "cancelled",
+            error: event.reason ?? { message: "Turn aborted" }
+          }
+        });
+        this.turnId = null;
+      } else if (mappedMethod === Methods.ERROR) {
+        this.emitNotification(Methods.ERROR, {
+          threadId: this.threadId,
+          turnId: this.turnId,
+          error: event.message ?? event.error ?? type,
+          willRetry: isRetryableError(event)
+        });
+      } else {
+        this.emitNotification(mappedMethod, {
+          threadId: this.threadId,
+          turnId: this.turnId,
+          ...event
+        });
+      }
+      return;
+    }
+    console.error(`[exec-client] Unmapped exec event type: ${type}`);
+  }
+  emitNotification(method, params) {
+    if (this.notificationHandler) {
+      this.notificationHandler(method, params);
+    }
+  }
+  killProcess() {
+    if (!this.process || this.process.killed) return;
+    if (process.platform !== "win32" && this.process.pid) {
+      try {
+        process.kill(-this.process.pid, "SIGTERM");
+        return;
+      } catch {
+      }
+    }
+    try {
+      this.process.kill("SIGTERM");
+    } catch {
+    }
+  }
+};
+
 // src/index.ts
 async function main() {
   const preflight = runStdioPreflight();
@@ -3706,8 +4319,15 @@ async function main() {
     );
   }
   checkDefaultCodexExecutableAvailability();
+  const executable = getDefaultCodexExecutable();
+  const clientMode = await detectClientMode(executable.command, executable.isPath);
+  console.error(`[codex-mcp] client mode: ${clientMode} (binary: ${executable.command})`);
+  const createClient = () => clientMode === "exec" ? new ExecClient() : new AppServerClient();
   const serverCwd = process.cwd();
-  const server = createServer(serverCwd);
+  const server = createServer(serverCwd, {
+    createClient,
+    clientMode
+  });
   const transport = new StdioServerTransport();
   let closing = false;
   const shutdown = async () => {