chromiumfish 0.1.3 → 0.2.0

package/README.md

@@ -12,9 +12,9 @@ npx chromiumfish fetch        # download + cache the browser build
 ```javascript
 import { ChromiumFish } from "chromiumfish";
 
-const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
 const page = await browser.newPage();
-await page.goto("https://abrahamjuliot.github.io/creepjs/");
+await page.goto("https://example.com");
 await page.screenshot({ path: "fp.png" });
 await browser.close();
 ```
@@ -26,7 +26,7 @@ await browser.close();
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `personaSeed` | — | Integer seed for a stable, internally-consistent fingerprint persona. |
+| `personaSeed` | — | String id for a stable, internally-consistent fingerprint persona (any string; a number works too). |
 | `headless` | `true` | Run headless (SwiftShader). |
 | `proxy` | — | Playwright proxy object, e.g. `{ server, username, password }`. |
 | `windowSize` | `[1920, 1080]` | Window dimensions (`null` to omit). |
@@ -53,6 +53,38 @@ The DB auto-updates: it tracks the `latest` monthly build (cached, re-checked
 weekly), so you get fresh data without upgrading the SDK. Pin a fixed version
 with `CHROMIUMFISH_GEOIP_VERSION=2026.06` for reproducibility.
 
+## AI agent
+
+ChromiumFish ships a native in-browser agent (perceive → think → act, driven by
+an OpenAI-compatible LLM). `launchAgent` starts the browser with the agent layer
+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),
+);
+console.log(url);
+```
+
+`withAgent` shuts the browser down for you; use `launchAgent` directly if you
+want to manage the lifecycle (`const { agent, close } = await launchAgent()`).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `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. |
+| `chrome` | `CHROME_BIN` / cached build | Path to the ChromiumFish binary. |
+| `port` | `9222` | DevTools remote-debugging port. |
+| `extraArgs` | — | Extra Chromium flags. |
+
+> Needs a WebSocket: the Node 22+ global `WebSocket` is used automatically; on
+> Node <22 install the optional `ws` package (`npm install ws`).
+
 ## CLI
 
 ```bash

package/dist/agent.d.ts

@@ -0,0 +1,89 @@
+export declare const AGENT_SYSTEM_PROMPT: string;
+export declare const TYPING_PROFILES: Record<string, [string, string, string]>;
+type Cadence = [string | number, string | number, string | number];
+export type TypingSpeed = keyof typeof TYPING_PROFILES | (string & {}) | Cadence;
+/** Build the GlicActorIncrementalTyping switch for a typing-speed setting. */
+export declare function typingFlag(typing?: TypingSpeed): string;
+export interface AgentStep {
+    action?: string;
+    status?: string;
+    [k: string]: unknown;
+}
+/** Outcome of one agent task plus the resolved step plan. */
+export declare class AgentResult {
+    success: boolean;
+    finalText: string;
+    steps: AgentStep[];
+    replayed: boolean;
+    constructor(success: boolean, finalText: string, steps: AgentStep[], replayed?: boolean);
+    /** Number of steps replayed deterministically (no LLM call). */
+    get fromCache(): number;
+    /** Number of steps the page had drifted on, re-resolved via the LLM. */
+    get healed(): number;
+    /** Number of steps resolved by the LLM on a fresh run. */
+    get recorded(): number;
+    summary(): string;
+}
+export interface RunTaskOptions {
+    /** Navigate here before the agent loop (the agent can also navigate itself). */
+    url?: string;
+    /** Max perceive→act iterations. Defaults to 25. */
+    maxSteps?: number;
+    /** Per-task model override. */
+    model?: string;
+    /** A resolved plan to REPLAY (descriptor match per step, LLM only to heal). */
+    plan?: AgentStep[];
+    /** System prompt override (honored by builds whose agent layer reads it). */
+    systemPrompt?: string | null;
+}
+/** Connects to a running ChromiumFish CDP endpoint and runs agent tasks. */
+export declare class AgentClient {
+    port: number;
+    private host;
+    private timeoutMs;
+    constructor(port?: number, host?: string, timeoutMs?: number);
+    private httpGet;
+    /** Return {targetId, wsUrl}, reusing a real page or opening one. */
+    private pickPage;
+    runTask(goal: string, opts?: RunTaskOptions): Promise<AgentResult>;
+}
+export interface LaunchAgentOptions {
+    /** DevTools remote-debugging port. Defaults to 9222. */
+    port?: number;
+    /** Path to the ChromiumFish binary; defaults to CHROME_BIN env or the cached build. */
+    chrome?: string;
+    /** Model for this session (overrides OPENAI_API_MODEL). */
+    model?: string;
+    /** Typing cadence: "human" (default), "fast", "instant", or a [keyDown, keyUp, multiplier] triple. */
+    typing?: TypingSpeed;
+    /** Load a nearby .env for OPENAI_* config. Defaults to true. */
+    loadDotenv?: boolean;
+    /** Extra Chromium flags. */
+    extraArgs?: string[];
+    /** How long to wait for the CDP endpoint to come up (ms). Defaults to 30000. */
+    timeoutMs?: number;
+}
+/** A launched agent session: the connected client plus a cleanup function. */
+export interface AgentSession {
+    agent: AgentClient;
+    /** Shut the browser down and remove its temp profile. */
+    close: () => Promise<void>;
+}
+/**
+ * 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()`.
+ */
+export declare function launchAgent(opts?: LaunchAgentOptions): Promise<AgentSession>;
+/**
+ * Run `fn` against a freshly launched agent, shutting the browser down and
+ * cleaning up afterwards — the ergonomic equivalent of Python's
+ * `with launch_agent() as agent:`.
+ *
+ *   const url = await withAgent({ typing: "fast" }, (agent) =>
+ *     agent.runTask("...").then((r) => r.finalText));
+ */
+export declare function withAgent<T>(opts: LaunchAgentOptions, fn: (agent: AgentClient) => Promise<T>): Promise<T>;
+export {};

package/dist/agent.js

@@ -0,0 +1,452 @@
+/**
+ * Native in-browser AI agent client (TypeScript port of the Python SDK's
+ * ``chromiumfish.agent``).
+ *
+ * Drives the fork's native ``Browser.agentRunTask`` CDP command on a running
+ * ChromiumFish (launched with ``--remote-debugging-port`` and the ``--agent-*``
+ * switches). Talks raw CDP over a WebSocket — the same path the Python client
+ * uses — which avoids Playwright's ``connectOverCDP`` context setup that this
+ * fork's CDP surface doesn't fully support.
+ *
+ *   import { launchAgent } from "chromiumfish";
+ *
+ *   const { agent, close } = await launchAgent({ typing: "fast" });
+ *   try {
+ *     const r = await agent.runTask("search for 'automation' and open the first result",
+ *                                   { url: "http://127.0.0.1:8000/search" });
+ *     console.log(r.success, r.finalText);
+ *   } finally {
+ *     await close();
+ *   }
+ *
+ * Needs a WebSocket implementation: the Node 22+ global ``WebSocket`` is used if
+ * present, otherwise the optional ``ws`` package (``npm install ws``) on Node <22.
+ */
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { binaryPath } from "./fetch.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// The agent's master/system prompt, sent per task as Browser.agentRunTask's
+// `systemPrompt` param. NOTE: current shipped builds use the prompt baked into
+// the binary (C++ `kSystemPrompt`) and ignore this param — so it is effectively
+// a no-op against them; kept for parity with the Python SDK and to declare the
+// intended contract (the final `done` answer is ONLY the value the task asked
+// for — no prose, no labels — so callers get a clean result).
+export const AGENT_SYSTEM_PROMPT = "You are an autonomous web-browsing agent operating directly inside the " +
+    "browser. Each turn you receive the interactive elements currently visible " +
+    "on the page, one per line:\n" +
+    "  [<index>]<role>label\n" +
+    "Roles: a (link), button, input, textarea, select, checkbox. Each input " +
+    'shows its STATE in brackets: [EMPTY; placeholder hint "..."] = empty, the ' +
+    'hint is NOT a value, type into it; [value: "..."] = already contains that ' +
+    "text; [filled]/[empty] = a password field; [checked]/[unchecked] = a " +
+    'checkbox; [selected: "..."]/[no selection] = a select (its choices follow ' +
+    "as opts:[value=text, ...] — use one exact value). Disabled controls are " +
+    "marked (disabled). You also get a one-line note saying whether the page " +
+    "changed since your last action.\n\n" +
+    "Respond with ONLY a JSON object (no prose, no markdown):\n" +
+    "{\n" +
+    '  "thought": "brief reasoning",\n' +
+    '  "actions": [ <one or more action steps, run in order, in one shot> ]\n' +
+    "}\n" +
+    'Each step is an object: {"action": ' +
+    '"click|type|scroll|navigate|select|read|wait|done", "index": <element ' +
+    'index>, "text": "to type", "enter": true (type: press Enter), ' +
+    '"url": "https://..." (navigate), "value": "exact option value" ' +
+    '(select), "direction": "down|up|left|right" (scroll), "seconds": 1 ' +
+    '(wait), "success": true and "final": "<answer>" (done)}.\n' +
+    "Put MULTIPLE steps in the array to do them in ONE shot (strongly preferred " +
+    "for speed): whenever you know the values, fill ALL fields AND click submit " +
+    "in a single response. Use a single step only when the next step truly " +
+    "depends on this one's result.\n\n" +
+    "Rules:\n" +
+    "- If a cookie/consent dialog or modal is open — its elements are marked " +
+    '(modal), or you see text like "Accept all" / "Reject all" / ' +
+    '"consent" / "Before you continue" — DISMISS it FIRST by clicking its ' +
+    "accept/agree/continue button, before attempting anything else. Elements " +
+    "behind a modal are still listed but are visually covered and cannot be " +
+    "used until it is gone.\n" +
+    "- Use only indices in the CURRENT list; they are renumbered every step.\n" +
+    '- Link items (role a) show their destination URL after " -> ". To report ' +
+    "or use a link's URL, READ it from the list — do not click/navigate to the " +
+    "link just to find its address.\n" +
+    "- The element list shows only INTERACTIVE controls, NOT the article/body " +
+    "text. To read or summarize page CONTENT (article, blog post, paragraphs), " +
+    'issue {"action":"read"} by itself; the page\'s text appears in your NEXT ' +
+    "observation as PAGE TEXT — then answer from it.\n" +
+    "- To submit a search or form, set \"enter\": true when typing, or click the " +
+    "submit/Continue button. Typing alone does not submit.\n" +
+    "- For a select, use action \"select\" with an exact value from its opts.\n" +
+    "- AVOID LOOPS: do each step ONCE. Never re-issue the same action (or the " +
+    "same type+type+click batch) just because the page still looks unfinished. " +
+    "A submit/save that clears or reloads the form almost always SUCCEEDED — " +
+    "treat the reset/empty form as success, NOT a reason to submit again. " +
+    "Created items and counts are non-interactive and invisible here; confirm " +
+    'with {"action":"read"} then finish. Repeat an action only if the task TEXT ' +
+    "explicitly asks for it.\n" +
+    "- RETURN ONLY WHAT WAS ASKED. When you are done, the \"final\" field must " +
+    "contain EXACTLY the value the task requested and NOTHING else — no " +
+    "sentences, no labels, no explanation, no quotes, no markdown. Only when the " +
+    "task asks for a description/summary should \"final\" be a sentence.\n" +
+    "- Finish with a {\"action\":\"done\",\"success\":true,\"final\":\"...\"} " +
+    "step by itself; use success false only if the goal is genuinely impossible.";
+// Per-keystroke typing cadence for the agent's incremental typing, as
+// [key-down, key-up, long-text-multiplier]. The Actor framework default is
+// ~25ms/25ms/0.2 (~240 WPM — superhuman); "human" slows it to ~75 WPM so the
+// typing looks natural. "fast"/"instant" trade realism for speed.
+export const TYPING_PROFILES = {
+    human: ["45ms", "110ms", "0.7"], // ~75 WPM — natural, the default
+    fast: ["10ms", "18ms", "0.3"], // brisk, still per-keystroke
+    instant: ["0ms", "0ms", "0"], // no inter-key delay (fastest)
+};
+/** Build the GlicActorIncrementalTyping switch for a typing-speed setting. */
+export function typingFlag(typing = "human") {
+    let kd, ku, mult;
+    if (typeof typing === "string") {
+        const prof = TYPING_PROFILES[typing];
+        if (!prof) {
+            throw new Error(`unknown typing speed '${typing}'; use one of ` +
+                `${Object.keys(TYPING_PROFILES).join(", ")} or a [keyDown, keyUp, multiplier] triple`);
+        }
+        [kd, ku, mult] = prof;
+    }
+    else {
+        [kd, ku, mult] = typing;
+    }
+    const ms = (v) => (typeof v === "string" ? v : `${v}ms`);
+    return ("--enable-features=GlicActorIncrementalTyping:" +
+        `glic-actor-incremental-typing-key-down-duration/${ms(kd)}/` +
+        `glic-actor-incremental-typing-key-up-duration/${ms(ku)}/` +
+        `glic-actor-incremental-typing-long-multiplier/${mult}`);
+}
+/** Outcome of one agent task plus the resolved step plan. */
+export class AgentResult {
+    success;
+    finalText;
+    steps;
+    replayed;
+    constructor(success, finalText, steps, replayed = false) {
+        this.success = success;
+        this.finalText = finalText;
+        this.steps = steps;
+        this.replayed = replayed;
+    }
+    /** Number of steps replayed deterministically (no LLM call). */
+    get fromCache() {
+        return this.steps.filter((s) => s.status === "replayed").length;
+    }
+    /** Number of steps the page had drifted on, re-resolved via the LLM. */
+    get healed() {
+        return this.steps.filter((s) => s.status === "healed").length;
+    }
+    /** Number of steps resolved by the LLM on a fresh run. */
+    get recorded() {
+        return this.steps.filter((s) => s.status === "recorded").length;
+    }
+    summary() {
+        return (`${this.success ? "ok" : "fail"} | ${this.steps.length} steps ` +
+            `(${this.fromCache} replayed, ${this.healed} healed, ${this.recorded} recorded)`);
+    }
+}
+async function getWebSocketCtor() {
+    const g = globalThis.WebSocket;
+    if (g)
+        return g;
+    try {
+        const spec = "ws"; // variable specifier: keeps tsc from requiring `ws` at build
+        const mod = await import(spec);
+        return mod.default ?? mod.WebSocket ?? mod;
+    }
+    catch {
+        throw new Error("the AI agent client needs a WebSocket implementation; on Node <22 install " +
+            "it with `npm install ws`");
+    }
+}
+/** Minimal CDP-over-WebSocket client. */
+class CDP {
+    ws;
+    id = 0;
+    pending = new Map();
+    waiters = [];
+    constructor(ws) {
+        this.ws = ws;
+        ws.addEventListener("message", (ev) => {
+            const text = typeof ev.data === "string" ? ev.data : ev.data?.toString?.() ?? "";
+            let msg;
+            try {
+                msg = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            if (msg.id != null && this.pending.has(msg.id)) {
+                const p = this.pending.get(msg.id);
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    p.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+                else
+                    p.resolve(msg.result ?? {});
+            }
+            else if (msg.method) {
+                for (let i = this.waiters.length - 1; i >= 0; i--) {
+                    if (this.waiters[i].method === msg.method) {
+                        const w = this.waiters.splice(i, 1)[0];
+                        clearTimeout(w.timer);
+                        w.resolve();
+                    }
+                }
+            }
+        });
+    }
+    static async connect(url) {
+        const WS = await getWebSocketCtor();
+        const ws = new WS(url);
+        await new Promise((resolve, reject) => {
+            ws.addEventListener("open", () => resolve(), { once: true });
+            ws.addEventListener("error", () => reject(new Error("CDP WebSocket error")), { once: true });
+        });
+        return new CDP(ws);
+    }
+    send(method, params = {}, timeoutMs) {
+        const id = ++this.id;
+        return new Promise((resolve, reject) => {
+            let timer;
+            if (timeoutMs) {
+                timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`${method}: timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            this.pending.set(id, {
+                resolve: (v) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve(v);
+                },
+                reject,
+            });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    waitEvent(method, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                const i = this.waiters.findIndex((w) => w.timer === timer);
+                if (i >= 0)
+                    this.waiters.splice(i, 1);
+                resolve();
+            }, timeoutMs);
+            this.waiters.push({ method, resolve, timer });
+        });
+    }
+    close() {
+        try {
+            this.ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Connects to a running ChromiumFish CDP endpoint and runs agent tasks. */
+export class AgentClient {
+    port;
+    host;
+    timeoutMs;
+    constructor(port = 9222, host = "localhost", timeoutMs = 420_000) {
+        this.port = port;
+        this.host = host;
+        this.timeoutMs = timeoutMs;
+    }
+    async httpGet(p) {
+        const res = await fetch(`http://${this.host}:${this.port}${p}`);
+        if (!res.ok)
+            throw new Error(`GET ${p} -> ${res.status}`);
+        return res.json();
+    }
+    /** Return {targetId, wsUrl}, reusing a real page or opening one. */
+    async pickPage() {
+        const targets = await this.httpGet("/json");
+        const pages = targets.filter((t) => t.type === "page" && !String(t.url ?? "").startsWith("chrome://") && t.webSocketDebuggerUrl);
+        if (pages.length)
+            return { targetId: pages[0].id, wsUrl: pages[0].webSocketDebuggerUrl };
+        // No usable page: create one via the browser endpoint. (GET /json/new 405s on
+        // recent builds, so go through Target.createTarget instead.)
+        const ver = await this.httpGet("/json/version");
+        const browser = await CDP.connect(ver.webSocketDebuggerUrl);
+        try {
+            const { targetId } = await browser.send("Target.createTarget", { url: "about:blank" });
+            const again = await this.httpGet("/json");
+            const pg = again.find((t) => t.id === targetId);
+            if (!pg?.webSocketDebuggerUrl)
+                throw new Error("could not open a page target");
+            return { targetId, wsUrl: pg.webSocketDebuggerUrl };
+        }
+        finally {
+            browser.close();
+        }
+    }
+    async runTask(goal, opts = {}) {
+        const { url, maxSteps = 25, model = "", plan, systemPrompt = AGENT_SYSTEM_PROMPT } = opts;
+        const { targetId, wsUrl } = await this.pickPage();
+        const cdp = await CDP.connect(wsUrl);
+        try {
+            await cdp.send("Page.enable");
+            if (url && url !== "about:blank") {
+                await cdp.send("Page.navigate", { url });
+                await cdp.waitEvent("Page.loadEventFired", 20_000);
+                await sleep(500);
+            }
+            const params = { targetId, goal, maxSteps };
+            if (model)
+                params.model = model;
+            if (plan)
+                params.planJson = JSON.stringify(plan);
+            if (systemPrompt)
+                params.systemPrompt = systemPrompt;
+            const res = (await cdp.send("Browser.agentRunTask", params, this.timeoutMs)) ?? {};
+            let steps = [];
+            try {
+                const parsed = JSON.parse(res.stepsJson ?? "[]");
+                if (Array.isArray(parsed))
+                    steps = parsed;
+            }
+            catch {
+                /* leave steps empty */
+            }
+            return new AgentResult(Boolean(res.success), res.finalText ?? "", steps, Boolean(plan));
+        }
+        finally {
+            cdp.close();
+        }
+    }
+}
+/** Load KEY=VALUE lines from the nearest .env (cwd or a parent) without override. */
+function loadDotenv() {
+    let dir = process.cwd();
+    for (;;) {
+        const envFile = path.join(dir, ".env");
+        if (existsSync(envFile)) {
+            for (const raw of readFileSync(envFile, "utf8").split(/\r?\n/)) {
+                const line = raw.trim();
+                if (!line || line.startsWith("#") || !line.includes("="))
+                    continue;
+                const idx = line.indexOf("=");
+                const key = line.slice(0, idx).trim();
+                const val = line.slice(idx + 1).trim();
+                if (!(key in process.env))
+                    process.env[key] = val;
+            }
+            return;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}
+/**
+ * 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()`.
+ */
+export async function launchAgent(opts = {}) {
+    const { port = 9222, model = "", typing = "human", loadDotenv: doDotenv = true, extraArgs = [], timeoutMs = 30_000 } = opts;
+    if (doDotenv)
+        loadDotenv();
+    let chrome = opts.chrome ?? process.env.CHROME_BIN;
+    if (!chrome)
+        chrome = await binaryPath();
+    const profile = mkdtempSync(path.join(tmpdir(), "cf-agent-"));
+    const args = [
+        `--remote-debugging-port=${port}`,
+        "--remote-allow-origins=*",
+        `--user-data-dir=${profile}`,
+        "--disable-actor-safety-checks", // let the agent act unattended
+        // Typing cadence (see TYPING_PROFILES). Default "human" ~75 WPM so the
+        // agent's keystrokes look natural; "fast"/"instant" go quicker.
+        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-model=${model || (process.env.OPENAI_API_MODEL ?? "")}`,
+        ...extraArgs,
+    ];
+    const proc = spawn(chrome, args, { stdio: "ignore" });
+    const cleanup = () => rmSync(profile, { recursive: true, force: true });
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const r = await fetch(`http://localhost:${port}/json/version`);
+            if (r.ok)
+                break;
+        }
+        catch {
+            /* not up yet */
+        }
+        if (Date.now() > deadline) {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+            cleanup();
+            throw new Error("ChromiumFish did not expose its CDP endpoint in time");
+        }
+        await sleep(500);
+    }
+    // Open an initial page target so runTask can find one immediately.
+    try {
+        const ver = await (await fetch(`http://localhost:${port}/json/version`)).json();
+        const browser = await CDP.connect(ver.webSocketDebuggerUrl);
+        try {
+            await browser.send("Target.createTarget", { url: "about:blank" });
+        }
+        finally {
+            browser.close();
+        }
+    }
+    catch {
+        /* runTask.pickPage will retry if needed */
+    }
+    const close = async () => {
+        try {
+            proc.kill("SIGTERM");
+        }
+        catch {
+            /* ignore */
+        }
+        await sleep(300);
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            /* ignore */
+        }
+        cleanup();
+    };
+    return { agent: new AgentClient(port), close };
+}
+/**
+ * Run `fn` against a freshly launched agent, shutting the browser down and
+ * cleaning up afterwards — the ergonomic equivalent of Python's
+ * `with launch_agent() as agent:`.
+ *
+ *   const url = await withAgent({ typing: "fast" }, (agent) =>
+ *     agent.runTask("...").then((r) => r.finalText));
+ */
+export async function withAgent(opts, fn) {
+    const { agent, close } = await launchAgent(opts);
+    try {
+        return await fn(agent);
+    }
+    finally {
+        await close();
+    }
+}

package/dist/fetch.js

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import * as https from "node:https";
 import * as os from "node:os";
 import * as path from "node:path";
-import { browserVersion, releaseBaseUrl } from "./version.js";
+import { assertSafeVersion, browserVersion, releaseBaseUrl } from "./version.js";
 export function cacheRoot() {
     const env = process.env.CHROMIUMFISH_CACHE_DIR;
     if (env)
@@ -35,12 +35,13 @@ export function platformSlug() {
     throw new Error(`unsupported platform: ${process.platform}`);
 }
 function assetName(version) {
+    assertSafeVersion(version);
     const slug = platformSlug();
     const ext = slug.startsWith("win") ? "zip" : "tar.gz";
     return `chromiumfish-${version}-${slug}.${ext}`;
 }
 export function installDir(version = browserVersion()) {
-    return path.join(cacheRoot(), version, platformSlug());
+    return path.join(cacheRoot(), assertSafeVersion(version), platformSlug());
 }
 const BINARY_NAMES = ["chromiumfish", "chrome", "chromiumfish.exe", "chrome.exe", "ChromiumFish"];
 export function findBinary(root) {
@@ -48,8 +49,15 @@ export function findBinary(root) {
         return null;
     for (const name of BINARY_NAMES) {
         const direct = path.join(root, name);
-        if (fs.existsSync(direct) && fs.statSync(direct).isFile())
-            return direct;
+        // statSync can throw if the file is removed between existsSync and stat
+        // (TOCTOU); treat any stat failure as "not a usable binary here".
+        try {
+            if (fs.statSync(direct).isFile())
+                return direct;
+        }
+        catch {
+            /* keep looking */
+        }
     }
     const stack = [root];
     while (stack.length) {
@@ -64,11 +72,15 @@ export function findBinary(root) {
     }
     return null;
 }
+// Idle-timeout (ms) applied to every download/fetch socket. A stalled server
+// (no bytes for this long) aborts instead of hanging the launch forever.
+const DOWNLOAD_IDLE_TIMEOUT_MS = 60_000;
+const FETCH_IDLE_TIMEOUT_MS = 30_000;
 function download(url, dest) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     return new Promise((resolve, reject) => {
         const get = (u) => {
-            https.get(u, (res) => {
+            const req = https.get(u, (res) => {
                 if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
                     res.resume();
                     return get(res.headers.location);
@@ -80,15 +92,31 @@ function download(url, dest) {
                 const total = Number(res.headers["content-length"] || 0);
                 let read = 0;
                 const out = fs.createWriteStream(dest);
+                // On any failure: tear down both streams and remove the partial file
+                // so a later run doesn't trip over a truncated/corrupt download.
+                const fail = (err) => {
+                    res.destroy();
+                    out.destroy();
+                    try {
+                        fs.rmSync(dest, { force: true });
+                    }
+                    catch { /* best effort */ }
+                    reject(err);
+                };
                 res.on("data", (c) => {
                     read += c.length;
                     if (total)
                         process.stderr.write(`\r[chromiumfish] ${Math.floor((read / total) * 100)}%`);
                 });
+                res.on("error", fail);
                 res.pipe(out);
                 out.on("finish", () => { process.stderr.write("\n"); out.close(() => resolve()); });
-                out.on("error", reject);
-            }).on("error", reject);
+                out.on("error", fail);
+            });
+            req.on("error", reject);
+            req.setTimeout(DOWNLOAD_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`download timed out (no data for ${DOWNLOAD_IDLE_TIMEOUT_MS}ms) for ${u}`));
+            });
         };
         process.stderr.write(`[chromiumfish] downloading ${url}\n`);
         get(url);
@@ -96,20 +124,27 @@ function download(url, dest) {
 }
 function fetchText(url) {
     return new Promise((resolve, reject) => {
-        const get = (u) => https.get(u, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                res.resume();
-                return get(res.headers.location);
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                return reject(new Error(`HTTP ${res.statusCode}`));
-            }
-            let data = "";
-            res.setEncoding("utf8");
-            res.on("data", (c) => (data += c));
-            res.on("end", () => resolve(data));
-        }).on("error", reject);
+        const get = (u) => {
+            const req = https.get(u, (res) => {
+                if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                    res.resume();
+                    return get(res.headers.location);
+                }
+                if (res.statusCode !== 200) {
+                    res.resume();
+                    return reject(new Error(`HTTP ${res.statusCode}`));
+                }
+                let data = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (data += c));
+                res.on("end", () => resolve(data));
+                res.on("error", reject);
+            });
+            req.on("error", reject);
+            req.setTimeout(FETCH_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`request timed out for ${u}`));
+            });
+        };
         get(url);
     });
 }

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { ChromiumFish, buildArgs, BASE_ARGS } from "./launcher.js";
 export type { ChromiumFishOptions } from "./launcher.js";
+export { launchAgent, withAgent, AgentClient, AgentResult, typingFlag, TYPING_PROFILES, AGENT_SYSTEM_PROMPT, } from "./agent.js";
+export type { LaunchAgentOptions, AgentSession, RunTaskOptions, AgentStep, TypingSpeed, } from "./agent.js";
 export { fetchBrowser, binaryPath, installDir, cacheRoot, platformSlug, findBinary } from "./fetch.js";
 export { Ip2TzDB, fetchDb, lookupTimezone, resolveTimezone, resolveVersion as resolveGeoipVersion, egressIp, assetName as ip2tzAssetName, dbPath as ip2tzDbPath, } from "./ip2tz.js";
 export { SDK_VERSION, DEFAULT_BROWSER_VERSION, DEFAULT_GEOIP_VERSION, GEOIP_FALLBACK_VERSION, RELEASE_REPO, browserVersion, releaseBaseUrl, geoipVersion, geoipBaseUrl, } from "./version.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { ChromiumFish, buildArgs, BASE_ARGS } from "./launcher.js";
+export { launchAgent, withAgent, AgentClient, AgentResult, typingFlag, TYPING_PROFILES, AGENT_SYSTEM_PROMPT, } from "./agent.js";
 export { fetchBrowser, binaryPath, installDir, cacheRoot, platformSlug, findBinary } from "./fetch.js";
 export { Ip2TzDB, fetchDb, lookupTimezone, resolveTimezone, resolveVersion as resolveGeoipVersion, egressIp, assetName as ip2tzAssetName, dbPath as ip2tzDbPath, } from "./ip2tz.js";
 export { SDK_VERSION, DEFAULT_BROWSER_VERSION, DEFAULT_GEOIP_VERSION, GEOIP_FALLBACK_VERSION, RELEASE_REPO, browserVersion, releaseBaseUrl, geoipVersion, geoipBaseUrl, } from "./version.js";

package/dist/ip2tz.js

@@ -18,10 +18,12 @@
  */
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
+import * as http from "node:http";
 import * as https from "node:https";
 import * as path from "node:path";
+import * as tls from "node:tls";
 import { cacheRoot } from "./fetch.js";
-import { GEOIP_FALLBACK_VERSION, geoipBaseUrl, geoipLatestManifestUrl, geoipVersion } from "./version.js";
+import { assertSafeVersion, GEOIP_FALLBACK_VERSION, geoipBaseUrl, geoipLatestManifestUrl, geoipVersion, } from "./version.js";
 const MAGIC = Buffer.from("IP2TZ\x01", "latin1");
 const V4_REC = 6; // uint32 start + uint16 tz_idx
 const V6_REC = 18; // 16-byte start + uint16 tz_idx
@@ -89,33 +91,42 @@ export async function resolveVersion(version = geoipVersion(), download = true)
     return cached?.version || GEOIP_FALLBACK_VERSION;
 }
 export function assetName(version = geoipVersion()) {
-    return `ip2tz-${resolveVersionSync(version)}.bin`;
+    return `ip2tz-${assertSafeVersion(resolveVersionSync(version))}.bin`;
 }
 export function dbPath(version = geoipVersion()) {
-    return path.join(geoipDir(), `ip2tz-${resolveVersionSync(version)}.bin`);
+    return path.join(geoipDir(), `ip2tz-${assertSafeVersion(resolveVersionSync(version))}.bin`);
 }
+// Idle-timeout (ms) for the geoip manifest / DB / checksum fetches so a
+// stalled server can't hang resolution or download forever.
+const GET_IDLE_TIMEOUT_MS = 30_000;
 function get(url) {
     return new Promise((resolve, reject) => {
-        const go = (u) => https
-            .get(u, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                res.resume();
-                return go(res.headers.location);
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                return reject(new Error(`HTTP ${res.statusCode}`));
-            }
-            const chunks = [];
-            res.on("data", (c) => chunks.push(c));
-            res.on("end", () => resolve(Buffer.concat(chunks)));
-        })
-            .on("error", reject);
+        const go = (u) => {
+            const req = https
+                .get(u, (res) => {
+                if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                    res.resume();
+                    return go(res.headers.location);
+                }
+                if (res.statusCode !== 200) {
+                    res.resume();
+                    return reject(new Error(`HTTP ${res.statusCode}`));
+                }
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => resolve(Buffer.concat(chunks)));
+                res.on("error", reject);
+            })
+                .on("error", reject);
+            req.setTimeout(GET_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`request timed out for ${u}`));
+            });
+        };
         go(url);
     });
 }
 export async function fetchDb(version = geoipVersion(), force = false) {
-    const v = await resolveVersion(version); // concrete, e.g. "2026.06"
+    const v = assertSafeVersion(await resolveVersion(version)); // concrete, e.g. "2026.06"
     const dest = path.join(geoipDir(), `ip2tz-${v}.bin`);
     if (fs.existsSync(dest) && !force)
         return dest;
@@ -256,28 +267,29 @@ function parseV6(ip) {
     }
     return b;
 }
-let cached = null;
+// Keyed by *resolved* concrete version so a later lookup with a different
+// version doesn't silently reuse the first DB loaded.
+const cache = new Map();
 async function getDb(version = geoipVersion(), download = true) {
-    if (cached)
-        return cached;
-    const v = await resolveVersion(version, download);
+    const v = assertSafeVersion(await resolveVersion(version, download));
+    const existing = cache.get(v);
+    if (existing)
+        return existing;
     let p = path.join(geoipDir(), `ip2tz-${v}.bin`);
     if (!fs.existsSync(p)) {
         if (!download)
             throw new Error("ip2tz DB not installed. Call fetchDb().");
         p = await fetchDb(v);
     }
-    cached = Ip2TzDB.load(p);
-    return cached;
+    const db = Ip2TzDB.load(p);
+    cache.set(v, db);
+    return db;
 }
 export async function lookupTimezone(ip, version = geoipVersion(), download = true) {
     return (await getDb(version, download)).lookup(ip);
 }
-export function egressIp(proxy, timeoutMs = 8000) {
-    // Note: proxy support for the probe would require an https-proxy agent; when
-    // a proxy is configured we currently probe direct and rely on the caller to
-    // pass an explicit IP if egress differs.
-    void proxy;
+/** Probe the egress IP directly (no proxy). */
+function egressDirect(timeoutMs) {
     return new Promise((resolve) => {
         const req = https.get(EGRESS_PROBE, { headers: { "User-Agent": "chromiumfish" } }, (res) => {
             let data = "";
@@ -299,6 +311,101 @@ export function egressIp(proxy, timeoutMs = 8000) {
         });
     });
 }
+/**
+ * Probe the egress IP *through an HTTP(S) proxy* by CONNECT-tunnelling to the
+ * probe host, so the resolved timezone matches the proxy's exit — the whole
+ * point of timezone:"auto". Mirrors what the Python SDK gets from urllib's
+ * ProxyHandler. Returns null on any failure (never falls back to a direct
+ * probe, which would report the machine's real-IP timezone).
+ */
+function egressViaProxy(proxy, timeoutMs) {
+    return new Promise((resolve) => {
+        let pu;
+        let tu;
+        try {
+            pu = new URL(proxy);
+            tu = new URL(EGRESS_PROBE);
+        }
+        catch {
+            return resolve(null);
+        }
+        let settled = false;
+        const done = (ip) => {
+            if (!settled) {
+                settled = true;
+                resolve(ip);
+            }
+        };
+        const headers = {};
+        if (pu.username) {
+            const creds = `${decodeURIComponent(pu.username)}:${decodeURIComponent(pu.password)}`;
+            headers["Proxy-Authorization"] = "Basic " + Buffer.from(creds).toString("base64");
+        }
+        const connectReq = http.request({
+            host: pu.hostname,
+            port: Number(pu.port) || (pu.protocol === "https:" ? 443 : 80),
+            method: "CONNECT",
+            path: `${tu.hostname}:443`,
+            headers,
+            timeout: timeoutMs,
+        });
+        connectReq.on("connect", (res, socket) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                return done(null);
+            }
+            const tlsSock = tls.connect({ socket, servername: tu.hostname }, () => {
+                // HTTP/1.0 so the response isn't chunk-encoded (simpler to parse).
+                tlsSock.write(`GET ${tu.pathname} HTTP/1.0\r\nHost: ${tu.hostname}\r\n` +
+                    `User-Agent: chromiumfish\r\nAccept: application/json\r\nConnection: close\r\n\r\n`);
+            });
+            let raw = "";
+            tlsSock.setEncoding("utf8");
+            tlsSock.setTimeout(timeoutMs, () => {
+                tlsSock.destroy();
+                done(null);
+            });
+            tlsSock.on("data", (d) => (raw += d));
+            tlsSock.on("end", () => {
+                const body = raw.split("\r\n\r\n").slice(1).join("\r\n\r\n");
+                const m = body.match(/\{[\s\S]*\}/);
+                try {
+                    done(m ? JSON.parse(m[0]).ip || null : null);
+                }
+                catch {
+                    done(null);
+                }
+            });
+            tlsSock.on("error", () => done(null));
+        });
+        connectReq.on("error", () => done(null));
+        connectReq.on("timeout", () => {
+            connectReq.destroy();
+            done(null);
+        });
+        connectReq.end();
+    });
+}
+export function egressIp(proxy, timeoutMs = 8000) {
+    if (proxy) {
+        let scheme = "";
+        try {
+            scheme = new URL(proxy).protocol;
+        }
+        catch {
+            /* invalid proxy URL */
+        }
+        if (scheme === "http:" || scheme === "https:")
+            return egressViaProxy(proxy, timeoutMs);
+        // SOCKS / unknown schemes aren't supported for the probe. Return null
+        // (leave the timezone unset) rather than probing the direct connection
+        // and reporting the machine's real-IP timezone — the incoherence we want
+        // to avoid.
+        process.stderr.write(`[chromiumfish] egress probe: unsupported proxy scheme '${scheme || proxy}'; skipping timezone resolution\n`);
+        return Promise.resolve(null);
+    }
+    return egressDirect(timeoutMs);
+}
 export async function resolveTimezone(opts = {}) {
     const { proxy, version = geoipVersion(), download = true } = opts;
     let ip = opts.ip;

package/dist/launcher.d.ts

@@ -6,8 +6,8 @@ import { type Browser, type LaunchOptions } from "playwright-core";
  */
 export declare const BASE_ARGS: string[];
 export interface ChromiumFishOptions extends Omit<LaunchOptions, "executablePath"> {
-    /** Integer seed for a stable, internally-consistent fingerprint persona. */
-    personaSeed?: number;
+    /** String id for a stable, internally-consistent fingerprint persona. */
+    personaSeed?: string;
     /** Run headless (SwiftShader). Defaults to true. */
     headless?: boolean;
     /** Window dimensions; defaults to [1920, 1080]. Pass null to omit. */
@@ -28,6 +28,6 @@ export declare function buildArgs(opts: ChromiumFishOptions): string[];
  * Launch ChromiumFish and return a standard Playwright `Browser`.
  *
  *   import { ChromiumFish } from "chromiumfish";
- *   const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+ *   const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
  */
 export declare function ChromiumFish(opts?: ChromiumFishOptions): Promise<Browser>;

package/dist/launcher.js

@@ -20,8 +20,12 @@ function proxyToUrl(proxy) {
         return undefined;
     const { server, username, password } = proxy;
     if (username && server.includes("://")) {
-        const [scheme, host] = server.split("://", 2);
-        return `${scheme}://${username}:${password ?? ""}@${host}`;
+        const idx = server.indexOf("://");
+        const scheme = server.slice(0, idx);
+        const host = server.slice(idx + 3);
+        // Percent-encode credentials so a password containing ':' / '@' / '/'
+        // can't corrupt the URL; the egress probe decodes them again.
+        return `${scheme}://${encodeURIComponent(username)}:${encodeURIComponent(password ?? "")}@${host}`;
     }
     return server;
 }
@@ -40,7 +44,7 @@ export function buildArgs(opts) {
  * Launch ChromiumFish and return a standard Playwright `Browser`.
  *
  *   import { ChromiumFish } from "chromiumfish";
- *   const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+ *   const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
  */
 export async function ChromiumFish(opts = {}) {
     const { personaSeed, headless = true, windowSize, version, download = true, timezone, args, ...launch } = opts;

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.1.3";
+export declare const SDK_VERSION = "0.1.4";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export declare const DEFAULT_BROWSER_VERSION = "150.0.7844";
 /** Public repo hosting the release assets. */
@@ -26,6 +26,14 @@ export declare const DEFAULT_GEOIP_VERSION = "latest";
  * pointer). Bump occasionally so the offline floor stays recent.
  */
 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",
+ * "latest").
+ */
+export declare function assertSafeVersion(version: string): string;
 export declare function browserVersion(): string;
 export declare function releaseBaseUrl(version?: string): string;
 export declare function geoipVersion(): string;

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.1.3";
+export const SDK_VERSION = "0.1.4";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export const DEFAULT_BROWSER_VERSION = "150.0.7844";
 /** Public repo hosting the release assets. */
@@ -26,14 +26,27 @@ export const DEFAULT_GEOIP_VERSION = "latest";
  * pointer). Bump occasionally so the offline floor stays recent.
  */
 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",
+ * "latest").
+ */
+export function assertSafeVersion(version) {
+    if (!/^[A-Za-z0-9._-]+$/.test(version) || version === "." || version === "..") {
+        throw new Error(`invalid version string: ${JSON.stringify(version)}`);
+    }
+    return version;
+}
 export function browserVersion() {
-    return process.env.CHROMIUMFISH_VERSION || DEFAULT_BROWSER_VERSION;
+    return assertSafeVersion(process.env.CHROMIUMFISH_VERSION || DEFAULT_BROWSER_VERSION);
 }
 export function releaseBaseUrl(version = browserVersion()) {
     return `https://github.com/${RELEASE_REPO}/releases/download/v${version}`;
 }
 export function geoipVersion() {
-    return process.env.CHROMIUMFISH_GEOIP_VERSION || DEFAULT_GEOIP_VERSION;
+    return assertSafeVersion(process.env.CHROMIUMFISH_GEOIP_VERSION || DEFAULT_GEOIP_VERSION);
 }
 export function geoipBaseUrl(version = geoipVersion()) {
     return `https://github.com/${RELEASE_REPO}/releases/download/geoip-${version}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromiumfish",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,13 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "playwright-core": ">=1.40"
+    "playwright-core": ">=1.40",
+    "ws": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^20.0.0",