@minhspark/codex-mcp-bridge 1.12.1 → 1.12.3

package/src/index.mjs

@@ -2,6 +2,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import path from "node:path";
+import { realpathSync } from "node:fs";
 
 import { CodexAppServerClient, writerLockWarning } from "./app-server-client.mjs";
 import {
@@ -21,7 +23,7 @@ import {
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 
-const VERSION = "1.12.1";
+const VERSION = "1.12.3";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -38,7 +40,7 @@ const DEFAULT_RELEASE_AFTER_TURN = process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN
   ? process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN === "1"
   : IS_WINDOWS;
 const TERMINAL_TURN_STATUSES = new Set(["completed", "interrupted", "failed"]);
-const RELEASE_TURN_STATUSES = new Set([...TERMINAL_TURN_STATUSES, "disconnected"]);
+const RELEASE_TURN_STATUSES = TERMINAL_TURN_STATUSES;
 const security = new BridgeSecurityPolicy();
 
 const client = new CodexAppServerClient({
@@ -115,6 +117,15 @@ async function createCodexThread({ cwd, model, name, prompt }) {
   });
   const thread = res?.thread ?? {};
   if (!thread.id) throw new Error("Codex app-server created no thread id");
+  try {
+    security.assertCwd(thread.cwd);
+    if (!path.isAbsolute(thread.cwd) || path.relative(realpathSync(workspace.path), realpathSync(thread.cwd))) {
+      throw new Error("Codex app-server created the thread in a different workspace than requested");
+    }
+  } catch (err) {
+    await client.releaseThread(thread.id).catch(() => {});
+    throw err;
+  }
   const threadName = name || prompt ? threadNameFor({ cwd: thread.cwd ?? workspace.path, prompt, name }) : null;
   if (threadName) {
     await client.call("thread/name/set", { threadId: thread.id, name: threadName });
@@ -138,26 +149,18 @@ async function finishDesktopHandoff({ threadId, result, openInApp, releaseAfterT
 
   if (releaseAfterTurn && releasable) {
     try {
-      const released = await client.stopServer();
-      if (released.stopped) {
-        if (released.stillListening) {
-          canOpenAfterRelease = false;
-          notes.push(
-            `stop requested for app-server${released.pids?.length ? ` (pid ${released.pids.join(", ")})` : ""}, but it is still listening`,
-          );
-          notes.push("WARNING: the app-server is still listening, so the desktop thread was not opened to avoid another lock");
-        } else {
-          notes.push(
-            `released app-server${released.pids?.length ? ` (pid ${released.pids.join(", ")})` : ""}; Codex Desktop can write this thread`,
-          );
-        }
+      const released = await client.releaseThread(threadId);
+      if (released.released) {
+        notes.push(`released thread ${threadId}; other app-server threads remain active`);
       } else {
         canOpenAfterRelease = false;
-        notes.push(`could not release app-server: ${released.reason}`);
+        notes.push(released.unsubscribed
+          ? `unsubscribed from thread ${threadId}; desktop opening is deferred until the server unloads it`
+          : `could not release thread: ${released.reason ?? released.status}`);
       }
     } catch (err) {
       canOpenAfterRelease = false;
-      notes.push(`could not release app-server: ${err.message}`);
+      notes.push(`could not release thread: ${err.message}`);
     }
   }
 
@@ -267,7 +270,7 @@ server.registerTool(
       releaseAfterTurn: z
         .boolean()
         .optional()
-        .describe("Stop the bridge app-server after a terminal turn so Codex Desktop owns the writer lock"),
+        .describe("Unsubscribe this thread after a terminal turn; open Desktop only after its unload is confirmed"),
     },
     annotations: {
       readOnlyHint: false,
@@ -358,7 +361,7 @@ server.registerTool(
       releaseAfterTurn: z
         .boolean()
         .optional()
-        .describe("Stop the bridge app-server after a terminal turn so Codex Desktop owns the writer lock"),
+        .describe("Unsubscribe this thread after a terminal turn; open Desktop only after its unload is confirmed"),
     },
     annotations: {
       readOnlyHint: false,
@@ -368,64 +371,66 @@ server.registerTool(
     },
   },
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
-    const notes = [];
-    const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
-    const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
-    try {
-      const authorizedThread = await assertThreadAccess(threadId);
-      let resolvedCwd = null;
-      if (cwd) {
-        const workspace = resolveWorkspacePath(cwd);
-        security.assertCwd(workspace.path);
-        resolvedCwd = workspace.path;
-        if (workspace.note) notes.push(workspace.note);
-      } else if (authorizedThread?.cwd) {
-        const workspace = resolveWorkspacePath(authorizedThread.cwd);
-        resolvedCwd = workspace.path;
-        if (workspace.note) notes.push(workspace.note);
-      }
-      const attached = await client.ensureThreadAttached(threadId, resolvedCwd ? { cwd: resolvedCwd } : {});
-      const attachedThread = normalizeThreadCwd(attached.thread ?? authorizedThread, { strict: true });
-      security.assertCwd(attachedThread?.cwd);
-      if (name) {
-        await client.call("thread/name/set", { threadId, name: name.trim().slice(0, 200) });
-        notes.push(`session name: ${name.trim().slice(0, 200)}`);
-      }
-      /**
-       * Opening the thread in the app comes after both gates. It ran first
-       * once, which meant a thread this bridge was about to refuse still got
-       * raised on screen - a refusal that leaked which threads exist.
-       */
-      if (shouldOpen && !shouldRelease) {
-        try {
-          notes.push(`opened in Codex app: ${await openThreadInCodexApp(threadId)}`);
-        } catch (err) {
-          notes.push(`could not open the thread in the Codex app: ${err.message}`);
+    return client.withThread(threadId, async () => {
+      const notes = [];
+      const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
+      const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
+      try {
+        const authorizedThread = await assertThreadAccess(threadId);
+        let resolvedCwd = null;
+        if (cwd) {
+          const workspace = resolveWorkspacePath(cwd);
+          security.assertCwd(workspace.path);
+          resolvedCwd = workspace.path;
+          if (workspace.note) notes.push(workspace.note);
+        } else if (authorizedThread?.cwd) {
+          const workspace = resolveWorkspacePath(authorizedThread.cwd);
+          resolvedCwd = workspace.path;
+          if (workspace.note) notes.push(workspace.note);
+        }
+        const attached = await client.ensureThreadAttached(threadId, resolvedCwd ? { cwd: resolvedCwd } : {});
+        const attachedThread = normalizeThreadCwd(attached.thread ?? authorizedThread, { strict: true });
+        security.assertCwd(attachedThread?.cwd);
+        if (name) {
+          await client.call("thread/name/set", { threadId, name: name.trim().slice(0, 200) });
+          notes.push(`session name: ${name.trim().slice(0, 200)}`);
         }
+        /**
+         * Opening the thread in the app comes after both gates. It ran first
+         * once, which meant a thread this bridge was about to refuse still got
+         * raised on screen - a refusal that leaked which threads exist.
+         */
+        if (shouldOpen && !shouldRelease) {
+          try {
+            notes.push(`opened in Codex app: ${await openThreadInCodexApp(threadId)}`);
+          } catch (err) {
+            notes.push(`could not open the thread in the Codex app: ${err.message}`);
+          }
+        }
+        const result = await runTurn(client, {
+          threadId,
+          input: [{ type: "text", text: prompt }],
+          timeoutMs: (timeoutSec ?? 240) * 1000,
+          turnOverrides: {
+            ...(resolvedCwd ? { cwd: resolvedCwd } : {}),
+            ...(model ?? DEFAULT_MODEL ? { model: model ?? DEFAULT_MODEL } : {}),
+            ...(effort ?? DEFAULT_EFFORT ? { effort: effort ?? DEFAULT_EFFORT } : {}),
+          },
+        });
+        const body = formatTurn(result);
+        const failed = result.status === "failed" || result.status === "disconnected";
+        notes.push(...(await finishDesktopHandoff({
+          threadId,
+          result,
+          openInApp: shouldOpen,
+          releaseAfterTurn: shouldRelease,
+        })));
+        const held = shouldOpen && !shouldRelease && client.holdsThread(threadId) ? writerLockWarning(threadId) : "";
+        return textResult(`${notes.length ? `${notes.join("\n")}\n` : ""}${body}${held}`, failed);
+      } catch (err) {
+        return failure(err);
       }
-      const result = await runTurn(client, {
-        threadId,
-        input: [{ type: "text", text: prompt }],
-        timeoutMs: (timeoutSec ?? 240) * 1000,
-        turnOverrides: {
-          ...(resolvedCwd ? { cwd: resolvedCwd } : {}),
-          ...(model ?? DEFAULT_MODEL ? { model: model ?? DEFAULT_MODEL } : {}),
-          ...(effort ?? DEFAULT_EFFORT ? { effort: effort ?? DEFAULT_EFFORT } : {}),
-        },
-      });
-      const body = formatTurn(result);
-      const failed = result.status === "failed" || result.status === "disconnected";
-      notes.push(...(await finishDesktopHandoff({
-        threadId,
-        result,
-        openInApp: shouldOpen,
-        releaseAfterTurn: shouldRelease,
-      })));
-      const held = shouldOpen && !shouldRelease && client.holdsThread(threadId) ? writerLockWarning(threadId) : "";
-      return textResult(`${notes.length ? `${notes.join("\n")}\n` : ""}${body}${held}`, failed);
-    } catch (err) {
-      return failure(err);
-    }
+    });
   },
 );
 
@@ -459,16 +464,40 @@ server.registerTool(
       }
       if (searchTerm) params.searchTerm = searchTerm;
       const method = loadedOnly ? "thread/loaded/list" : "thread/list";
-      const res = await client.call(method, loadedOnly ? { limit: limit ?? 15 } : params);
-      const rows = security.filterThreads(
-        (res?.data ?? res?.threads ?? []).flatMap((thread) => {
+      const rows = [];
+      const seenIds = new Set();
+      const seenCursors = new Set();
+      let cursor;
+      do {
+        const res = await client.call(method, loadedOnly ? { limit: params.limit, ...(cursor ? { cursor } : {}) } : params);
+        let threads = res?.data ?? res?.threads ?? [];
+        if (loadedOnly) {
+          threads = await Promise.all(threads.map(async (threadId) => {
+            if (seenIds.has(threadId)) return null;
+            seenIds.add(threadId);
+            try {
+              const read = await client.call("thread/read", { threadId });
+              return read?.thread ?? null;
+            } catch {
+              return null;
+            }
+          }));
+        }
+        rows.push(...security.filterThreads(threads.flatMap((thread) => {
           try {
-            return [normalizeThreadCwd(thread, { strict: true })];
+            const normalized = normalizeThreadCwd(thread, { strict: true });
+            if (loadedOnly && params.cwd && (!normalized?.cwd || path.relative(params.cwd.paths[0], normalized.cwd))) return [];
+            if (loadedOnly && searchTerm && !String(normalized?.name ?? normalized?.preview ?? "").toLowerCase().includes(searchTerm.toLowerCase())) return [];
+            return [normalized];
           } catch {
             return [];
           }
-        }),
-      );
+        })));
+        cursor = res?.nextCursor;
+        if (!loadedOnly || !cursor || seenCursors.has(cursor)) break;
+        seenCursors.add(cursor);
+      } while (rows.length < params.limit);
+      rows.splice(params.limit);
       if (!rows.length) {
         return textResult(
           security.summary().allowedRoots.length
@@ -648,6 +677,9 @@ server.registerTool(
   async () => {
     try {
       const result = await client.stopServer();
+      if (result.stillListening) {
+        return textResult("The app-server is still listening after the stop request; its thread writer locks are not confirmed released.", true);
+      }
       return textResult(
         result.stopped
           ? `Stopped the shared app-server (pid ${result.pids.join(", ")}). Its thread writer locks are released, so the Codex desktop app now owns ~/.codex and every thread it was holding.`

package/src/native-relay-companion.mjs

@@ -6,32 +6,18 @@ import { fileURLToPath } from "node:url";
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
 
 import {
   MAX_FRAME_BYTES,
   NATIVE_DISPATCH_METHOD,
+  NativeToolsClient,
   RELAY_PROTOCOL_VERSION,
-  nativeDispatchParams,
   relaySocketPath,
   resolveRelayThreadId,
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 
-/**
- * The companion half of the Codex Desktop native relay.
- *
- * Codex Desktop launches this as one of its own MCP servers, so the connection
- * it answers on belongs to the app's real app-server - the one already holding
- * the writer lock of every thread the human has open. Asking that app-server to
- * deliver a message is therefore not a second writer, and the thread stays open
- * and owned by Codex Desktop throughout.
- *
- * Everything else is deliberately small: a private socket, one accepted shape
- * (`{ targetThreadId, message }`), one dispatch, one acknowledgement.
- */
-
-const VERSION = "1.12.1";
+const VERSION = "1.12.3";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {
@@ -56,6 +42,11 @@ export async function handleRelayRequest(
   payload,
   { dispatch, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
 ) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
+      Object.keys(payload).some((key) => !["v", "targetThreadId", "message"].includes(key)) ||
+      (payload.v !== undefined && payload.v !== RELAY_PROTOCOL_VERSION)) {
+    return errorResponse("RELAY_BAD_REQUEST", "expected a relay request with targetThreadId and message");
+  }
   const targetThreadId = typeof payload?.targetThreadId === "string" ? payload.targetThreadId.trim() : "";
   const message = typeof payload?.message === "string" ? payload.message : "";
 
@@ -84,6 +75,10 @@ export async function handleRelayRequest(
 
   try {
     const result = await dispatch({ executorThreadId, targetThreadId, message });
+    if (result?.success !== true || result?.isError === true) {
+      const detail = typeof result?.error === "string" ? result.error : result?.error?.message;
+      return errorResponse("NATIVE_DISPATCH_FAILED", detail ?? "Codex Desktop did not confirm successful native dispatch");
+    }
     return { ok: true, v: RELAY_PROTOCOL_VERSION, targetThreadId, executorThreadId, result: result ?? null };
   } catch (err) {
     return errorResponse(errorCode(err), err?.message ?? String(err));
@@ -113,6 +108,8 @@ export class RelaySocketServer {
     this.log = logFn;
     this.server = null;
     this.started = false;
+    this.connections = new Set();
+    this.processHandlers = new Map();
   }
 
   async start() {
@@ -139,12 +136,16 @@ export class RelaySocketServer {
     this.started = true;
 
     for (const signal of ["SIGINT", "SIGTERM"]) {
-      process.on(signal, () => {
+      const handler = () => {
         this.stop();
         process.exit(0);
-      });
+      };
+      this.processHandlers.set(signal, handler);
+      process.on(signal, handler);
     }
-    process.on("exit", () => this.stop());
+    const onExit = () => this.stop();
+    this.processHandlers.set("exit", onExit);
+    process.on("exit", onExit);
 
     this.log(`relay socket listening on ${this.socketPath}`);
     return this.socketPath;
@@ -200,23 +201,30 @@ export class RelaySocketServer {
     });
   }
 
+  async isListening() {
+    return this.started || this.#socketIsLive();
+  }
+
   #handleConnection(socket) {
-    let buffer = "";
+    let buffer = Buffer.alloc(0);
+    let handled = false;
+    this.connections.add(socket);
+    socket.on("close", () => this.connections.delete(socket));
+    socket.setTimeout(30000, () => socket.destroy());
     socket.on("error", (err) => this.log(`relay socket error: ${err.message}`));
     socket.on("data", (chunk) => {
-      buffer += chunk.toString("utf8");
-      if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+      if (handled) return;
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > MAX_FRAME_BYTES) {
+        handled = true;
         this.#reply(socket, errorResponse("RELAY_MESSAGE_TOO_LARGE", `a relay frame may not exceed ${MAX_FRAME_BYTES} bytes`));
-        socket.destroy();
         return;
       }
-      let index;
-      while ((index = buffer.indexOf("\n")) >= 0) {
-        const line = buffer.slice(0, index).trim();
-        buffer = buffer.slice(index + 1);
-        if (!line) continue;
-        void this.#handleLine(socket, line);
-      }
+      const index = buffer.indexOf(10);
+      if (index < 0) return;
+      handled = true;
+      void this.#handleLine(socket, buffer.subarray(0, index).toString("utf8"));
+      buffer = Buffer.alloc(0);
     });
   }
 
@@ -239,10 +247,14 @@ export class RelaySocketServer {
 
   #reply(socket, response) {
     if (socket.destroyed) return;
-    socket.write(`${JSON.stringify(response)}\n`);
+    socket.end(`${JSON.stringify(response)}\n`);
   }
 
   stop() {
+    for (const [event, handler] of this.processHandlers) process.off(event, handler);
+    this.processHandlers.clear();
+    for (const socket of this.connections) socket.destroy();
+    this.connections.clear();
     try {
       this.server?.close();
     } catch {}
@@ -253,6 +265,58 @@ export class RelaySocketServer {
   }
 }
 
+export function startRelayWhenAvailable({ nativeTools, relay, log: logFn = () => {}, retryDelayMs = 250, maxRetryDelayMs = 30000 }) {
+  let stopped = false;
+  let timer = null;
+  let delayMs = retryDelayMs;
+  let resolveReady;
+  const ready = new Promise((resolve) => { resolveReady = resolve; });
+  const attempt = async () => {
+    if (stopped) return;
+    try {
+      await nativeTools.connect();
+      if (stopped) {
+        nativeTools.close();
+        return;
+      }
+      await relay.start();
+      if (stopped) {
+        relay.stop();
+        nativeTools.close();
+        return;
+      }
+      resolveReady(true);
+    } catch (err) {
+      if (stopped) return;
+      nativeTools.close();
+      if (!nativeTools.socketPath) {
+        logFn(`native relay unavailable (${err.message})`);
+        resolveReady(false);
+        return;
+      }
+      logFn(`native relay unavailable (${err.message}); retrying in ${delayMs}ms`);
+      timer = globalThis.setTimeout(() => {
+        timer = null;
+        void attempt();
+      }, delayMs);
+      timer.unref();
+      delayMs = Math.min(delayMs * 2, maxRetryDelayMs);
+    }
+  };
+  void attempt();
+  return {
+    ready,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      globalThis.clearTimeout(timer);
+      nativeTools.close();
+      relay.stop();
+      resolveReady(false);
+    },
+  };
+}
+
 /**
  * `import.meta.main` is Node 24 and up, and this project supports Node 22, so
  * the entry point is detected by comparing the resolved argv path instead.
@@ -271,20 +335,8 @@ if (invokedDirectly) {
     },
   );
 
-  /**
-   * The dispatch goes back over the very connection Codex Desktop opened to
-   * launch this process, which is what keeps the app the single writer. Sent as
-   * a plain JSON-RPC request rather than through a typed helper because the
-   * method is an internal of the app, not part of the MCP specification.
-   */
-  const dispatch = ({ executorThreadId, targetThreadId, message }) =>
-    mcp.server.request(
-      {
-        method: process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
-        params: nativeDispatchParams({ executorThreadId, targetThreadId, message }),
-      },
-      z.any(),
-    );
+  const nativeTools = new NativeToolsClient();
+  const dispatch = (args) => nativeTools.dispatch(args);
 
   const relay = new RelaySocketServer({ socketPath: relaySocketPath(), dispatch, log });
 
@@ -302,6 +354,7 @@ if (invokedDirectly) {
       },
     },
     async () => {
+      const listening = await relay.isListening();
       let executor = "(unconfigured)";
       try {
         const resolved = resolveRelayThreadId();
@@ -316,9 +369,10 @@ if (invokedDirectly) {
             text: [
               `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
               `companion:      codex-native-relay ${VERSION}`,
-              `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (not listening)`}`,
+              `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (${listening ? "shared companion listening" : "not listening"})`}`,
               `executor:       ${executor}`,
               `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
+              `native pipe:    ${nativeTools.socketPath ?? "unavailable (requires Codex Desktop)"}`,
             ].join("\n"),
           },
         ],
@@ -326,18 +380,8 @@ if (invokedDirectly) {
     },
   );
 
-  /**
-   * Never let the socket take the MCP server down. Codex Desktop waits on the
-   * `initialize` handshake, so a process that dies before answering reads as a
-   * hang rather than an error - the same failure mode `claude-bridge` already
-   * guards its peer endpoint against.
-   */
-  try {
-    await relay.start();
-  } catch (err) {
-    log(`relay socket unavailable (${err.message}) - claude-bridge will fall back to the app-server path`);
-  }
-
+  const startup = startRelayWhenAvailable({ nativeTools, relay, log });
+  mcp.server.onclose = () => startup.stop();
   await mcp.connect(new StdioServerTransport());
   log(`ready on ${PLATFORM_LABEL} (${relay.started ? relay.socketPath : "socket down"})`);
 }