@minhspark/codex-mcp-bridge 1.13.3 → 1.13.5

package/src/reply-forwarder.mjs

@@ -0,0 +1,172 @@
+const KNOWN_UNSENT_CODES = new Set([
+  "RELAY_UNREACHABLE",
+  "RELAY_MESSAGE_TOO_LARGE",
+  "RELAY_THREAD_UNCONFIGURED",
+  "RELAY_BAD_REQUEST",
+]);
+
+function validIdentity(value) {
+  return typeof value === "string" && value.length > 0 && !/\s/.test(value);
+}
+
+function identityError(message) {
+  return Object.assign(new Error(message), { code: "INVALID_REPLY_IDENTITY" });
+}
+
+function failureState(error) {
+  const code = typeof error?.code === "string" ? error.code : "FORWARD_OUTCOME_UNKNOWN";
+  const uncertain = error?.reachedCompanion === true || error?.deliveryUncertain === true
+    || /TIMEOUT|TIMEDOUT/.test(code) || error?.name === "TimeoutError";
+  const unsent = error?.sent === false || error?.dispatched === false
+    || error?.preflight?.sent === false || KNOWN_UNSENT_CODES.has(code);
+  return {
+    status: !uncertain && unsent ? "failed" : "unknown",
+    reasonCode: code,
+    reason: error?.message ?? String(error),
+  };
+}
+
+export class ReplyForwarder {
+  constructor({
+    deliver,
+    minIntervalMs = 5000,
+    maxPerSession = 50,
+    now = Date.now,
+    schedule = (callback, delay) => setTimeout(callback, delay),
+    cancel = clearTimeout,
+    beforeForward,
+  } = {}) {
+    if (typeof deliver !== "function") throw new TypeError("Reply forwarding requires a delivery function");
+    if (!Number.isFinite(minIntervalMs) || minIntervalMs < 0) throw new TypeError("Invalid reply forwarding interval");
+    if (!Number.isSafeInteger(maxPerSession) || maxPerSession < 1) throw new TypeError("Invalid reply forwarding limit");
+    if (![now, schedule, cancel].every((value) => typeof value === "function")
+      || (beforeForward !== undefined && typeof beforeForward !== "function")) {
+      throw new TypeError("Invalid reply forwarding callbacks");
+    }
+    this.deliver = deliver;
+    this.minIntervalMs = minIntervalMs;
+    this.maxPerSession = maxPerSession;
+    this.now = now;
+    this.schedule = schedule;
+    this.cancel = cancel;
+    this.beforeForward = beforeForward;
+    this.records = new Map();
+    this.queue = [];
+    this.timer = null;
+    this.active = null;
+    this.lastAt = null;
+    this.attempts = 0;
+    this.closed = false;
+  }
+
+  enqueue(record, threadId) {
+    const msgId = record?.inReplyTo ?? record?.msgId;
+    if (!validIdentity(msgId) || !validIdentity(threadId) || typeof record?.text !== "string" || !record.text.trim()) {
+      throw identityError("Reply forwarding requires an original message ID, exact destination task ID, and nonempty text");
+    }
+    if (record.replyThreadId != null && record.replyThreadId !== threadId) {
+      throw identityError("The reply destination differs from the original sending task");
+    }
+    const existing = this.records.get(msgId);
+    if (existing) {
+      if (existing.receipt.threadId !== threadId) throw identityError("An existing reply cannot be redirected to another task");
+      return this.read(msgId);
+    }
+    const entry = {
+      record: Object.freeze({ ...record, text: record.text, replyThreadId: threadId }),
+      receipt: { msgId, threadId, status: "queued", reasonCode: null, reason: null, queuedAt: this.now() },
+    };
+    this.records.set(msgId, entry);
+    if (this.closed) this.#block(entry, "FORWARDER_CLOSED", "Reply forwarding is closed; this reply was not dispatched");
+    else if (this.attempts >= this.maxPerSession) this.#block(entry, "SESSION_LIMIT_REACHED", "The per-session reply forwarding limit was reached; this reply was not dispatched");
+    else {
+      this.queue.push(entry);
+      this.#scheduleNext();
+    }
+    return this.read(msgId);
+  }
+
+  read(msgId) {
+    const entry = this.records.get(msgId);
+    return entry ? { ...entry.receipt } : null;
+  }
+
+  status() {
+    const counts = { total: this.records.size, queued: 0, sending: 0, forwarded: 0, failed: 0, unknown: 0, blocked: 0 };
+    for (const { receipt } of this.records.values()) counts[receipt.status] += 1;
+    return { ...counts, attempts: this.attempts, maxPerSession: this.maxPerSession, closed: this.closed };
+  }
+
+  close() {
+    this.closed = true;
+    if (this.timer !== null) this.cancel(this.timer);
+    this.timer = null;
+    for (const entry of this.queue.splice(0)) {
+      this.#block(entry, "FORWARDER_CLOSED", "Reply forwarding closed before this reply was dispatched");
+    }
+    if (this.active?.receipt.status === "queued") {
+      this.#block(this.active, "FORWARDER_CLOSED", "Reply forwarding closed before this reply was dispatched");
+    }
+    return this.status();
+  }
+
+  #block(entry, reasonCode, reason) {
+    Object.assign(entry.receipt, { status: "blocked", reasonCode, reason, completedAt: this.now() });
+  }
+
+  #scheduleNext() {
+    if (this.closed || this.active || this.timer !== null || !this.queue.length) return;
+    if (this.attempts >= this.maxPerSession) {
+      for (const entry of this.queue.splice(0)) {
+        this.#block(entry, "SESSION_LIMIT_REACHED", "The per-session reply forwarding limit was reached; this reply was not dispatched");
+      }
+      return;
+    }
+    const delay = this.lastAt === null ? 0 : Math.max(0, this.lastAt + this.minIntervalMs - this.now());
+    this.timer = this.schedule(() => {
+      this.timer = null;
+      void this.#forwardNext();
+    }, delay);
+  }
+
+  async #forwardNext() {
+    if (this.closed || this.active || !this.queue.length) return;
+    const entry = this.queue.shift();
+    this.active = entry;
+    try {
+      try {
+        await this.beforeForward?.(entry.record, entry.receipt.threadId);
+      } catch (error) {
+        if (entry.receipt.status !== "blocked") {
+          Object.assign(entry.receipt, {
+            status: "failed",
+            reasonCode: typeof error?.code === "string" ? error.code : "FORWARD_PREFLIGHT_FAILED",
+            reason: error?.message ?? String(error),
+            completedAt: this.now(),
+          });
+        }
+        return;
+      }
+      if (this.closed) {
+        this.#block(entry, "FORWARDER_CLOSED", "Reply forwarding closed before this reply was dispatched");
+        return;
+      }
+      this.lastAt = this.now();
+      this.attempts += 1;
+      Object.assign(entry.receipt, { status: "sending", attemptedAt: this.lastAt });
+      try {
+        const result = await this.deliver(entry.receipt.threadId, entry.record);
+        Object.assign(entry.receipt, {
+          status: "forwarded",
+          completedAt: this.now(),
+          ...(typeof result?.backend === "string" ? { backend: result.backend } : {}),
+        });
+      } catch (error) {
+        Object.assign(entry.receipt, failureState(error), { completedAt: this.now() });
+      }
+    } finally {
+      this.active = null;
+      this.#scheduleNext();
+    }
+  }
+}

package/src/runtime-state.mjs

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+export function createRuntimeState({ directory = path.dirname(fileURLToPath(import.meta.url)), configuration = () => null } = {}) {
+  const fingerprint = () => {
+    const hash = createHash("sha256");
+    for (const file of ["../package.json", ...readdirSync(directory).filter((file) => file.endsWith(".mjs")).sort()]) {
+      hash.update(file).update("\0").update(readFileSync(path.join(directory, file))).update("\0");
+    }
+    return hash.digest("hex");
+  };
+  const revision = fingerprint();
+  const configured = JSON.stringify(configuration());
+  const startedAt = new Date().toISOString();
+  const status = () => {
+    let diskRevision = null;
+    let reason = null;
+    try {
+      diskRevision = fingerprint();
+      if (diskRevision !== revision) reason = "Bridge source changed after this MCP process started";
+      else if (JSON.stringify(configuration()) !== configured) reason = "Bridge routing configuration changed after this MCP process started";
+    } catch {
+      reason = "Bridge source or routing configuration can no longer be read";
+    }
+    return { pid: process.pid, startedAt, revision, diskRevision, current: reason === null, reason };
+  };
+  const assertCurrent = () => {
+    const state = status();
+    if (!state.current) throw new Error(`${state.reason}. Reconnect this MCP server in the existing Desktop task before sending. No message was sent; do not create a replacement task or use an external app-server.`);
+  };
+  return { status, assertCurrent };
+}

package/src/thread-delivery.mjs

@@ -64,8 +64,9 @@ export class DesktopTaskDelivery {
 
   async withThread(threadId, operation, { deadline } = {}) {
     const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
+    let expired = false;
     const current = previous.catch(() => {}).then(() => {
-      if (deadline !== undefined && this.now() >= deadline) throw new Error("The response deadline elapsed while another operation held this thread. No new prompt was sent.");
+      if (expired || (deadline !== undefined && this.now() >= deadline)) throw new Error("The response deadline elapsed while another operation held this thread. No new prompt was sent.");
       return operation();
     });
     this.threadOperations.set(threadId, current);
@@ -75,7 +76,10 @@ export class DesktopTaskDelivery {
     let timer;
     try {
       return await Promise.race([current, new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error("The Desktop response deadline elapsed. A previous operation may still be running; inspect the existing task before sending anything again.")), Math.max(1, deadline - this.now()));
+        timer = setTimeout(() => {
+          expired = true;
+          reject(new Error("The Desktop response deadline elapsed. A previous operation may still be running; inspect the existing task before sending anything again."));
+        }, Math.max(1, deadline - this.now()));
       })]);
     } finally {
       clearTimeout(timer);
@@ -314,7 +318,7 @@ export function createThreadDelivery({
         return { backend: NATIVE_BACKEND, threadId, ack };
       } catch (err) {
         if (err.reachedCompanion || err.code !== "RELAY_UNREACHABLE") throw err;
-        if (desktopOnly) throw new Error(`Codex Desktop relay is unavailable: ${err.message}. Desktop-only mode will not start or use an external app-server.`);
+        if (desktopOnly) throw Object.assign(new Error(`Codex Desktop relay is unavailable: ${err.message}. Desktop-only mode will not start or use an external app-server.`), { code: "RELAY_UNREACHABLE", sent: false });
         log(`native relay unreachable (${err.message}); falling back to the app-server path`);
       }
     } else if (status.reason !== reportedUnavailable) {
@@ -322,7 +326,7 @@ export function createThreadDelivery({
       log(`native relay not in use: ${status.reason}`);
     }
 
-    if (desktopOnly) throw new Error(`Codex Desktop relay is unavailable: ${status.reason ?? "no native acknowledgement"}. Desktop-only mode will not start or use an external app-server.`);
+    if (desktopOnly) throw Object.assign(new Error(`Codex Desktop relay is unavailable: ${status.reason ?? "no native acknowledgement"}. Desktop-only mode will not start or use an external app-server.`), { code: "RELAY_UNREACHABLE", sent: false });
     if (!codex) throw new Error("No Codex app-server client is configured to deliver this message");
     const send = async () => {
       await codex.ensureThreadAttached(threadId);