clearcote 0.6.0 → 0.8.0

package/README.md

@@ -81,6 +81,61 @@ const context = await launchPersistentContext("./profile-7423", {
 });
 ```
 
+### AI agent (OpenRouter)
+
+Drive a page with an **in-browser AI agent** — it perceives the live page, asks an LLM what to do,
+and executes the steps as real, trusted input through Chrome's Actor framework. Defaults to
+[OpenRouter](https://openrouter.ai); switch models with a single slug.
+
+```ts
+import { launchAgent, runAgentTask } from "clearcote";
+
+const ctx = await launchAgent({
+  agentLlmKey: process.env.OPENROUTER_API_KEY,   // turns the agent on
+  agentModel: "openai/gpt-4o-mini",              // any provider/model slug
+});
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+await page.goto("https://example.com");
+
+const result = await runAgentTask(page, "Click the 'More information...' link.", { maxSteps: 8 });
+console.log(result.success, result.finalText, result.steps);
+await ctx.close();
+```
+
+- `agentLlmKey` is all you need — the engine auto-enables Chrome's Actor framework (no extra flags).
+- `agentLlmUrl` points at any OpenAI-compatible endpoint (default OpenRouter); `agentToolMode` is `"tools"` (function-calling) or `"json"`.
+- Override the model per task: `runAgentTask(page, goal, { model: "anthropic/claude-3.5-sonnet" })`.
+- The agent needs a **regular profile** — use `launchAgent` / `launchPersistentContext`, not the incognito `launch()`.
+
+### Capture or import a profile
+
+Make Clearcote present a **real machine's** identity instead of the synthetic seed-derived one. Pass
+a captured fingerprint as `fingerprintProfile` — a file path, a plain object, or a JSON string (the
+SDK gzip+base64-encodes it for the engine):
+
+```ts
+const browser = await launch({
+  fingerprint: "seed-1",                 // still the farbling root / fallback for absent fields
+  fingerprintProfile: "profile.json",    // a real machine's captured identity
+});
+```
+
+Get a profile two ways:
+
+- **Capture** from a donor Chrome — open
+  [`tools/fingerprint-collect/collect.html`](../../tools/fingerprint-collect/README.md) and click
+  Capture, or paste `collect.js` + `snippet.js` in DevTools. Either downloads the JSON.
+- **Convert** the open-source [chrome-fingerprints](https://github.com/Vinyzu/chrome-fingerprints)
+  dataset: `pip install chrome-fingerprints && python tools/fingerprint-collect/convert_dataset.py
+  --out ./profiles --count 100`.
+
+**Override / fallback semantics:** fields present in the profile **override** the `fingerprint`
+seed-derived persona; **absent** fields **fall back** to the seed, so partial profiles stay
+coherent. The SDK also derives `acceptLanguage` from the profile's `navigator.languages` when you
+don't set `acceptLanguage` explicitly. See the
+[collector README](../../tools/fingerprint-collect/README.md) for the full schema and what each
+field drives.
+
 ## Fingerprint options
 
 All optional. Anything not listed here is passed straight through to Playwright
@@ -102,6 +157,7 @@ All optional. Anything not listed here is passed straight through to Playwright
 | `webrtcIp` | `--webrtc-ip` | WebRTC IP to report. The engine **fabricates** the `srflx` candidate at this IP and sends **no real STUN** from the host, so the real IP never leaks (not merely relabeled). |
 | `disableGpuFingerprint` | `--disable-gpu-fingerprint` | Turn off GPU/WebGL spoofing. |
 | `geoip` | _(directive)_ | `true` → resolve the proxy's exit-IP geo and auto-fill timezone/acceptLanguage/location/**webrtcIp**. |
+| `fingerprintProfile` | `--fingerprint-profile` | A real machine's captured fingerprint (file path / object / JSON string; the SDK gzip+base64-encodes it). Fields present override the seed-derived persona; absent fields fall back to `fingerprint`. |
 
 ## API
 

package/dist/agent.d.ts

@@ -0,0 +1,68 @@
+import type { Page } from "playwright-core";
+/** OpenAI-compatible chat-completions endpoints. OpenRouter is the default so you can switch between
+ * any provider/model with a single `agentModel` slug. */
+export declare const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export interface AgentOptions {
+    /**
+     * Base URL of an OpenAI-compatible chat-completions API. Defaults to OpenRouter
+     * (`https://openrouter.ai/api/v1`) when `agentLlmKey` is set. Point it at any OpenAI-compatible
+     * gateway (a local model server, Azure OpenAI, etc.) to use a different backend.
+     */
+    agentLlmUrl?: string;
+    /**
+     * API key (sent as a Bearer token) for the LLM endpoint — e.g. an OpenRouter key. **Setting this
+     * turns the in-browser AI agent on** (and makes the engine auto-enable Chrome's Actor framework).
+     */
+    agentLlmKey?: string;
+    /**
+     * Model slug, e.g. `"openai/gpt-4o-mini"`, `"anthropic/claude-3.5-sonnet"`, `"google/gemini-2.0-flash-001"`
+     * — any model your provider exposes (OpenRouter routes by `provider/model`). Switching models =
+     * switching this one value. Override per task via `runAgentTask(page, goal, { model })`.
+     */
+    agentModel?: string;
+    /**
+     * How the agent gets actions from the model: `"tools"` (OpenAI function-calling) or `"json"`
+     * (a plain JSON reply). Defaults to the engine default; use `"json"` for models without reliable
+     * tool-calling.
+     */
+    agentToolMode?: "tools" | "json" | (string & {});
+}
+export declare const AGENT_KEYS: (keyof AgentOptions)[];
+/** Split an options object into its agent half and the remaining (Playwright/other) half. */
+export declare function splitAgentOptions<T extends AgentOptions>(options: T): {
+    agent: AgentOptions;
+    rest: Omit<T, keyof AgentOptions>;
+};
+/** Build the Chromium switches for the AI agent. Returns `[]` (agent off) unless a key or URL is set. */
+export declare function agentArgs(o: AgentOptions): string[];
+export interface AgentTaskOptions {
+    /** Hard cap on observe→think→act iterations before the agent stops (default: engine default, ~20). */
+    maxSteps?: number;
+    /** Override the launch-time `agentModel` for just this task (any OpenRouter slug). */
+    model?: string;
+    /** Optional JSON plan/hint string passed verbatim to the agent's planner. */
+    planJson?: string;
+}
+/** One recorded step of the agent loop (shape mirrors the engine's step journal). */
+export interface AgentStep {
+    action?: string;
+    status?: string;
+    [k: string]: unknown;
+}
+export interface AgentTaskResult {
+    /** Whether the agent reported the goal as completed (vs. hitting the step limit or erroring). */
+    success: boolean;
+    /** The agent's final message (completion summary, or an error description). */
+    finalText: string;
+    /** Parsed per-step journal (clicks/types/scrolls/navigations and their outcomes). */
+    steps: AgentStep[];
+    /** The raw `stepsJson` string as returned by the engine (in case `steps` failed to parse). */
+    stepsJson: string;
+}
+/**
+ * Run an autonomous AI-agent task against `page`: the engine perceives the page, asks the LLM
+ * (OpenRouter by default) what to do, and executes the actions until the goal is met or `maxSteps`
+ * is reached. The browser must have been launched with `agentLlmKey` (and optionally `agentModel`).
+ */
+export declare function runAgentTask(page: Page, goal: string, opts?: AgentTaskOptions): Promise<AgentTaskResult>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;yDACyD;AACzD,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,UAAU,EAAE,CAAC,MAAM,YAAY,CAAC,EAK5C,CAAC;AAEF,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EACtD,OAAO,EAAE,CAAC,GACT;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,YAAY,CAAC,CAAA;CAAE,CAW5D;AAED,yGAAyG;AACzG,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAQnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA8B1B"}

package/dist/agent.js

@@ -0,0 +1,105 @@
+// In-browser AI agent (OpenRouter / any OpenAI-compatible endpoint).
+//
+//   import { launchAgent, runAgentTask } from "clearcote";
+//   const ctx = await launchAgent({
+//     agentLlmKey: process.env.OPENROUTER_API_KEY,   // turns the agent on
+//     agentModel: "openai/gpt-4o-mini",              // any OpenRouter model slug
+//   });
+//   const page = ctx.pages()[0] ?? (await ctx.newPage());
+//   await page.goto("https://example.com");
+//   const result = await runAgentTask(page, "Click the 'More information...' link.", { maxSteps: 8 });
+//   console.log(result.success, result.finalText, result.steps);
+//
+// The agent runs *inside* the browser process: it perceives the live page, asks the LLM what to do,
+// and drives real (trusted) input through Chrome's Actor framework. Setting `agentLlmKey` (or
+// `agentLlmUrl`) is all that's needed — the engine auto-enables the Actor framework whenever
+// `--agent-llm-url` is present, so no `--enable-features`/`--disable-actor-safety-checks` flags are
+// required. Requires a Clearcote binary that exposes `Browser.agentRunTask`.
+//
+// IMPORTANT — the agent needs a REGULAR profile. Chrome's Actor framework only attaches to a normal
+// (persistent) profile, not an incognito one, so drive the agent from `launchAgent()` or
+// `launchPersistentContext()`. Plain `launch()` returns an incognito browser where the agent can't
+// attach the tab ("Actor service unavailable" / "could not attach tab to task").
+/** OpenAI-compatible chat-completions endpoints. OpenRouter is the default so you can switch between
+ * any provider/model with a single `agentModel` slug. */
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export const AGENT_KEYS = [
+    "agentLlmUrl",
+    "agentLlmKey",
+    "agentModel",
+    "agentToolMode",
+];
+/** Split an options object into its agent half and the remaining (Playwright/other) half. */
+export function splitAgentOptions(options) {
+    const agent = {};
+    const rest = {};
+    for (const [k, v] of Object.entries(options)) {
+        if (AGENT_KEYS.includes(k)) {
+            agent[k] = v;
+        }
+        else {
+            rest[k] = v;
+        }
+    }
+    return { agent, rest: rest };
+}
+/** Build the Chromium switches for the AI agent. Returns `[]` (agent off) unless a key or URL is set. */
+export function agentArgs(o) {
+    const args = [];
+    if (o.agentLlmKey == null && o.agentLlmUrl == null)
+        return args;
+    args.push(`--agent-llm-url=${o.agentLlmUrl ?? OPENROUTER_BASE_URL}`);
+    if (o.agentLlmKey != null)
+        args.push(`--agent-llm-key=${o.agentLlmKey}`);
+    if (o.agentModel != null)
+        args.push(`--agent-model=${o.agentModel}`);
+    if (o.agentToolMode != null)
+        args.push(`--agent-tool-mode=${o.agentToolMode}`);
+    return args;
+}
+async function pageTargetId(page) {
+    const s = await page.context().newCDPSession(page);
+    const info = await s.send("Target.getTargetInfo");
+    return info.targetInfo.targetId;
+}
+/**
+ * Run an autonomous AI-agent task against `page`: the engine perceives the page, asks the LLM
+ * (OpenRouter by default) what to do, and executes the actions until the goal is met or `maxSteps`
+ * is reached. The browser must have been launched with `agentLlmKey` (and optionally `agentModel`).
+ */
+export async function runAgentTask(page, goal, opts = {}) {
+    const browser = page.context().browser();
+    if (!browser)
+        throw new Error("runAgentTask: page is not attached to a Browser");
+    const session = await browser.newBrowserCDPSession();
+    const params = { targetId: await pageTargetId(page), goal };
+    if (opts.maxSteps != null)
+        params.maxSteps = opts.maxSteps;
+    if (opts.model != null)
+        params.model = opts.model;
+    if (opts.planJson != null)
+        params.planJson = opts.planJson;
+    let res;
+    try {
+        res = await session.send("Browser.agentRunTask", params);
+    }
+    catch (e) {
+        throw new Error("Browser.agentRunTask failed — make sure this is a Clearcote build with the AI agent and that " +
+            "the browser was launched with agentLlmKey/agentLlmUrl set. Underlying error: " +
+            e.message);
+    }
+    let steps = [];
+    try {
+        steps = JSON.parse(res.stepsJson || "[]");
+    }
+    catch {
+        /* leave steps = [] */
+    }
+    return {
+        success: !!res.success,
+        finalText: res.finalText ?? "",
+        steps,
+        stepsJson: res.stepsJson ?? "[]",
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAsbA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhF"}

package/dist/cli.js

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+// clearcote-agent — a terminal wrapper around Clearcote's in-browser AI agent.
+//
+// Launches a REGULAR-profile Clearcote (anti-detect Chromium), points it at OpenRouter, and runs
+// natural-language goals on a page via the SDK. The agent perceives the page, asks an LLM, and acts
+// via Chrome's Actor framework.
+//
+//   clearcote-agent --goal "Click the 'More information...' link" --url https://example.com
+//   clearcote-agent -i --url https://example.com           # interactive REPL
+//
+// The agent only works in a regular/persistent profile, so this always uses launchAgent() (never the
+// incognito launch()). Logins/cookies persist in --profile so you can sign in once and reuse it.
+import { parseArgs } from "node:util";
+import * as readline from "node:readline";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { launchAgent, runAgentTask } from "./index.js";
+const USAGE = `clearcote-agent — run natural-language goals on a page via Clearcote's in-browser AI agent.
+
+USAGE
+  clearcote-agent --goal <text> [--url <url>] [options]      one-shot
+  clearcote-agent -i|--interactive [--url <url>] [options]   interactive REPL
+
+OPTIONS
+  --goal <text>        the task (required in one-shot; optional in REPL)
+  --url <url>          starting page (default: about:blank)
+  -i, --interactive    REPL mode (always headed + persistent)
+  --model <slug>       OpenRouter provider/model slug (default: openai/gpt-4o)
+  --key <k>            OpenRouter API key (env OPENROUTER_API_KEY or CLEARCOTE_AGENT_KEY)
+  --llm-url <url>      OpenAI-compatible base URL (default: OpenRouter)
+  --tool-mode <m>      "tools" | "json"
+  --max-steps <n>      max agent steps (default: 20)
+  --profile <dir>      persistent profile dir (default: ~/.clearcote/agent-profile)
+  --headless           run headless (default: headed; ignored in REPL)
+  --executable <path>  path to Clearcote chrome.exe (else auto-download / CLEARCOTE_BINARY)
+  --fingerprint <seed> anti-detect fingerprint seed
+  --proxy <url>        proxy, e.g. http://user:pass@host:port
+  --timezone <tz>      IANA timezone, e.g. America/New_York
+  --json               one-shot only: print the raw result object as JSON (logs to stderr)
+  -h, --help           show this help
+
+REPL COMMANDS
+  :goto <url>   navigate the current page
+  :url          print the current URL
+  :model <slug> change the model for subsequent goals
+  :steps <n>    change max-steps
+  :help         list commands
+  :quit, :exit  close and exit (Ctrl-D also quits)
+  <anything>    run as a goal against the current page`;
+/** Friendly, expected-condition error — no stack trace, custom exit code. */
+class UsageError extends Error {
+    code;
+    constructor(message, code = 2) {
+        super(message);
+        this.code = code;
+        this.name = "UsageError";
+    }
+}
+/** Log to stderr (results go to stdout). */
+function log(msg) {
+    process.stderr.write(msg + "\n");
+}
+/** Parse a proxy URL into a Playwright proxy descriptor, splitting credentials out of the userinfo. */
+function parseProxy(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new UsageError(`Invalid --proxy URL: ${raw}`);
+    }
+    const proxy = { server: `${u.protocol}//${u.host}` };
+    if (u.username)
+        proxy.username = decodeURIComponent(u.username);
+    if (u.password)
+        proxy.password = decodeURIComponent(u.password);
+    return proxy;
+}
+/** Validate a starting URL (about:blank or anything URL-parseable). A bare host like "example.com"
+ * is upgraded to https:// so users don't have to type the scheme. Returns the normalized URL. */
+function validateUrl(raw) {
+    if (raw === "about:blank")
+        return raw;
+    try {
+        new URL(raw);
+        return raw;
+    }
+    catch {
+        try {
+            const upgraded = "https://" + raw;
+            new URL(upgraded);
+            return upgraded;
+        }
+        catch {
+            throw new UsageError(`Invalid --url: ${raw}`);
+        }
+    }
+}
+/** Parse a positive-integer step count. */
+function parseMaxSteps(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new UsageError(`Invalid --max-steps (expected a positive integer): ${raw}`);
+    }
+    return n;
+}
+/** Render a result to stdout in human form (header already printed by caller). */
+function printResult(result, currentUrl) {
+    process.stdout.write((result.success ? "OK" : "FAIL") + "\n");
+    if (result.finalText)
+        process.stdout.write(result.finalText + "\n");
+    if (result.steps.length) {
+        process.stdout.write("\nsteps:\n");
+        result.steps.forEach((step, i) => {
+            const action = step.action ?? "(step)";
+            const status = step.status != null ? ` [${step.status}]` : "";
+            const fields = [];
+            for (const [k, v] of Object.entries(step)) {
+                if (k === "action" || k === "status")
+                    continue;
+                if (v == null)
+                    continue;
+                const s = typeof v === "string" ? v : JSON.stringify(v);
+                fields.push(`${k}=${s.length > 80 ? s.slice(0, 77) + "..." : s}`);
+            }
+            const detail = fields.length ? ` ${fields.join(" ")}` : "";
+            process.stdout.write(`  ${i + 1}. ${action}${detail}${status}\n`);
+        });
+    }
+    process.stdout.write(`\nurl: ${currentUrl}\n`);
+}
+/** Parse + validate process argv into a normalized Cli config. Throws UsageError on bad input. */
+function parseCli(argv) {
+    const config = {
+        args: argv,
+        allowPositionals: false,
+        strict: true,
+        options: {
+            goal: { type: "string" },
+            url: { type: "string" },
+            interactive: { type: "boolean", short: "i" },
+            model: { type: "string" },
+            key: { type: "string" },
+            "llm-url": { type: "string" },
+            "tool-mode": { type: "string" },
+            "max-steps": { type: "string" },
+            profile: { type: "string" },
+            headless: { type: "boolean" },
+            executable: { type: "string" },
+            fingerprint: { type: "string" },
+            proxy: { type: "string" },
+            timezone: { type: "string" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    };
+    let values;
+    try {
+        ({ values } = parseArgs(config));
+    }
+    catch (e) {
+        throw new UsageError(e.message);
+    }
+    if (values.help)
+        return { cli: {}, help: true };
+    const key = values.key ??
+        process.env.OPENROUTER_API_KEY ??
+        process.env.CLEARCOTE_AGENT_KEY;
+    if (!key) {
+        throw new UsageError("No OpenRouter API key. Pass --key <k>, or set OPENROUTER_API_KEY or CLEARCOTE_AGENT_KEY.");
+    }
+    const interactive = !!values.interactive;
+    const goal = values.goal;
+    if (!interactive && (goal == null || goal.trim() === "")) {
+        throw new UsageError("Missing --goal. Provide a task with --goal <text>, or use -i for the REPL.");
+    }
+    const url = validateUrl(values.url ?? "about:blank");
+    const maxSteps = values["max-steps"] != null ? parseMaxSteps(values["max-steps"]) : 20;
+    const proxy = values.proxy != null ? parseProxy(values.proxy) : undefined;
+    let headless = !!values.headless;
+    if (interactive && headless) {
+        log("warning: --headless is ignored in interactive mode (REPL is always headed).");
+        headless = false;
+    }
+    const profile = values.profile ?? join(homedir(), ".clearcote", "agent-profile");
+    return {
+        cli: {
+            goal,
+            url,
+            interactive,
+            model: values.model ?? "openai/gpt-4o",
+            key,
+            llmUrl: values["llm-url"],
+            toolMode: values["tool-mode"],
+            maxSteps,
+            profile,
+            headless,
+            executable: values.executable,
+            fingerprint: values.fingerprint,
+            proxy,
+            timezone: values.timezone,
+            json: !!values.json,
+        },
+        help: false,
+    };
+}
+/** Build the launchAgent options from the parsed config. */
+function launchOptions(cli) {
+    mkdirSync(cli.profile, { recursive: true });
+    return {
+        userDataDir: cli.profile,
+        agentLlmKey: cli.key,
+        agentLlmUrl: cli.llmUrl,
+        agentModel: cli.model,
+        agentToolMode: cli.toolMode,
+        headless: cli.headless,
+        proxy: cli.proxy,
+        fingerprint: cli.fingerprint,
+        timezone: cli.timezone,
+        executablePath: cli.executable,
+    };
+}
+/** Resolve the page to drive (reuse the first open page, else create one). */
+async function currentPage(ctx) {
+    return ctx.pages()[0] ?? (await ctx.newPage());
+}
+/** One-shot: launch -> goto -> run goal -> print -> close. Returns the process exit code. */
+async function runOneShot(cli) {
+    log(`launching Clearcote (profile: ${cli.profile})...`);
+    const ctx = await launchAgent(launchOptions(cli));
+    try {
+        const page = await currentPage(ctx);
+        if (cli.url !== "about:blank") {
+            log(`navigating to ${cli.url}...`);
+            await page.goto(cli.url);
+        }
+        if (!cli.json)
+            process.stdout.write(`goal: ${cli.goal}\n`);
+        log(`running (${cli.model}, up to ${cli.maxSteps} steps)...`);
+        const result = await runAgentTask(page, cli.goal, {
+            model: cli.model,
+            maxSteps: cli.maxSteps,
+        });
+        const finalUrl = page.url();
+        if (cli.json) {
+            process.stdout.write(JSON.stringify({ ...result, url: finalUrl }, null, 2) + "\n");
+        }
+        else {
+            printResult(result, finalUrl);
+        }
+        return result.success ? 0 : 1;
+    }
+    finally {
+        await ctx.close();
+    }
+}
+/** Interactive REPL: persistent headed session; each non-':' line is a goal on the current page. */
+async function runRepl(cli) {
+    log(`launching Clearcote (profile: ${cli.profile})...`);
+    const ctx = await launchAgent(launchOptions(cli));
+    let page = await currentPage(ctx);
+    if (cli.url !== "about:blank") {
+        log(`navigating to ${cli.url}...`);
+        await page.goto(cli.url);
+    }
+    let model = cli.model;
+    let maxSteps = cli.maxSteps;
+    log("interactive mode. Type a goal, or :help for commands. Ctrl-D to quit.");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: "agent> " });
+    const replHelp = [
+        "commands:",
+        "  :goto <url>   navigate the current page",
+        "  :url          print the current URL",
+        "  :model <slug> change the model for subsequent goals",
+        "  :steps <n>    change max-steps",
+        "  :help         this help",
+        "  :quit, :exit  close and exit",
+        "  <anything>    run as a goal against the current page",
+    ].join("\n");
+    return await new Promise((resolve) => {
+        let closing = false;
+        const finish = () => {
+            if (closing)
+                return;
+            closing = true;
+            rl.close();
+            ctx
+                .close()
+                .catch((e) => log(`warning: closing browser failed: ${e.message}`))
+                .finally(() => resolve(0));
+        };
+        // Process one input line (a ':' command or a goal); resolves when it fully settles.
+        const processLine = async (line) => {
+            if (line.startsWith(":")) {
+                const sp = line.indexOf(" ");
+                const cmd = (sp === -1 ? line : line.slice(0, sp)).toLowerCase();
+                const arg = sp === -1 ? "" : line.slice(sp + 1).trim();
+                switch (cmd) {
+                    case ":quit":
+                    case ":exit":
+                        finish();
+                        return;
+                    case ":help":
+                        log(replHelp);
+                        break;
+                    case ":url":
+                        process.stdout.write(page.url() + "\n");
+                        break;
+                    case ":goto": {
+                        if (!arg) {
+                            log("usage: :goto <url>");
+                            break;
+                        }
+                        let target;
+                        try {
+                            target = validateUrl(arg);
+                        }
+                        catch (e) {
+                            log(e.message);
+                            break;
+                        }
+                        try {
+                            await page.goto(target);
+                            process.stdout.write(page.url() + "\n");
+                        }
+                        catch (e) {
+                            log(`navigation failed: ${e.message}`);
+                        }
+                        break;
+                    }
+                    case ":model":
+                        if (!arg) {
+                            log(`model: ${model}`);
+                            break;
+                        }
+                        model = arg;
+                        log(`model set to ${model}`);
+                        break;
+                    case ":steps":
+                        if (!arg) {
+                            log(`max-steps: ${maxSteps}`);
+                            break;
+                        }
+                        try {
+                            maxSteps = parseMaxSteps(arg);
+                            log(`max-steps set to ${maxSteps}`);
+                        }
+                        catch (e) {
+                            log(e.message);
+                        }
+                        break;
+                    default:
+                        log(`unknown command: ${cmd} (try :help)`);
+                }
+                return;
+            }
+            // A goal line.
+            process.stdout.write(`goal: ${line}\n`);
+            log(`running (${model}, up to ${maxSteps} steps)...`);
+            // Re-resolve the page in case the previous one was closed.
+            page = await currentPage(ctx);
+            const result = await runAgentTask(page, line, { model, maxSteps });
+            printResult(result, page.url());
+        };
+        // Serialize input: pause stdin while a goal/command runs so a second Enter can't start a
+        // concurrent goal against the shared page; resume + re-prompt once it settles.
+        const pump = (line) => {
+            rl.pause();
+            processLine(line)
+                .catch((e) => log(`error: ${e.message}`))
+                .finally(() => {
+                if (!closing) {
+                    rl.resume();
+                    rl.prompt();
+                }
+            });
+        };
+        // If a --goal was passed alongside -i, run it as the first goal before the prompt loop.
+        const initial = cli.goal?.trim();
+        if (initial) {
+            pump(initial);
+        }
+        else {
+            rl.prompt();
+        }
+        rl.on("line", (raw) => {
+            const line = raw.trim();
+            if (line === "") {
+                rl.prompt();
+                return;
+            }
+            pump(line);
+        });
+        rl.on("close", finish);
+    });
+}
+export async function main(argv = process.argv.slice(2)) {
+    let cli;
+    try {
+        const parsed = parseCli(argv);
+        if (parsed.help) {
+            process.stdout.write(USAGE + "\n");
+            return;
+        }
+        cli = parsed.cli;
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            log(e.message);
+            process.exitCode = e.code;
+            return;
+        }
+        throw e;
+    }
+    try {
+        process.exitCode = cli.interactive ? await runRepl(cli) : await runOneShot(cli);
+    }
+    catch (e) {
+        log(`error: ${e.message}`);
+        process.exitCode = 1;
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/fingerprint.d.ts

@@ -31,7 +31,20 @@ export interface FingerprintOptions {
     acceptLanguage?: string;
     /** WebRTC egress IP to report (typically your proxy's public IP). */
     webrtcIp?: string;
-    /** Turn OFF GPU/WebGL fingerprint spoofing (advertise the real backend). */
+    /**
+     * Present the machine's **real GPU** instead of a spoofed one. WebGL `UNMASKED_VENDOR`/`RENDERER`,
+     * the `getParameter` table, and the canvas/WebGL render all report the genuine host backend. This
+     * is the most coherent setting against strict browser-tampering classifiers: the GPU string and
+     * the actually-rendered pixels match, so there is no GPU spoof to catch (the same reason a stock
+     * browser passes). Composes with `fingerprintProfile` — the profile still supplies
+     * screen/fonts/audio/hardware, but the **real host GPU is kept** instead of the profile's GPU
+     * (which the host cannot actually render, and would otherwise be a string-vs-render mismatch).
+     * Pair with `fingerprintNoise: false` so the canvas/WebGL readback isn't perturbed either.
+     *
+     * Trade-off: every persona on one physical machine then shares the same canvas/WebGL identity, so
+     * a tracker can link them by GPU hash. Best for single-identity / one-persona-per-host use; for
+     * multi-account-on-one-machine, keep this off and instead match the profile's GPU to the host.
+     */
     disableGpuFingerprint?: boolean;
     /**
      * Set `false` to turn OFF the per-eTLD+1 farbling NOISE (canvas/WebGL/audio/client-rects), so
@@ -40,6 +53,19 @@ export interface FingerprintOptions {
      * stay on. Default (unset/`true`) keeps the noise.
      */
     fingerprintNoise?: boolean;
+    /**
+     * Import a real captured fingerprint so the browser presents *that machine's* identity instead
+     * of the synthetic seed-derived one. Accepts a path to a `.json` profile, a profile object, or a
+     * JSON string (capture one with `tools/fingerprint-collect`). Fields present in the profile
+     * override the seed-derived persona; absent fields fall back to the seed, so partial profiles
+     * stay coherent.
+     */
+    fingerprintProfile?: string | Record<string, unknown>;
+    /**
+     * `navigator.storage.estimate().quota` in **megabytes**. A tiny/ephemeral quota reads as a test
+     * machine or incognito; set a realistic on-disk value (e.g. `250000` for ~244 GB).
+     */
+    storageQuota?: number;
 }
 /** Split an options object into its fingerprint half and the remaining (Playwright) half. */
 export declare function splitFingerprintOptions<T extends FingerprintOptions>(options: T): {
@@ -50,6 +76,13 @@ export declare function splitFingerprintOptions<T extends FingerprintOptions>(op
  * tag list with NO `;q=` weights or spaces (Chromium adds the q-weights to the header itself; a
  * `;` in the switch value trips a DCHECK and crashes the renderer). */
 export declare function cleanAcceptLanguage(v: string): string;
+/** Encode a captured clearcote-profile for the `--fingerprint-profile` switch. `value` may be a
+ * path to a `.json` file, a profile object, or a JSON string. gzip+base64 keeps the full capture
+ * (~40 KB) within Chromium's command-line length limit (gzip ~6x); the engine gunzips + parses it. */
+export declare function encodeProfile(value: string | Record<string, unknown>): string;
+/** Best-effort: derive an Accept-Language from an imported profile's navigator.languages
+ * (path / object / JSON string), so an imported identity keeps the donor's language order. */
+export declare function profileAcceptLanguage(value: string | Record<string, unknown>): string | undefined;
 /** Build the Chromium switches for a set of fingerprint options. */
 export declare function fingerprintArgs(o: FingerprintOptions): string[];
 //# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACzC,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChE,qBAAqB;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAmBD,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,EAClE,OAAO,EAAE,CAAC,GACT;IAAE,WAAW,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,kBAAkB,CAAC,CAAA;CAAE,CAW9E;AAED;;uEAEuE;AACvE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,EAAE,CA4B/D"}
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACzC,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChE,qBAAqB;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtD;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAqBD,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,EAClE,OAAO,EAAE,CAAC,GACT;IAAE,WAAW,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,kBAAkB,CAAC,CAAA;CAAE,CAW9E;AAED;;uEAEuE;AACvE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;sGAEsG;AACtG,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAU7E;AAED;8FAC8F;AAC9F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAajG;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAiD/D"}

package/dist/fingerprint.js

@@ -1,5 +1,7 @@
 // Maps the SDK's fingerprint options to the Clearcote Chromium command-line switches.
 // Switch names mirror components/ungoogled/ungoogled_switches.cc (see patches/000-fingerprint-switches.patch).
+import { gzipSync } from "node:zlib";
+import { existsSync, readFileSync } from "node:fs";
 const FINGERPRINT_KEYS = [
     "fingerprint",
     "platform",
@@ -15,6 +17,8 @@ const FINGERPRINT_KEYS = [
     "webrtcIp",
     "disableGpuFingerprint",
     "fingerprintNoise",
+    "fingerprintProfile",
+    "storageQuota",
 ];
 /** Split an options object into its fingerprint half and the remaining (Playwright) half. */
 export function splitFingerprintOptions(options) {
@@ -40,6 +44,43 @@ export function cleanAcceptLanguage(v) {
         .filter(Boolean)
         .join(",");
 }
+/** Encode a captured clearcote-profile for the `--fingerprint-profile` switch. `value` may be a
+ * path to a `.json` file, a profile object, or a JSON string. gzip+base64 keeps the full capture
+ * (~40 KB) within Chromium's command-line length limit (gzip ~6x); the engine gunzips + parses it. */
+export function encodeProfile(value) {
+    let raw;
+    if (typeof value === "object") {
+        raw = Buffer.from(JSON.stringify(value));
+    }
+    else if (existsSync(value)) {
+        raw = readFileSync(value);
+    }
+    else {
+        raw = Buffer.from(value); // assume a JSON string
+    }
+    return gzipSync(raw, { level: 9 }).toString("base64");
+}
+/** Best-effort: derive an Accept-Language from an imported profile's navigator.languages
+ * (path / object / JSON string), so an imported identity keeps the donor's language order. */
+export function profileAcceptLanguage(value) {
+    let obj;
+    try {
+        if (typeof value === "object")
+            obj = value;
+        else if (existsSync(value))
+            obj = JSON.parse(readFileSync(value, "utf8"));
+        else
+            obj = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    const nav = obj?.navigator;
+    const langs = nav?.languages;
+    if (Array.isArray(langs) && langs.length)
+        return langs.map(String).join(",");
+    return undefined;
+}
 /** Build the Chromium switches for a set of fingerprint options. */
 export function fingerprintArgs(o) {
     const args = [];
@@ -60,9 +101,25 @@ export function fingerprintArgs(o) {
     set("fingerprint-gpu-renderer", o.gpuRenderer);
     set("fingerprint-hardware-concurrency", o.hardwareConcurrency);
     set("fingerprint-location", o.location);
+    set("fingerprint-storage-quota", o.storageQuota);
     set("timezone", o.timezone);
-    if (o.acceptLanguage)
-        args.push(`--accept-lang=${cleanAcceptLanguage(String(o.acceptLanguage))}`);
+    // Always send a coherent Accept-Language. Without --accept-lang Chromium falls back to the
+    // build/OS locale, which can leak a language that mismatches the proxy's country/timezone
+    // (e.g. en-GB on a US IP) — a geo-inconsistency tell. Prefer an explicit value, then an imported
+    // profile's languages, then en-US,en (the common Chrome default; set acceptLanguage or geoip to
+    // match the proxy region).
+    const acceptLanguage = o.acceptLanguage ||
+        (o.fingerprintProfile ? profileAcceptLanguage(o.fingerprintProfile) : undefined) ||
+        "en-US,en";
+    const cleanLang = cleanAcceptLanguage(String(acceptLanguage));
+    args.push(`--accept-lang=${cleanLang}`);
+    // Also pin the UI/ICU locale to the PRIMARY Accept-Language tag, so Intl.DateTimeFormat /
+    // NumberFormat / Collator (main thread AND workers) resolve to the same locale as
+    // navigator.language. Without --lang, Chromium falls back to the build/OS locale (e.g. en-GB on an
+    // en-US persona) — a locale-incoherence tell auditors flag (navigator.language=en-US but Intl=en-GB).
+    const primaryLang = cleanLang.split(",")[0];
+    if (primaryLang)
+        args.push(`--lang=${primaryLang}`);
     set("webrtc-ip", o.webrtcIp);
     if (o.disableGpuFingerprint)
         args.push("--disable-gpu-fingerprint");
@@ -71,6 +128,11 @@ export function fingerprintArgs(o) {
     // Identity spoofs (UA/screen/GPU/persona) stay on. Default keeps the noise.
     if (o.fingerprintNoise === false)
         args.push("--disable-fingerprint-noise");
+    // fingerprintProfile imports a real captured fingerprint (path/object/JSON) — see
+    // tools/fingerprint-collect. Its fields override the seed-derived persona; absent fields fall
+    // back to the seed, so partial profiles stay coherent.
+    if (o.fingerprintProfile)
+        args.push(`--fingerprint-profile=${encodeProfile(o.fingerprintProfile)}`);
     return args;
 }
 //# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -1 +1 @@
-{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,21 +2,23 @@ import type { Browser, BrowserContext, BrowserContextOptions, LaunchOptions as P
 import { type DownloadOptions } from "./download.js";
 import { type FingerprintOptions } from "./fingerprint.js";
 import { type HumanizeOptions } from "./humanize.js";
+import { type AgentOptions } from "./agent.js";
 export type { FingerprintOptions } from "./fingerprint.js";
 export type { DownloadOptions } from "./download.js";
 export { resolveGeo, type Geo } from "./geoip.js";
 export type { HumanizeOptions } from "./humanize.js";
+export { runAgentTask, agentArgs, OPENROUTER_BASE_URL, type AgentOptions, type AgentTaskOptions, type AgentTaskResult, type AgentStep, } from "./agent.js";
 export { RELEASE } from "./release.js";
 /** When true (and a proxy is set), resolve the proxy's exit-IP geo and auto-fill any unset
  * `timezone` + `acceptLanguage` (+ `location`) so they match the proxy region. */
 interface GeoipOption {
     geoip?: boolean;
 }
-/** Options for {@link launch}: Playwright launch options + Clearcote fingerprint + download options. */
-export interface LaunchOptions extends PlaywrightLaunchOptions, FingerprintOptions, GeoipOption, HumanizeOptions, DownloadOptions {
+/** Options for {@link launch}: Playwright launch options + Clearcote fingerprint + agent + download options. */
+export interface LaunchOptions extends PlaywrightLaunchOptions, FingerprintOptions, AgentOptions, GeoipOption, HumanizeOptions, DownloadOptions {
 }
 /** Options for {@link launchPersistentContext}. */
-export interface PersistentContextOptions extends PlaywrightLaunchOptions, BrowserContextOptions, FingerprintOptions, GeoipOption, HumanizeOptions, DownloadOptions {
+export interface PersistentContextOptions extends PlaywrightLaunchOptions, BrowserContextOptions, FingerprintOptions, AgentOptions, GeoipOption, HumanizeOptions, DownloadOptions {
 }
 /**
  * Resolve the Clearcote chrome.exe path, downloading + verifying it if needed.
@@ -34,11 +36,37 @@ export declare function launch(options?: LaunchOptions): Promise<Browser>;
  * {@link BrowserContext} (cookies, storage, etc. persist in `userDataDir`).
  */
 export declare function launchPersistentContext(userDataDir: string, options?: PersistentContextOptions): Promise<BrowserContext>;
+/** Options for {@link launchAgent}: persistent-context options + an optional `userDataDir`. */
+export interface LaunchAgentOptions extends PersistentContextOptions {
+    /** Profile directory to persist (cookies/storage/logins). Defaults to a fresh temp dir. */
+    userDataDir?: string;
+}
+/**
+ * Launch Clearcote ready for the in-browser AI agent and return a Playwright {@link BrowserContext}.
+ *
+ * The agent drives Chrome's Actor framework, which only attaches to a **regular profile** — not
+ * incognito — so this uses a *persistent* context (a fresh temp `userDataDir` unless you pass one).
+ * Set `agentLlmKey` (+ optional `agentModel`), then drive a page with {@link runAgentTask}:
+ *
+ * ```ts
+ * const ctx = await launchAgent({ agentLlmKey: process.env.OPENROUTER_API_KEY, agentModel: "openai/gpt-4o-mini" });
+ * const page = ctx.pages()[0] ?? (await ctx.newPage());
+ * await page.goto("https://example.com");
+ * const result = await runAgentTask(page, "Click the 'More information...' link.");
+ * ```
+ *
+ * Use this (or {@link launchPersistentContext}) for the agent — plain {@link launch} is incognito,
+ * where the Actor framework can't attach the tab.
+ */
+export declare function launchAgent(options?: LaunchAgentOptions): Promise<BrowserContext>;
+import { runAgentTask } from "./agent.js";
 declare const _default: {
     launch: typeof launch;
     launchPersistentContext: typeof launchPersistentContext;
+    launchAgent: typeof launchAgent;
     executablePath: typeof executablePath;
     download: typeof download;
+    runAgentTask: typeof runAgentTask;
     RELEASE: import("./release.js").ReleaseInfo;
 };
 export default _default;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,qBAAqB,EACrB,aAAa,IAAI,uBAAuB,EACzC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAA4C,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAErG,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhG,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;kFACkF;AAClF,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAc,SAAQ,uBAAuB,EAAE,kBAAkB,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe;CAAG;AAEpI,mDAAmD;AACnD,MAAM,WAAW,wBACf,SAAQ,uBAAuB,EAC7B,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,eAAe;CAAG;AAwBtB;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,eAAoB,GAC1D,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,iGAAiG;AACjG,wBAAsB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED,yEAAyE;AACzE,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAa1E;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,cAAc,CAAC,CAazB;;;;;;;;AAED,wBAAsF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,qBAAqB,EACrB,aAAa,IAAI,uBAAuB,EACzC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAA4C,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAErG,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAG7E,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,YAAY,EACZ,SAAS,EACT,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;kFACkF;AAClF,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,gHAAgH;AAChH,MAAM,WAAW,aAAc,SAAQ,uBAAuB,EAAE,kBAAkB,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe;CAAG;AAElJ,mDAAmD;AACnD,MAAM,WAAW,wBACf,SAAQ,uBAAuB,EAC7B,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,eAAe;CAAG;AAwBtB;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,eAAoB,GAC1D,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,iGAAiG;AACjG,wBAAsB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED,yEAAyE;AACzE,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAc1E;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,cAAc,CAAC,CAczB;AAED,+FAA+F;AAC/F,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAClE,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CAI3F;AAED,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;;;;;;;;;;AAC1C,wBAAiH"}

package/dist/index.js

@@ -10,12 +10,17 @@
 // (headless, proxy, args, timeout, ...) passes through; the fingerprint options below are added
 // as engine switches.
 import { chromium } from "playwright-core";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { ensureBinary } from "./download.js";
 import { fingerprintArgs, splitFingerprintOptions } from "./fingerprint.js";
 import { resolveGeo } from "./geoip.js";
 import { installHumanize, installHumanizeOnContext } from "./humanize.js";
+import { agentArgs, splitAgentOptions } from "./agent.js";
 import { RELEASE } from "./release.js";
 export { resolveGeo } from "./geoip.js";
+export { runAgentTask, agentArgs, OPENROUTER_BASE_URL, } from "./agent.js";
 export { RELEASE } from "./release.js";
 /** Fill unset timezone/acceptLanguage/location/webrtcIp on `fp` from the proxy's exit-IP geo. */
 async function applyGeoip(fp, proxy) {
@@ -58,7 +63,8 @@ export async function download(options = {}) {
 /** Launch Clearcote and return a standard Playwright {@link Browser}. */
 export async function launch(options = {}) {
     const { executablePath: exeOption, args, geoip, humanize, showCursor, autoUpdate, cacheDir, quiet, ...rest } = options;
-    const { fingerprint, rest: pwOptions } = splitFingerprintOptions(rest);
+    const { fingerprint, rest: afterFp } = splitFingerprintOptions(rest);
+    const { agent, rest: pwOptions } = splitAgentOptions(afterFp);
     if (geoip)
         await applyGeoip(fingerprint, pwOptions.proxy);
     const exe = await executablePath({ executablePath: exeOption, autoUpdate, cacheDir, quiet });
@@ -66,7 +72,7 @@ export async function launch(options = {}) {
     const browser = await chromium.launch({
         ...pwOptions,
         executablePath: exe,
-        args: [...fingerprintArgs(fingerprint), ...(args ?? [])],
+        args: [...fingerprintArgs(fingerprint), ...agentArgs(agent), ...(args ?? [])],
     });
     installHumanize(browser, { humanize, showCursor });
     return browser;
@@ -77,7 +83,8 @@ export async function launch(options = {}) {
  */
 export async function launchPersistentContext(userDataDir, options = {}) {
     const { executablePath: exeOption, args, geoip, humanize, showCursor, autoUpdate, cacheDir, quiet, ...rest } = options;
-    const { fingerprint, rest: pwOptions } = splitFingerprintOptions(rest);
+    const { fingerprint, rest: afterFp } = splitFingerprintOptions(rest);
+    const { agent, rest: pwOptions } = splitAgentOptions(afterFp);
     if (geoip)
         await applyGeoip(fingerprint, pwOptions.proxy);
     const exe = await executablePath({ executablePath: exeOption, autoUpdate, cacheDir, quiet });
@@ -85,10 +92,33 @@ export async function launchPersistentContext(userDataDir, options = {}) {
     const context = await chromium.launchPersistentContext(userDataDir, {
         ...pwOptions,
         executablePath: exe,
-        args: [...fingerprintArgs(fingerprint), ...(args ?? [])],
+        args: [...fingerprintArgs(fingerprint), ...agentArgs(agent), ...(args ?? [])],
     });
     installHumanizeOnContext(context, { humanize, showCursor });
     return context;
 }
-export default { launch, launchPersistentContext, executablePath, download, RELEASE };
+/**
+ * Launch Clearcote ready for the in-browser AI agent and return a Playwright {@link BrowserContext}.
+ *
+ * The agent drives Chrome's Actor framework, which only attaches to a **regular profile** — not
+ * incognito — so this uses a *persistent* context (a fresh temp `userDataDir` unless you pass one).
+ * Set `agentLlmKey` (+ optional `agentModel`), then drive a page with {@link runAgentTask}:
+ *
+ * ```ts
+ * const ctx = await launchAgent({ agentLlmKey: process.env.OPENROUTER_API_KEY, agentModel: "openai/gpt-4o-mini" });
+ * const page = ctx.pages()[0] ?? (await ctx.newPage());
+ * await page.goto("https://example.com");
+ * const result = await runAgentTask(page, "Click the 'More information...' link.");
+ * ```
+ *
+ * Use this (or {@link launchPersistentContext}) for the agent — plain {@link launch} is incognito,
+ * where the Actor framework can't attach the tab.
+ */
+export async function launchAgent(options = {}) {
+    const { userDataDir, ...rest } = options;
+    const dir = userDataDir ?? mkdtempSync(join(tmpdir(), "clearcote-agent-"));
+    return launchPersistentContext(dir, rest);
+}
+import { runAgentTask } from "./agent.js";
+export default { launch, launchPersistentContext, launchAgent, executablePath, download, runAgentTask, RELEASE };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/release.js

@@ -4,13 +4,13 @@
 // this package, the hash check guarantees you run exactly the published, signed binary.
 // Published checksums + GPG signatures live on the release page.
 export const RELEASE = {
-    tag: "v0.1.0-pre.7",
+    tag: "v0.1.0-pre.10",
     version: "149.0.7827.114",
     asset: "clearcote-149.0.7827.114-windows-x64.zip",
-    url: "https://github.com/clearcotelabs/clearcote-browser/releases/download/v0.1.0-pre.7/clearcote-149.0.7827.114-windows-x64.zip",
-    sha256: "85417dacb82d074a9f23ff326fb9837df3387e4c72b0c628c21d8d407d5f6f58",
+    url: "https://github.com/clearcotelabs/clearcote-browser/releases/download/v0.1.0-pre.10/clearcote-149.0.7827.114-windows-x64.zip",
+    sha256: "8e1f72cc32b3c2adcc64b6ef6be9d367c4a63b51c4a459a626b000126cb019af",
     exeSha256: "5743595256c89c6874804bf3315acce592fc7f1883760c8d380c010151a73b23",
-    size: 242557010,
+    size: 242602257,
     os: "win32",
 };
 /** GitHub repo (owner/name) the releases come from — used by the opt-in auto-update resolver. */

package/dist/release.js.map

@@ -1 +1 @@
-{"version":3,"file":"release.js","sourceRoot":"","sources":["../src/release.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,wFAAwF;AACxF,2FAA2F;AAC3F,wFAAwF;AACxF,iEAAiE;AAqBjE,MAAM,CAAC,MAAM,OAAO,GAAgB;IAClC,GAAG,EAAE,cAAc;IACnB,OAAO,EAAE,gBAAgB;IACzB,KAAK,EAAE,0CAA0C;IACjD,GAAG,EAAE,4HAA4H;IACjI,MAAM,EAAE,kEAAkE;IAC1E,SAAS,EAAE,kEAAkE;IAC7E,IAAI,EAAE,SAAS;IACf,EAAE,EAAE,OAAO;CACZ,CAAC;AAEF,iGAAiG;AACjG,MAAM,CAAC,MAAM,IAAI,GAAG,iCAAiC,CAAC;AAEtD;;;qFAGqF;AACrF,MAAM,CAAC,MAAM,eAAe,GAAG,0CAA0C,CAAC"}
+{"version":3,"file":"release.js","sourceRoot":"","sources":["../src/release.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,wFAAwF;AACxF,2FAA2F;AAC3F,wFAAwF;AACxF,iEAAiE;AAqBjE,MAAM,CAAC,MAAM,OAAO,GAAgB;IAClC,GAAG,EAAE,eAAe;IACpB,OAAO,EAAE,gBAAgB;IACzB,KAAK,EAAE,0CAA0C;IACjD,GAAG,EAAE,6HAA6H;IAClI,MAAM,EAAE,kEAAkE;IAC1E,SAAS,EAAE,kEAAkE;IAC7E,IAAI,EAAE,SAAS;IACf,EAAE,EAAE,OAAO;CACZ,CAAC;AAEF,iGAAiG;AACjG,MAAM,CAAC,MAAM,IAAI,GAAG,iCAAiC,CAAC;AAEtD;;;qFAGqF;AACrF,MAAM,CAAC,MAAM,eAAe,GAAG,0CAA0C,CAAC"}

package/package.json

@@ -1,58 +1,65 @@
-{
-  "name": "clearcote",
-  "version": "0.6.0",
-  "description": "Playwright drop-in for the Clearcote anti-fingerprint Chromium build. launch() returns a standard Playwright Browser backed by the verified Clearcote binary, which is auto-downloaded and SHA-256 checked.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "prepublishOnly": "npm run clean && npm run build"
-  },
-  "dependencies": {
-    "extract-zip": "^2.0.1",
-    "maxmind": "^4.3.0",
-    "playwright-core": "^1.49.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  },
-  "keywords": [
-    "clearcote",
-    "playwright",
-    "puppeteer",
-    "chromium",
-    "anti-detect",
-    "anti-fingerprint",
-    "fingerprint",
-    "farbling",
-    "automation",
-    "stealth",
-    "ungoogled"
-  ],
-  "license": "BSD-3-Clause",
-  "homepage": "https://github.com/clearcotelabs/clearcote-browser",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/clearcotelabs/clearcote-browser.git",
-    "directory": "sdk/node"
-  },
-  "bugs": {
-    "url": "https://github.com/clearcotelabs/clearcote-browser/issues"
-  }
-}
+{
+  "name": "clearcote",
+  "version": "0.8.0",
+  "description": "Playwright drop-in for the Clearcote anti-fingerprint Chromium build. launch() returns a standard Playwright Browser backed by the verified Clearcote binary, which is auto-downloaded and SHA-256 checked.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "clearcote-agent": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "extract-zip": "^2.0.1",
+    "maxmind": "^4.3.0",
+    "playwright-core": "^1.49.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "keywords": [
+    "clearcote",
+    "playwright",
+    "puppeteer",
+    "chromium",
+    "anti-detect",
+    "anti-fingerprint",
+    "fingerprint",
+    "farbling",
+    "automation",
+    "stealth",
+    "ungoogled"
+  ],
+  "license": "BSD-3-Clause",
+  "homepage": "https://github.com/clearcotelabs/clearcote-browser",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clearcotelabs/clearcote-browser.git",
+    "directory": "sdk/node"
+  },
+  "bugs": {
+    "url": "https://github.com/clearcotelabs/clearcote-browser/issues"
+  }
+}