@minhspark/codex-mcp-bridge 1.25.2 → 1.25.3

package/src/recipient-preflight.mjs

@@ -1,5 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const diagnosticCode = (value) => typeof value === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(value) ? value : null;
+const diagnosticId = (value) => typeof value === "string" && /^(?:[a-f0-9]{64}|(?:local_)?[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$/i.test(value) ? value : null;
+
+export function diagnosticText(value) {
+  return String(value ?? "Unknown bridge failure")
+    .replace(/\{[\s\S]*\}|\[\s*(?:\{|"|true|false|null|\d)[\s\S]*\]/g, "[structured details omitted]")
+    .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[credential]")
+    .replace(/((?:access[_-]?token|refresh[_-]?token|api[_-]?key|token|secret|password|authorization)\s*["']?\s*[:=]\s*)["']?[^\s,"';}]+["']?/gi, "$1[redacted]")
+    .replace(/https?:\/\/[^\s<>"']+/gi, "[url]")
+    .replace(/(?:[a-z]:[\\/]|\\\\)[^\r\n"'<>|,;]*/gi, "[path]")
+    .replace(/(^|[\s"'(])\/(?:Users|home|tmp|var|private|Volumes|mnt)\/[^\r\n"'<>|,;]*/g, "$1[path]")
+    .replace(/[\w.+-]+@[\w.-]+\.[a-z]{2,}/gi, "[email]")
+    .replace(/\b(?:sk-[a-z0-9_-]+|gh[pousr]_[a-z0-9_]+)\b/gi, "[credential]")
+    .replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 1400);
+}
+
+export function bridgeDiagnostic(error, options = {}) {
+  const previous = error?.diagnostic?.schemaVersion === 1 ? error.diagnostic : null;
+  const chain = [];
+  const seen = new Set();
+  for (let cause = error; cause && !seen.has(cause) && chain.length < 8; cause = cause.cause) {
+    seen.add(cause);
+    chain.push(cause);
+  }
+  const codes = [...new Set(chain.flatMap((cause) => [cause?.preflight?.code, cause?.code, cause?.reasonCode, cause?.diagnostic?.code]).map(diagnosticCode).filter(Boolean))];
+  const code = diagnosticCode(previous?.code) ?? diagnosticCode(options.code) ?? codes[0] ?? "BRIDGE_OPERATION_FAILED";
+  const state = options.deliveryState ?? previous?.deliveryState ?? error?.deliveryState;
+  const deliveryState = state === "not_applicable" || options.readOnly && !previous ? "not_applicable"
+    : ["not_sent", "not-sent"].includes(state) ? "not_sent"
+    : state === "sent" ? "sent"
+    : state === "unknown" || error?.deliveryUncertain ? "unknown"
+    : chain.some((cause) => cause?.sent === false || cause?.preflight?.sent === false) ? "not_sent" : "unknown";
+  const name = (value, fallback) => typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_./-]{0,99}$/.test(value) ? value : fallback;
+  const ids = {};
+  for (const key of ["requestId", "msgId", "deliveryId", "threadId", "taskId", "conversationId"]) {
+    const id = diagnosticId(previous?.ids?.[key] ?? options[key] ?? error?.[key]);
+    if (id) ids[key] = id;
+  }
+  const timestamp = previous?.timestamp;
+  return {
+    schemaVersion: 1,
+    reportId: diagnosticId(previous?.reportId) ?? randomUUID(),
+    timestamp: typeof timestamp === "string" && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(timestamp) ? timestamp : new Date().toISOString(),
+    component: name(previous?.component ?? options.component, "bridge"),
+    operation: name(previous?.operation === "unknown" ? options.operation : previous?.operation ?? options.operation, "unknown"),
+    version: typeof previous?.version === "string" && /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(previous.version) ? previous.version : version,
+    platform: process.platform,
+    nodeVersion: process.versions.node,
+    code,
+    causeCodes: [...new Set([...(Array.isArray(previous?.causeCodes) ? previous.causeCodes : []).map(diagnosticCode).filter(Boolean), ...codes])].filter((value) => value !== code).slice(0, 8),
+    phase: name(previous?.phase ?? options.phase ?? error?.phase ?? error?.diagnostic?.stage, deliveryState === "not_sent" ? "preflight" : options.readOnly ? "inspection" : "delivery"),
+    deliveryState,
+    sent: deliveryState === "not_sent" ? false : deliveryState === "sent" ? true : null,
+    retrySafe: deliveryState === "not_sent",
+    nextAction: deliveryState === "not_sent" ? "Inspect the reported cause and bridge status before retrying. Do not open or create chats to load a relay."
+      : deliveryState === "not_applicable" ? "Inspect bridge status and include this diagnostic in the report."
+      : "Inspect the original delivery receipt. Do not resend automatically or create a replacement chat.",
+    reason: diagnosticText(previous?.reason ?? error?.preflight?.reason ?? error?.message ?? error),
+    ids,
+  };
+}
+
+export function withBridgeDiagnostic(result, error, options = {}) {
+  const diagnostic = bridgeDiagnostic({ ...error, cause: error?.cause, message: error?.message ?? String(error ?? "Bridge operation failed"), diagnostic: result?.structuredContent?.diagnostic ?? result?.diagnostic ?? error?.diagnostic }, options);
+  const report = ["Bridge diagnostic (include this block in a bug report)", `${diagnostic.code} | ${diagnostic.component} / ${diagnostic.operation}`,
+    `Bridge ${diagnostic.version} | ${diagnostic.platform} | Node ${diagnostic.nodeVersion}`,
+    `Phase: ${diagnostic.phase} | Delivery: ${diagnostic.deliveryState} | Sent: ${diagnostic.sent ?? "unconfirmed"}`,
+    `Reason: ${diagnostic.reason}`, ...(diagnostic.causeCodes.length ? [`Cause codes: ${diagnostic.causeCodes.join(", ")}`] : []),
+    ...Object.entries(diagnostic.ids).map(([key, value]) => `${key}: ${value}`),
+    `Report: ${diagnostic.reportId} | ${diagnostic.timestamp}`, diagnostic.nextAction].join("\n");
+  return { ...result, content: [...(result?.content ?? []).filter((item) => item.type !== "text" || !item.text.startsWith("Bridge diagnostic (")), { type: "text", text: report }],
+    structuredContent: { ...result?.structuredContent, diagnostic } };
+}
+
 export function preflightFailure(code, reason) {
   const error = new Error(`${reason} No message was sent.`);
+  error.code = code;
+  error.deliveryState = "not_sent";
+  error.sent = false;
   error.preflight = { status: "blocked", code, reason, sent: false };
   return error;
 }

package/src/setup.mjs

@@ -89,7 +89,7 @@ export function setupEnvironment(env, paths, codex) {
 }
 
 function configurationCheck(label, check, components) {
-  try { check(); components.push({ name: label, status: "configured" }); }
+  try { const details = check(); components.push({ name: label, status: "configured", ...details }); }
   catch (error) { components.push({ name: label, status: "incomplete", detail: error.message }); }
 }
 
@@ -99,8 +99,9 @@ function assertEntry(entry, worker, root, { caller } = {}) {
   const expected = worker === "index.mjs" || worker === "claude-bridge.mjs" || worker === "native-relay-companion.mjs"
     ? [path.join(root, "src", "mcp-supervisor.mjs"), worker] : [path.join(root, "src", worker)];
   if (JSON.stringify(args) !== JSON.stringify(expected)) throw new Error("MCP entry points to a different installation or unsupported launcher");
-  if (entry.enabled === false || entry.disabled === true) throw new Error("MCP entry is disabled; the saved choice was preserved");
   if (caller && entry.env?.ANTIGRAVITY_BRIDGE_CALLER !== caller) throw new Error("Antigravity caller registration is missing or conflicting");
+  if (entry.enabled === false || entry.disabled === true) return { deliveryEnabled: false,
+    notices: ["This MCP registration is intentionally disabled. Its saved choice was preserved; delivery through this connector is disabled."] };
 }
 
 export function checkSetup({ env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
@@ -119,8 +120,9 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
       const item = inventory?.find((server) => server.name === name);
       if (!item) throw new Error("MCP registration is missing");
       const entry = JSON.parse(run(codex, ["mcp", "get", name, "--json"], setupEnvironment(env, paths, codex), 30000));
-      assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
+      const details = assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
       if (name === "codex-native-relay" && !entry.transport.env_vars?.includes("CODEX_APP_TOOLS_PIPE_PATH")) throw new Error("Native pipe forwarding is missing");
+      return details;
     }, components);
   }
   for (const [label, file, name, worker, caller] of [
@@ -130,14 +132,26 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
     ["Antigravity / agent-bridge", path.join(paths.gemini, "mcp_config.json"), "agent-bridge", "antigravity-outbound-bridge.mjs"],
   ]) configurationCheck(label, () => {
     const entry = readJson(file)?.mcpServers?.[name];
-    assertEntry(entry, worker, root, { caller });
+    const details = assertEntry(entry, worker, root, { caller });
+    if (worker === "index.mjs" && entry.env?.CODEX_BRIDGE_OPEN_IN_APP === "1") {
+      throw new Error("Managed bridge settings still allow opening Codex Desktop. Run codex-bridge-setup to apply the current silent configuration.");
+    }
     if (name === "codex-bridge-desktop" && entry.env?.CODEX_BRIDGE_DESKTOP_TASKS === "1") {
-      throw new Error("Shared Desktop chat cannot use native Code routing. Its saved choice was preserved; explicitly set CODEX_BRIDGE_DESKTOP_TASKS=0 for the local app-server route and CODEX_BRIDGE_AUTOSTART=1 if the bridge should start that server.");
+      return { ...details, nativeCodeOnly: true, sharedChatDelivery: "unsupported",
+        notices: [...(details?.notices ?? []), "The saved native Code-only policy was preserved. Ordinary Claude Desktop Chat cannot deliver through this connector; native delivery uses the registered Claude Desktop Code connector and remains unverified by setup."] };
     }
+    return details;
+  }, components);
+  configurationCheck("Claude Desktop / background preference", () => {
+    if (readJson(paths.desktop)?.preferences?.menuBarEnabled !== true) throw new Error("The managed Claude background preference is not enabled. Run codex-bridge-setup to apply it; live activation is verified separately.");
   }, components);
   configurationCheck("Antigravity / codex-bridge sidecar", () => {
-    assertEntry(readJson(path.join(paths.gemini, "sidecars", "codex-bridge", "sidecar.json")), "antigravity-sidecar.mjs", root);
-    if (readJson(path.join(paths.gemini, "config.json"))?.sidecars?.["codex-bridge"]?.enabled !== true) throw new Error("Antigravity sidecar is not enabled");
+    const details = assertEntry(readJson(path.join(paths.gemini, "sidecars", "codex-bridge", "sidecar.json")), "antigravity-sidecar.mjs", root);
+    const enabled = readJson(path.join(paths.gemini, "config.json"))?.sidecars?.["codex-bridge"]?.enabled;
+    if (typeof enabled !== "boolean") throw new Error("Antigravity sidecar enabled setting is missing or invalid");
+    if (!enabled) return { deliveryEnabled: false,
+      notices: [...(details?.notices ?? []), "The Antigravity bridge sidecar is intentionally disabled. Its saved choice was preserved; native Desktop delivery through this sidecar is disabled."] };
+    return details;
   }, components);
   if (native) configurationCheck("Native relay executor", () => {
     const relay = readJson(path.join(paths.codex, "native-relay.json"));
@@ -151,7 +165,7 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
 
 export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
   const options = setupArguments(args);
-  if (options.help) return { help: "Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nGlobal npm installation configures Claude Desktop, Claude Code, Codex and Antigravity automatically. CODEX_BRIDGE_SKIP_SETUP=1 opts out." };
+  if (options.help) return { help: "Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings with: npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge\nGlobal npm installation configures Claude Desktop, Claude Code, Codex and Antigravity automatically. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration and loaded app connections are verified separately." };
   if (options.postinstall && !automaticSetupEnabled(env)) return { skipped: true, reason: "Automatic configuration runs only for a global npm install; use codex-bridge-setup for manual setup." };
   if (options.check) return checkSetup({ env, platform, root, run, resolve });
   const native = platform === "win32" || platform === "darwin";
@@ -166,16 +180,18 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const install = (name, script, arguments_, environment = base) => {
     try {
       const output = run(process.execPath, [path.join(root, "scripts", script), ...arguments_], environment, 180000);
-      let notices = [];
-      try { notices = JSON.parse(output).notices ?? []; } catch {}
-      components.push({ name, status: "configured", ...(notices.length ? { notices } : {}) });
+      let details = {};
+      try { details = JSON.parse(output); } catch {}
+      const notices = details.notices ?? [];
+      components.push({ name, status: "configured", ...(notices.length ? { notices } : {}),
+        ...(details.backgroundPreference ? { backgroundPreference: details.backgroundPreference } : {}) });
       return true;
     } catch (error) { components.push({ name, status: "incomplete", detail: error.message }); return false; }
   };
-  const code = install(planned[0], "install-claude-code.mjs", ["--install", "--desktop-config", paths.desktop], {
+  const code = install(planned[0], "install-claude-code.mjs", ["--install", "--setup", "--desktop-config", paths.desktop], {
     ...base, CODEX_BRIDGE_DESKTOP_TASKS: native ? "1" : "0", CODEX_BRIDGE_AUTOSTART: native ? "0" : "1", CODEX_BRIDGE_THREAD_POLICY: "roots",
   });
-  if (code) install(planned[1], "install-claude-desktop.mjs", ["--entry-name", "codex-bridge-desktop", "--quiet"]);
+  if (code) install(planned[1], "install-claude-desktop.mjs", ["--entry-name", "codex-bridge-desktop", "--quiet", "--setup"]);
   if (native) {
     const relay = readJson(path.join(paths.codex, "native-relay.json"));
     install("Codex / codex-native-relay and executor", "install-native-relay.mjs", ["--setup", ...(relay?.desktopTasks === undefined ? ["--desktop-tasks"] : [])]);
@@ -185,20 +201,24 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const inspection = checkSetup({ env: base, platform, root, run, resolve: () => runtime.binary });
   return { configured: components.every((item) => item.status === "configured") && inspection.configured, liveVerified: false,
     cliInstalled: runtime.installed, components, verification: inspection.components,
-    nextActions: ["Open or reconnect Claude, Codex and Antigravity after active work finishes so they load the new entries.",
-      "Use the same saved project in Claude Desktop Code and Codex Desktop. Keep the apps signed in.",
-      "Verify codex_bridge_status in Claude Code, native_relay_status in Codex, and agent_bridge_status in Antigravity. Shared Claude Desktop chat uses the local app-server route."] };
+    nextActions: ["Running MCP processes may still hold earlier settings. Setup does not start apps or open conversations.",
+      "Existing compatible supervisors reload installed source when idle; configuration changes are not proof of loaded-process readiness.",
+      "Native delivery uses the same saved project and signed-in accounts in Claude Desktop Code and Codex Desktop.",
+      "codex_bridge_status, native_relay_status and agent_bridge_status report live readiness separately from this configuration check."] };
 }
 
 export function printSetup(result, { json = false, output = console.log } = {}) {
   if (json) { output(JSON.stringify(result, null, 2)); return; }
   if (result.help) { output(result.help); return; }
   if (result.skipped) { output(result.reason); return; }
-  output(result.dryRun ? "Bridge setup preview (no changes)" : result.configured ? "Bridge configuration verified. Live connections still require the apps to load it." : "Bridge setup is incomplete. Fix the items below, then run codex-bridge-setup again.");
+  output(result.dryRun ? "Bridge setup preview (no changes)" : result.configured ? "Bridge configuration verified. Running app connections have not been verified." : "Bridge setup is incomplete. Fix the items below, then run codex-bridge-setup again.");
   for (const item of result.components ?? []) {
     output(`[${item.status}] ${item.name}${item.detail ? `: ${item.detail}` : ""}`);
     for (const notice of item.notices ?? []) output(`  ${notice}`);
   }
-  for (const item of result.verification ?? []) if (item.status !== "configured") output(`[${item.status}] ${item.name}: ${item.detail}`);
+  for (const item of result.verification ?? []) {
+    if (item.status !== "configured") output(`[${item.status}] ${item.name}: ${item.detail}`);
+    for (const notice of item.notices ?? []) output(`${item.name}: ${notice}`);
+  }
   for (const action of result.nextActions ?? []) output(action);
 }

package/src/thread-delivery.mjs

@@ -9,6 +9,7 @@ import { captureCodexRolloutWatermark, inspectCodexNativeTurn, readCodexNativeTu
 import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
 import { isRolloutChangedDuringRead } from "./rollout-segments.mjs";
 import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
+import { bridgeDiagnostic } from "./recipient-preflight.mjs";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -74,7 +75,7 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
   return matches[0];
 }
 
-export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening after waiting for silent recovery. Its Desktop-owned supervisor restarts crashed relay workers without replaying requests. If Desktop has not loaded the relay MCP, reconnect it in a regular project task; automatic recovery never opens a task or window. Do not open the internal Native Relay executor task.";
+export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening after waiting for silent recovery. Its Desktop-owned supervisor restarts crashed relay workers without replaying requests. An unloaded native host cannot be cold-started by this bridge. Inspect codex_bridge_status and include its diagnostic in a report. Never open an app or an old, new, empty or failed chat to load a relay.";
 
 function relayUnreachable(error) {
   return error?.code === "RELAY_UNREACHABLE" && error.sent === false;
@@ -196,13 +197,17 @@ 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." };
+    if (this.accountContext && !accountContext) {
+      const reason = "The current Claude and Codex accounts could not both be verified. Finish signing in and inspect the account diagnostics before sending work.";
+      return { available: false, socketPath, code: "BRIDGE_ACCOUNT_UNVERIFIED", reason, diagnostic: bridgeDiagnostic(new Error(reason), { component: "codex-bridge", operation: "codex_bridge_status", code: "BRIDGE_ACCOUNT_UNVERIFIED", readOnly: true }) };
+    }
     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, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
     } catch (err) {
-      return { available: false, socketPath, reason: err.message };
+      const diagnostic = bridgeDiagnostic(err, { component: "codex-bridge", operation: "codex_bridge_status", readOnly: true });
+      return { available: false, socketPath, code: diagnostic.code, reason: err.message, diagnostic };
     }
   }
 
@@ -336,11 +341,11 @@ export class DesktopTaskDelivery {
         const confirmedId = response?.threadId ?? response?.conversationId;
         threadId = confirmedId;
         if (!threadId && (response?.status === "outcome-unknown" || response?.firstTurn?.status === "outcome-unknown")) threadId = response?.clientThreadId;
-        if (typeof confirmedId !== "string" || !confirmedId.trim() || response?.status === "outcome-unknown" || response.hostId !== "local") throw new Error(`Desktop creation is not confirmed: ${JSON.stringify(response)}`);
+        if (typeof confirmedId !== "string" || !confirmedId.trim() || response?.status === "outcome-unknown" || response.hostId !== "local") throw Object.assign(new Error("Desktop creation is not confirmed; inspect the original native receipt."), { code: "CODEX_CREATION_UNCONFIRMED", deliveryState: "unknown", phase: "creation" });
         await this.receipts.write(identity.key, { ...receipt, state: "known", threadId });
         creationConfirmed = true;
         this.security.registerThread(threadId);
-        if (response.firstTurn && response.firstTurn.status !== "accepted") throw new Error(`Desktop created task ${threadId}; its first turn reports ${response.firstTurn.status ?? "an unconfirmed state"}: ${JSON.stringify(response)}`);
+        if (response.firstTurn && response.firstTurn.status !== "accepted") throw Object.assign(new Error(`Desktop created task ${threadId}; its first turn reports ${["failed", "waitingOnApproval", "waitingOnUserInput", "outcome-unknown"].includes(response.firstTurn.status) ? response.firstTurn.status : "an unconfirmed state"}. Inspect the original native receipt.`), { code: "CODEX_FIRST_TURN_NOT_ACCEPTED", deliveryState: "sent", phase: "first_turn" });
         const created = { threadId, name, cwd, projectId: project.projectId, projectName: project.label, backend: NATIVE_BACKEND };
         const delivered = { ...created, previousTurnId: null, deliveryStatus: "accepted", responseObservation: {
             operation: "create_thread", threadId, previousTurnId: null, expectedCwd: cwd,