xmux-bridge 1.0.41 → 1.2.0

package/README.md

@@ -151,9 +151,10 @@ shortcuts for orchestrating that runtime. The MCP command is install-scoped and
 does not pin `XMUX_PROJECT_DIR`/`XMUX_STATE_DIR`; those values come from the
 active `xmux -n <session>` lead runtime.
 
-Provider teammates write responses through `mcp/servers/bridge.js`, using the
-team runtime environment prepared by XMux. The MCP and mailbox paths are
-implementation details behind Codex-led teammate orchestration.
+Provider teammates write responses through the versioned npm `xmux-bridge`
+entrypoint, using the team runtime environment prepared by XMux. MCP and
+mailbox paths are implementation details behind Codex-led teammate
+orchestration.
 
 Users can ask for teammate work in natural language. When XMux skills are
 available in Codex, the official skill shortcuts are:

package/mcp/setup/claude.js

@@ -6,6 +6,8 @@ const os = require("node:os");
 const path = require("node:path");
 
 const SERVER_NAME = "xmux_bridge";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 const LEGACY_NAMES = new Set([
   "xmux_bridge",
   "xmux-bridge",
@@ -73,7 +75,7 @@ function atomicWriteJson(filePath, data) {
 
 function usage() {
   process.stderr.write(
-    "usage: claude.js <bridge_js> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
+    "usage: claude.js <bridge_js|npx> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
   );
 }
 
@@ -83,7 +85,8 @@ function main(argv = process.argv.slice(2)) {
     return 2;
   }
 
-  const bridgeJs = stableHomebrewXmuxFilePath(argv[0]);
+  const bridgeRef = argv[0];
+  const bridgeJs = bridgeRef === "npx" ? "" : stableHomebrewXmuxFilePath(bridgeRef);
   const projectDir = absolute(argv[1]);
   const outbox = absolute(argv[2]);
   const agent = argv[3];
@@ -116,20 +119,41 @@ function main(argv = process.argv.slice(2)) {
     delete servers[legacyName];
   }
 
-  servers[SERVER_NAME] = {
-    type: "stdio",
-    command: "node",
-    args: [bridgeJs, "--outbox", outbox, "--agent", agent, "--team", team],
-    env: {
-      XMUX_AGENT: agent,
-      XMUX_INSTALL_DIR: installDir,
-      XMUX_OUTBOX: outbox,
-      XMUX_PROJECT_DIR: projectDir,
-      XMUX_STATE_DIR: stateDir,
-      XMUX_TEAM: team,
-    },
+  const commonEnv = {
+    XMUX_AGENT: agent,
+    XMUX_INSTALL_DIR: installDir,
+    XMUX_OUTBOX: outbox,
+    XMUX_PROJECT_DIR: projectDir,
+    XMUX_STATE_DIR: stateDir,
+    XMUX_TEAM: team,
   };
 
+  if (bridgeRef === "npx") {
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
+    servers[SERVER_NAME] = {
+      type: "stdio",
+      command: "npx",
+      args: [
+        "--prefix", npxPrefix,
+        "-y",
+        "-p", packageSpec,
+        "xmux-bridge",
+        "--outbox", outbox,
+        "--agent", agent,
+        "--team", team,
+      ],
+      env: commonEnv,
+    };
+  } else {
+    servers[SERVER_NAME] = {
+      type: "stdio",
+      command: "node",
+      args: [bridgeJs, "--outbox", outbox, "--agent", agent, "--team", team],
+      env: commonEnv,
+    };
+  }
+
   atomicWriteJson(configPath, config);
   return 0;
 }

package/mcp/setup/codex.js

@@ -151,6 +151,20 @@ function package_spec_has_version(packageSpec) {
   return text.includes("@");
 }
 
+function package_name_from_spec(packageSpec) {
+  const text = String(packageSpec || "");
+  if (text.startsWith("@")) {
+    const slash = text.indexOf("/");
+    if (slash < 0) return text;
+    const scope = text.slice(0, slash);
+    const rest = text.slice(slash + 1);
+    const versionIndex = rest.indexOf("@");
+    return `${scope}/${versionIndex < 0 ? rest : rest.slice(0, versionIndex)}`;
+  }
+  const versionIndex = text.indexOf("@");
+  return versionIndex < 0 ? text : text.slice(0, versionIndex);
+}
+
 function xmux_version_from_install_dir(xmuxInstallDir) {
   const root = abs(xmuxInstallDir);
   const content = read_text(xmux_runtime_shell_path(root)) || read_text(path.join(root, "xmux.zsh"));
@@ -246,6 +260,70 @@ function ensure_mcp_runtime_dirs(mcpConfig) {
   }
 }
 
+function cached_package_root(mcpConfig) {
+  if (!mcpConfig || !mcpConfig.npx_prefix || !mcpConfig.package_spec) return "";
+  return path.join(abs(mcpConfig.npx_prefix), "node_modules", package_name_from_spec(mcpConfig.package_spec));
+}
+
+function cached_mailbox_candidates(mcpConfig) {
+  const prefix = mcpConfig && mcpConfig.npx_prefix ? abs(mcpConfig.npx_prefix) : "";
+  const root = cached_package_root(mcpConfig);
+  return [
+    prefix ? path.join(prefix, "node_modules", ".bin", "xmux-mailbox") : "",
+    root ? path.join(root, "dist", "bin", "xmux-mailbox.js") : "",
+  ].filter(Boolean);
+}
+
+function mailbox_source(xmuxInstallDir, mcpConfig) {
+  const explicit = process.env.XMUX_MAILBOX_NODE_CLI ? abs(process.env.XMUX_MAILBOX_NODE_CLI) : "";
+  if (explicit && fs.existsSync(explicit)) return { ok: true, kind: "env", label: explicit };
+
+  for (const candidate of cached_mailbox_candidates(mcpConfig)) {
+    if (fs.existsSync(candidate)) return { ok: true, kind: "npm-cache", label: candidate };
+  }
+
+  const bundled = path.join(abs(xmuxInstallDir), "dist", "bin", "xmux-mailbox.js");
+  if (fs.existsSync(bundled)) return { ok: true, kind: "brew-bundled", label: bundled };
+
+  const npx = spawnSync("npx", ["--version"], { encoding: "utf8" });
+  if (npx.status === 0 && mcpConfig && mcpConfig.mode === "npx" && mcpConfig.package_spec) {
+    return { ok: true, kind: "npx", label: `${mcpConfig.package_spec} via ${mcpConfig.npx_prefix}` };
+  }
+
+  return { ok: false, kind: "missing", label: "no mailbox CLI source found" };
+}
+
+function ensure_mcp_package_cache(mcpConfig, enabled = true) {
+  if (!enabled || !mcpConfig || mcpConfig.mode !== "npx") {
+    return { status: "skipped", message: "disabled" };
+  }
+  if (!mcpConfig.npx_prefix || !mcpConfig.package_spec) {
+    return { status: "skipped", message: "missing npx package metadata" };
+  }
+  ensure_mcp_runtime_dirs(mcpConfig);
+
+  const root = cached_package_root(mcpConfig);
+  if (root && fs.existsSync(root)) {
+    return { status: "ok", message: `using existing cache at ${root}` };
+  }
+
+  const npm = spawnSync("npm", [
+    "install",
+    "--prefix",
+    abs(mcpConfig.npx_prefix),
+    "--no-save",
+    "--omit=dev",
+    mcpConfig.package_spec,
+  ], { encoding: "utf8" });
+
+  if (npm.status === 0) {
+    return { status: "ok", message: `installed ${mcpConfig.package_spec} under ${mcpConfig.npx_prefix}` };
+  }
+
+  const detail = (npm.stderr || npm.stdout || "").trim().split(/\r?\n/).slice(-2).join(" ");
+  return { status: "failed", message: detail || `npm install exited with ${npm.status}` };
+}
+
 function build_block(mcpConfigOrServerPath, xmuxInstallDir) {
   const mcpConfig = normalize_mcp_config(mcpConfigOrServerPath, xmuxInstallDir);
   const pathEnv = resolve_path_with_node();
@@ -659,6 +737,10 @@ function doctor_codex(configPath, xmuxInstallDir, mcpConfigOrServerPath, skillsD
     notes.push(["OK", "legacy XMux plugin cache is absent"]);
   }
 
+  const mailbox = mailbox_source(xmuxInstallDir, mcpConfig);
+  if (mailbox.ok) notes.push(["OK", `mailbox source: ${mailbox.kind} (${mailbox.label})`]);
+  else issues.push(`mailbox source is unavailable: ${mailbox.label}`);
+
   const staleProcesses = stale_xmux_lead_mcp_processes(mcpConfig);
   for (const proc of staleProcesses.slice(0, 5)) {
     notes.push([
@@ -700,6 +782,7 @@ function parse_args(argv) {
     mcp_version: "",
     mcp_bin: DEFAULT_MCP_BIN,
     mcp_npx_prefix: "",
+    cache_mcp: true,
   };
   for (let i = 0; i < argv.length;) {
     const arg = argv[i];
@@ -711,6 +794,10 @@ function parse_args(argv) {
       opts.quiet = true; i += 1;
     } else if (arg === "--without-skills") {
       opts.install_skills = false; i += 1;
+    } else if (arg === "--cache-mcp") {
+      opts.cache_mcp = true; i += 1;
+    } else if (arg === "--no-cache-mcp") {
+      opts.cache_mcp = false; i += 1;
     } else if ([
       "--skills-dir",
       "--home",
@@ -774,6 +861,10 @@ function main(argv = process.argv.slice(2)) {
   }
 
   ensure_mcp_runtime_dirs(mcpConfig);
+  const cacheResult = ensure_mcp_package_cache(mcpConfig, opts.cache_mcp);
+  if (cacheResult.status === "failed") {
+    console.error(`[WARN] XMux MCP package cache failed: ${cacheResult.message}`);
+  }
 
   let content = remove_xmux_blocks(read_text(configPath));
   if (opts.remove) {
@@ -805,6 +896,8 @@ function main(argv = process.argv.slice(2)) {
 
   console.log(`[OK] Wrote ${SERVER_NAME} to ${configPath}`);
   console.log(`     mcp: ${mcpConfig.label}`);
+  if (cacheResult.status === "ok") console.log(`     mcp_cache: ${cacheResult.message}`);
+  else if (cacheResult.status === "skipped") console.log(`     mcp_cache: ${cacheResult.message}`);
   console.log(`     xmux_install_dir: ${xmuxInstallDir}`);
   console.log("     xmux_project_dir: inherited from xmux-launched Codex runtime");
   console.log("     xmux_state_dir: inherited from xmux-launched Codex runtime");
@@ -830,6 +923,7 @@ module.exports = {
   build_block,
   default_mcp_package_spec,
   default_mcp_npx_prefix,
+  mailbox_source,
   resolve_mcp_config,
   path_with_xmux_bin,
   ensure_codex_shell_environment,

package/mcp/setup/copilot.js

@@ -6,6 +6,8 @@ const os = require("node:os");
 const path = require("node:path");
 
 const SERVER_NAME = "xmux_bridge";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 const LEGACY_NAMES = new Set([
   "xmux_bridge",
   "xmux-bridge",
@@ -57,7 +59,13 @@ function main(argv = process.argv.slice(2)) {
   if (cmd.startsWith("http")) {
     servers[SERVER_NAME] = { type: "sse", url: cmd, tools: TOOLS };
   } else if (cmd === "npx") {
-    servers[SERVER_NAME] = { command: "npx", args: ["-y", "xmux-bridge"], tools: TOOLS };
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
+    servers[SERVER_NAME] = {
+      command: "npx",
+      args: ["--prefix", npxPrefix, "-y", "-p", packageSpec, "xmux-bridge"],
+      tools: TOOLS,
+    };
   } else {
     servers[SERVER_NAME] = {
       command: "node",

package/mcp/setup/gemini.js

@@ -14,7 +14,8 @@ const LEGACY_NAMES = new Set([
   "amux_bridge",
   "amux-bridge",
 ]);
-const NPM_PIN = "xmux-bridge@^1.3.0";
+const DEFAULT_NPM_PACKAGE = "xmux-bridge";
+const DEFAULT_NPX_PREFIX = path.join(os.homedir(), ".cache", "xmux", "npm-prefix");
 
 function stableHomebrewXmuxFilePath(inputPath) {
   const resolved = path.resolve(inputPath.replace(/^~(?=$|\/)/, os.homedir()));
@@ -55,9 +56,11 @@ function main(argv = process.argv.slice(2)) {
   }
 
   if (cmd === "npx") {
+    const packageSpec = process.env.XMUX_MCP_PACKAGE_SPEC || DEFAULT_NPM_PACKAGE;
+    const npxPrefix = process.env.XMUX_MCP_NPX_PREFIX || DEFAULT_NPX_PREFIX;
     servers[SERVER_NAME] = {
       command: "npx",
-      args: ["-y", NPM_PIN],
+      args: ["--prefix", npxPrefix, "-y", "-p", packageSpec, "xmux-bridge"],
       trust: true,
     };
   } else {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "xmux-bridge",
-  "version": "1.0.41",
+  "version": "1.2.0",
   "description": "MCP bridge and lead server package for XMux",
   "bin": {
-    "xmux-lead-mcp": "./mcp/servers/lead.js",
-    "xmux-bridge": "./mcp/servers/bridge.js",
-    "xmux-mailbox": "./dist/bin/xmux-mailbox.js"
+    "xmux-lead-mcp": "mcp/servers/lead.js",
+    "xmux-bridge": "mcp/servers/bridge.js",
+    "xmux-mailbox": "dist/bin/xmux-mailbox.js"
   },
   "files": [
     "mcp/servers",
@@ -27,6 +27,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DwvN-Lee/XMux.git"
+    "url": "git+https://github.com/DwvN-Lee/XMux.git"
   }
 }