@minhspark/codex-mcp-bridge 1.13.9 → 1.15.0

package/src/release-snapshot.mjs

@@ -0,0 +1,95 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function digestFiles(root, files) {
+  const hash = createHash("sha256");
+  for (const file of files) hash.update(file).update("\0").update(fs.readFileSync(path.join(root, file))).update("\0");
+  return hash.digest("hex");
+}
+
+function inventory(root, prefix = "") {
+  const files = [];
+  for (const entry of fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"))) {
+    if (entry.name === ".bin") continue;
+    const relative = path.join(prefix, entry.name);
+    const stat = entry.isSymbolicLink() ? fs.statSync(path.join(root, relative)) : entry;
+    if (stat.isDirectory()) files.push(...inventory(root, relative));
+    else if (stat.isFile()) files.push(relative);
+    else throw new Error(`Unsupported release file: ${relative}`);
+  }
+  return files;
+}
+
+export function sourceRevision(root) {
+  const files = ["package.json", ...inventory(root, "src")];
+  for (const file of ["package-lock.json", "node_modules/.package-lock.json"]) {
+    if (fs.existsSync(path.join(root, file))) files.push(file);
+  }
+  return digestFiles(root, files);
+}
+
+export function snapshotRoot(env = process.env) {
+  return path.resolve(env.CODEX_BRIDGE_RUNTIME_CACHE ?? path.join(env.CODEX_HOME ?? path.join(os.homedir(), ".codex"), "bridge-runtimes"));
+}
+
+function removeOwned(directory, cache) {
+  const relative = path.relative(cache, directory);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Refusing to remove an unowned runtime directory");
+  if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink()) throw new Error("Refusing to remove a linked runtime directory");
+  fs.rmSync(directory, { recursive: true, force: true });
+}
+
+export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRevision = sourceRevision(root) } = {}) {
+  root = fs.realpathSync.native(root);
+  if (fs.existsSync(cache) && fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
+  const missing = [];
+  let ancestor = path.resolve(cache);
+  while (!fs.existsSync(ancestor)) {
+    missing.unshift(path.basename(ancestor));
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) throw new Error("The runtime cache has no accessible filesystem root");
+    ancestor = parent;
+  }
+  cache = path.join(fs.realpathSync.native(ancestor), ...missing);
+  fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
+  cache = fs.realpathSync.native(cache);
+  const dependencies = inventory(root, "node_modules");
+  const dependencyRevision = digestFiles(root, dependencies);
+  const key = createHash("sha256").update(expectedRevision).update(dependencyRevision).digest("hex");
+  const target = path.join(cache, key);
+  const validate = (directory) => {
+    if (fs.lstatSync(directory).isSymbolicLink()) throw new Error("The release directory cannot be a symbolic link");
+    return sourceRevision(directory) === expectedRevision && digestFiles(directory, inventory(directory, "node_modules")) === dependencyRevision;
+  };
+  if (fs.existsSync(target)) {
+    if (!validate(target)) throw new Error("An existing immutable runtime failed integrity verification");
+    if (sourceRevision(root) !== expectedRevision) throw new Error("The installation changed during snapshot verification");
+    return { directory: target, revision: expectedRevision, key };
+  }
+  const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
+  try {
+    fs.mkdirSync(temporary, { mode: 0o700 });
+    const files = ["package.json", ...inventory(root, "src"), ...dependencies];
+    if (fs.existsSync(path.join(root, "package-lock.json"))) files.push("package-lock.json");
+    const directories = new Set(["src", "node_modules", ...files.map((file) => path.dirname(file))]);
+    for (const directory of directories) fs.mkdirSync(path.join(temporary, directory), { recursive: true, mode: 0o700 });
+    for (const file of files) {
+      fs.copyFileSync(path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
+    }
+    if (sourceRevision(root) !== expectedRevision || digestFiles(root, inventory(root, "node_modules")) !== dependencyRevision || !validate(temporary)) {
+      throw new Error("The installation changed while its immutable runtime was being prepared");
+    }
+    try { fs.renameSync(temporary, target); }
+    catch (error) {
+      if (!fs.existsSync(target) || !validate(target)) throw error;
+      removeOwned(temporary, cache);
+    }
+    return { directory: target, revision: expectedRevision, key };
+  } catch (error) {
+    removeOwned(temporary, cache);
+    throw error;
+  }
+}

package/src/reload-control.mjs

@@ -0,0 +1,96 @@
+export function cloneReloadState(value) {
+  const encoded = JSON.stringify(value);
+  if (typeof encoded !== "string" || Buffer.byteLength(encoded) > 16 * 1024 * 1024) {
+    throw new Error("Reload state is missing or exceeds its transfer limit");
+  }
+  return JSON.parse(encoded);
+}
+
+export function clientReloadReason(client) {
+  if (!client) return null;
+  for (const field of ["pending", "threadOperations", "attachingThreads", "activeTurns", "threadListeners"]) {
+    if (client[field]?.size) return `The app-server still has ${field}`;
+  }
+  if (client.connecting) return "The app-server connection is still being established";
+  return null;
+}
+
+export function createReloadControl({ entry, inspect = () => null, quiesce = () => {}, exportState = () => ({}), restore = () => {}, activate = () => {}, resume = activate, env = process.env, channel = process } = {}) {
+  if (!["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"].includes(entry)) throw new Error("Invalid reload entry point");
+  const enabled = env.CODEX_BRIDGE_WORKER === "1" && typeof channel.send === "function";
+  let phase = enabled && env.CODEX_BRIDGE_STAGED === "1" ? "staged" : "active";
+  let active = 0;
+  let deferred = null;
+  let listening = false;
+  let commands = Promise.resolve();
+
+  const status = () => {
+    const reason = active ? "MCP tool calls are still active" : deferred ?? inspect();
+    return { reloadable: phase === "active" && !reason, reason: reason ?? (phase === "active" ? null : `The worker is ${phase}`), schema: 1, phase };
+  };
+
+  const control = async (action, data) => {
+    if (action === "inspect") return status();
+    if (action === "quiesce") {
+      const current = status();
+      if (!current.reloadable) throw new Error(current.reason);
+      phase = "quiescing";
+      try {
+        await quiesce();
+        const reason = deferred ?? inspect();
+        if (active || reason) throw new Error(reason ?? "A tool call raced with quiescence");
+        const state = cloneReloadState({ schema: 1, entry, payload: exportState() });
+        phase = "quiesced";
+        return { state };
+      } catch (error) {
+        phase = "quiesced";
+        throw error;
+      }
+    }
+    if (action === "restore") {
+      if (phase !== "staged") throw new Error("Reload state can only be restored into a staged worker");
+      const state = cloneReloadState(data);
+      if (!state || state.schema !== 1 || state.entry !== entry || !state.payload || typeof state.payload !== "object" || Array.isArray(state.payload)) {
+        throw new Error("Reload state schema or entry point does not match this worker");
+      }
+      await restore(state.payload);
+      return { restored: true, schema: 1 };
+    }
+    if (action === "activate" || action === "resume") {
+      if (phase === "active") return { active: true, schema: 1 };
+      if (action === "activate" && phase !== "staged" || action === "resume" && phase !== "quiesced") {
+        throw new Error(`Cannot ${action} a ${phase} worker`);
+      }
+      await (action === "activate" ? activate() : resume());
+      phase = "active";
+      return { active: true, schema: 1 };
+    }
+    throw new Error("Unknown bridge control action");
+  };
+
+  return {
+    get staged() { return phase === "staged"; },
+    inspect: status,
+    defer(reason) { deferred ??= String(reason); },
+    async run(handler) {
+      if (phase !== "active") throw new Error(`Bridge worker is ${phase}; no tool operation was started`);
+      active += 1;
+      try { return await handler(); }
+      finally { active -= 1; }
+    },
+    control,
+    listen() {
+      if (!enabled || listening) return;
+      listening = true;
+      channel.on("message", (message) => {
+        if (message?.type !== "bridge:control" || !["string", "number"].includes(typeof message.id)) return;
+        commands = commands.catch(() => {}).then(async () => {
+          let response;
+          try { response = { result: await control(message.action, message.data) }; }
+          catch (error) { response = { error: error?.message ?? String(error) }; }
+          if (channel.connected !== false) channel.send({ type: "bridge:control-result", id: message.id, ...response });
+        });
+      });
+    },
+  };
+}

package/src/reply-forwarder.mjs

@@ -1,3 +1,5 @@
+import { cloneReloadState } from "./reload-control.mjs";
+
 const KNOWN_UNSENT_CODES = new Set([
   "RELAY_UNREACHABLE",
   "RELAY_MESSAGE_TOO_LARGE",
@@ -97,6 +99,47 @@ export class ReplyForwarder {
     return { ...counts, attempts: this.attempts, maxPerSession: this.maxPerSession, closed: this.closed };
   }
 
+  reloadReason() {
+    if (this.active || this.queue.length || this.timer !== null) return "Reply forwarding is still active or queued";
+    if ([...this.records.values()].some(({ receipt }) => ["queued", "sending", "unknown"].includes(receipt.status))) {
+      return "A reply forwarding outcome remains unconfirmed";
+    }
+    return null;
+  }
+
+  exportReloadState() {
+    const reason = this.reloadReason();
+    if (reason) throw new Error(reason);
+    return cloneReloadState({ records: [...this.records], attempts: this.attempts, lastAt: this.lastAt, closed: this.closed,
+      maxPerSession: this.maxPerSession, minIntervalMs: this.minIntervalMs });
+  }
+
+  restoreReloadState(input) {
+    if (this.records.size || this.active || this.queue.length || this.timer !== null) throw new Error("Reply forwarding state is not empty");
+    const state = cloneReloadState(input);
+    if (!state || !Array.isArray(state.records) || !Number.isSafeInteger(state.attempts) || state.attempts < 0
+      || !Number.isSafeInteger(state.maxPerSession) || state.maxPerSession < 1 || state.attempts > state.maxPerSession
+      || !Number.isFinite(state.minIntervalMs) || state.minIntervalMs < 0 || typeof state.closed !== "boolean"
+      || state.lastAt !== null && (!Number.isFinite(state.lastAt) || state.lastAt < 0)) throw new Error("Invalid reply forwarding reload state");
+    const records = new Map();
+    for (const pair of state.records) {
+      if (!Array.isArray(pair) || pair.length !== 2) throw new Error("Invalid reply forwarding record");
+      const [id, entry] = pair;
+      if (!validIdentity(id) || records.has(id) || !entry?.record || !entry.receipt
+        || entry.receipt.msgId !== id || !validIdentity(entry.receipt.threadId)
+        || entry.record.replyThreadId !== entry.receipt.threadId || (entry.record.inReplyTo ?? entry.record.msgId) !== id
+        || typeof entry.record.text !== "string" || !entry.record.text.trim()
+        || !["forwarded", "failed", "blocked"].includes(entry.receipt.status)) throw new Error("Invalid or unconfirmed reply forwarding record");
+      records.set(id, { record: Object.freeze(entry.record), receipt: entry.receipt });
+    }
+    this.records = records;
+    this.attempts = state.attempts;
+    this.lastAt = state.lastAt;
+    this.closed = state.closed;
+    this.maxPerSession = Math.min(this.maxPerSession, state.maxPerSession);
+    this.minIntervalMs = Math.max(this.minIntervalMs, state.minIntervalMs);
+  }
+
   close() {
     this.closed = true;
     if (this.timer !== null) this.cancel(this.timer);

package/src/thread-delivery.mjs

@@ -1,4 +1,4 @@
-import { NativeDesktopRelay, desktopTaskSocketPath, desktopTasksConfigured } from "./native-relay.mjs";
+import { NativeDesktopRelay, accountRelaySocketPath, desktopTaskSocketPath, desktopTasksConfigured } from "./native-relay.mjs";
 import { runTurn } from "./turn.mjs";
 import { realpathSync } from "node:fs";
 import path from "node:path";
@@ -42,20 +42,28 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
 }
 
 export class DesktopTaskDelivery {
-  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts() } = {}) {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext } = {}) {
     this.relay = relay;
     this.security = security;
     this.sleep = sleep;
     this.now = now;
     this.receipts = receipts;
+    this.beforeRequest = beforeRequest;
+    this.accountContext = accountContext;
     this.threadOperations = new Map();
   }
 
   async request(operation, args, { deadline } = {}) {
     try {
+      await this.beforeRequest?.({ operation, args });
       const remaining = deadline === undefined ? undefined : deadline - this.now();
       if (remaining !== undefined && remaining <= 0) throw new Error("The bridge's response deadline has elapsed; this operation was not sent");
-      const response = await this.relay.requestDesktop(operation, args, remaining === undefined ? undefined : { timeoutMs: remaining });
+      const accountContext = this.accountContext?.();
+      const response = await this.relay.requestDesktop(operation, args, {
+        ...(remaining === undefined ? {} : { timeoutMs: remaining }),
+        ...(this.beforeRequest ? { beforeSend: () => this.beforeRequest({ operation, args, phase: "write" }) } : {}),
+        ...(accountContext ? { accountContext } : {}),
+      });
       return response.result;
     } catch (err) {
       throw new Error(`Codex Desktop operation ${operation} failed: ${err.message}. Desktop-only mode will not start or use an external app-server. Open Codex Desktop and reconnect its native relay, then inspect the existing task before retrying a send.`, { cause: err });
@@ -87,12 +95,15 @@ export class DesktopTaskDelivery {
   }
 
   async status() {
+    const accountContext = this.accountContext?.();
+    const socketPath = this.relay.status?.({ accountContext })?.socketPath ?? this.relay.socketPath;
+    if (this.accountContext && !accountContext) return { available: false, socketPath, reason: "The current Claude and Codex accounts could not both be verified. Finish signing in and inspect the account diagnostics before sending work." };
     try {
       const response = await this.request("list_projects", {});
       if (!Array.isArray(response?.projects)) throw new Error("Desktop returned no project list");
-      return { available: true, socketPath: this.relay.socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
+      return { available: true, socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
     } catch (err) {
-      return { available: false, socketPath: this.relay.socketPath, reason: err.message };
+      return { available: false, socketPath, reason: err.message };
     }
   }
 
@@ -118,8 +129,11 @@ export class DesktopTaskDelivery {
     return { rows, coverage: "Codex Desktop's recent/pinned snapshot; local Codex workspaces only. Agent-created tasks visible in the sidebar can be omitted; read a known task ID directly before assuming creation failed." };
   }
 
-  async reuseReceipt(receipt, { cwd, promptHash, deadline }) {
+  async reuseReceipt(receipt, { cwd, promptHash, deadline, accountContext }) {
     if (!receipt) return null;
+    if (accountContext && (!receipt.accountContext || ["claude", "codex"].some((provider) => receipt.accountContext[provider] !== accountContext[provider]))) {
+      throw new Error(`The existing Desktop creation receipt ${receipt.threadId ? `for task ${receipt.threadId} ` : ""}${receipt.accountContext ? "belongs to different accounts" : "has no verified original account binding"}. Its receipt and task ID were retained. No creation or prompt resend was attempted; inspect the explicit existing task before continuing.`);
+    }
     if (path.relative(cwd, realpathSync.native(receipt.cwd))) throw new Error("The stored Desktop creation receipt belongs to another workspace. No prompt was sent.");
     if (receipt.state !== "known") throw new Error(`An earlier Desktop creation is ${receipt.state} and may already have started. ${receipt.threadId ? `threadId: ${receipt.threadId}. ` : ""}Do not resend or create another task; inspect the existing Desktop task and resolve its creation receipt first.`);
     let response;
@@ -180,7 +194,9 @@ export class DesktopTaskDelivery {
     this.security.assertCwd(cwd);
     dedupeName = dedupeName?.normalize("NFC").trim().replace(/\s+/g, " ") || undefined;
     const identity = this.receipts.key({ cwd, prompt, name: dedupeName });
-    const options = { cwd, promptHash: identity.promptHash, deadline };
+    const accountContext = this.accountContext?.();
+    if (this.accountContext && !accountContext) throw new Error("Desktop creation requires the original verified account context.");
+    const options = { cwd, promptHash: identity.promptHash, deadline, accountContext };
     const reused = await this.reuseReceipt(await this.receipts.read(identity.key), options);
     if (reused) return reused;
     const listed = await this.request("list_projects", {}, { deadline });
@@ -190,7 +206,7 @@ export class DesktopTaskDelivery {
       const existing = await this.reuseReceipt(await this.receipts.read(identity.key), options);
       if (existing) return existing;
       if (this.now() >= deadline) throw new Error("The response deadline elapsed before Desktop creation. No task was created.");
-      const receipt = { version: 1, ...identity, cwd, state: "pending", startedAt: this.now(), ...(dedupeName ? { name: dedupeName } : {}), projectId: project.projectId, ...(project.label ? { projectName: project.label } : {}) };
+      const receipt = { version: 1, ...identity, cwd, state: "pending", startedAt: this.now(), ...(accountContext ? { accountContext: { ...accountContext } } : {}), ...(dedupeName ? { name: dedupeName } : {}), projectId: project.projectId, ...(project.label ? { projectName: project.label } : {}) };
       await this.receipts.write(identity.key, receipt);
       let threadId;
       let creationConfirmed = false;
@@ -309,11 +325,11 @@ export function createThreadDelivery({
    * app-server only spawns a process that contends for the ~/.codex state and
    * then fails on the writer lock the native path exists to avoid.
    */
-  async function deliver(threadId, text) {
-    const status = relay.status();
+  async function deliver(threadId, text, options = {}) {
+    const status = relay.status(options);
     if (status.enabled) {
       try {
-        const ack = await relay.sendMessage(threadId, text);
+        const ack = await relay.sendMessage(threadId, text, options);
         reportedUnavailable = null;
         return { backend: NATIVE_BACKEND, threadId, ack };
       } catch (err) {