@matelink/cli 2026.4.11 → 2026.4.13

package/bin/matecli.mjs

@@ -440,6 +440,10 @@ function resolveBridgeLogsDir() {
   return path.join(resolveMatecliRuntimeDir(), "logs");
 }
 
+function resolveBridgeLaunchScriptPath() {
+  return path.join(resolveMatecliRuntimeDir(), "bridge-launch.sh");
+}
+
 function resolveMacLaunchAgentPath() {
   return path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
 }
@@ -1247,6 +1251,127 @@ function bridgeInvocationArgs({ relayUrl, gatewayBaseUrl }) {
   return [CLI_ENTRY, "bridge", "--relay", relayUrl, "--gateway", gatewayBaseUrl];
 }
 
+function escapePosixShellSingleQuoted(value) {
+  return String(value ?? "").replaceAll("'", "'\"'\"'");
+}
+
+function buildPosixShellExec(command, args) {
+  return [command, ...args]
+    .map((part) => `'${escapePosixShellSingleQuoted(part)}'`)
+    .join(" ");
+}
+
+function resolveNodeCandidates() {
+  const homeDir = os.homedir();
+  const candidates = new Set();
+  const addCandidate = (candidate) => {
+    const normalized = String(candidate ?? "").trim();
+    if (!normalized) {
+      return;
+    }
+    try {
+      if (fs.existsSync(normalized)) {
+        candidates.add(fs.realpathSync(normalized));
+      }
+    } catch {
+      if (fs.existsSync(normalized)) {
+        candidates.add(normalized);
+      }
+    }
+  };
+
+  addCandidate(process.execPath);
+  addCandidate(path.join(homeDir, ".nvm", "current", "bin", "node"));
+  addCandidate(path.join(homeDir, ".volta", "bin", "node"));
+  addCandidate("/opt/homebrew/bin/node");
+  addCandidate("/usr/local/bin/node");
+  addCandidate("/usr/bin/node");
+
+  const nvmVersionsDir = path.join(homeDir, ".nvm", "versions", "node");
+  try {
+    const nvmEntries = fs
+      .readdirSync(nvmVersionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }));
+    for (const version of nvmEntries) {
+      addCandidate(path.join(nvmVersionsDir, version, "bin", "node"));
+    }
+  } catch {}
+
+  const localNodeRoots = [
+    path.join(homeDir, ".local"),
+    path.join(homeDir, ".local", "node"),
+  ];
+  for (const root of localNodeRoots) {
+    try {
+      const entries = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith("node-"))
+        .map((entry) => entry.name)
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }));
+      for (const name of entries) {
+        addCandidate(path.join(root, name, "bin", "node"));
+      }
+    } catch {}
+  }
+
+  return [...candidates];
+}
+
+function resolveBridgeServiceNodePath() {
+  for (const candidate of resolveNodeCandidates()) {
+    if (candidate && fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  const whichNode = runCommand("which", ["node"]);
+  if (whichNode.status === 0) {
+    const resolved = String(whichNode.stdout ?? "").trim();
+    if (resolved && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  fail("node runtime is required for bridge service install");
+}
+
+function writeBridgeLaunchScript(installConfig) {
+  const scriptPath = resolveBridgeLaunchScriptPath();
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  const defaultPath = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+    path.join(os.homedir(), ".volta", "bin"),
+    path.join(os.homedir(), ".nvm", "current", "bin"),
+  ].join(":");
+  const knownNodeCandidates = resolveNodeCandidates();
+  const candidateChecks = knownNodeCandidates
+    .map((candidate) => `if [ -x '${escapePosixShellSingleQuoted(candidate)}' ]; then NODE_BIN='${escapePosixShellSingleQuoted(candidate)}'; fi`)
+    .join("\n");
+  const fallbackLine = buildPosixShellExec("node", installConfig.args);
+  const script = [
+    "#!/bin/sh",
+    "set -eu",
+    "export PATH='" + escapePosixShellSingleQuoted(defaultPath) + ":'\"${PATH:-}\"",
+    "NODE_BIN=''",
+    candidateChecks,
+    "if [ -z \"$NODE_BIN\" ] && command -v node >/dev/null 2>&1; then",
+    "  NODE_BIN=\"$(command -v node)\"",
+    "fi",
+    "if [ -n \"$NODE_BIN\" ]; then",
+    `  exec "$NODE_BIN" ${installConfig.args.map((arg) => `'${escapePosixShellSingleQuoted(arg)}'`).join(" ")}`,
+    "fi",
+    `exec ${fallbackLine}`,
+    "",
+  ].join("\n");
+  fs.writeFileSync(scriptPath, script, { encoding: "utf8", mode: 0o755 });
+  return scriptPath;
+}
+
 function ensureBridgeServiceInstallConfig({ relayUrl, gatewayBaseUrl }) {
   if (!relayUrl) {
     fail("relay URL is required for bridge service");
@@ -1262,17 +1387,72 @@ function ensureBridgeServiceInstallConfig({ relayUrl, gatewayBaseUrl }) {
     logDir,
     stdoutLog: path.join(logDir, "bridge.stdout.log"),
     stderrLog: path.join(logDir, "bridge.stderr.log"),
-    nodePath: process.execPath,
+    nodePath: resolveBridgeServiceNodePath(),
     scriptPath: CLI_ENTRY,
     args: bridgeInvocationArgs({ relayUrl, gatewayBaseUrl }),
   };
 }
 
+function escapeXmlText(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function readMacLaunchdServiceStatus(uid, plistPath) {
+  const refs = uid == null ? [] : [`gui/${uid}/${SERVICE_LABEL}`, `user/${uid}/${SERVICE_LABEL}`];
+  for (const ref of refs) {
+    const result = runCommand("launchctl", ["print", ref]);
+    if (result.status !== 0) {
+      continue;
+    }
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    const stateMatch = output.match(/state = ([^\n]+)/u);
+    const activeCountMatch = output.match(/active count = (\d+)/u);
+    const pidMatch = output.match(/\bpid = (\d+)/u);
+    const exitCodeMatch = output.match(/last exit code = (\d+)/u);
+    const state = stateMatch?.[1]?.trim() ?? "";
+    const activeCount = Number.parseInt(activeCountMatch?.[1] ?? "0", 10) || 0;
+    const pid = Number.parseInt(pidMatch?.[1] ?? "0", 10) || 0;
+    const lastExitCode = Number.parseInt(exitCodeMatch?.[1] ?? "0", 10) || 0;
+    const running =
+      state.toLowerCase() === "running" ||
+      activeCount > 0 ||
+      (pid > 0 && isPidAlive(pid));
+    return {
+      manager: "launchd",
+      installed: true,
+      running,
+      target: plistPath,
+      logDir: resolveBridgeLogsDir(),
+      ref,
+      state,
+      activeCount,
+      pid: pid || null,
+      lastExitCode,
+    };
+  }
+  return {
+    manager: "launchd",
+    installed: fs.existsSync(plistPath),
+    running: false,
+    target: plistPath,
+    logDir: resolveBridgeLogsDir(),
+    ref: SERVICE_LABEL,
+    state: "not-loaded",
+    activeCount: 0,
+    pid: null,
+    lastExitCode: 0,
+  };
+}
+
 function installBridgeServiceMac(installConfig) {
   const plistPath = resolveMacLaunchAgentPath();
+  const launchScriptPath = writeBridgeLaunchScript(installConfig);
   fs.mkdirSync(path.dirname(plistPath), { recursive: true });
-  const argsXml = installConfig.args
-    .map((arg) => `    <string>${String(arg).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</string>`)
+  const argsXml = [launchScriptPath]
+    .map((arg) => `    <string>${escapeXmlText(arg)}</string>`)
     .join("\n");
   const plist = [
     "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
@@ -1315,6 +1495,13 @@ function installBridgeServiceMac(installConfig) {
     }
     selectedDomain = "launchd";
   }
+  const status = readMacLaunchdServiceStatus(uid, plistPath);
+  if (!status.running) {
+    const details = status.lastExitCode
+      ? `launchd last exit code: ${status.lastExitCode}`
+      : "launchd service failed to stay running";
+    throw new Error(details);
+  }
   return {
     manager: "launchd",
     installed: true,
@@ -1409,6 +1596,7 @@ function installBridgeService({ relayUrl, gatewayBaseUrl }) {
 function uninstallBridgeService() {
   if (process.platform === "darwin") {
     const plistPath = resolveMacLaunchAgentPath();
+    const launchScriptPath = resolveBridgeLaunchScriptPath();
     const uid = typeof process.getuid === "function" ? process.getuid() : null;
     if (uid != null) {
       runCommand("launchctl", ["bootout", `gui/${uid}`, plistPath]);
@@ -1417,6 +1605,9 @@ function uninstallBridgeService() {
     try {
       fs.unlinkSync(plistPath);
     } catch {}
+    try {
+      fs.unlinkSync(launchScriptPath);
+    } catch {}
     return { manager: "launchd", installed: false, running: false, target: plistPath, logDir: resolveBridgeLogsDir() };
   }
   if (process.platform === "linux") {
@@ -1435,23 +1626,56 @@ function uninstallBridgeService() {
   throw new Error(`unsupported platform for service uninstall: ${process.platform}`);
 }
 
+function stopBridgeService() {
+  if (process.platform === "darwin") {
+    const plistPath = resolveMacLaunchAgentPath();
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid != null) {
+      runCommand("launchctl", ["bootout", `gui/${uid}`, plistPath]);
+      runCommand("launchctl", ["bootout", `user/${uid}`, plistPath]);
+    }
+    return {
+      manager: "launchd",
+      installed: fs.existsSync(plistPath),
+      running: false,
+      target: plistPath,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  if (process.platform === "linux") {
+    const unitPath = resolveLinuxUserUnitPath();
+    runCommand("systemctl", ["--user", "stop", SERVICE_UNIT_NAME]);
+    return {
+      manager: "systemd-user",
+      installed: fs.existsSync(unitPath),
+      running: false,
+      target: unitPath,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  if (process.platform === "win32") {
+    runCommand("powershell.exe", ["-NoProfile", "-Command", `Stop-ScheduledTask -TaskName '${SERVICE_TASK_NAME}' -ErrorAction SilentlyContinue`]);
+    return {
+      manager: "task-scheduler",
+      installed: true,
+      running: false,
+      target: SERVICE_TASK_NAME,
+      logDir: resolveBridgeLogsDir(),
+    };
+  }
+  return { manager: process.platform, installed: false, running: false, target: null, logDir: resolveBridgeLogsDir() };
+}
+
 function restartBridgeService({ relayUrl, gatewayBaseUrl }) {
-  const installed = installBridgeService({ relayUrl, gatewayBaseUrl });
-  return installed;
+  stopBridgeService();
+  return installBridgeService({ relayUrl, gatewayBaseUrl });
 }
 
 function getBridgeServiceStatus() {
   if (process.platform === "darwin") {
     const plistPath = resolveMacLaunchAgentPath();
     const uid = typeof process.getuid === "function" ? process.getuid() : null;
-    const refs = uid == null ? [] : [`gui/${uid}/${SERVICE_LABEL}`, `user/${uid}/${SERVICE_LABEL}`];
-    for (const ref of refs) {
-      const result = runCommand("launchctl", ["print", ref]);
-      if (result.status === 0) {
-        return { manager: "launchd", installed: true, running: true, target: plistPath, logDir: resolveBridgeLogsDir(), ref };
-      }
-    }
-    return { manager: "launchd", installed: fs.existsSync(plistPath), running: false, target: plistPath, logDir: resolveBridgeLogsDir(), ref: SERVICE_LABEL };
+    return readMacLaunchdServiceStatus(uid, plistPath);
   }
   if (process.platform === "linux") {
     const enabled = runCommand("systemctl", ["--user", "is-enabled", SERVICE_UNIT_NAME]);
@@ -1541,6 +1765,29 @@ function stopBridgeProcesses({ relayUrl, gatewayBaseUrl }) {
   };
 }
 
+function clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl }) {
+  const serviceStatus = getBridgeServiceStatus();
+  let serviceStopped = null;
+  if (serviceStatus.installed) {
+    try {
+      serviceStopped = stopBridgeService();
+    } catch (error) {
+      serviceStopped = {
+        error: String(error instanceof Error ? error.message : error),
+      };
+    }
+  }
+  const stoppedProcesses =
+    relayUrl && gatewayBaseUrl
+      ? stopBridgeProcesses({ relayUrl, gatewayBaseUrl })
+      : { count: 0, pids: [] };
+  return {
+    serviceStatus,
+    serviceStopped,
+    stoppedProcesses,
+  };
+}
+
 function resolvePublishedGatewayBaseUrl({
   relayUrl,
   bindPublicBaseUrl,
@@ -2462,9 +2709,34 @@ async function callGatewayRpcLocal({
     };
   }
 
-  // In bridge mode the CLI path is more reliable than the shared WebSocket client,
-  // especially while long-running streamed chats are also active.
-  return callGatewayRpcLocalViaCli({ gatewayBaseUrl, gatewayAuthToken, method, params });
+  // Prefer CLI first for broad compatibility, but fall back to the persistent
+  // WS client when the CLI gateway call hits transient websocket closures.
+  try {
+    return await callGatewayRpcLocalViaCli({
+      gatewayBaseUrl,
+      gatewayAuthToken,
+      method,
+      params,
+    });
+  } catch (error) {
+    if (!shouldFallbackGatewayRpcViaWs(error)) {
+      throw error;
+    }
+    const client = getOrCreateGatewayWsClient({ gatewayBaseUrl, gatewayAuthToken });
+    return client.call(method, params ?? {});
+  }
+}
+
+function shouldFallbackGatewayRpcViaWs(error) {
+  const message = String(error instanceof Error ? error.message : error).toLowerCase();
+  return (
+    message.includes("gateway closed") ||
+    message.includes("abnormal closure") ||
+    message.includes("(1006") ||
+    message.includes("no close reason") ||
+    message.includes("gateway ws error") ||
+    message.includes("gateway disconnected")
+  );
 }
 
 async function callGatewayRpcLocalViaCli({
@@ -2480,6 +2752,8 @@ async function callGatewayRpcLocalViaCli({
     method,
     "--url",
     wsUrl,
+    "--timeout",
+    String(GATEWAY_RPC_CLI_TIMEOUT_MS),
     "--params",
     JSON.stringify(params ?? {}),
     "--json",
@@ -3162,11 +3436,24 @@ async function runPair({
     publishedGatewayBaseUrl,
     gatewayRestarted: Boolean(restartResult?.ok),
     relayGatewayId: relayCredentials?.gatewayId ?? null,
+    bridgeCleanup: null,
   };
 
   if (serveRelay && !json) {
+    const bridgeCleanup = clearExistingBridgeRuntime({
+      relayUrl,
+      gatewayBaseUrl: localGatewayBaseUrl,
+    });
+    output.bridgeCleanup = {
+      serviceInstalled: bridgeCleanup.serviceStatus?.installed === true,
+      serviceRunning: bridgeCleanup.serviceStatus?.running === true,
+      serviceStopError: bridgeCleanup.serviceStopped?.error ?? null,
+      stoppedProcessCount: bridgeCleanup.stoppedProcesses?.count ?? 0,
+      stoppedPids: bridgeCleanup.stoppedProcesses?.pids ?? [],
+    };
     try {
-      const serviceResult = installBridgeService({
+      const serviceStatus = getBridgeServiceStatus();
+      const serviceResult = (serviceStatus.installed ? restartBridgeService : installBridgeService)({
         relayUrl,
         gatewayBaseUrl: localGatewayBaseUrl,
       });
@@ -3240,10 +3527,6 @@ async function runReset({ json, relay, noRelay, gateway }) {
     });
   }
 
-  const stoppedBridges =
-    relayUrl && gatewayBaseUrl
-      ? stopBridgeProcesses({ relayUrl, gatewayBaseUrl })
-      : { count: 0, pids: [] };
   let serviceReset = null;
   if (relayUrl && gatewayBaseUrl) {
     try {
@@ -3252,6 +3535,10 @@ async function runReset({ json, relay, noRelay, gateway }) {
       serviceReset = { error: String(error instanceof Error ? error.message : error) };
     }
   }
+  const stoppedBridges =
+    relayUrl && gatewayBaseUrl
+      ? stopBridgeProcesses({ relayUrl, gatewayBaseUrl })
+      : { count: 0, pids: [] };
   const nextState = resetLocalBindingState({ accountId });
 
   const output = {
@@ -3324,9 +3611,11 @@ async function runService({ json, relay, noRelay, gateway, serviceAction }) {
       result = getBridgeServiceStatus();
       break;
     case "install":
+      clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl });
       result = installBridgeService({ relayUrl, gatewayBaseUrl });
       break;
     case "restart":
+      clearExistingBridgeRuntime({ relayUrl, gatewayBaseUrl });
       result = restartBridgeService({ relayUrl, gatewayBaseUrl });
       break;
     case "uninstall":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matelink/cli",
-  "version": "2026.4.11",
+  "version": "2026.4.13",
   "private": false,
   "description": "Relay-first CLI for pairing and bridging OpenClaw gateway traffic",
   "type": "module",