@minhspark/codex-mcp-bridge 1.12.1 → 1.12.2

package/src/native-relay.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import net from "node:net";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 
 import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
 
@@ -29,7 +30,7 @@ import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
  * below are the two places to fix, and `CODEX_NATIVE_RELAY_METHOD` overrides
  * the name without a release.
  */
-export const NATIVE_DISPATCH_METHOD = "codex_app.send_message_to_thread";
+export const NATIVE_DISPATCH_METHOD = "tools/call";
 
 export const RELAY_PROTOCOL_VERSION = 1;
 
@@ -47,13 +48,6 @@ const WINDOWS_RELAY_SOCKET = "\\\\.\\pipe\\LOCAL\\codex-native-relay";
 const RELAY_CONFIG_NAME = "native-relay.json";
 
 export class NativeRelayError extends Error {
-  /**
-   * `reachedCompanion` is what decides whether falling back to the app-server
-   * path is worth doing. A companion that never answered says nothing about
-   * the target thread, so the older path deserves its turn; a companion that
-   * answered with a refusal has already asked Codex, and asking again through
-   * a second app-server only adds a writer-lock failure on top.
-   */
   constructor(message, code, { reachedCompanion = false } = {}) {
     super(message);
     this.name = "NativeRelayError";
@@ -135,7 +129,149 @@ export function resolveRelayThreadId(env = process.env) {
  * middle of a request.
  */
 export function nativeDispatchParams({ executorThreadId, targetThreadId, message }) {
-  return { executorThreadId, threadId: targetThreadId, message };
+  return {
+    arguments: { threadId: targetThreadId, prompt: message },
+    callId: `codex-native-relay-${randomUUID()}`,
+    namespace: "codex_app",
+    threadId: executorThreadId,
+    tool: "send_message_to_thread",
+    turnId: `codex-native-relay-turn-${randomUUID()}`,
+  };
+}
+
+export class NativeToolsClient {
+  constructor({ env = process.env, socketPath = env.CODEX_APP_TOOLS_PIPE_PATH, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    this.env = env;
+    this.socketPath = socketPath;
+    this.timeoutMs = timeoutMs;
+    this.socket = null;
+    this.connectingSocket = null;
+    this.connecting = null;
+    this.pending = new Map();
+    this.nextId = 1;
+  }
+
+  async connect() {
+    if (this.connecting) return this.connecting;
+    if (this.socket && !this.socket.destroyed) return;
+    if (!this.socketPath) {
+      throw new NativeRelayError("CODEX_APP_TOOLS_PIPE_PATH is missing; launch the companion from Codex Desktop", "NATIVE_PIPE_UNAVAILABLE");
+    }
+    this.connecting = new Promise((resolve, reject) => {
+      const socket = net.connect({ path: this.socketPath });
+      this.connectingSocket = socket;
+      let buffer = Buffer.alloc(0);
+      let connected = false;
+      const timer = globalThis.setTimeout(() => {
+        reject(new NativeRelayError("Timed out connecting to the Codex Desktop native tools pipe", "NATIVE_PIPE_UNAVAILABLE"));
+        socket.destroy();
+      }, this.timeoutMs);
+      const fail = (err) => {
+        globalThis.clearTimeout(timer);
+        if (!connected) reject(err);
+        if (this.socket === socket) this.socket = null;
+        for (const pending of this.pending.values()) {
+          if (pending.socket === socket) pending.reject(err);
+        }
+        socket.destroy();
+      };
+      socket.on("connect", () => {
+        connected = true;
+        globalThis.clearTimeout(timer);
+        this.socket = socket;
+        resolve();
+      });
+      socket.on("data", (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        while (buffer.length >= 4) {
+          const length = buffer.readUInt32LE(0);
+          if (!length || length > MAX_FRAME_BYTES) {
+            fail(new NativeRelayError("Invalid Codex Desktop native frame length", "NATIVE_BAD_RESPONSE"));
+            return;
+          }
+          if (buffer.length < length + 4) return;
+          let response;
+          try {
+            response = JSON.parse(buffer.subarray(4, length + 4).toString("utf8"));
+          } catch {
+            fail(new NativeRelayError("Malformed Codex Desktop native response", "NATIVE_BAD_RESPONSE"));
+            return;
+          }
+          buffer = buffer.subarray(length + 4);
+          if (!response || typeof response !== "object" || response.jsonrpc !== "2.0") {
+            fail(new NativeRelayError("Invalid Codex Desktop JSON-RPC response", "NATIVE_BAD_RESPONSE"));
+            return;
+          }
+          const pending = this.pending.get(response.id);
+          if (!pending) continue;
+          if (response.error) {
+            pending.reject(new NativeRelayError(response.error.message ?? "Codex Desktop rejected the native dispatch", "NATIVE_DISPATCH_FAILED"));
+          } else if (Object.hasOwn(response, "result")) {
+            pending.resolve(response.result);
+          } else {
+            pending.reject(new NativeRelayError("Codex Desktop native response has no result", "NATIVE_BAD_RESPONSE"));
+          }
+        }
+      });
+      socket.on("error", (err) => fail(new NativeRelayError(`Codex Desktop native pipe failed: ${err.message}`, connected ? "NATIVE_DELIVERY_UNCONFIRMED" : "NATIVE_PIPE_UNAVAILABLE")));
+      socket.on("close", () => fail(new NativeRelayError("Codex Desktop native tools pipe closed before confirming delivery", connected ? "NATIVE_DELIVERY_UNCONFIRMED" : "NATIVE_PIPE_UNAVAILABLE")));
+    });
+    try {
+      await this.connecting;
+    } finally {
+      this.connecting = null;
+      this.connectingSocket = null;
+    }
+  }
+
+  async dispatch(args) {
+    const id = this.nextId++;
+    const payload = Buffer.from(JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method: this.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
+      params: nativeDispatchParams(args),
+    }));
+    if (payload.length > MAX_FRAME_BYTES) {
+      throw new NativeRelayError("Native dispatch exceeds the frame limit", "RELAY_MESSAGE_TOO_LARGE");
+    }
+    await this.connect();
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(payload.length);
+    return new Promise((resolve, reject) => {
+      const finish = (fn, value) => {
+        if (!this.pending.delete(id)) return;
+        globalThis.clearTimeout(timer);
+        fn(value);
+      };
+      const timer = globalThis.setTimeout(() => {
+        finish(reject, new NativeRelayError("Codex Desktop native dispatch timed out; delivery may have occurred", "NATIVE_DELIVERY_UNCONFIRMED"));
+      }, this.timeoutMs);
+      this.pending.set(id, {
+        socket: this.socket,
+        resolve: (value) => finish(resolve, value),
+        reject: (err) => finish(reject, err),
+      });
+      try {
+        if (!this.socket || this.socket.destroyed) throw new Error("native tools pipe is closed");
+        this.socket.write(Buffer.concat([header, payload]), (err) => {
+          if (err) finish(reject, new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED"));
+        });
+      } catch (err) {
+        finish(reject, new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED"));
+      }
+    });
+  }
+
+  close() {
+    const socket = this.socket;
+    this.socket = null;
+    for (const pending of this.pending.values()) {
+      pending.reject(new NativeRelayError("Native tools client closed before confirming delivery", "NATIVE_DELIVERY_UNCONFIRMED"));
+    }
+    socket?.destroy();
+    this.connectingSocket?.destroy();
+  }
 }
 
 /**
@@ -211,7 +347,7 @@ export class NativeDesktopRelay {
     }
 
     const response = await this.#roundTrip(line, timeoutMs);
-    if (response?.ok) return response;
+    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) return response;
     throw new NativeRelayError(
       response?.error?.message ?? "the Codex Desktop relay refused the message",
       response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
@@ -222,8 +358,9 @@ export class NativeDesktopRelay {
   #roundTrip(line, timeoutMs) {
     const socketPath = this.socketPath;
     return new Promise((resolve, reject) => {
-      let buffer = "";
+      let buffer = Buffer.alloc(0);
       let settled = false;
+      let dispatched = false;
       const socket = net.connect({ path: socketPath });
 
       const finish = (fn, value) => {
@@ -241,16 +378,19 @@ export class NativeDesktopRelay {
             new NativeRelayError(
               `The Codex Desktop relay did not answer within ${timeoutMs}ms`,
               "RELAY_TIMEOUT",
-              { reachedCompanion: true },
+              { reachedCompanion: dispatched },
             ),
           ),
         timeoutMs,
       );
 
-      socket.on("connect", () => socket.write(line));
+      socket.on("connect", () => {
+        dispatched = true;
+        socket.write(line);
+      });
       socket.on("data", (chunk) => {
-        buffer += chunk.toString("utf8");
-        if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+        buffer = Buffer.concat([buffer, chunk]);
+        if (buffer.length > MAX_FRAME_BYTES) {
           finish(
             reject,
             new NativeRelayError("The Codex Desktop relay answered with an oversized frame", "RELAY_BAD_RESPONSE", {
@@ -259,10 +399,10 @@ export class NativeDesktopRelay {
           );
           return;
         }
-        const index = buffer.indexOf("\n");
+        const index = buffer.indexOf(10);
         if (index < 0) return;
         try {
-          finish(resolve, JSON.parse(buffer.slice(0, index)));
+          finish(resolve, JSON.parse(buffer.subarray(0, index).toString("utf8")));
         } catch (err) {
           finish(
             reject,
@@ -277,7 +417,7 @@ export class NativeDesktopRelay {
       socket.on("error", (err) =>
         finish(
           reject,
-          new NativeRelayError(`Cannot reach the Codex Desktop relay at ${socketPath}: ${err.message}`, "RELAY_UNREACHABLE"),
+          new NativeRelayError(`Codex Desktop relay connection failed at ${socketPath}: ${err.message}`, dispatched ? "RELAY_DELIVERY_UNCONFIRMED" : "RELAY_UNREACHABLE", { reachedCompanion: dispatched }),
         ),
       );
       socket.on("close", () =>
@@ -285,7 +425,8 @@ export class NativeDesktopRelay {
           reject,
           new NativeRelayError(
             `The Codex Desktop relay at ${socketPath} closed before answering`,
-            "RELAY_UNREACHABLE",
+            dispatched ? "RELAY_DELIVERY_UNCONFIRMED" : "RELAY_UNREACHABLE",
+            { reachedCompanion: dispatched },
           ),
         ),
       );
@@ -293,13 +434,6 @@ export class NativeDesktopRelay {
   }
 }
 
-/**
- * Creates the dedicated executor thread once and remembers it, using the
- * ordinary app-server path - which is allowed to take a writer lock here
- * precisely because this thread belongs to nobody else. The caller stops the
- * app-server afterwards, so the lock is released and Codex Desktop is left
- * with the state to itself.
- */
 export async function bootstrapRelayThread(client, { cwd = homeDir(), env = process.env, name = "Native Relay" } = {}) {
   const res = await client.call("thread/start", {
     cwd,
@@ -309,14 +443,16 @@ export async function bootstrapRelayThread(client, { cwd = homeDir(), env = proc
   const threadId = res?.thread?.id;
   if (!threadId) throw new NativeRelayError("Codex app-server created no relay thread id", "RELAY_BOOTSTRAP_FAILED");
 
+  let release;
   try {
-    await client.call("thread/name/set", { threadId, name });
-  } catch {
-    // A thread without a title still works as an executor context.
+    try {
+      await client.call("thread/name/set", { threadId, name });
+    } catch {}
+    writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
+  } finally {
+    release = await client.releaseThread(threadId);
   }
-
-  writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
-  return { threadId, configPath: relayConfigPath(env) };
+  return { threadId, configPath: relayConfigPath(env), release };
 }
 
 export function writeRelayConfig(config, env = process.env) {

package/src/peer-protocol.mjs

@@ -212,6 +212,9 @@ export class PeerEndpoint {
     this.server = null;
     this.inbox = [];
     this.listeners = new Set();
+    this.messageSequence = 0;
+    this.requestQueues = new Map();
+    this.unconfirmedReplies = new Map();
     this.started = false;
   }
 
@@ -292,8 +295,9 @@ export class PeerEndpoint {
 
   #handleConnection(socket) {
     let buffer = "";
+    socket.setEncoding("utf8");
     socket.on("data", (chunk) => {
-      buffer += chunk.toString("utf8");
+      buffer += chunk;
       let index;
       while ((index = buffer.indexOf("\n")) >= 0) {
         const line = buffer.slice(0, index).trim();
@@ -306,8 +310,9 @@ export class PeerEndpoint {
           this.log(`ignored malformed peer frame (${line.slice(0, 80)})`);
           continue;
         }
-        const record = { ...message, receivedAt: Date.now() };
+        const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
         this.inbox.push(record);
+        this.#removePendingReply(record.fromSocket);
         this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.slice(0, 120)}`);
         for (const listener of [...this.listeners]) {
           try {
@@ -394,12 +399,55 @@ export class PeerEndpoint {
     return frame.msg_id;
   }
 
+  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next" } = {}) {
+    const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
+    const pending = previous.catch(() => {}).then(async () => {
+      const unconfirmed = this.unconfirmedReplies.get(targetSocket) ?? 0;
+      if (timeoutMs > 0 && unconfirmed > 0) {
+        const error = new Error(
+          `${unconfirmed} earlier message(s) to ${targetSocket} still await a reply; this message was not sent. `
+          + "Wait for Claude's outstanding replies and check read_claude_inbox, or set waitSec to 0 to send without matching a reply.",
+        );
+        error.code = "PEER_REPLY_PENDING";
+        throw error;
+      }
+      const since = Date.now();
+      const afterSequence = this.messageSequence;
+      this.unconfirmedReplies.set(targetSocket, unconfirmed + 1);
+      let msgId;
+      try {
+        msgId = await this.send(targetSocket, text, { priority });
+      } catch (err) {
+        this.#removePendingReply(targetSocket);
+        throw err;
+      }
+      const reply = timeoutMs > 0
+        ? await this.waitForReply(targetSocket, { timeoutMs, since, afterSequence })
+        : null;
+      return { msgId, reply };
+    });
+    this.requestQueues.set(targetSocket, pending);
+    try {
+      return await pending;
+    } finally {
+      if (this.requestQueues.get(targetSocket) === pending) this.requestQueues.delete(targetSocket);
+    }
+  }
+
+  #removePendingReply(fromSocket) {
+    const pending = this.unconfirmedReplies.get(fromSocket) ?? 0;
+    if (pending > 1) this.unconfirmedReplies.set(fromSocket, pending - 1);
+    else this.unconfirmedReplies.delete(fromSocket);
+  }
+
   /**
    * Claude answers with a fresh msg_id rather than an in-reply-to field, so a
    * reply is matched by origin socket and arrival time.
    */
-  waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now() } = {}) {
-    const existing = this.inbox.find((m) => m.fromSocket === fromSocket && m.receivedAt >= since);
+  waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now(), afterSequence = null } = {}) {
+    const matches = (record) => record.fromSocket === fromSocket
+      && (afterSequence === null ? record.receivedAt >= since : record.sequence > afterSequence);
+    const existing = this.inbox.find(matches);
     if (existing) return Promise.resolve(existing);
     return new Promise((resolve) => {
       const timer = globalThis.setTimeout(() => {
@@ -407,7 +455,7 @@ export class PeerEndpoint {
         resolve(null);
       }, timeoutMs);
       const unsubscribe = this.onMessage((record) => {
-        if (record.fromSocket !== fromSocket) return;
+        if (!matches(record)) return;
         globalThis.clearTimeout(timer);
         unsubscribe();
         resolve(record);

package/src/platform.mjs

@@ -188,6 +188,7 @@ export function resolveCodexBin(explicit) {
  */
 export function isWritableDir(target) {
   try {
+    if (!statSync(target).isDirectory()) return false;
     accessSync(target, constants.W_OK);
     return true;
   } catch {
@@ -293,7 +294,7 @@ export function resolveWorkspacePath(input) {
   const writable = ordered.find((candidate) => existsSync(candidate) && isWritableDir(candidate));
   if (writable) {
     return {
-      path: writable,
+      path: path.resolve(writable),
       remapped: writable !== original,
       writable: true,
       note:
@@ -305,10 +306,16 @@ export function resolveWorkspacePath(input) {
     };
   }
 
-  const existing = ordered.find((candidate) => existsSync(candidate));
+  const existing = ordered.find((candidate) => {
+    try {
+      return statSync(candidate).isDirectory();
+    } catch {
+      return false;
+    }
+  });
   if (existing) {
     return {
-      path: existing,
+      path: path.resolve(existing),
       remapped: existing !== original,
       writable: false,
       note: `cwd ${existing} exists but is not writable on ${PLATFORM_LABEL}; Codex will fail on any file edit.`,

package/src/thread-delivery.mjs

@@ -17,7 +17,7 @@ import { runTurn } from "./turn.mjs";
  */
 export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
-const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed", "disconnected"]);
+const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 
 export function createThreadDelivery({
   codex,
@@ -47,7 +47,7 @@ export function createThreadDelivery({
         reportedUnavailable = null;
         return { backend: NATIVE_BACKEND, threadId, ack };
       } catch (err) {
-        if (err.reachedCompanion) throw err;
+        if (err.reachedCompanion || err.code !== "RELAY_UNREACHABLE") throw err;
         log(`native relay unreachable (${err.message}); falling back to the app-server path`);
       }
     } else if (status.reason !== reportedUnavailable) {
@@ -56,22 +56,24 @@ export function createThreadDelivery({
     }
 
     if (!codex) throw new Error("No Codex app-server client is configured to deliver this message");
-    await codex.ensureThreadAttached(threadId);
-    const turn = await runTurn(codex, {
-      threadId,
-      input: [{ type: "text", text }],
-      timeoutMs,
-    });
-    if (releaseAfterTurn && RELEASE_STATUSES.has(turn.status) && typeof codex.stopServer === "function") {
-      try {
-        const released = await codex.stopServer();
-        if (released?.stillListening) log("app-server release requested but it is still listening");
-        if (released?.stopped === false) log("app-server release skipped: " + (released.reason ?? "unknown reason"));
-      } catch (err) {
-        log("app-server release failed: " + err.message);
+    const send = async () => {
+      await codex.ensureThreadAttached(threadId);
+      const turn = await runTurn(codex, {
+        threadId,
+        input: [{ type: "text", text }],
+        timeoutMs,
+      });
+      if (releaseAfterTurn && RELEASE_STATUSES.has(turn.status) && typeof codex.releaseThread === "function") {
+        try {
+          const released = await codex.releaseThread(threadId);
+          if (!released?.released) log("thread release pending: " + (released.reason ?? released.status ?? "awaiting unload"));
+        } catch (err) {
+          log("thread release failed: " + err.message);
+        }
       }
-    }
-    return { backend: APP_SERVER_BACKEND, threadId, turn };
+      return { backend: APP_SERVER_BACKEND, threadId, turn };
+    };
+    return codex.withThread ? codex.withThread(threadId, send) : send();
   }
 
   function describe() {

package/src/turn.mjs

@@ -54,10 +54,16 @@ export async function runTurn(client, { threadId, input, timeoutMs = 240000, tur
   });
 
   const process = (msg) => {
+    if (settled) return;
     const params = msg.params ?? {};
     if (turnId && params.turnId && params.turnId !== turnId) return;
 
     switch (msg.method) {
+      case "thread/closed": {
+        settled = true;
+        resolveDone({ status: "disconnected", error: { message: "The thread closed before its turn completed" } });
+        return;
+      }
       case "item/completed": {
         const summary = summarizeItem(params.item);
         if (!summary) return;
@@ -90,7 +96,7 @@ export async function runTurn(client, { threadId, input, timeoutMs = 240000, tur
   };
 
   const unsubscribe = client.subscribe(threadId, (msg) => {
-    if (!turnId) {
+    if (!turnId && msg.method !== "thread/closed") {
       buffered.push(msg);
       return;
     }
@@ -113,15 +119,27 @@ export async function runTurn(client, { threadId, input, timeoutMs = 240000, tur
   });
 
   try {
-    const started = await client.request(
-      "turn/start",
-      { threadId, input, ...turnOverrides },
-      { timeoutMs: Math.min(timeoutMs, 60000) },
-    );
-    turnId = started?.turn?.id ?? null;
-    for (const msg of buffered.splice(0)) process(msg);
-
-    const outcome = await done;
+    const start = await Promise.race([
+      client.request(
+        "turn/start",
+        { ...turnOverrides, threadId, input },
+        { timeoutMs: Math.min(timeoutMs, 60000) },
+      ).then((started) => ({ started }), (error) => ({ error })),
+      done.then((outcome) => ({ outcome })),
+    ]);
+    if (start.error) throw start.error;
+    let outcome = start.outcome;
+    if (!outcome) {
+      turnId = start.started?.turn?.id ?? null;
+      if (typeof turnId !== "string" || !turnId.trim()) {
+        throw new Error("Codex app-server did not return a turn id for turn/start");
+      }
+      for (const msg of buffered.splice(0)) process(msg);
+      if (TERMINAL_STATUSES.has(start.started?.turn?.status)) {
+        process({ method: "turn/completed", params: { turn: start.started.turn } });
+      }
+      outcome = await done;
+    }
     return {
       threadId,
       turnId,