openclaw-navigator 4.3.8 → 4.4.0

package/cli.mjs

@@ -17,6 +17,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createServer, request as httpRequest } from "node:http";
+import { connect as netConnect } from "node:net";
 import { networkInterfaces, hostname, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -58,6 +59,12 @@ const validTokens = new Set();
 // OC Web UI reverse proxy target (configurable via --ui-port or env)
 let ocUIPort = parseInt(process.env.OPENCLAW_UI_PORT ?? "4000", 10);
 
+// OC Gateway port — where sessions API + WebSocket live (separate from web UI)
+let ocGatewayPort = parseInt(process.env.OPENCLAW_GATEWAY_PORT ?? "18789", 10);
+
+// Bridge port — set in main(), exposed for status endpoint
+let bridgePort = 18790;
+
 // Tunnel URL — set once the tunnel is active, exposed via /navigator/status
 let activeTunnelURL = null;
 
@@ -220,10 +227,24 @@ function handleRequest(req, res) {
         pendingCommandCount: pendingCommands.length,
         recentEventCount: recentEvents.length,
       },
-      tunnel: activeTunnelURL ? {
-        url: activeTunnelURL,
-        uiURL: `${activeTunnelURL}/ui/`,
-      } : null,
+      ports: {
+        bridge: bridgePort,
+        ui: ocUIPort,
+        gateway: ocGatewayPort,
+      },
+      routing: {
+        "/ui/*": `localhost:${ocUIPort}`,
+        "/api/*": `localhost:${ocGatewayPort}`,
+        "/ws": `localhost:${ocGatewayPort}`,
+      },
+      tunnel: activeTunnelURL
+        ? {
+            url: activeTunnelURL,
+            uiURL: `${activeTunnelURL}/ui/`,
+            apiURL: `${activeTunnelURL}/api/`,
+            wsURL: `${activeTunnelURL.replace("https://", "wss://")}/ws`,
+          }
+        : null,
     });
     return;
   }
@@ -454,7 +475,7 @@ function handleRequest(req, res) {
 
   // ── Health check ──
   if (req.method === "GET" && path === "/health") {
-    sendJSON(res, 200, { ok: true, service: "openclaw-navigator-bridge", version: "4.3.4" });
+    sendJSON(res, 200, { ok: true, service: "openclaw-navigator-bridge", version: "4.4.0" });
     return;
   }
 
@@ -490,7 +511,7 @@ function handleRequest(req, res) {
         ok: false,
         error: `OC Web UI not reachable on port ${ocUIPort}`,
         detail: err.message,
-        hint: "Make sure the OC gateway is running (openclaw gateway start)",
+        hint: `Not found — Reverse proxy rule for /ui/* → localhost:${ocUIPort} is working, but the web UI is not running. Start it with: openclaw gateway start`,
       });
     });
 
@@ -499,16 +520,70 @@ function handleRequest(req, res) {
     return;
   }
 
-  // ── Root → redirect to /ui/ if OC Web UI is available ──
+  // ── Reverse proxy: /api/* → OC Gateway (localhost:ocGatewayPort) ─────
+  // Keeps /api/ prefix intact so /api/sessions/send → localhost:18789/api/sessions/send
+  if (path.startsWith("/api/")) {
+    const targetURL = `${path}${url.search}`;
+
+    const proxyOpts = {
+      hostname: "127.0.0.1",
+      port: ocGatewayPort,
+      path: targetURL,
+      method: req.method,
+      headers: {
+        ...req.headers,
+        host: `127.0.0.1:${ocGatewayPort}`,
+      },
+    };
+
+    const proxyReq = httpRequest(proxyOpts, (proxyRes) => {
+      const headers = { ...proxyRes.headers };
+      headers["access-control-allow-origin"] = "*";
+      headers["access-control-allow-methods"] = "GET, POST, PUT, DELETE, OPTIONS";
+      headers["access-control-allow-headers"] = "Content-Type, Authorization";
+      res.writeHead(proxyRes.statusCode ?? 502, headers);
+      proxyRes.pipe(res, { end: true });
+    });
+
+    proxyReq.on("error", (err) => {
+      sendJSON(res, 502, {
+        ok: false,
+        error: `OC Gateway not reachable on port ${ocGatewayPort}`,
+        detail: err.message,
+        hint: "Make sure the OC gateway is running on port " + ocGatewayPort + " (openclaw gateway start)",
+      });
+    });
+
+    req.pipe(proxyReq, { end: true });
+    return;
+  }
+
+  // ── Root → proxy to OC Web UI if available, else show bridge status ──
   if (req.method === "GET" && path === "") {
     // Quick probe to check if OC UI is running
     const probe = httpRequest(
       { hostname: "127.0.0.1", port: ocUIPort, path: "/", method: "HEAD", timeout: 1000 },
       (probeRes) => {
         probeRes.resume(); // drain
-        // OC UI is running — redirect to it
-        res.writeHead(302, { Location: "/ui/" });
-        res.end();
+        // OC UI is running — proxy root to it
+        const rootProxyOpts = {
+          hostname: "127.0.0.1",
+          port: ocUIPort,
+          path: `/${url.search}`,
+          method: req.method,
+          headers: { ...req.headers, host: `127.0.0.1:${ocUIPort}` },
+        };
+        const rootProxy = httpRequest(rootProxyOpts, (rootRes) => {
+          const headers = { ...rootRes.headers };
+          headers["access-control-allow-origin"] = "*";
+          res.writeHead(rootRes.statusCode ?? 502, headers);
+          rootRes.pipe(res, { end: true });
+        });
+        rootProxy.on("error", () => {
+          res.writeHead(302, { Location: "/ui/" });
+          res.end();
+        });
+        rootProxy.end();
       },
     );
     probe.on("error", () => {
@@ -516,8 +591,9 @@ function handleRequest(req, res) {
       sendJSON(res, 200, {
         ok: true,
         service: "openclaw-navigator-bridge",
-        version: "4.3.4",
+        version: "4.4.0",
         ui: { available: false, port: ocUIPort, hint: "Start the OC gateway to enable /ui/" },
+        gateway: { port: ocGatewayPort },
         navigator: { connected: bridgeState.connected },
       });
     });
@@ -526,7 +602,7 @@ function handleRequest(req, res) {
       sendJSON(res, 200, {
         ok: true,
         service: "openclaw-navigator-bridge",
-        version: "4.3.4",
+        version: "4.4.0",
         ui: { available: false, port: ocUIPort, hint: "OC UI timed out" },
       });
     });
@@ -534,7 +610,39 @@ function handleRequest(req, res) {
     return;
   }
 
-  sendJSON(res, 404, { ok: false, error: "Not found" });
+  // ── Fallback: proxy unmatched paths → OC Web UI (for static assets) ──
+  // The web UI at localhost:4000 may serve assets at /_next/*, /static/*, etc.
+  // These don't start with /ui/ but still need to reach the web UI server.
+  {
+    const targetURL = `${path}${url.search}`;
+
+    const proxyOpts = {
+      hostname: "127.0.0.1",
+      port: ocUIPort,
+      path: targetURL,
+      method: req.method,
+      headers: {
+        ...req.headers,
+        host: `127.0.0.1:${ocUIPort}`,
+      },
+    };
+
+    const proxyReq = httpRequest(proxyOpts, (proxyRes) => {
+      const headers = { ...proxyRes.headers };
+      headers["access-control-allow-origin"] = "*";
+      headers["access-control-allow-methods"] = "GET, POST, PUT, DELETE, OPTIONS";
+      headers["access-control-allow-headers"] = "Content-Type, Authorization";
+      res.writeHead(proxyRes.statusCode ?? 502, headers);
+      proxyRes.pipe(res, { end: true });
+    });
+
+    proxyReq.on("error", () => {
+      sendJSON(res, 404, { ok: false, error: "Not found" });
+    });
+
+    req.pipe(proxyReq, { end: true });
+    return;
+  }
 }
 
 // ── Relay registration ────────────────────────────────────────────────────
@@ -612,6 +720,9 @@ async function main() {
     if (args[i] === "--ui-port" && args[i + 1]) {
       ocUIPort = parseInt(args[i + 1], 10);
     }
+    if (args[i] === "--gateway-port" && args[i + 1]) {
+      ocGatewayPort = parseInt(args[i + 1], 10);
+    }
     if (args[i] === "--help" || args[i] === "-h") {
       console.log(`
 ${BOLD}openclaw-navigator${RESET} — One-command bridge + tunnel for Navigator
@@ -623,12 +734,24 @@ ${BOLD}Usage:${RESET}
   npx openclaw-navigator --port 18790     Custom port
 
 ${BOLD}Options:${RESET}
-  --port <port>    Bridge server port (default: 18790)
-  --mcp            Also start the MCP server (stdio) for OpenClaw agent
-  --ui-port <port> OC web UI port to reverse-proxy (default: 4000)
-  --no-tunnel      Skip auto-tunnel, use SSH or LAN instead
-  --bind <host>    Bind address (default: 127.0.0.1)
-  --help           Show this help
+  --port <port>         Bridge server port (default: 18790)
+  --mcp                 Also start the MCP server (stdio) for OpenClaw agent
+  --ui-port <port>      OC web UI port to reverse-proxy (default: 4000)
+  --gateway-port <port> OC gateway port for API + WebSocket (default: 18789)
+  --no-tunnel           Skip auto-tunnel, use SSH or LAN instead
+  --bind <host>         Bind address (default: 127.0.0.1)
+  --help                Show this help
+
+${BOLD}Routing (through Cloudflare tunnel):${RESET}
+  /ui/*          → localhost:<ui-port>      Web UI (login page, dashboard)
+  /api/*         → localhost:<gateway-port> Sessions API, chat endpoints
+  /ws, WebSocket → localhost:<gateway-port> Real-time streaming, chat events
+  /health        → bridge itself            Health check
+  /navigator/*   → bridge itself            Navigator control endpoints
+
+${BOLD}Environment variables:${RESET}
+  OPENCLAW_UI_PORT=4000         Where the web UI runs
+  OPENCLAW_GATEWAY_PORT=18789   Where the OC gateway runs
 
 ${BOLD}How it works:${RESET}
   1. Starts a bridge server on localhost
@@ -641,6 +764,8 @@ ${BOLD}How it works:${RESET}
     }
   }
 
+  bridgePort = port; // Expose for status endpoint
+
   heading("🧭 Navigator Bridge");
   info("One-command bridge + tunnel for the Navigator browser\n");
 
@@ -658,6 +783,51 @@ ${BOLD}How it works:${RESET}
     server.listen(port, bindHost, () => resolve());
   });
 
+  // ── WebSocket upgrade proxy → OC Gateway (localhost:ocGatewayPort) ───
+  // Proxies WebSocket connections so Navigator can stream chat events
+  server.on("upgrade", (req, socket, head) => {
+    const reqUrl = new URL(req.url ?? "/", "http://localhost");
+    const reqPath = reqUrl.pathname;
+
+    // Only proxy WebSocket paths intended for the OC gateway
+    if (reqPath === "/ws" || reqPath.startsWith("/ws/") || reqPath.startsWith("/api/") || reqPath === "/") {
+      const targetPath = `${reqPath}${reqUrl.search}`;
+
+      const proxy = netConnect(ocGatewayPort, "127.0.0.1", () => {
+        // Forward the original HTTP upgrade request over the TCP socket
+        const upgradeReq =
+          `${req.method} ${targetPath} HTTP/${req.httpVersion}\r\n` +
+          Object.entries(req.headers)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join("\r\n") +
+          "\r\n\r\n";
+        proxy.write(upgradeReq);
+        if (head && head.length > 0) {
+          proxy.write(head);
+        }
+        // Pipe bidirectionally
+        socket.pipe(proxy);
+        proxy.pipe(socket);
+      });
+
+      proxy.on("error", (err) => {
+        console.log(`  ${DIM}WebSocket proxy error: ${err.message}${RESET}`);
+        socket.destroy();
+      });
+
+      socket.on("error", () => {
+        proxy.destroy();
+      });
+
+      socket.on("close", () => {
+        proxy.destroy();
+      });
+    } else {
+      // Not a proxied path — reject
+      socket.destroy();
+    }
+  });
+
   ok(`Bridge server running on ${bindHost}:${port}`);
 
   // ── Step 2: Set up connectivity ───────────────────────────────────────
@@ -746,10 +916,42 @@ ${BOLD}How it works:${RESET}
     info(`  Token: ${token}`);
   }
 
-  // ── Show OC Web UI access ────────────────────────────────────────────
+  // ── Show OC Web UI access + routing info ─────────────────────────────
   const uiURL = tunnelURL ? `${tunnelURL}/ui/` : `http://localhost:${port}/ui/`;
   console.log(`  ${BOLD}OC Web UI:${RESET} ${CYAN}${uiURL}${RESET}`);
-  info(`  (reverse-proxies to localhost:${ocUIPort} — make sure OC gateway is running)`);
+  info(`  /ui/*  → localhost:${ocUIPort} (web UI)`);
+  info(`  /api/* → localhost:${ocGatewayPort} (gateway API)`);
+  info(`  /ws    → localhost:${ocGatewayPort} (WebSocket)`);
+
+  // ── Startup health checks ──────────────────────────────────────────
+  console.log("");
+  const checkPort = (label, checkPort, checkPath) => {
+    return new Promise((resolve) => {
+      const probe = httpRequest(
+        { hostname: "127.0.0.1", port: checkPort, path: checkPath, method: "HEAD", timeout: 2000 },
+        (probeRes) => {
+          probeRes.resume();
+          ok(`${label} reachable on port ${checkPort}`);
+          resolve(true);
+        },
+      );
+      probe.on("error", () => {
+        warn(`${label} NOT reachable on port ${checkPort} — start it before using the tunnel`);
+        resolve(false);
+      });
+      probe.on("timeout", () => {
+        probe.destroy();
+        warn(`${label} timed out on port ${checkPort}`);
+        resolve(false);
+      });
+      probe.end();
+    });
+  };
+
+  await Promise.all([
+    checkPort("OC Web UI", ocUIPort, "/"),
+    checkPort("OC Gateway", ocGatewayPort, "/health"),
+  ]);
 
   console.log("");
   console.log(`${BOLD}${GREEN}Bridge is running.${RESET} Waiting for Navigator to connect...`);
@@ -852,8 +1054,106 @@ ${BOLD}How it works:${RESET}
 
       mkdirSync(mcporterDir, { recursive: true });
       writeFileSync(mcporterConfigPath, JSON.stringify(mcporterConfig, null, 2) + "\n", "utf8");
-      ok("Registered MCP server with mcporter (15 browser tools available)");
+      ok("Registered MCP server with mcporter (16 browser tools available)");
       info(`  Config: ${mcporterConfigPath}`);
+
+      // Step 3: Install the navigator-bridge skill so the OC agent knows about all tools
+      // Try multiple known skill locations
+      const skillLocations = [
+        "/opt/homebrew/lib/node_modules/openclaw/skills/navigator-bridge",
+        join(homedir(), ".openclaw/skills/navigator-bridge"),
+      ];
+      // Find the first parent that exists, or use the homebrew path
+      let skillDir = skillLocations[0]; // default
+      for (const loc of skillLocations) {
+        const parent = dirname(loc);
+        if (existsSync(parent)) {
+          skillDir = loc;
+          break;
+        }
+      }
+      const skillPath = join(skillDir, "SKILL.md");
+      const BT = "```"; // backtick triple for markdown code blocks
+      const skillContent = [
+        "---",
+        "name: navigator-bridge",
+        "description: Control the remote Navigator browser and access the OC Web UI via MCP tools. Navigate to URLs, click elements, fill forms, read page content, execute JavaScript, manage tabs, and open the OC dashboard.",
+        "metadata:",
+        '  { "openclaw": { "emoji": "🌐", "requires": { "bins": ["mcporter"] } } }',
+        "---",
+        "",
+        "# Navigator Bridge (Remote Browser Control + OC Web UI)",
+        "",
+        "Control the **remote** Navigator browser through MCP tools via mcporter.",
+        "",
+        "**Important:** This controls the REMOTE Navigator instance connected via pairing code, NOT local Navigator.",
+        "",
+        "## Quick start",
+        "",
+        BT + "bash",
+        "# Get the OC Web UI URL and open it in Navigator",
+        "mcporter call navigator.navigator_get_ui_url",
+        "mcporter call navigator.navigator_navigate url=<uiURL from above>",
+        "",
+        "# Check connection status",
+        "mcporter call navigator.navigator_status",
+        BT,
+        "",
+        "## All 16 tools",
+        "",
+        "| Tool | What it does |",
+        "|------|-------------|",
+        "| `navigator_status` | Bridge status, connection, tunnel URL |",
+        "| `navigator_get_ui_url` | Get the OC Web UI URL (tunnel + /ui/) |",
+        "| `navigator_navigate` | Go to a URL |",
+        "| `navigator_open_tab` | Open new tab |",
+        "| `navigator_close_tab` | Close a tab |",
+        "| `navigator_list_tabs` | List all open tabs |",
+        "| `navigator_snapshot` | Full browser state snapshot |",
+        "| `navigator_get_text` | Read page text content |",
+        "| `navigator_get_html` | Get full page HTML |",
+        "| `navigator_click` | Click element by CSS selector |",
+        "| `navigator_fill` | Fill input field |",
+        "| `navigator_submit` | Submit form |",
+        "| `navigator_scroll` | Scroll page |",
+        "| `navigator_execute_js` | Run arbitrary JavaScript |",
+        "| `navigator_query_element` | Inspect DOM element |",
+        "| `navigator_wait_ready` | Wait for page load |",
+        "",
+        "## Usage",
+        "",
+        BT + "bash",
+        "mcporter call navigator.<tool_name> param=value",
+        BT,
+        "",
+        "## Common workflows",
+        "",
+        "### Open OC dashboard in Navigator",
+        BT + "bash",
+        "mcporter call navigator.navigator_get_ui_url",
+        "mcporter call navigator.navigator_navigate url=<uiURL>",
+        "mcporter call navigator.navigator_wait_ready",
+        BT,
+        "",
+        "### Browse and read a website",
+        BT + "bash",
+        "mcporter call navigator.navigator_navigate url=https://example.com",
+        "mcporter call navigator.navigator_wait_ready",
+        "mcporter call navigator.navigator_get_text",
+        BT,
+        "",
+        "### Fill and submit a form",
+        BT + "bash",
+        'mcporter call navigator.navigator_fill selector="#email" value="user@example.com"',
+        'mcporter call navigator.navigator_click selector="#submit"',
+        "mcporter call navigator.navigator_wait_ready",
+        BT,
+        "",
+      ].join("\n");
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(skillPath, skillContent, "utf8");
+      ok("Installed navigator-bridge skill for OC agent");
+      info(`  Skill: ${skillPath}`);
     } catch (err) {
       warn(`mcporter registration failed: ${err.message}`);
       info("  You can manually configure mcporter for Navigator MCP");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-navigator",
-  "version": "4.3.8",
+  "version": "4.4.0",
   "description": "One-command bridge + tunnel for the Navigator browser — works on any machine, any OS",
   "keywords": [
     "browser",