@matelink/cli 2026.4.17 → 2026.4.19

package/bin/matecli.mjs

@@ -53,6 +53,102 @@ const DEFAULT_GATEWAY_SCOPES = [
 ].join(",");
 const SESSION_CONTEXT_MIN_TOKENS = 1024;
 const CLI_ENTRY = fileURLToPath(import.meta.url);
+
+
+function buildPathString(values) {
+  const entries = [];
+  const seen = new Set();
+  for (const value of values) {
+    const raw = String(value ?? "").trim();
+    if (!raw) continue;
+    for (const part of raw.split(":")) {
+      const normalized = part.trim();
+      if (!normalized || seen.has(normalized)) continue;
+      seen.add(normalized);
+      entries.push(normalized);
+    }
+  }
+  return entries.join(":");
+}
+
+function resolveSiblingBinDirs(executablePath) {
+  const normalized = String(executablePath ?? "").trim();
+  if (!normalized) return [];
+  const binDir = path.dirname(normalized);
+  return [binDir];
+}
+
+function resolveOpenClawBinaryCandidates() {
+  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);
+      }
+    }
+  };
+
+  for (const nodeCandidate of resolveNodeCandidates()) {
+    addCandidate(path.join(path.dirname(nodeCandidate), "openclaw"));
+  }
+  addCandidate(path.join(homeDir, ".nvm", "current", "bin", "openclaw"));
+  addCandidate(path.join(homeDir, ".volta", "bin", "openclaw"));
+  addCandidate("/opt/homebrew/bin/openclaw");
+  addCandidate("/usr/local/bin/openclaw");
+  addCandidate("/usr/bin/openclaw");
+
+  const whichOpenClaw = runCommand("which", ["openclaw"]);
+  if (whichOpenClaw.status === 0) {
+    const resolved = String(whichOpenClaw.stdout ?? "").trim();
+    if (resolved && fs.existsSync(resolved)) {
+      addCandidate(resolved);
+    }
+  }
+
+  return [...candidates];
+}
+
+function resolveOpenClawBinaryPath() {
+  for (const candidate of resolveOpenClawBinaryCandidates()) {
+    if (candidate && fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return "openclaw";
+}
+
+function buildBridgeRuntimeEnv(extraEnv = {}) {
+  const homeDir = os.homedir();
+  const nodePath = resolveBridgeServiceNodePath();
+  const openclawPath = resolveOpenClawBinaryPath();
+  const pathValue = buildPathString([
+    ...resolveSiblingBinDirs(nodePath),
+    ...resolveSiblingBinDirs(openclawPath),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+    path.join(homeDir, ".volta", "bin"),
+    path.join(homeDir, ".nvm", "current", "bin"),
+    process.env.PATH ?? "",
+  ]);
+  return {
+    ...process.env,
+    ...extraEnv,
+    PATH: pathValue,
+  };
+}
 const CLI_LANGUAGE = detectCliLanguage();
 const CLI_I18N = {
   zh: {
@@ -728,6 +824,7 @@ function listFixedMemoryFiles(workspaceRoot) {
         workspaceRoot,
         relativePath,
         absolutePath,
+        includeContent: true,
       });
     });
 }
@@ -1375,6 +1472,40 @@ function extractErrorMessage(decoded, fallback) {
   return fallback;
 }
 
+function formatErrorDetails(error) {
+  if (!(error instanceof Error)) {
+    return String(error ?? "");
+  }
+  const details = [];
+  if (error.name && error.name !== "Error") {
+    details.push(`name=${error.name}`);
+  }
+  if (error.code) {
+    details.push(`code=${String(error.code)}`);
+  }
+  if (error.errno) {
+    details.push(`errno=${String(error.errno)}`);
+  }
+  if (error.type) {
+    details.push(`type=${String(error.type)}`);
+  }
+  if (error.cause && typeof error.cause === "object") {
+    const cause = error.cause;
+    if (cause?.code) {
+      details.push(`cause.code=${String(cause.code)}`);
+    }
+    if (cause?.errno) {
+      details.push(`cause.errno=${String(cause.errno)}`);
+    }
+    if (cause?.message) {
+      details.push(`cause=${String(cause.message)}`);
+    }
+  }
+  return details.length > 0
+    ? `${error.message} [${details.join(", ")}]`
+    : error.message;
+}
+
 async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_NETWORK_TIMEOUT_MS) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(new Error(`fetch timeout after ${timeoutMs}ms`)), timeoutMs);
@@ -1383,6 +1514,8 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_NETWORK_T
       ...options,
       signal: controller.signal,
     });
+  } catch (error) {
+    throw new Error(formatErrorDetails(error));
   } finally {
     clearTimeout(timer);
   }
@@ -1756,7 +1889,9 @@ function resolveBridgeServiceNodePath() {
 function writeBridgeLaunchScript(installConfig) {
   const scriptPath = resolveBridgeLaunchScriptPath();
   fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
-  const defaultPath = [
+  const defaultPath = buildPathString([
+    ...resolveSiblingBinDirs(installConfig.nodePath),
+    ...resolveSiblingBinDirs(installConfig.openclawPath),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -1765,11 +1900,16 @@ function writeBridgeLaunchScript(installConfig) {
     "/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 knownNodeCandidates = [installConfig.nodePath, ...resolveNodeCandidates()]
+    .filter(Boolean)
+    .filter((candidate, index, values) => values.indexOf(candidate) === index);
+  const candidateChecks = knownNodeCandidates.length > 0
+    ? `${knownNodeCandidates
+        .map((candidate, index) => `${index === 0 ? 'if' : 'elif'} [ -x '${escapePosixShellSingleQuoted(candidate)}' ]; then NODE_BIN='${escapePosixShellSingleQuoted(candidate)}';`)
+        .join("\n")}
+fi`
+    : "";
   const fallbackLine = buildPosixShellExec("node", installConfig.args);
   const script = [
     "#!/bin/sh",
@@ -1806,6 +1946,7 @@ function ensureBridgeServiceInstallConfig({ relayUrl, gatewayBaseUrl }) {
     stdoutLog: path.join(logDir, "bridge.stdout.log"),
     stderrLog: path.join(logDir, "bridge.stderr.log"),
     nodePath: resolveBridgeServiceNodePath(),
+    openclawPath: resolveOpenClawBinaryPath(),
     scriptPath: CLI_ENTRY,
     args: bridgeInvocationArgs({ relayUrl, gatewayBaseUrl }),
   };
@@ -2610,7 +2751,7 @@ async function readRelayNextGatewayRequest({
     if (message.includes("timeout")) {
       return null;
     }
-    throw error;
+    throw new Error(`relay gateway poll transport failed: GET ${url} -> ${message}`);
   }
 
   if (response.status === 204) {
@@ -3011,13 +3152,11 @@ function createGatewayWsClient({ gatewayBaseUrl, gatewayAuthToken }) {
           connectTimer = null;
         }
         const role = "operator";
-        const scopes = [
-          "operator.admin",
-          "operator.read",
-          "operator.write",
-          "operator.approvals",
-          "operator.pairing",
-        ];
+        // The bridge WS client only performs read-side gateway RPCs such as
+        // config.get, sessions.list, skills.status, and chat.history. Asking
+        // for broader scopes causes local token-mode gateways to reject the
+        // connection with a scope-upgrade/pairing-required error.
+        const scopes = ["operator.read"];
         const clientId = "openclaw-macos";
         const clientMode = "ui";
         const signedAtMs = Date.now();
@@ -3146,6 +3285,11 @@ async function callGatewayRpcLocal({
     return callWorkspaceRpcLocal({ method, params });
   }
 
+  if (method === "config.get" || method === "sessions.list") {
+    const client = getOrCreateGatewayWsClient({ gatewayBaseUrl, gatewayAuthToken });
+    return client.call(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 {
@@ -3172,7 +3316,10 @@ function shouldFallbackGatewayRpcViaWs(error) {
     message.includes("(1006") ||
     message.includes("no close reason") ||
     message.includes("gateway ws error") ||
-    message.includes("gateway disconnected")
+    message.includes("gateway disconnected") ||
+    message.includes("spawn openclaw enoent") ||
+    message.includes("enoent") ||
+    message.includes("gateway call timed out")
   );
 }
 
@@ -3199,8 +3346,9 @@ async function callGatewayRpcLocalViaCli({
     args.push("--token", gatewayAuthToken);
   }
 
-  const child = spawn("openclaw", args, {
+  const child = spawn(resolveOpenClawBinaryPath(), args, {
     stdio: ["ignore", "pipe", "pipe"],
+    env: buildBridgeRuntimeEnv(),
   });
   let timedOut = false;
   const timeout = setTimeout(() => {
@@ -3212,7 +3360,7 @@ async function callGatewayRpcLocalViaCli({
     }
   }, GATEWAY_RPC_CLI_TIMEOUT_MS);
 
-  const [stdoutChunks, stderrChunks] = await Promise.all([
+  const [stdoutChunks, stderrChunks, spawnError] = await Promise.all([
     new Promise((resolve) => {
       const chunks = [];
       child.stdout?.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
@@ -3225,10 +3373,18 @@ async function callGatewayRpcLocalViaCli({
       child.stderr?.on("end", () => resolve(chunks));
       child.stderr?.on("error", () => resolve(chunks));
     }),
+    new Promise((resolve) => {
+      child.once("error", (error) => resolve(error));
+      child.once("spawn", () => resolve(null));
+    }),
     new Promise((resolve) => child.on("close", resolve)),
   ]);
   clearTimeout(timeout);
 
+  if (spawnError instanceof Error) {
+    throw spawnError;
+  }
+
   const stdoutText = Buffer.concat(stdoutChunks).toString("utf8");
   const stderrText = Buffer.concat(stderrChunks).toString("utf8");
   if (timedOut) {
@@ -3453,6 +3609,11 @@ async function proxyGatewayRequestLocal({
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
 
+  // Fire-and-forget chunk publishing: don't await each POST so the reader
+  // is never blocked by network round-trips.  We keep an ordered queue of
+  // in-flight promises and drain it before sending the final "end" event.
+  const inflightChunks = [];
+
   while (true) {
     const { done, value } = await reader.read();
     if (done) {
@@ -3462,7 +3623,7 @@ async function proxyGatewayRequestLocal({
     if (!text) {
       continue;
     }
-    await publishRelayGatewayEvent({
+    const p = publishRelayGatewayEvent({
       relayUrl,
       gatewayId,
       gatewayToken,
@@ -3471,12 +3632,15 @@ async function proxyGatewayRequestLocal({
         event: "chunk",
         data: text,
       },
+    }).catch((err) => {
+      console.error(`[relay chunk publish error] ${err?.message || err}`);
     });
+    inflightChunks.push(p);
   }
 
   const tail = decoder.decode();
   if (tail) {
-    await publishRelayGatewayEvent({
+    const p = publishRelayGatewayEvent({
       relayUrl,
       gatewayId,
       gatewayToken,
@@ -3485,9 +3649,15 @@ async function proxyGatewayRequestLocal({
         event: "chunk",
         data: tail,
       },
+    }).catch((err) => {
+      console.error(`[relay tail publish error] ${err?.message || err}`);
     });
+    inflightChunks.push(p);
   }
 
+  // Wait for all chunk publishes to complete before sending "end".
+  await Promise.all(inflightChunks);
+
   await publishRelayGatewayEvent({
     relayUrl,
     gatewayId,
@@ -3629,12 +3799,12 @@ function startRelayBridgeDetached({
   }
 
   const child = spawn(
-    process.execPath,
+    resolveBridgeServiceNodePath(),
     [CLI_ENTRY, "bridge", "--relay", relayUrl, "--gateway", gatewayBaseUrl],
     {
       detached: true,
       stdio: "ignore",
-      env: { ...process.env },
+      env: buildBridgeRuntimeEnv(),
       windowsHide: process.platform === "win32",
     },
   );

package/package.json

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