chromiumfish 0.2.1 → 0.2.2

package/README.md

@@ -84,11 +84,27 @@ want to manage the lifecycle (`const { agent, close } = await launchAgent()`).
 > Needs a WebSocket: the Node 22+ global `WebSocket` is used automatically; on
 > Node <22 install the optional `ws` package (`npm install ws`).
 
+## External agents
+
+Prefer a third-party framework (Hermes, OpenClaw, browser-use, Playwright, …)? `chromiumfish
+serve` exposes a plain CDP endpoint — with your persona/proxy/timezone active — for any of them
+to attach to:
+
+```bash
+npx chromiumfish serve --persona-seed alice        # -> http://127.0.0.1:9222
+# e.g. Hermes ~/.hermes/config.yaml: browser: { cdp_url: "http://127.0.0.1:9222" }
+```
+
+Full guide: [chromiumfish.com/agents](https://chromiumfish.com/agents).
+
 ## CLI
 
 ```bash
 npx chromiumfish fetch [--browser-version X] [--force]   # download + cache
 npx chromiumfish path                                     # print binary path
+npx chromiumfish serve [--port 9222] [--persona-seed S]  # CDP endpoint for external agents
+                       [--proxy URL] [--window-size WxH] [--timezone Z] [--headless]
+                       [--browser-version X] [--extra-args ARGS] [--timeout S]
 npx chromiumfish clear                                    # wipe the cache
 npx chromiumfish --version
 ```

package/dist/cli.js

@@ -1,7 +1,149 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
 import { binaryPath, cacheRoot, fetchBrowser } from "./fetch.js";
+import { buildArgs } from "./launcher.js";
+import { resolveTimezone } from "./ip2tz.js";
 import { SDK_VERSION, browserVersion } from "./version.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Read `--flag value` from argv, or undefined. */
+function flag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/**
+ * Launch ChromiumFish as a bare CDP endpoint for external agent frameworks
+ * (Hermes, OpenClaw, browser-use, ...) to attach to. Unlike `launchAgent`, this
+ * adds NO `--agent-*` switches — it just exposes Chrome DevTools Protocol with
+ * the persona/proxy/timezone you pick, then blocks until interrupted.
+ */
+async function serve(argv) {
+    const port = Number(flag(argv, "--port") ?? 9222);
+    const personaSeed = flag(argv, "--persona-seed");
+    const proxy = flag(argv, "--proxy");
+    const windowSize = flag(argv, "--window-size") ?? "1920x1080";
+    const timezone = flag(argv, "--timezone");
+    const headless = argv.includes("--headless");
+    const version = flag(argv, "--browser-version");
+    const extraArgsRaw = flag(argv, "--extra-args");
+    const timeoutSecs = Number(flag(argv, "--timeout") ?? 30);
+    // Validate up front — Python's argparse does this for us; here it's manual.
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        console.error(`invalid --port ${flag(argv, "--port")}; expected an integer 1-65535`);
+        return 1;
+    }
+    if (!Number.isFinite(timeoutSecs) || timeoutSecs <= 0) {
+        console.error(`invalid --timeout ${flag(argv, "--timeout")}; expected a positive number of seconds`);
+        return 1;
+    }
+    const [w, h] = windowSize.toLowerCase().split("x").map(Number);
+    if (!w || !h) {
+        console.error(`invalid --window-size ${windowSize}; expected WIDTHxHEIGHT, e.g. 1920x1080`);
+        return 1;
+    }
+    const chrome = await binaryPath(version); // fetches if not cached
+    const profile = mkdtempSync(path.join(tmpdir(), "cf-serve-"));
+    const cleanup = () => rmSync(profile, { recursive: true, force: true });
+    let proc;
+    const killTree = (sig) => {
+        if (!proc?.pid)
+            return;
+        try {
+            process.kill(-proc.pid, sig); // negative pid = the whole process group
+        }
+        catch {
+            try {
+                proc.kill(sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    // try/finally guarantees the browser tree + temp profile are torn down even
+    // if resolveTimezone/spawn throws or an early return fires — matches the
+    // Python handler's finally -> _teardown().
+    try {
+        const extra = [];
+        if (headless)
+            extra.push("--headless=new");
+        if (proxy)
+            extra.push(`--proxy-server=${proxy}`);
+        if (extraArgsRaw)
+            extra.push(...extraArgsRaw.split(",").filter(Boolean));
+        const args = [
+            `--remote-debugging-port=${port}`,
+            // External clients send an Origin header DevTools rejects unless allowed.
+            "--remote-allow-origins=*",
+            `--user-data-dir=${profile}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            ...buildArgs({ personaSeed, windowSize: [w, h], args: extra }),
+        ];
+        const env = { ...process.env };
+        if (timezone) {
+            const tz = timezone === "auto" ? await resolveTimezone({ proxy }) : timezone;
+            if (tz)
+                env.TZ = tz;
+        }
+        const base = `http://127.0.0.1:${port}`;
+        // detached: own process group, so we can signal the WHOLE tree (browser +
+        // GPU/renderer/network helpers) on exit instead of leaking the helpers.
+        proc = spawn(chrome, args, { stdio: "ignore", env, detached: true });
+        const deadline = Date.now() + timeoutSecs * 1000;
+        let ver = null;
+        for (;;) {
+            try {
+                const r = await fetch(`${base}/json/version`);
+                if (r.ok) {
+                    ver = (await r.json());
+                    break;
+                }
+            }
+            catch {
+                /* not up yet */
+            }
+            if (proc.exitCode !== null) {
+                console.error("ChromiumFish exited before the CDP endpoint came up");
+                return 1;
+            }
+            if (Date.now() > deadline) {
+                console.error("ChromiumFish did not expose its CDP endpoint in time");
+                return 1;
+            }
+            await sleep(400);
+        }
+        console.log(`ChromiumFish ${ver?.Browser ?? ""} ready — CDP endpoint for external agents`);
+        console.log(`  HTTP : ${base}   (discovery: ${base}/json/version)`);
+        if (ver?.webSocketDebuggerUrl)
+            console.log(`  WS   : ${ver.webSocketDebuggerUrl}`);
+        console.log("");
+        console.log("Attach an agent, e.g.:");
+        console.log(`  Hermes       ~/.hermes/config.yaml  ->  browser: { cdp_url: "${base}" }`);
+        console.log(`  browser-use  BrowserSession(cdp_url="${base}")`);
+        console.log(`  OpenClaw     profile  cdpUrl: "${base}"`);
+        console.log("Ctrl-C to stop.");
+        await new Promise((resolve) => {
+            const stop = () => {
+                console.log("\nstopping…");
+                killTree("SIGTERM");
+                resolve();
+            };
+            process.on("SIGINT", stop);
+            process.on("SIGTERM", stop);
+            proc.on("exit", () => resolve());
+        });
+        return 0;
+    }
+    finally {
+        await sleep(300);
+        killTree("SIGKILL");
+        cleanup();
+    }
+}
 async function main(argv) {
     const cmd = argv[2];
     switch (cmd) {
@@ -26,6 +168,8 @@ async function main(argv) {
             }
             return 0;
         }
+        case "serve":
+            return await serve(argv);
         case "--version":
         case "-V":
             console.log(`chromiumfish ${SDK_VERSION} (browser ${browserVersion()})`);
@@ -37,6 +181,9 @@ async function main(argv) {
                 "Usage:",
                 "  chromiumfish fetch [--browser-version X] [--force]   download + cache",
                 "  chromiumfish path                                    print binary path",
+                "  chromiumfish serve [--port 9222] [--persona-seed S]  CDP endpoint for agents",
+                "       [--proxy URL] [--window-size WxH] [--timezone Z] [--headless]",
+                "       [--browser-version X] [--extra-args ARGS] [--timeout S]",
                 "  chromiumfish clear                                   wipe the cache",
                 "  chromiumfish --version",
             ].join("\n"));

package/dist/version.d.ts

@@ -6,7 +6,7 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export declare const SDK_VERSION = "0.2.1";
+export declare const SDK_VERSION = "0.2.2";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export declare const DEFAULT_BROWSER_VERSION = "149.0.7827.115";
 /** Public repo hosting the release assets. */

package/dist/version.js

@@ -6,7 +6,7 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export const SDK_VERSION = "0.2.1";
+export const SDK_VERSION = "0.2.2";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export const DEFAULT_BROWSER_VERSION = "149.0.7827.115";
 /** Public repo hosting the release assets. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromiumfish",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser.",
   "type": "module",
   "main": "./dist/index.js",