chromiumfish 0.2.0 → 0.2.2

package/README.md

@@ -62,13 +62,11 @@ and connects over CDP; `runTask` drives it from a plain-language goal.
 ```ts
 import { withAgent } from "chromiumfish";
 
-// LLM config from a nearby .env: OPENAI_API_BASE / OPENAI_API_KEY / OPENAI_API_MODEL
-const url = await withAgent({ typing: "human" }, (agent) =>
-  agent
-    .runTask("Search DuckDuckGo for 'chromiumfish' and give me the first result's URL.")
-    .then((r) => r.finalText),
+// LLM config: a nearby .env (OPENAI_API_*), or pass apiKey/apiBase/model here.
+const result = await withAgent({ typing: "human" }, (agent) =>
+  agent.runTask("Search DuckDuckGo for 'chromiumfish' and give me the first result's URL."),
 );
-console.log(url);
+console.log(result.finalText);
 ```
 
 `withAgent` shuts the browser down for you; use `launchAgent` directly if you
@@ -78,6 +76,7 @@ want to manage the lifecycle (`const { agent, close } = await launchAgent()`).
 |--------|---------|-------------|
 | `typing` | `"human"` | Typing speed: `"human"` (~75 WPM, natural), `"fast"`, `"instant"`, or a custom `[keyDown, keyUp, longMultiplier]` triple (numbers = ms). |
 | `model` | env | Model for the session (overrides `OPENAI_API_MODEL`); `runTask({ model })` overrides per task. |
+| `apiKey` / `apiBase` | env | LLM key / base URL (override `OPENAI_API_KEY` / `OPENAI_API_BASE`). |
 | `chrome` | `CHROME_BIN` / cached build | Path to the ChromiumFish binary. |
 | `port` | `9222` | DevTools remote-debugging port. |
 | `extraArgs` | — | Extra Chromium flags. |
@@ -85,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/agent.d.ts

@@ -52,6 +52,10 @@ export interface LaunchAgentOptions {
     port?: number;
     /** Path to the ChromiumFish binary; defaults to CHROME_BIN env or the cached build. */
     chrome?: string;
+    /** LLM API key (overrides OPENAI_API_KEY). */
+    apiKey?: string;
+    /** LLM base URL (overrides OPENAI_API_BASE). */
+    apiBase?: string;
     /** Model for this session (overrides OPENAI_API_MODEL). */
     model?: string;
     /** Typing cadence: "human" (default), "fast", "instant", or a [keyDown, keyUp, multiplier] triple. */
@@ -72,9 +76,10 @@ export interface AgentSession {
 /**
  * Launch a local ChromiumFish with the AI agent layer and connect to it.
  *
- * LLM config is read from OPENAI_API_BASE / OPENAI_API_KEY / OPENAI_API_MODEL
- * (a nearby .env is loaded automatically). Prefer {@link withAgent} for
- * automatic cleanup, or remember to call the returned `close()`.
+ * LLM config can be passed in-script (`apiKey` / `apiBase` / `model`) or left to
+ * OPENAI_API_KEY / OPENAI_API_BASE / OPENAI_API_MODEL (a nearby .env is loaded
+ * automatically); an explicit option wins over the env var. Prefer {@link withAgent}
+ * for automatic cleanup, or remember to call the returned `close()`.
  */
 export declare function launchAgent(opts?: LaunchAgentOptions): Promise<AgentSession>;
 /**

package/dist/agent.js

@@ -350,12 +350,13 @@ function loadDotenv() {
 /**
  * Launch a local ChromiumFish with the AI agent layer and connect to it.
  *
- * LLM config is read from OPENAI_API_BASE / OPENAI_API_KEY / OPENAI_API_MODEL
- * (a nearby .env is loaded automatically). Prefer {@link withAgent} for
- * automatic cleanup, or remember to call the returned `close()`.
+ * LLM config can be passed in-script (`apiKey` / `apiBase` / `model`) or left to
+ * OPENAI_API_KEY / OPENAI_API_BASE / OPENAI_API_MODEL (a nearby .env is loaded
+ * automatically); an explicit option wins over the env var. Prefer {@link withAgent}
+ * for automatic cleanup, or remember to call the returned `close()`.
  */
 export async function launchAgent(opts = {}) {
-    const { port = 9222, model = "", typing = "human", loadDotenv: doDotenv = true, extraArgs = [], timeoutMs = 30_000 } = opts;
+    const { port = 9222, apiKey = "", apiBase = "", model = "", typing = "human", loadDotenv: doDotenv = true, extraArgs = [], timeoutMs = 30_000 } = opts;
     if (doDotenv)
         loadDotenv();
     let chrome = opts.chrome ?? process.env.CHROME_BIN;
@@ -372,8 +373,8 @@ export async function launchAgent(opts = {}) {
         typingFlag(typing),
         "--no-first-run",
         "--no-default-browser-check",
-        `--agent-llm-url=${process.env.OPENAI_API_BASE ?? ""}`,
-        `--agent-llm-key=${process.env.OPENAI_API_KEY ?? ""}`,
+        `--agent-llm-url=${apiBase || (process.env.OPENAI_API_BASE ?? "")}`,
+        `--agent-llm-key=${apiKey || (process.env.OPENAI_API_KEY ?? "")}`,
         `--agent-model=${model || (process.env.OPENAI_API_MODEL ?? "")}`,
         ...extraArgs,
     ];

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,9 +6,9 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export declare const SDK_VERSION = "0.1.4";
+export declare const SDK_VERSION = "0.2.2";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
-export declare const DEFAULT_BROWSER_VERSION = "150.0.7844";
+export declare const DEFAULT_BROWSER_VERSION = "149.0.7827.115";
 /** Public repo hosting the release assets. */
 export declare const RELEASE_REPO = "arman-bd/chromiumfish";
 /**
@@ -30,7 +30,7 @@ export declare const GEOIP_FALLBACK_VERSION = "2026.06";
  * Reject version strings that aren't a plain build tag. Versions are
  * interpolated into filesystem cache paths and release URLs, so a crafted
  * value like `../../../etc` would escape the cache dir (path traversal).
- * Real tags are digits, dots, and hyphens (e.g. "150.0.7844", "2026.06",
+ * Real tags are digits, dots, and hyphens (e.g. "149.0.7827.115", "2026.06",
  * "latest").
  */
 export declare function assertSafeVersion(version: string): string;

package/dist/version.js

@@ -6,9 +6,9 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export const SDK_VERSION = "0.1.4";
+export const SDK_VERSION = "0.2.2";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
-export const DEFAULT_BROWSER_VERSION = "150.0.7844";
+export const DEFAULT_BROWSER_VERSION = "149.0.7827.115";
 /** Public repo hosting the release assets. */
 export const RELEASE_REPO = "arman-bd/chromiumfish";
 /**
@@ -30,7 +30,7 @@ export const GEOIP_FALLBACK_VERSION = "2026.06";
  * Reject version strings that aren't a plain build tag. Versions are
  * interpolated into filesystem cache paths and release URLs, so a crafted
  * value like `../../../etc` would escape the cache dir (path traversal).
- * Real tags are digits, dots, and hyphens (e.g. "150.0.7844", "2026.06",
+ * Real tags are digits, dots, and hyphens (e.g. "149.0.7827.115", "2026.06",
  * "latest").
  */
 export function assertSafeVersion(version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromiumfish",
-  "version": "0.2.0",
+  "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",