@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/docs/project-onboarding.md

@@ -1,26 +1,33 @@
 # Project onboarding and shared authorization
 
-The recommended global installation registers the bridges automatically:
+The recommended global installation registers the bridges and configures the
+independent worker relay automatically:
 
 ```sh
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 In Windows PowerShell use `npm.cmd`. The script allowance authorizes only this
 package's setup hook; npm versions that block install scripts by default need
-it. A plain install runs setup only when the hook is allowed. Append
-`--foreground-scripts` to see progress. If npm prints
+it. A plain install runs setup only when the hook is allowed.
+`--foreground-scripts` displays progress. If npm prints
 `1 package had install scripts blocked`, rerun the recommended command or run
 `codex-bridge-setup` explicitly. The setup creates
 `codex-bridge` for Claude Code and the separate `codex-bridge-desktop` shared
 Claude connector, configures Codex and Antigravity, and initializes the native
-relay on Windows/macOS. See [installation](../README.md#installation).
+relay on Windows/macOS. It also installs the per-user background service and
+worker communication settings, including Antigravity's four scoped relay tool
+grants. See [installation](../README.md#installation).
 
 Setup preserves existing scope and permission choices. Registration does not
 grant workspace trust, authorize cross-project work, or establish a live
 connection. The shared Desktop connector uses local app-server sessions;
 native Codex Desktop handoffs require a verified Claude Code sender in the
-same saved project.
+same saved project. Independent CLI workers require their own provider
+authentication and project authorization; they can communicate while Desktop
+apps are closed or frozen. A frozen UI still cannot accept new user input or
+display results. Use a terminal or another responsive client, subject to the
+[background worker prerequisites](../README.md#independent-background-workers).
 
 `codex-bridge-setup --check` inspects all saved registrations. Use
 `codex-bridge-setup --dry-run` to preview or rerun `codex-bridge-setup` to apply
@@ -31,15 +38,21 @@ If app configuration is incomplete, npm retains the package for repair; its
 success exit alone does not verify setup. Explicit setup and `--check` return
 a nonzero status until the saved configuration passes verification.
 
-## Optional shared project policy
+## Shared project policy
 
-Both bridge directions can read the same optional policy file via
+Native Codex/Claude handoffs can read the same optional policy file via
 `CODEX_BRIDGE_PROJECT_POLICY`. `bridge-projects` defaults to
 `~/.config/GptClaudeBridge/projects.json`. A shared home-directory path avoids
 different AppData views in packaged Windows applications. The policy stores
 canonical directory identities; do not copy it to a new machine as proof of
 authorization there.
 
+Independent background dispatch always requires a matching explicit project
+or parent grant from the shared
+policy; setup preserves grants and revocations rather than authorizing a new
+project. Use `bridge-projects allow-project <absolute-project-path>` for a
+selected project (`bridge-projects.cmd` on Windows), or the source commands below.
+
 ```sh
 node scripts/bridge-projects.mjs allow-project /absolute/projects/example
 node scripts/bridge-projects.mjs allow-parent /absolute/projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.25.2",
+  "version": "1.26.0",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",
@@ -30,6 +30,7 @@
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "codex-bridge-code-install": "scripts/install-claude-code.mjs",
     "codex-bridge-setup": "scripts/setup.mjs",
+    "worker-relay": "scripts/worker-relay.mjs",
     "bridge-projects": "scripts/bridge-projects.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
     "codex-native-relay": "src/native-relay-launcher.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.25.2",
+  "version": "1.26.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/background-relay-hidden.vbs

@@ -0,0 +1,11 @@
+Option Explicit
+If WScript.Arguments.Count <> 3 Then WScript.Quit 2
+Dim relayShell, relayEnvironment, relayNode, relayService
+Set relayShell = CreateObject("WScript.Shell")
+Set relayEnvironment = relayShell.Environment("PROCESS")
+relayNode = WScript.Arguments(0)
+relayService = WScript.Arguments(1)
+If InStr(relayNode, Chr(34)) > 0 Or InStr(relayNode, "%") > 0 Then WScript.Quit 2
+If InStr(relayService, Chr(34)) > 0 Or InStr(relayService, "%") > 0 Then WScript.Quit 2
+relayEnvironment("AGENT_RELAY_DIRECTORY") = WScript.Arguments(2)
+WScript.Quit relayShell.Run(Chr(34) & relayNode & Chr(34) & " " & Chr(34) & relayService & Chr(34), 0, True)

package/scripts/install-antigravity-bridge.mjs

@@ -7,6 +7,7 @@ import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mc
 import { isMainModule, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 import { homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 
 const NAME = "antigravity-bridge";
 const SIDECAR = "codex-bridge";
@@ -17,7 +18,7 @@ function object(value, label) {
   return value;
 }
 
-function snapshot(file) {
+function snapshot(file, jsonLabel) {
   let descriptor;
   try { descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); }
   catch (error) {
@@ -41,7 +42,13 @@ function snapshot(file) {
     }
     if (length !== opened.size || !matches(opened, fs.fstatSync(descriptor)) || !matches(opened, fs.lstatSync(file))) throw new Error(`Configuration changed while reading: ${file}`);
     const text = buffer.subarray(0, length).toString("utf8");
-    return { file, text, value: object(JSON.parse(text), file), mode: opened.mode & 0o777, dev: opened.dev, ino: opened.ino };
+    let value;
+    try { value = object(JSON.parse(text), file); }
+    catch (error) {
+      if (jsonLabel) throw new Error(`Invalid ${jsonLabel}: expected a JSON object.`);
+      throw error;
+    }
+    return { file, text, value, ...(jsonLabel ? { jsonLabel } : {}), mode: opened.mode & 0o777, dev: opened.dev, ino: opened.ino };
   } finally { fs.closeSync(descriptor); }
 }
 
@@ -53,17 +60,21 @@ export function validateCodexExecutable(executable, { platform = process.platfor
   return resolved;
 }
 
-function ownEntry(entry, expected, label, retarget = false) {
+function ownEntry(entry, expected, label, retarget = false, supervised = false) {
   if (entry === undefined || entry === null) return;
   object(entry, label);
   const script = entry.args?.[0];
-  if (!Array.isArray(entry.args) || entry.args.length !== 1 || typeof script !== "string") {
+  const managed = supervised && Array.isArray(entry.args) && entry.args.length === 2
+    && typeof script === "string" && path.basename(script) === "mcp-supervisor.mjs" && entry.args[1] === path.basename(expected);
+  if (!Array.isArray(entry.args) || !managed && entry.args.length !== 1 || typeof script !== "string") {
     throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
   }
-  if (path.resolve(script) === path.resolve(expected)) return;
+  const target = managed ? path.join(path.dirname(expected), "mcp-supervisor.mjs") : expected;
+  if (path.resolve(script) === path.resolve(target) && !managed) return;
   const source = path.dirname(script);
-  if (!retarget || !path.isAbsolute(script) || script.includes("\0") || path.basename(script) !== path.basename(expected)
-    || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge") {
+  if (!path.isAbsolute(script) || script.includes("\0") || path.resolve(script) !== path.resolve(target)
+    && (!retarget || path.basename(script) !== path.basename(target)
+      || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge")) {
     throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
   }
   const command = entry.command;
@@ -79,36 +90,41 @@ function changed(original, value) {
   return { ...original, next: text };
 }
 
-export function planAntigravityInstallation({ home = homeDir(), codeConfigDir = process.env.CLAUDE_CONFIG_DIR || home, root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, setup = false, codexExisting = null } = {}) {
+export function planAntigravityInstallation({ home = homeDir(), codeConfigDir = process.env.CLAUDE_CONFIG_DIR || home, root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, setup = false, codexExisting = null, platform = process.platform, appData = process.env.APPDATA } = {}) {
   if (!path.isAbsolute(home) || !path.isAbsolute(codeConfigDir) || !path.isAbsolute(root) || !path.isAbsolute(node)) throw new Error("Installer paths must be absolute");
   if (!targets.length || targets.some((target) => !["codex", "claude", "desktop"].includes(target))) throw new Error("Unknown installation target");
   const entry = path.join(root, "src", "antigravity-bridge.mjs");
   const sidecarEntry = path.join(root, "src", "antigravity-sidecar.mjs");
   const outboundEntry = path.join(root, "src", "antigravity-outbound-bridge.mjs");
+  const supervisorEntry = path.join(root, "src", "mcp-supervisor.mjs");
   const edits = [];
   const notices = [];
+  const runtimeCaches = new Set();
+  let backgroundPreference = null;
   const retarget = setup && !remove;
   let codex = null;
   if (targets.includes("codex")) {
     if (codexExisting && codexExisting.transport?.type !== "stdio") throw new Error("The existing Antigravity MCP transport is not stdio");
-    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget);
+    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget, true);
     const existingCaller = codexExisting?.transport?.env?.ANTIGRAVITY_BRIDGE_CALLER;
     if (existingCaller !== undefined && existingCaller !== "codex") throw new Error("The existing Codex bridge has a conflicting caller identity");
-    codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry, envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
+    codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry: supervisorEntry, entryArgs: [path.basename(entry)], envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
+    if (!remove) runtimeCaches.add(snapshotRoot({ ...process.env, ...codex.environment }));
   }
   if (targets.includes("claude")) {
     const original = snapshot(path.join(codeConfigDir, ".claude.json"));
     const value = structuredClone(original.value);
     if (value.mcpServers !== undefined) object(value.mcpServers, "Claude mcpServers");
     const existing = value.mcpServers?.[NAME];
-    ownEntry(existing, entry, "Claude Antigravity bridge", retarget);
+    ownEntry(existing, entry, "Claude Antigravity bridge", retarget, true);
     if (existing?.type !== undefined && existing.type !== "stdio") throw new Error("The existing Claude bridge transport is not stdio");
     if (existing?.env !== undefined) object(existing.env, "Claude bridge environment");
     if (existing?.env?.ANTIGRAVITY_BRIDGE_CALLER !== undefined && existing.env.ANTIGRAVITY_BRIDGE_CALLER !== "claude") throw new Error("The existing Claude bridge has a conflicting caller identity");
     if (remove) { if (existing) delete value.mcpServers[NAME]; }
     else {
       value.mcpServers ??= {};
-      value.mcpServers[NAME] = { ...existing, type: "stdio", command: node, args: [entry], env: { ...existing?.env, ANTIGRAVITY_BRIDGE_CALLER: "claude" } };
+      value.mcpServers[NAME] = { ...existing, type: "stdio", command: node, args: [supervisorEntry, path.basename(entry)], env: { ...existing?.env, ANTIGRAVITY_BRIDGE_CALLER: "claude" } };
+      runtimeCaches.add(snapshotRoot({ ...process.env, ...value.mcpServers[NAME].env }));
     }
     const edit = changed(original, value);
     if (edit) edits.push(edit);
@@ -119,7 +135,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const mcp = structuredClone(originalMcp.value);
     if (mcp.mcpServers !== undefined) object(mcp.mcpServers, "Antigravity mcpServers");
     const outbound = mcp.mcpServers?.[OUTBOUND];
-    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget);
+    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget, true);
     if (outbound?.type !== undefined && outbound.type !== "stdio" || outbound?.url !== undefined || outbound?.serverUrl !== undefined || outbound?.httpUrl !== undefined) throw new Error("The existing Antigravity outbound bridge transport is not stdio");
     if (outbound?.env !== undefined) object(outbound.env, "Antigravity outbound bridge environment");
     if (Object.keys(outbound?.env ?? {}).some((name) => /^(?:CLAUDE|CODEX_|ANTIGRAVITY_BRIDGE_CALLER$)/i.test(name))) throw new Error("The existing Antigravity outbound bridge contains a foreign caller environment; review it before installation");
@@ -129,7 +145,8 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     if (remove) { if (outbound) delete mcp.mcpServers[OUTBOUND]; }
     else {
       mcp.mcpServers ??= {};
-      mcp.mcpServers[OUTBOUND] = { ...outbound, command: node, args: [outboundEntry] };
+      mcp.mcpServers[OUTBOUND] = { ...outbound, command: node, args: [supervisorEntry, path.basename(outboundEntry)] };
+      runtimeCaches.add(snapshotRoot({ ...process.env, ...outbound?.env }));
     }
     const mcpEdit = changed(originalMcp, mcp);
     if (mcpEdit) edits.push(mcpEdit);
@@ -154,12 +171,31 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const configEdit = changed(originalConfig, config);
     if (sidecarEdit) edits.push(sidecarEdit);
     if (configEdit) edits.push(configEdit);
+    if (setup && !remove) {
+      backgroundPreference = { setting: "runInBackground", status: "unavailable", liveVerified: false };
+      if (platform !== "win32") {
+        backgroundPreference.detail = "Automatic Antigravity background preferences are not verified on this platform; native settings were preserved.";
+      } else if (typeof appData !== "string" || !path.isAbsolute(appData)) {
+        backgroundPreference.detail = "Antigravity background preferences were not applied because an absolute APPDATA path is unavailable.";
+      } else {
+        const storage = snapshot(path.join(appData, "Antigravity", "app_storage.json"), "Antigravity native preferences");
+        if (storage.text === null) {
+          backgroundPreference.detail = "Antigravity app_storage.json was not found; no native preferences file was created and background operation is unverified.";
+        } else {
+          const storageEdit = changed(storage, { ...storage.value, runInBackground: "true" });
+          if (storageEdit) edits.push(storageEdit);
+          backgroundPreference.status = storageEdit ? "planned" : "configured";
+        }
+      }
+      if (backgroundPreference.detail) notices.push(backgroundPreference.detail);
+    }
   }
-  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry };
+  if (!remove) notices.push("Running direct Antigravity MCP processes retain their current version until the host reconnects normally. Future supervised workers update automatically when quiescent.");
+  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry, supervisorEntry, runtimeCaches: [...runtimeCaches], backgroundPreference };
 }
 
 function assertCurrent(edit) {
-  const current = snapshot(edit.file);
+  const current = snapshot(edit.file, edit.jsonLabel);
   if (current.text !== edit.text || current.dev !== edit.dev || current.ino !== edit.ino) throw new Error(`Configuration changed while preparing installation: ${edit.file}`);
 }
 
@@ -180,11 +216,11 @@ export function applyJsonEdits(edits) {
         } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
       }
       completed.push(edit);
-      if (snapshot(edit.file).text !== edit.next) throw new Error(`Configuration readback did not match the saved update: ${edit.file}`);
+      if (snapshot(edit.file, edit.jsonLabel).text !== edit.next) throw new Error(`Configuration readback did not match the saved update: ${edit.file}`);
     }
   } catch (error) {
     for (const edit of completed.reverse()) {
-      if (snapshot(edit.file).text !== edit.next) continue;
+      if (snapshot(edit.file, edit.jsonLabel).text !== edit.next) continue;
       if (edit.text === null) fs.unlinkSync(edit.file);
       else fs.writeFileSync(edit.file, edit.text, { mode: edit.mode ?? 0o600 });
     }
@@ -199,7 +235,7 @@ export function installerArguments(args) {
   return { targets: args.includes("--all") || !selected.length ? ["codex", "claude", "desktop"] : selected, remove: args.includes("--remove"), dryRun: args.includes("--dry-run"), setup: args.includes("--setup"), help: args.includes("--help") };
 }
 
-export function runAntigravityInstaller(args = process.argv.slice(2)) {
+export function runAntigravityInstaller(args = process.argv.slice(2), { prepareRuntime = createReleaseSnapshot } = {}) {
   const options = installerArguments(args);
   if (options.help) {
     console.log("Usage: antigravity-mcp-bridge-install [--all|--codex|--claude|--desktop] [--remove] [--dry-run] [--setup]");
@@ -219,24 +255,30 @@ export function runAntigravityInstaller(args = process.argv.slice(2)) {
   }
   const plan = planAntigravityInstallation({ ...options, home, root, node, codexExisting });
   if (!options.remove) {
-    for (const entry of [plan.entry, ...(options.targets.includes("desktop") ? [plan.sidecarEntry, plan.outboundEntry] : [])]) {
+    for (const entry of [plan.supervisorEntry, plan.entry, ...(options.targets.includes("desktop") ? [plan.sidecarEntry, plan.outboundEntry] : [])]) {
       if (!fs.existsSync(entry)) throw new Error(`Missing bridge entrypoint: ${entry}`);
     }
   }
   if (options.dryRun) {
-    console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
+    console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, backgroundPreference: plan.backgroundPreference, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
     return plan;
   }
+  for (const cache of plan.runtimeCaches) prepareRuntime(root, { cache });
   for (const edit of plan.edits) assertCurrent(edit);
   if (plan.codex) {
     if (options.remove) { if (plan.codex.remove) run(["mcp", "remove", NAME]); }
     else applyStdioMcpRegistration({ name: NAME, registration: plan.codex, existing: codexExisting, run, configPath: path.join(process.env.CODEX_HOME ?? path.join(home, ".codex"), "config.toml") });
   }
   applyJsonEdits(plan.edits);
+  if (plan.backgroundPreference?.status === "planned") plan.backgroundPreference.status = "configured";
+  if (options.setup) {
+    console.log(JSON.stringify({ action: options.remove ? "remove" : "install", targets: plan.targets, configured: true, liveVerified: false,
+      changedFiles: plan.edits.length, notices: plan.notices, backgroundPreference: plan.backgroundPreference }));
+    return plan;
+  }
   console.log(`${options.remove ? "Removed" : "Installed"} Antigravity bridge: ${plan.targets.join(", ")}.`);
   for (const notice of plan.notices) console.log(notice);
-  if (!options.remove && options.targets.includes("desktop")) console.log("In Antigravity Customizations > Installed, find agent-bridge and choose More actions > Restart. If it is absent, reopen the App to load its new registration. In the CLI, use /mcp to reload server configurations.");
-  if (!options.remove) console.log("Reload the selected clients to load the bridge. Antigravity Desktop must launch its sidecar; installation alone does not prove a live connection. Native permissions were preserved.");
+  if (!options.remove) console.log("Bridge configuration saved; running clients and native permissions were preserved. Installation does not prove a live connection or load new settings into existing processes. This installer does not start apps or open conversations.");
   return plan;
 }