@beeos-ai/cli 1.0.19 → 1.0.21

package/dist/index.js

@@ -761,18 +761,22 @@ function buildBindUrl(dashboardBaseUrl, bindId) {
   const base = dashboardBaseUrl.replace(/\/+$/, "");
   return `${base}/bind/${bindId}`;
 }
-async function agentBind(apiUrl, publicKey, fingerprint2, agentFramework, hostname) {
+async function agentBind(apiUrl, publicKey, fingerprint2, agentFramework, hostname, osType) {
   const p = getPlatformAdapter();
   const url = `${apiUrl}/api/v1/agent/bind`;
+  const body = {
+    public_key: publicKey,
+    fingerprint: fingerprint2,
+    agent_framework: agentFramework,
+    hostname
+  };
+  if (osType && osType.length > 0) {
+    body.os_type = osType;
+  }
   const resp = await p.fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      public_key: publicKey,
-      fingerprint: fingerprint2,
-      agent_framework: agentFramework,
-      hostname
-    })
+    body: JSON.stringify(body)
   });
   if (!resp.ok) {
     throw await bindHttpError(resp, "bind");
@@ -925,7 +929,7 @@ async function bindAgent(opts) {
   const pollTimeoutMs = opts.pollTimeoutMs ?? 6e5;
   let resp;
   try {
-    resp = await agentBind(opts.apiUrl, opts.publicKey, opts.fingerprint, opts.agentFramework, opts.hostname);
+    resp = await agentBind(opts.apiUrl, opts.publicKey, opts.fingerprint, opts.agentFramework, opts.hostname, opts.osType);
   } catch (e) {
     if (isNetworkError(e) && opts.cachedBinding && opts.cachedBinding.fingerprint === opts.fingerprint) {
       return {
@@ -2047,13 +2051,34 @@ var init_vnc_bridge = __esm({
        * Build the environment map used when launching vnc-bridge for a
        * device. Exposed separately so the service target-spec builder
        * can reuse the same logic without duplicating it.
+       *
+       * Env-var names are aligned with the **vnc-bridge 0.3.6** clap
+       * definitions (`devices/vnc-bridge/src/main.rs`):
+       *
+       *     --vnc       env: VNC_ADDR=host:port      (combined, NOT VNC_HOST/VNC_PORT)
+       *     --gateway   env: AGENT_GATEWAY_URL
+       *     --key-file  env: AGENT_KEY_FILE          (single combined key, NOT BRIDGE_PRIVATE/PUBLIC)
+       *     --mqtt      env: MQTT_BROKER_URL         (static mode only)
+       *     --topic     env: DEVICE_TOPIC            (static mode only)
+       *
+       * Pre-1.0.21 we shipped the older naming (VNC_HOST + VNC_PORT,
+       * BRIDGE_PRIVATE_KEY_FILE etc.) which the binary silently ignored,
+       * causing it to bail out with `Error: Either --gateway + --key-file
+       * (bootstrap mode) or --mqtt + --topic (static mode) is required`
+       * at every restart. The legacy fields are retained alongside the
+       * new ones so any older Rust build that did read them still works.
        */
       buildEnv(opts) {
+        const vncPort = opts.vncPort ?? 5900;
         return {
+          // ── vnc-bridge 0.3.6 canonical env vars ────────────────
+          VNC_ADDR: `${opts.vncHost}:${vncPort}`,
+          AGENT_GATEWAY_URL: opts.agentGatewayUrl,
+          AGENT_KEY_FILE: opts.bridgePrivateKeyFile,
+          // ── Legacy names (pre-0.3.6 / future-compat / forensic) ─
           DEVICE_ID: opts.deviceId,
           VNC_HOST: opts.vncHost,
-          VNC_PORT: String(opts.vncPort ?? 5900),
-          AGENT_GATEWAY_URL: opts.agentGatewayUrl,
+          VNC_PORT: String(vncPort),
           BRIDGE_PRIVATE_KEY_FILE: opts.bridgePrivateKeyFile,
           BRIDGE_PUBLIC_KEY_FILE: opts.bridgePublicKeyFile,
           LOG_FORMAT: "json",
@@ -3244,6 +3269,74 @@ var init_agent_status = __esm({
   }
 });
 
+// ../core/dist/openclaw/desktop-detect.js
+function printMacosDesktopHint() {
+  for (const line of MACOS_DESKTOP_HINT_LINES)
+    console.log(line);
+}
+function readEnv(name) {
+  return globalThis.process?.env?.[name];
+}
+async function probeLocalVnc(opts = {}) {
+  if (readEnv("BEEOS_NO_DESKTOP") === "1")
+    return null;
+  const p = getPlatformAdapter();
+  const platform = p.platform();
+  if (platform !== "darwin" && platform !== "linux") {
+    return null;
+  }
+  const host = "127.0.0.1";
+  const timeoutMs = 200;
+  if (platform === "darwin") {
+    const ok2 = await p.tcpProbe(host, 5900, timeoutMs).catch(() => false);
+    if (ok2) {
+      return { kind: "macos", host, port: 5900, osType: "macos-desktop" };
+    }
+    return null;
+  }
+  const ok = await p.tcpProbe(host, 5901, timeoutMs).catch(() => false);
+  if (ok) {
+    return { kind: "linux", host, port: 5901, osType: "linux-desktop" };
+  }
+  if (opts.ttyHints) {
+    for (const line of LINUX_VNC_HINT_LINES)
+      console.log(line);
+  }
+  return null;
+}
+var MACOS_DESKTOP_HINT_LINES, MACOS_DESKTOP_DOCTOR_HINT_LINES, LINUX_VNC_HINT_LINES;
+var init_desktop_detect = __esm({
+  "../core/dist/openclaw/desktop-detect.js"() {
+    "use strict";
+    init_platform_adapter();
+    MACOS_DESKTOP_HINT_LINES = [
+      "Detected macOS Screen Sharing on :5900. Starting vnc-bridge...",
+      "  If desktop view shows a black screen / connection error on the dashboard:",
+      "    \u2022 System Settings \u2192 General \u2192 Sharing \u2192 Screen Sharing must be enabled",
+      "    \u2022 System Settings \u2192 Privacy & Security \u2192 Screen Recording must grant",
+      "      permission to the macOS Screen Sharing process",
+      "    \u2022 If a VNC password was set, export BEEOS_VNC_PASSWORD=<password>",
+      "      before re-running `beeos init`."
+    ];
+    MACOS_DESKTOP_DOCTOR_HINT_LINES = [
+      "vnc-bridge-openclaw is failing on macOS. Likely causes:",
+      "  \u2022 System Settings \u2192 General \u2192 Sharing \u2192 Screen Sharing turned off",
+      "  \u2022 System Settings \u2192 Privacy & Security \u2192 Screen Recording missing",
+      "    permission for the macOS Screen Sharing process",
+      "  \u2022 A VNC password is set; export BEEOS_VNC_PASSWORD=<password>",
+      "    before `beeos start openclaw --force` to retry."
+    ];
+    LINUX_VNC_HINT_LINES = [
+      "Tip: no VNC server detected on :5901. To enable BeeOS desktop streaming:",
+      "  Debian/Ubuntu:  sudo apt install tigervnc-standalone-server",
+      "  RHEL/Fedora:    sudo dnf install tigervnc-server",
+      "  Arch:           sudo pacman -S tigervnc",
+      "Then run `vncserver :1` and re-run `beeos start openclaw`.",
+      "Set BEEOS_NO_DESKTOP=1 to suppress this hint."
+    ];
+  }
+});
+
 // ../core/dist/detect.js
 async function detectExistingInstall() {
   const p = getPlatformAdapter();
@@ -3486,12 +3579,20 @@ function buildVncBridgeTargetSpec(binary, opts) {
     label: `vnc-bridge (${opts.serial})`
   };
 }
+function buildOpenclawDesktopVncBridgeSpec(binary, opts) {
+  return buildVncBridgeTargetSpec(binary, {
+    ...opts,
+    serial: OPENCLAW_VNC_BRIDGE_SERIAL
+  });
+}
+var OPENCLAW_VNC_BRIDGE_SERIAL;
 var init_target_spec = __esm({
   "../core/dist/services/target-spec.js"() {
     "use strict";
     init_scrcpy_bridge();
     init_vnc_bridge();
     init_spawn_env2();
+    OPENCLAW_VNC_BRIDGE_SERIAL = "openclaw";
   }
 });
 
@@ -4992,7 +5093,7 @@ function getCliVersion(moduleUrl, distTag) {
   return { version, distTag: safeTag, display };
 }
 function resolveActiveDistTag() {
-  const envTag = readEnv("BEEOS_CLI_TAG");
+  const envTag = readEnv2("BEEOS_CLI_TAG");
   if (envTag && envTag.trim())
     return envTag.trim();
   const baked = readBakedDistTag();
@@ -5000,7 +5101,7 @@ function resolveActiveDistTag() {
     return baked.trim();
   return "latest";
 }
-function readEnv(key) {
+function readEnv2(key) {
   const env = globalThis.process?.env;
   return env?.[key];
 }
@@ -5090,6 +5191,7 @@ var init_dist = __esm({
     init_driver2();
     init_constants();
     init_agent_status();
+    init_desktop_detect();
     init_detect();
     init_registry();
     init_target_spec();
@@ -6783,8 +6885,10 @@ async function run(agentFramework, options) {
   };
   const launchOutcome = await driver.launch(ctx, reporter);
   const spec = launchOutcome.spec;
-  const launchWarnings = launchOutcome.warnings;
+  const launchWarnings = [...launchOutcome.warnings];
   reporter.stop();
+  const ttyHints = !options.json && process.stdin.isTTY === true;
+  const vncEndpoint = agentFramework === OPENCLAW_ID ? await probeLocalVnc({ ttyHints }) : null;
   const hostname = buildHostname();
   const cachedBinding = await loadBindingInfo();
   const outcome = await bindAgent({
@@ -6794,6 +6898,7 @@ async function run(agentFramework, options) {
     fingerprint: fp,
     agentFramework,
     hostname,
+    osType: vncEndpoint?.osType,
     headless: options.browser === false,
     cachedBinding: cachedBinding ? {
       fingerprint: cachedBinding.fingerprint,
@@ -6898,6 +7003,19 @@ async function run(agentFramework, options) {
       });
     }
   }
+  if (vncEndpoint && !isOffline) {
+    if (vncEndpoint.kind === "macos" && ttyHints) {
+      printMacosDesktopHint();
+    }
+    const desktopWarning = await tryAttachOpenclawDesktopBridge({
+      vncEndpoint,
+      instanceId: boundInstanceId,
+      keyFile,
+      agentGatewayUrl,
+      mgr
+    });
+    if (desktopWarning) launchWarnings.push(desktopWarning);
+  }
   const gatewayPid = status2.pid ?? void 0;
   emit(options.json, {
     status: isOffline ? "bound_offline" : "bound",
@@ -6910,6 +7028,36 @@ async function run(agentFramework, options) {
   }, isOffline ? `Agent running (offline, cached instance: ${boundInstanceId})` : `Agent bound to instance: ${boundInstanceId}`);
   if (!options.json) printLaunchWarnings(launchWarnings);
 }
+async function tryAttachOpenclawDesktopBridge(params) {
+  const reporter = new CliReporter();
+  let binary = null;
+  try {
+    binary = await vncBridgeRuntime.ensureInstalled(reporter);
+  } catch (e) {
+    reporter.stop();
+    const reason = e instanceof Error ? e.message : String(e);
+    return `vnc-bridge install failed: ${reason}; OpenClaw is bound but desktop streaming is unavailable.`;
+  }
+  reporter.stop();
+  if (!binary) {
+    return `vnc-bridge binary unavailable (download or PATH lookup failed); OpenClaw is bound but desktop streaming is unavailable. Set BEEOS_VNC_BRIDGE_BIN to override.`;
+  }
+  const spec = buildOpenclawDesktopVncBridgeSpec(binary, {
+    deviceId: params.instanceId,
+    vncHost: params.vncEndpoint.host,
+    vncPort: params.vncEndpoint.port,
+    agentGatewayUrl: params.agentGatewayUrl,
+    bridgePrivateKeyFile: params.keyFile,
+    bridgePublicKeyFile: params.keyFile
+  });
+  try {
+    await params.mgr.install(spec);
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    return `vnc-bridge service install failed: ${reason}; OpenClaw is bound but desktop streaming is unavailable. Re-run \`beeos start openclaw --force\` to retry.`;
+  }
+  return null;
+}
 function buildHostname() {
   const machine = os6.hostname();
   const user = process.env.USER || process.env.USERNAME || "";
@@ -7538,6 +7686,17 @@ async function run8(options) {
           `service '${s.id}' looks like its Node binary moved (exit 127). Re-run \`beeos start ${s.id} --force\` to refresh the service definition with the current node path.`
         );
       }
+      if (s.id === `vnc-bridge-${OPENCLAW_VNC_BRIDGE_SERIAL}`) {
+        if (process.platform === "darwin") {
+          for (const line of MACOS_DESKTOP_DOCTOR_HINT_LINES) {
+            hints.push(line);
+          }
+        } else {
+          hints.push(
+            `vnc-bridge-${OPENCLAW_VNC_BRIDGE_SERIAL} is failing \u2014 see ${s.logFile} for the underlying error. Common causes: VNC server moved port, BEEOS_VNC_PASSWORD missing/incorrect, network blocking outbound MQTT.`
+          );
+        }
+      }
     }
   }
   if (!tools.adb.path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeos-ai/cli",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "type": "module",
   "description": "BeeOS CLI — run AI agents from your desktop",
   "bin": {