feat: add Chrome extension browser relay

src/cli/browser-cli-extension.test.ts

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+describe("browser extension install", () => {
+  it("installs into the state dir (never node_modules)", async () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-ext-"));
+    const { installChromeExtension } = await import("./browser-cli-extension.js");
+
+    const sourceDir = path.resolve(process.cwd(), "assets/chrome-extension");
+    const result = await installChromeExtension({ stateDir: tmp, sourceDir });
+
+    expect(result.path).toBe(path.join(tmp, "browser", "chrome-extension"));
+    expect(fs.existsSync(path.join(result.path, "manifest.json"))).toBe(true);
+    expect(result.path.includes("node_modules")).toBe(false);
+  });
+});
+

src/cli/browser-cli-extension.ts

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { Command } from "commander";
+
+import { STATE_DIR_CLAWDBOT } from "../config/paths.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+import { movePathToTrash } from "../browser/trash.js";
+
+function bundledExtensionRootDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "../../assets/chrome-extension");
+}
+
+function installedExtensionRootDir() {
+  return path.join(STATE_DIR_CLAWDBOT, "browser", "chrome-extension");
+}
+
+function hasManifest(dir: string) {
+  return fs.existsSync(path.join(dir, "manifest.json"));
+}
+
+export async function installChromeExtension(opts?: {
+  stateDir?: string;
+  sourceDir?: string;
+}): Promise<{ path: string }> {
+  const src = opts?.sourceDir ?? bundledExtensionRootDir();
+  if (!hasManifest(src)) {
+    throw new Error("Bundled Chrome extension is missing. Reinstall Clawdbot and try again.");
+  }
+
+  const stateDir = opts?.stateDir ?? STATE_DIR_CLAWDBOT;
+  const dest = path.join(stateDir, "browser", "chrome-extension");
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  if (fs.existsSync(dest)) {
+    await movePathToTrash(dest).catch(() => {
+      const backup = `${dest}.old-${Date.now()}`;
+      fs.renameSync(dest, backup);
+    });
+  }
+
+  await fs.promises.cp(src, dest, { recursive: true });
+  if (!hasManifest(dest)) {
+    throw new Error("Chrome extension install failed (manifest.json missing). Try again.");
+  }
+
+  return { path: dest };
+}
+
+export function registerBrowserExtensionCommands(
+  browser: Command,
+  parentOpts: (cmd: Command) => { json?: boolean },
+) {
+  const ext = browser.command("extension").description("Chrome extension helpers");
+
+  ext
+    .command("install")
+    .description("Install the Chrome extension to a stable local path")
+    .action(async (_opts, cmd) => {
+      const parent = parentOpts(cmd);
+      let installed: { path: string };
+      try {
+        installed = await installChromeExtension();
+      } catch (err) {
+        defaultRuntime.error(danger(String(err)));
+        defaultRuntime.exit(1);
+      }
+
+      if (parent?.json) {
+        defaultRuntime.log(JSON.stringify({ ok: true, path: installed.path }, null, 2));
+        return;
+      }
+      defaultRuntime.log(installed.path);
+    });
+
+  ext
+    .command("path")
+    .description("Print the path to the installed Chrome extension (load unpacked)")
+    .action((_opts, cmd) => {
+      const parent = parentOpts(cmd);
+      const dir = installedExtensionRootDir();
+      if (!hasManifest(dir)) {
+        defaultRuntime.error(
+          danger('Chrome extension is not installed. Run: "clawdbot browser extension install"'),
+        );
+        defaultRuntime.exit(1);
+      }
+      if (parent?.json) {
+        defaultRuntime.log(JSON.stringify({ path: dir }, null, 2));
+        return;
+      }
+      defaultRuntime.log(dir);
+    });
+}

src/cli/browser-cli-manage.ts

@@ -382,28 +382,41 @@ export function registerBrowserManageCommands(
     .requiredOption("--name <name>", "Profile name (lowercase, numbers, hyphens)")
     .option("--color <hex>", "Profile color (hex format, e.g. #0066CC)")
     .option("--cdp-url <url>", "CDP URL for remote Chrome (http/https)")
-    .action(async (opts: { name: string; color?: string; cdpUrl?: string }, cmd) => {
-      const parent = parentOpts(cmd);
-      const baseUrl = resolveBrowserControlUrl(parent?.url);
-      try {
-        const result = await browserCreateProfile(baseUrl, {
-          name: opts.name,
-          color: opts.color,
-          cdpUrl: opts.cdpUrl,
-        });
-        if (parent?.json) {
-          defaultRuntime.log(JSON.stringify(result, null, 2));
-          return;
+    .option("--driver <driver>", "Profile driver (clawd|extension). Default: clawd")
+    .action(
+      async (
+        opts: { name: string; color?: string; cdpUrl?: string; driver?: string },
+        cmd,
+      ) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        try {
+          const result = await browserCreateProfile(baseUrl, {
+            name: opts.name,
+            color: opts.color,
+            cdpUrl: opts.cdpUrl,
+            driver: opts.driver === "extension" ? "extension" : undefined,
+          });
+          if (parent?.json) {
+            defaultRuntime.log(JSON.stringify(result, null, 2));
+            return;
+          }
+          const loc = result.isRemote
+            ? `  cdpUrl: ${result.cdpUrl}`
+            : `  port: ${result.cdpPort}`;
+          defaultRuntime.log(
+            info(
+              `🦞 Created profile "${result.profile}"\n${loc}\n  color: ${result.color}${
+                opts.driver === "extension" ? "\n  driver: extension" : ""
+              }`,
+            ),
+          );
+        } catch (err) {
+          defaultRuntime.error(danger(String(err)));
+          defaultRuntime.exit(1);
         }
-        const loc = result.isRemote ? `  cdpUrl: ${result.cdpUrl}` : `  port: ${result.cdpPort}`;
-        defaultRuntime.log(
-          info(`🦞 Created profile "${result.profile}"\n${loc}\n  color: ${result.color}`),
-        );
-      } catch (err) {
-        defaultRuntime.error(danger(String(err)));
-        defaultRuntime.exit(1);
-      }
-    });
+      },
+    );
 
   browser
     .command("delete-profile")

src/cli/browser-cli-serve.ts

@@ -0,0 +1,121 @@
+import type { Command } from "commander";
+
+import { loadConfig } from "../config/config.js";
+import { danger, info } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+import { resolveBrowserConfig, resolveProfile } from "../browser/config.js";
+import { startBrowserBridgeServer, stopBrowserBridgeServer } from "../browser/bridge-server.js";
+import { ensureChromeExtensionRelayServer } from "../browser/extension-relay.js";
+
+function isLoopbackBindHost(host: string) {
+  const h = host.trim().toLowerCase();
+  return h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "[::1]";
+}
+
+function parsePort(raw: unknown): number | null {
+  const v = typeof raw === "string" ? raw.trim() : "";
+  if (!v) return null;
+  const n = Number.parseInt(v, 10);
+  if (!Number.isFinite(n) || n < 0 || n > 65535) return null;
+  return n;
+}
+
+export function registerBrowserServeCommands(
+  browser: Command,
+  _parentOpts: (cmd: Command) => unknown,
+) {
+  browser
+    .command("serve")
+    .description("Run a standalone browser control server (for remote gateways)")
+    .option("--bind <host>", "Bind host (default: 127.0.0.1)")
+    .option("--port <port>", "Bind port (default: from browser.controlUrl)")
+    .option(
+      "--token <token>",
+      "Require Authorization: Bearer <token> (required when binding non-loopback)",
+    )
+    .action(async (opts: { bind?: string; port?: string; token?: string }) => {
+      const cfg = loadConfig();
+      const resolved = resolveBrowserConfig(cfg.browser);
+      if (!resolved.enabled) {
+        defaultRuntime.error(
+          danger("Browser control is disabled. Set browser.enabled=true and try again."),
+        );
+        defaultRuntime.exit(1);
+      }
+
+      const host = (opts.bind ?? "127.0.0.1").trim();
+      const port = parsePort(opts.port) ?? resolved.controlPort;
+
+      const envToken = process.env.CLAWDBOT_BROWSER_CONTROL_TOKEN?.trim();
+      const authToken = (opts.token ?? envToken ?? resolved.controlToken)?.trim();
+      if (!isLoopbackBindHost(host) && !authToken) {
+        defaultRuntime.error(
+          danger(
+            `Refusing to bind browser control on ${host} without --token (or CLAWDBOT_BROWSER_CONTROL_TOKEN, or browser.controlToken).`,
+          ),
+        );
+        defaultRuntime.exit(1);
+      }
+
+      const bridge = await startBrowserBridgeServer({
+        resolved,
+        host,
+        port,
+        ...(authToken ? { authToken } : {}),
+      });
+
+      // If any profile uses the Chrome extension relay, start the local relay server eagerly
+      // so the extension can connect before the first browser action.
+      for (const name of Object.keys(resolved.profiles)) {
+        const profile = resolveProfile(resolved, name);
+        if (!profile || profile.driver !== "extension") continue;
+        await ensureChromeExtensionRelayServer({ cdpUrl: profile.cdpUrl }).catch((err) => {
+          defaultRuntime.error(
+            danger(`Chrome extension relay init failed for profile "${name}": ${String(err)}`),
+          );
+        });
+      }
+
+      defaultRuntime.log(
+        info(
+          [
+            `🦞 Browser control listening on ${bridge.baseUrl}/`,
+            authToken ? "Auth: Bearer token required." : "Auth: off (loopback only).",
+            "",
+            "Paste on the Gateway (clawdbot.json):",
+            JSON.stringify(
+              {
+                browser: {
+                  enabled: true,
+                  controlUrl: bridge.baseUrl,
+                  ...(authToken ? { controlToken: authToken } : {}),
+                },
+              },
+              null,
+              2,
+            ),
+            ...(authToken
+              ? [
+                  "",
+                  "Or use env on the Gateway (instead of controlToken in config):",
+                  `export CLAWDBOT_BROWSER_CONTROL_TOKEN=${JSON.stringify(authToken)}`,
+                ]
+              : []),
+          ].join("\n"),
+        ),
+      );
+
+      let shuttingDown = false;
+      const shutdown = async (signal: string) => {
+        if (shuttingDown) return;
+        shuttingDown = true;
+        defaultRuntime.log(info(`Shutting down (${signal})...`));
+        await stopBrowserBridgeServer(bridge.server).catch(() => {});
+        process.exit(0);
+      };
+      process.once("SIGINT", () => void shutdown("SIGINT"));
+      process.once("SIGTERM", () => void shutdown("SIGTERM"));
+
+      await new Promise(() => {});
+    });
+}

src/cli/browser-cli.ts

@@ -8,8 +8,10 @@ import { registerBrowserActionInputCommands } from "./browser-cli-actions-input.
 import { registerBrowserActionObserveCommands } from "./browser-cli-actions-observe.js";
 import { registerBrowserDebugCommands } from "./browser-cli-debug.js";
 import { browserActionExamples, browserCoreExamples } from "./browser-cli-examples.js";
+import { registerBrowserExtensionCommands } from "./browser-cli-extension.js";
 import { registerBrowserInspectCommands } from "./browser-cli-inspect.js";
 import { registerBrowserManageCommands } from "./browser-cli-manage.js";
+import { registerBrowserServeCommands } from "./browser-cli-serve.js";
 import type { BrowserParentOpts } from "./browser-cli-shared.js";
 import { registerBrowserStateCommands } from "./browser-cli-state.js";
 
@@ -37,6 +39,8 @@ export function registerBrowserCli(program: Command) {
   const parentOpts = (cmd: Command) => cmd.parent?.opts?.() as BrowserParentOpts;
 
   registerBrowserManageCommands(browser, parentOpts);
+  registerBrowserExtensionCommands(browser, parentOpts);
+  registerBrowserServeCommands(browser, parentOpts);
   registerBrowserInspectCommands(browser, parentOpts);
   registerBrowserActionInputCommands(browser, parentOpts);
   registerBrowserActionObserveCommands(browser, parentOpts);