@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/src/setup.mjs

@@ -46,14 +46,23 @@ function execute(command, args, env, timeout = 120000) {
   const result = spawnSync(command, args, { env, encoding: "utf8", windowsHide: true, shell: false, timeout,
     maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
   if (result.error || result.status !== 0) {
-    const lines = String(result.stderr || "").split(/\r?\n/).filter((line) => /^Error:|^(?:Expected|Refusing|Invalid|Unknown|Shared|Claude|Codex|Configuration|The existing|Missing|Unsafe)/.test(line)
-      && !/Command failed|--env|password|secret|token|authorization/i.test(line));
-    const detail = lines.slice(0, 3).join(" ") || result.error?.code || `exit ${result.status}`;
-    throw new Error(`${path.basename(command)} ${path.basename(args[0] ?? "")}: ${detail}`);
+    throw setupProcessFailure(command, args, result);
   }
   return result.stdout || "";
 }
 
+export function setupProcessFailure(command, args, result) {
+  let structured;
+  try { structured = JSON.parse(String(result.stdout || "")); } catch {}
+  const validCode = value => typeof value === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(value);
+  const codes = [structured?.code, structured?.service?.code, structured?.permissions?.code, structured?.diagnostic?.code,
+    ...String(result.stderr || "").split(/\r?\n/).map(line => /^([A-Z][A-Z0-9_]{0,79}) \| /.exec(line)?.[1])].filter(validCode);
+  const lines = String(result.stderr || "").split(/\r?\n/).filter(line => /^Error:|^(?:Expected|Refusing|Invalid|Unknown|Shared|Claude|Codex|Configuration|The existing|Missing|Unsafe)/.test(line)
+    && !/Command failed|--env|password|secret|token|authorization/i.test(line));
+  const detail = [...new Set(codes)].join(", ") || lines.slice(0, 3).join(" ") || result.error?.code || `exit ${result.status}`;
+  return Object.assign(new Error(`${path.basename(command)} ${path.basename(args[0] ?? "")}: ${detail}`), codes[0] ? { code: codes[0] } : {});
+}
+
 function usableBinary(binary, platform) {
   return typeof binary === "string" && path.isAbsolute(binary) && fs.existsSync(binary)
     && fs.statSync(binary).isFile() && (platform !== "win32" || /\.(exe|com)$/i.test(binary));
@@ -83,24 +92,25 @@ export function ensureSetupCodex({ env, paths, platform, download = true, run =
 }
 
 export function setupEnvironment(env, paths, codex) {
-  const result = Object.fromEntries(Object.entries(env).filter(([name]) => !/^(?:CODEX_BRIDGE_|CLAUDE_BRIDGE_|CODEX_NATIVE_RELAY_|CODEX_RELAY_ID$|CODEX_THREAD_ID$|CODEX_APP_TOOLS_PIPE_PATH$)/.test(name)));
+  const result = Object.fromEntries(Object.entries(env).filter(([name]) => !/^(?:CODEX_BRIDGE_|CLAUDE_BRIDGE_|CODEX_NATIVE_RELAY_|CODEX_RELAY_ID$|CODEX_THREAD_ID$|CODEX_APP_TOOLS_PIPE_PATH$|AGENT_RELAY_(?:TOKEN|WORKER_ID|REQUEST_ID|ENDPOINT)$)/.test(name)));
   return { ...result, HOME: paths.home, USERPROFILE: paths.home, CODEX_HOME: paths.codex,
     CLAUDE_DESKTOP_CONFIG: paths.desktop, CODEX_EXE: codex, CODEX_BIN: 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 }); }
 }
 
 function assertEntry(entry, worker, root, { caller } = {}) {
   if (!entry || typeof entry.command !== "string" || !fs.existsSync(entry.command)) throw new Error("MCP command is missing or unavailable");
   const args = entry.args ?? [];
-  const expected = worker === "index.mjs" || worker === "claude-bridge.mjs" || worker === "native-relay-companion.mjs"
+  const expected = ["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs", "antigravity-bridge.mjs", "antigravity-outbound-bridge.mjs"].includes(worker)
     ? [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 +129,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 +141,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"));
@@ -146,17 +169,22 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
   configurationCheck("Claude registration names", () => {
     if (readJson(paths.desktop)?.mcpServers?.["codex-bridge"]) throw new Error("Shared codex-bridge shadows the Claude Code registration");
   }, components);
+  configurationCheck("Independent background relay", () => {
+    const details = JSON.parse(run(process.execPath, [path.join(root, "scripts", "setup-background-relay.mjs"), "--check", "--json"], setupEnvironment(env, paths, codex), 90000));
+    if (details.configured !== true) throw new Error("Independent worker relay configuration is incomplete");
+    return { liveVerified: details.liveVerified === true, transportReady: details.transportReady === true, notices: details.notices ?? [] };
+  }, components);
   return { configured: components.every((item) => item.status === "configured"), liveVerified: false, components };
 }
 
 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 --foreground-scripts\nGlobal npm installation configures Claude Desktop, Claude Code, Codex, Antigravity and the independent worker relay automatically. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration, background relay health and loaded native 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";
   const paths = setupPaths(env, platform);
-  const planned = ["Claude Code / codex-bridge", "Claude Desktop / codex-bridge-desktop", ...(native ? ["Codex / codex-native-relay and executor"] : []), "Codex / claude-bridge", "Antigravity / all components"];
+  const planned = ["Claude Code / codex-bridge", "Claude Desktop / codex-bridge-desktop", ...(native ? ["Codex / codex-native-relay and executor"] : []), "Codex / claude-bridge", "Antigravity / all components", "Independent background relay"];
   if (options.dryRun) return { dryRun: true, configured: false, liveVerified: false, components: planned.map((name) => ({ name, status: "planned" })), files: [paths.code, paths.desktop, path.join(paths.codex, "config.toml"), paths.gemini] };
   if (env.SUDO_USER && env.SUDO_USER !== "root" && typeof process.getuid === "function" && process.getuid() === 0) throw new Error("Run the global install without sudo in the account that runs the apps; setup will not write another account's configuration.");
   const runtime = ensureSetupCodex({ env, paths, platform, download: !options.noDownload, run, resolve });
@@ -166,39 +194,48 @@ 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 } : {}),
+        ...(typeof details.liveVerified === "boolean" ? { liveVerified: details.liveVerified, transportReady: details.transportReady === true } : {}),
+        ...(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"] : [])]);
   }
   install("Codex / claude-bridge", "install-codex-mcp.mjs", ["--setup"]);
   if (code) install("Antigravity / all components", "install-antigravity-bridge.mjs", ["--all", "--setup"]);
+  install("Independent background relay", "setup-background-relay.mjs", ["--json"]);
   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 native readiness separately from this configuration check.",
+      "worker_status or worker-relay status reports the independent service and CLI workers, which do not require a responsive Desktop host."] };
 }
 
 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,

package/src/windows-pipe-acl.ps1

@@ -1,6 +1,6 @@
 param([Parameter(Mandatory)][string]$PipeName,[Parameter(Mandatory)][uint32]$ServerPid)
 $ErrorActionPreference='Stop'
-if($PipeName -notmatch '^LOCAL\\(?:codex-native-relay|codex-bridge|cc-msg)-[A-Za-z0-9_.-]+$'){throw 'Refusing a pipe outside the bridge-owned namespace.'}
+if($PipeName -notmatch '^LOCAL\\(?:(?:codex-native-relay|codex-bridge|cc-msg)-[A-Za-z0-9_.-]+|minhspark-agent-relay-[a-f0-9]{24})$'){throw 'Refusing a pipe outside the bridge-owned namespace.'}
 Add-Type @'
 using System;
 using System.ComponentModel;