clearcote 0.32.0 → 0.34.0

package/README.md

@@ -5,7 +5,8 @@ open, reproducible, anti-fingerprint Chromium build. `launch()` returns a standa
 `Browser`, so migrating is a one-line import change.
 
 The verified Clearcote binary is **auto-downloaded and SHA-256 checked** on first use, then cached —
-you don't manage zips or paths.
+you don't manage zips or paths. Or run the same code on a hosted Clearcote browser with
+`launch({ cloud: true })`: see [Local or cloud](#local-or-cloud).
 
 > **Platform:** Clearcote ships **Windows x64** and **Linux x64** binaries; `launch()` runs on both
 > and the SDK auto-downloads the right one for your OS. On Linux the persona is Linux-native (Linux
@@ -16,6 +17,9 @@ you don't manage zips or paths.
 > libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libxfixes3 libxext6 libpango-1.0-0
 > libcairo2 libx11-6 libxcb1 libexpat1 libdbus-1-3`) and pass `args: ["--no-sandbox"]` (or
 > `chown root:root chrome-sandbox && chmod 4755 chrome-sandbox`) in containers.
+> Running as **root** in a container? Run as a normal user (the official Docker image does) or add
+> `--cap-add=SYS_NICE`: the open build is compiled with debug assertions, and a root container that
+> refuses Chromium's process-priority call stops it at start.
 
 ## Install
 
@@ -131,6 +135,7 @@ npx clearcote login [key]      # validates the key, saves it to ~/.clearcote/lic
 npx clearcote logout
 npx clearcote clear-cache
 npx clearcote serve [--port 9222] ...
+npx clearcote cloud run|sessions|stop|events|recording|profile sync|webhooks ...   # the hosted API, see Local or cloud
 ```
 
 `info` never downloads: it reports the SDK, the cached builds, which engine features the binary supports, a launch test (skipped with `--quick`), licence seats, fonts and missing system libraries.
@@ -198,6 +203,8 @@ if (!verdict.coherent) console.warn(verdict.warnings);
 
 It reads the (unmasked) WebGL vendor/renderer the page sees, flags a software rasterizer (a fatal headless tell — enable the canvas bridge or run headed on a real GPU) and an incoherent vendor/renderer pair. Pass a second arg (`claimedGpu`) to also assert the rendered family.
 
+The renderer *string* alone is not enough: a persona renames the backend, so a SwiftShader fallback stops looking like one. The check therefore also measures limits the string cannot move — `MAX_TEXTURE_SIZE`, the vertex/fragment uniform-vector pair, and an actual 16384-wide texture allocation — and reports them as `maxTextureSize`, `maxVertexUniformVectors`, `maxFragmentUniformVectors` and `canAllocate16kTexture`. A renderer naming a desktop GPU while `MAX_TEXTURE_SIZE` is below 16384 is a spoof over a software rasterizer and comes back `coherent: false`. **Headless on Linux with no GPU hits exactly this** — Chromium falls back to SwiftShader (8192) whatever the persona claims, and no launch flag changes it on a display-less host. Run headed under Xvfb, or use the canvas bridge.
+
 ### Hardened launch defaults
 
 Every `launch()` already, with no extra options: **drops Playwright's `--enable-automation`** (so the engine's `AutomationControlled` feature stays off — pass your own `ignoreDefaultArgs` to override); **disables QUIC/HTTP-3 when a proxy is set** (a SOCKS5/HTTP proxy carries only TCP, so no UDP egresses around it); and prints a one-line **coherence warning** to stderr for incoherent option combos (silence with `quiet: true` or `CLEARCOTE_NO_WARN=1`).
@@ -300,6 +307,109 @@ don't set `acceptLanguage` explicitly. See the
 [collector README](../../tools/fingerprint-collect/README.md) for the full schema and what each
 field drives.
 
+## Local or cloud
+
+The same `launch()` runs the browser on this machine or on Clearcote's servers. One flag picks which,
+and both resolve to the same Playwright `Browser`:
+
+```ts
+import { launch } from "clearcote";
+
+const browser = await launch({ cloud: true, country: "us", identity: "acct-1", humanize: true });
+const page = await browser.newPage();
+await page.goto("https://example.com");
+await browser.close();               // disconnects and ends the hosted session
+```
+
+Leave `cloud` unset and set `CLEARCOTE_CLOUD=1` to move existing code to the cloud without editing
+it. The API key comes from `apiKey` or `CLEARCOTE_API_KEY`, and `CLEARCOTE_API_URL` points the SDK at
+another server (https only: plain `http://` is accepted for `127.0.0.1`, `::1` and `localhost` alone,
+so the key never crosses a network unencrypted).
+
+What changes in the cloud:
+
+- **Options** keep the API's names: `fingerprint`, `identity`, `platform`, `brand`, `timezone`,
+  `locale` (or `acceptLanguage`), `geoip`, `headless`, `lightStealth`, `proxy` (`"managed"`, a URL, or
+  `{ server, username, password }`), `country`/`state`/`city`, `proxySession`, `timeoutSec`,
+  `idleTimeoutSec`, `maxGb`, `version`, `profile`, `url`, `adblock`, `keepAlive`, `record`, `note`,
+  `worker`. `humanize` and `showCursor` run in the SDK, exactly as for a local browser.
+- **Local-only options are refused, by name.** `executablePath`, `args`, `userDataDir`, `extensions`,
+  `ignoreDefaultArgs`, the finer persona switches (`gpuVendor`, `webrtcIp`, ...) and the licence
+  options throw `<name> is not available for cloud browsers` before anything starts.
+- **Profiles are cloud profiles.** `profile: "acct-1"` loads the cookies of a named cloud profile, and
+  `launchPersistentContext({ cloud: true, profile: "acct-1" })` resolves to a context that also saves
+  them back when it closes. Fill one from a browser you are logged in to with `profiles.sync` (below).
+- **The session.** `cloudSessionOf(browser)` (also `browser.cloudSession`) holds its `id`, `worker` and
+  `expiresAt`. `close()` disconnects and ends the session; a `keepAlive: true` session is left running
+  (stop it with `cloud.browsers.stop(id)`).
+
+### The Cloud client
+
+Everything else the hosted API does is on `Cloud`:
+
+```ts
+import { Cloud } from "clearcote";
+
+const cloud = new Cloud();                        // CLEARCOTE_API_KEY
+
+// An agent run: a task in, JSON out
+const run = await cloud.runs.create("Log in with {{password}} and read the current plan's price", {
+  url: "https://example.com/login",
+  schema: { type: "object", properties: { price: { type: "string" } } },
+  secrets: { password: { value: "s3cret", domains: ["example.com"] } },   // the model never sees it
+});
+console.log(run.status, run.result.output, run.costEur.total);
+
+// Copy a logged-in state into a cloud profile: only the cookies a browser would use on the domains you
+// name (theirs, their subdomains', and parent-domain ones such as .example.com for www.example.com)
+await cloud.profiles.sync("acct-1", { loginUrl: "https://example.com/login", domains: ["example.com"] });
+
+// Recordings, the event timeline, hand-off to a person
+const s = await cloud.browsers.create({ record: true });
+await cloud.browsers.events(s.id);                // { events: [...], next }
+await cloud.browsers.downloadRecording(s.id, "session.mp4");
+```
+
+- `browsers`: `create(options)`, `get(id)`, `list({ status, note, limit, before })`, `stop(id)`,
+  `live(id, { control })`, `share(id, { control, minutes, recording })`,
+  `handoff(id, { reason, timeoutSec })`, `handoffDone(id)`, `waitHandoff(id, { timeout, poll })`,
+  `events(id, { after, limit })`, `recordingUrl(id)`, `downloadRecording(id, path)`.
+  `waitHandoff` on a session with no hand-off rejects with `CloudError` (code `NO_HANDOFF`).
+- `runs`: `create(task, { url, schema, secrets, wait = true, timeout, poll = 1.5, onUpdate, ...options })`
+  (the browser options above plus `maxSteps`, `handoff`, `handoffTimeoutSec`), `get(id)`,
+  `list({ limit, before })`, `cancel(id)`, `wait(id, { timeout, poll, onUpdate })`. A run that pauses
+  for a person (`waiting_for_human`) is not finished: `onUpdate` hears about it, and without one the
+  live link is printed to stderr. `timeout` and `poll` are in seconds, as in the Python SDK.
+- `profiles`: `list()`, `get(name)`, `delete(name)`, `importCookies(name, cookies, { mode })`,
+  `sync(name, { fromProfile | fromCdp | fromFile | loginUrl, domains | allDomains, replace })`. `sync`
+  refuses to run without `domains` or `allDomains: true`.
+- `webhooks`: `create(url, { events, description })` (the answer carries the `secret`, shown once),
+  `list()`, `delete(id)`, `test(id)`
+
+Every method resolves to the parsed JSON of its endpoint. An API refusal rejects with `CloudError`
+(`status`, `code` such as `"PROFILE_IN_USE"`, and the server's own `message`); a wait that runs out
+rejects with `CloudTimeoutError`, whose `last` holds the last view (the run carries on on the server).
+
+Check a webhook delivery with the raw request body and the `Clearcote-Signature` header:
+
+```ts
+import { verifyWebhook } from "clearcote";
+
+const event = verifyWebhook(rawBody, req.headers["clearcote-signature"], "whsec_..."); // throws if forged or stale
+```
+
+The same from the command line (`--json` for machine-readable output):
+
+```bash
+npx clearcote cloud run "Read the price of the Pro plan" --url https://example.com/pricing --schema price.json
+npx clearcote cloud run "Open my account page" --country us --profile acct-1 --persist-profile --max-steps 20
+npx clearcote cloud sessions
+npx clearcote cloud events bs_123
+npx clearcote cloud recording bs_123 -o session.mp4
+npx clearcote cloud profile sync acct-1 --login https://example.com/login --domain example.com
+npx clearcote cloud webhooks add https://hooks.example.com/clearcote --event run.finished
+```
+
 ## Fingerprint options
 
 All optional. Anything not listed here is passed straight through to Playwright
@@ -399,8 +509,9 @@ Profiles are JSON at `~/.clearcote/profiles/<name>.json` (set `CLEARCOTE_PROFILE
 
 ## API
 
-- `launch(options?)` → `Promise<Browser>` — launch and get a Playwright `Browser`. Pass `profile` (a name, path, or `Profile`) to launch a saved persona.
-- `launchPersistentContext(userDataDir, options?)` → `Promise<BrowserContext>`.
+- `launch(options?)` → `Promise<Browser>` — launch and get a Playwright `Browser`. Pass `profile` (a name, path, or `Profile`) to launch a saved persona; `cloud: true` for a hosted browser ([Local or cloud](#local-or-cloud)).
+- `launchPersistentContext(userDataDir, options?)` → `Promise<BrowserContext>`; `launchPersistentContext({ cloud: true, profile: "name" })` for a cloud profile.
+- `new Cloud({ apiKey, baseUrl })` — the hosted API (`browsers`, `runs`, `profiles`, `webhooks`); `CloudError`, `CloudTimeoutError`, `verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300)`, `cloudSessionOf(browser)`.
 - `serve(options?)` → `Promise<Server>` — a standing, stealthy CDP endpoint (`.cdpUrl` / `.wsUrl()` / `.close()`) any Playwright/Puppeteer/CDP client attaches to via `connectOverCDP`.
 - `executablePath(options?)` → `Promise<string>` — resolve (download/verify if needed) the chrome.exe path, e.g. for raw `chromium.launch({ executablePath })`.
 - `download(options?)` → `Promise<string>` — pre-fetch + verify the binary without launching.
@@ -492,7 +603,7 @@ The identity surface is **free in full**. A licence does not unlock "more spoofi
 control below is in the open build. The licensed build adds behavioural realism that needs recorded
 data or engine work held out of the public tree. **It is free with GitHub for one browser at a time**
 (sign in at [clearcotelabs.com](https://clearcotelabs.com/pricing#free), needs SDK 0.29.0+); **PRO**
-runs as many browsers at once as you need and adds email support.
+runs up to 250 browsers at once and adds email support.
 
 | Capability | Open source | Free with GitHub | PRO |
 |---|:---:|:---:|:---:|
@@ -508,7 +619,7 @@ runs as many browsers at once as you need and adds email support.
 | **Coherent WebRTC srflx fabrication** (`webrtcIp`) | — | ✅ | ✅ |
 | **WebRTC host-candidate concealment** (`.local` names) | — | ✅ | ✅ |
 | **Request-header hygiene** on revalidation | — | ✅ | ✅ |
-| Floating-concurrency licensing + run-token gate | — | 1 browser | ✅ unlimited |
+| Floating-concurrency licensing + run-token gate | — | 1 browser | ✅ up to 250 |
 | Email support from the owner | — | — | ✅ |
 
 The mouse tier is decided **at runtime** from a signed claim in the run-token — same SDK call,

package/dist/cli-commands.d.ts

@@ -1,5 +1,8 @@
 import { type SessionSeats } from "./index.js";
+import { type Json } from "./cloud.js";
 export declare const USAGE: string;
+/** `clearcote cloud --help`. Kept byte-identical to CLOUD_USAGE in the Python SDK's _commands.py. */
+export declare const CLOUD_USAGE = "clearcote cloud -- the hosted Clearcote API from the command line.\n\nUSAGE\n  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]...\n                      [--secret-domain <name>=<host>]... [--handoff] [--record] [--json]\n                      [--country <cc>] [--state <s>] [--city <c>] [--proxy managed|<url>]\n                      [--profile <name> [--persist-profile]] [--fingerprint <seed>]\n                      [--timeout-sec <n>] [--max-steps <n>] [--note <text>]\n  clearcote cloud sessions [--json]\n  clearcote cloud stop <id> [--json]\n  clearcote cloud events <id> [--json]\n  clearcote cloud recording <id> [-o <file.mp4>] [--json]\n  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <state.json>\n                      | --login <url>) (--domain <domain>... | --all-domains) [--replace] [--json]\n  clearcote cloud webhooks add <url> [--event <type>]... [--json]\n  clearcote cloud webhooks list [--json]\n  clearcote cloud webhooks rm <id> [--json]\n  clearcote cloud webhooks test <id> [--json]\n\n  run waits for the result and exits 0 only when the run succeeded. profile sync uploads only the\n  cookies of the --domain names you list (subdomains included); --all-domains uploads every cookie.\n\nENVIRONMENT\n  CLEARCOTE_API_KEY (required), CLEARCOTE_API_URL (default https://www.clearcotelabs.com)";
 /** What `info` reports. Also the `--json` shape. */
 export interface InfoReport {
     sdk: {
@@ -53,6 +56,16 @@ export declare function buildInfo(flags: {
     proxy?: string;
 }): Promise<InfoReport>;
 export declare function main(argv?: string[]): Promise<void>;
+/** The human summary `clearcote cloud run` prints. */
+export declare function formatRun(run: Json): string[];
+/** --secret name=value and --secret-domain name=host as the API's `secrets` object: a plain string,
+ * or { value, domains } once a domain is given for that name. */
+export declare function cloudSecrets(secretArgs?: string[], domainArgs?: string[]): Record<string, unknown>;
+/** The browser and run options of `clearcote cloud run` (unset ones left out). --profile NAME loads a
+ * cloud profile; with --persist-profile the run also saves it back. */
+export declare function cloudRunOptions(v: Record<string, Json>): Record<string, unknown>;
+/** `clearcote cloud …`: resolves to the exit code (0 ok, 1 failed, 2 usage). Never exits itself. */
+export declare function cloudMain(argv: string[]): Promise<number>;
 /** `--proxy scheme://user:pass@host:port` as a launch proxy option with the credentials split out. */
 export declare function proxyOption(url: string): {
     server: string;

package/dist/cli-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"AAiBA,OAAO,EAcL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAcpB,eAAO,MAAM,KAAK,QAqBiF,CAAC;AAWpG,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;IAChE,MAAM,EAAE;QACN,MAAM,EAAE,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;QAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7C,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,KAAK,EAAE;QAAE,cAAc,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,cAAc,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC7J;AAYD,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAkE/F;AAyDD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0HtE;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAKjG"}
+{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"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"}

package/dist/cli-commands.js

@@ -7,6 +7,7 @@
 //   clearcote login   [key]                                 save a licence key (validated first)
 //   clearcote logout                                        remove the saved key
 //   clearcote serve   [--port 9222] [--idle-timeout 300] …  multi-identity CDP endpoint
+//   clearcote cloud   run|sessions|stop|events|recording|profile sync|webhooks …  the hosted API
 //
 // `info` never downloads: it reports what is already cached and what a launch would resolve to.
 import { parseArgs } from "node:util";
@@ -19,6 +20,7 @@ import { defaultCacheRoot, listCachedBuilds } from "./download.js";
 import { geoCacheRoot } from "./geoip.js";
 import { GATED_ENGINE_SWITCHES } from "./launchopts.js";
 import { toProxySpec } from "./net.js";
+import { Cloud, CloudError, announceHandoff } from "./cloud.js";
 const SDK_VERSION = (() => {
     try {
         return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -40,6 +42,10 @@ USAGE
                   [--max-browsers 16] [--allow-origin <origin>]... [--allow-host <name>]... [--headed]
                   [--fingerprint <seed>] [--platform <os>] [--proxy <url>] [--timezone <tz>]
                   [--accept-language <l>] [--geoip]
+  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]... [--json]
+  clearcote cloud sessions | stop <id> | events <id> | recording <id> [-o <file.mp4>]
+  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <file> | --login <url>)
+  clearcote cloud webhooks add <url> | list | rm <id> | test <id>      (all flags: clearcote cloud --help)
 
 INFO FLAGS
   --quick          skip everything that needs the network or a launch (seat count, launch test)
@@ -48,7 +54,33 @@ INFO FLAGS
 
 ENVIRONMENT
   CLEARCOTE_LICENSE_KEY, CLEARCOTE_RELEASE_CHANNEL, CLEARCOTE_GEOIP_TIMEOUT_SECONDS,
-  CLEARCOTE_LICENSE_THROUGH_PROXY, CLEARCOTE_BINARY, CLEARCOTE_CACHE, CLEARCOTE_SERVE_IDLE_TIMEOUT`;
+  CLEARCOTE_LICENSE_THROUGH_PROXY, CLEARCOTE_BINARY, CLEARCOTE_CACHE, CLEARCOTE_SERVE_IDLE_TIMEOUT,
+  CLEARCOTE_API_KEY, CLEARCOTE_API_URL, CLEARCOTE_CLOUD`;
+/** `clearcote cloud --help`. Kept byte-identical to CLOUD_USAGE in the Python SDK's _commands.py. */
+export const CLOUD_USAGE = `clearcote cloud -- the hosted Clearcote API from the command line.
+
+USAGE
+  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]...
+                      [--secret-domain <name>=<host>]... [--handoff] [--record] [--json]
+                      [--country <cc>] [--state <s>] [--city <c>] [--proxy managed|<url>]
+                      [--profile <name> [--persist-profile]] [--fingerprint <seed>]
+                      [--timeout-sec <n>] [--max-steps <n>] [--note <text>]
+  clearcote cloud sessions [--json]
+  clearcote cloud stop <id> [--json]
+  clearcote cloud events <id> [--json]
+  clearcote cloud recording <id> [-o <file.mp4>] [--json]
+  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <state.json>
+                      | --login <url>) (--domain <domain>... | --all-domains) [--replace] [--json]
+  clearcote cloud webhooks add <url> [--event <type>]... [--json]
+  clearcote cloud webhooks list [--json]
+  clearcote cloud webhooks rm <id> [--json]
+  clearcote cloud webhooks test <id> [--json]
+
+  run waits for the result and exits 0 only when the run succeeded. profile sync uploads only the
+  cookies of the --domain names you list (subdomains included); --all-domains uploads every cookie.
+
+ENVIRONMENT
+  CLEARCOTE_API_KEY (required), CLEARCOTE_API_URL (default https://www.clearcotelabs.com)`;
 function out(line = "") {
     process.stdout.write(line + "\n");
 }
@@ -111,7 +143,8 @@ export async function buildInfo(flags) {
     }
     else {
         try {
-            const b = await launch({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false });
+            // cloud: false — this tests the LOCAL install, whatever CLEARCOTE_CLOUD says.
+            const b = await launch({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false, cloud: false });
             const version = b.version();
             await b.close();
             report.launch = { tested: true, ok: true, version };
@@ -197,6 +230,12 @@ export async function main(argv = process.argv.slice(2)) {
         out(SDK_VERSION);
         return;
     }
+    if (cmd === "cloud") {
+        const code = await cloudMain(rest);
+        if (code)
+            process.exitCode = code;
+        return;
+    }
     if (cmd === "info" || cmd === "doctor") {
         const { values } = parseArgs({ args: rest, options: { quick: { type: "boolean" }, "no-launch": { type: "boolean" }, json: { type: "boolean" }, proxy: { type: "string" } } });
         const report = await buildInfo({ quick: !!(values.quick || values["no-launch"]), proxy: values.proxy });
@@ -317,6 +356,308 @@ export async function main(argv = process.argv.slice(2)) {
     }
     fail(`unknown command '${cmd}'. Run \`clearcote --help\`.`, 2);
 }
+// ── clearcote cloud ────────────────────────────────────────────────────────────────────────────────
+// Output is part of the contract: the Python SDK's tests/test_parity_cloud_cli.py runs this CLI and
+// the Python one against the same fake API and compares stdout byte for byte. Change a line here,
+// change it in _commands.py too.
+/** A usage error inside `clearcote cloud`: message already on stderr, exit with `code`. */
+class CloudCliExit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+function cloudFail(msg, code = 1) {
+    process.stderr.write(`clearcote: ${msg}\n`);
+    throw new CloudCliExit(code);
+}
+const dump = (obj) => out(JSON.stringify(obj, null, 2));
+const str = (v) => (v === null || v === undefined ? "-" : String(v));
+const eur = (v, places) => (typeof v === "number" ? `€${v.toFixed(places)}` : "-");
+/** The human summary `clearcote cloud run` prints. */
+export function formatRun(run) {
+    const lines = [`run ${str(run?.id)} ${str(run?.status)}`];
+    const r = run?.result ?? {};
+    if (r.status)
+        lines.push(`result  ${r.status}${r.detail ? `: ${r.detail}` : ""}`);
+    if (r.url)
+        lines.push(`url     ${r.url}`);
+    if (r.title)
+        lines.push(`title   ${r.title}`);
+    if (r.outputError)
+        lines.push(`output  error: ${r.outputError}`);
+    else if (r.output !== undefined && r.output !== null)
+        lines.push(`output  ${JSON.stringify(r.output, null, 2)}`);
+    const cost = run?.costEur;
+    if (cost && typeof cost === "object" && cost.total !== undefined && cost.total !== null)
+        lines.push(`cost    ${eur(cost.total, 4)}`);
+    return lines;
+}
+function sessionLine(s) {
+    const line = `${str(s?.id)}  ${str(s?.status)}  ${str(s?.createdAt)}  ${eur(s?.costEur, 4)}`;
+    return line + (s?.note ? `  ${s.note}` : "");
+}
+// A --secret argument is never echoed back, not even a malformed one: it may be the bare secret.
+const SECRET_SHAPE = "--secret wants <name>=<value> (the argument given is not shown: it may hold the secret)";
+function parsePairs(values, flag) {
+    return (values ?? []).map((raw) => {
+        const i = raw.indexOf("=");
+        const name = i < 0 ? "" : raw.slice(0, i).trim();
+        const value = i < 0 ? "" : raw.slice(i + 1);
+        if (!name || !value)
+            cloudFail(flag === "--secret" ? SECRET_SHAPE : `${flag} wants <name>=<value>, got '${raw}'`, 2);
+        return [name, value];
+    });
+}
+/** --secret name=value and --secret-domain name=host as the API's `secrets` object: a plain string,
+ * or { value, domains } once a domain is given for that name. */
+export function cloudSecrets(secretArgs, domainArgs) {
+    const secrets = new Map(parsePairs(secretArgs, "--secret"));
+    const domains = new Map();
+    for (const [name, host] of parsePairs(domainArgs, "--secret-domain")) {
+        if (!secrets.has(name))
+            cloudFail(`--secret-domain ${name}: there is no --secret ${name}=...`, 2);
+        domains.set(name, [...(domains.get(name) ?? []), host.trim().toLowerCase()]);
+    }
+    return Object.fromEntries([...secrets].map(([n, v]) => [n, domains.has(n) ? { value: v, domains: domains.get(n) } : v]));
+}
+// `clearcote cloud run` browser/run options that take a value, mapped to the Runs.create option of the
+// same meaning (the Python launch kwargs): --timeout-sec -> timeoutSec, --max-steps -> maxSteps, ...
+const RUN_OPTION_FLAGS = ["country", "state", "city", "proxy", "profile", "fingerprint", "timeout-sec", "max-steps", "note"];
+function whole(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[0-9]+$/.test(value))
+        cloudFail(`${flag} wants a whole number, got '${value}'`, 2);
+    return Number(value);
+}
+/** The browser and run options of `clearcote cloud run` (unset ones left out). --profile NAME loads a
+ * cloud profile; with --persist-profile the run also saves it back. */
+export function cloudRunOptions(v) {
+    if (v["persist-profile"] && !v.profile)
+        cloudFail("--persist-profile needs --profile <name>", 2);
+    const opts = {
+        country: v.country, state: v.state, city: v.city, proxy: v.proxy,
+        profile: v.profile ? (v["persist-profile"] ? { name: v.profile, persist: true } : v.profile) : undefined,
+        fingerprint: v.fingerprint, timeoutSec: whole(v["timeout-sec"], "--timeout-sec"),
+        maxSteps: whole(v["max-steps"], "--max-steps"), note: v.note,
+        handoff: v.handoff ? true : undefined, record: v.record ? true : undefined,
+    };
+    return Object.fromEntries(Object.entries(opts).filter(([, x]) => x !== undefined));
+}
+function runProgress(view) {
+    if (view?.status === "waiting_for_human")
+        announceHandoff(view);
+    else
+        process.stderr.write(`[clearcote] run ${view?.id}: ${view?.status}\n`);
+}
+function parse(args, options, positionals, what) {
+    let r;
+    try {
+        r = parseArgs({ args, options: { ...options, json: { type: "boolean" } }, allowPositionals: true, strict: true });
+    }
+    catch (e) {
+        cloudFail(e.message, 2);
+    }
+    if (positionals >= 0 ? r.positionals.length !== positionals : r.positionals.length < 1) {
+        cloudFail(`\`clearcote cloud ${what}\`: wrong arguments. Run \`clearcote cloud --help\`.`, 2);
+    }
+    return { values: r.values, pos: r.positionals };
+}
+/** `clearcote cloud …`: resolves to the exit code (0 ok, 1 failed, 2 usage). Never exits itself. */
+export async function cloudMain(argv) {
+    try {
+        return await cloudCommand(argv);
+    }
+    catch (e) {
+        if (e instanceof CloudCliExit)
+            return e.code;
+        if (e instanceof CloudError) {
+            process.stderr.write(`clearcote: ${e.message}${e.status ? ` (HTTP ${e.status}${e.code ? `, ${e.code}` : ""})` : ""}\n`);
+            return 1;
+        }
+        process.stderr.write(`clearcote: ${e?.message ?? String(e)}\n`);
+        return 1;
+    }
+}
+async function cloudCommand(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        out(CLOUD_USAGE);
+        return 0;
+    }
+    if (!["run", "sessions", "stop", "events", "recording", "profile", "webhooks"].includes(cmd)) {
+        cloudFail(`unknown cloud command '${cmd}'. Run \`clearcote cloud --help\`.`, 2);
+    }
+    if ((cmd === "profile" || cmd === "webhooks") && !rest[0]) {
+        cloudFail(`\`clearcote cloud ${cmd}\` needs a subcommand. Run \`clearcote cloud --help\`.`, 2);
+    }
+    if (cmd === "run") {
+        const { values: v, pos } = parse(rest, {
+            url: { type: "string" }, schema: { type: "string" }, secret: { type: "string", multiple: true },
+            "secret-domain": { type: "string", multiple: true }, handoff: { type: "boolean" }, record: { type: "boolean" },
+            ...Object.fromEntries(RUN_OPTION_FLAGS.map((f) => [f, { type: "string" }])),
+            "persist-profile": { type: "boolean" },
+        }, -1, "run");
+        const secrets = cloudSecrets(v.secret, v["secret-domain"]);
+        const runOptions = cloudRunOptions(v);
+        let schema;
+        if (v.schema) {
+            try {
+                schema = JSON.parse(readFileSync(v.schema, "utf8"));
+            }
+            catch (e) {
+                cloudFail(`--schema ${v.schema}: ${e.message}`, 2);
+            }
+        }
+        const cloud = new Cloud();
+        const run = await cloud.runs.create(pos.join(" "), {
+            url: v.url, schema, secrets: Object.keys(secrets).length ? secrets : undefined,
+            ...runOptions, onUpdate: runProgress,
+        });
+        if (v.json)
+            dump(run);
+        else
+            formatRun(run).forEach((l) => out(l));
+        return run?.status === "succeeded" ? 0 : 1;
+    }
+    if (cmd === "sessions") {
+        const { values: v } = parse(rest, {}, 0, "sessions");
+        const data = (await new Cloud().browsers.list()) ?? {};
+        if (v.json) {
+            dump(data);
+            return 0;
+        }
+        const sessions = data.sessions ?? [];
+        for (const s of sessions)
+            out(sessionLine(s));
+        if (!sessions.length)
+            out("no sessions");
+        if (data.balanceEur !== undefined && data.balanceEur !== null)
+            out(`balance ${eur(data.balanceEur, 2)}`);
+        return 0;
+    }
+    if (cmd === "stop") {
+        const { values: v, pos } = parse(rest, {}, 1, "stop");
+        const view = await new Cloud().browsers.stop(pos[0]);
+        if (v.json)
+            dump(view);
+        else
+            out(`stopped ${pos[0]} (${str(view?.status)})`);
+        return 0;
+    }
+    if (cmd === "events") {
+        const { values: v, pos } = parse(rest, {}, 1, "events");
+        const cloud = new Cloud();
+        const events = [];
+        let after = 0;
+        for (;;) {
+            const page = (await cloud.browsers.events(pos[0], { after })) ?? {};
+            const batch = page.events ?? [];
+            events.push(...batch);
+            const next = page.next;
+            if (!batch.length || next === null || next === undefined || next === after)
+                break;
+            after = next;
+        }
+        if (v.json) {
+            dump({ events });
+            return 0;
+        }
+        for (const e of events) {
+            const data = e?.data;
+            const extra = data && Object.keys(data).length ? `  ${JSON.stringify(data)}` : "";
+            out(`${str(e?.seq)}  ${str(e?.at)}  ${str(e?.type)}${extra}`);
+        }
+        if (!events.length)
+            out("no events");
+        return 0;
+    }
+    if (cmd === "recording") {
+        const { values: v, pos } = parse(rest, { output: { type: "string", short: "o" } }, 1, "recording");
+        const path = v.output || `${pos[0]}.mp4`;
+        await new Cloud().browsers.downloadRecording(pos[0], path);
+        const size = statSync(path).size;
+        if (v.json)
+            dump({ path, bytes: size });
+        else
+            out(`saved ${path} (${size} bytes)`);
+        return 0;
+    }
+    if (cmd === "profile") {
+        if (rest[0] !== "sync")
+            cloudFail(`unknown profile command '${rest[0]}'. Run \`clearcote cloud --help\`.`, 2);
+        const { values: v, pos } = parse(rest.slice(1), {
+            "from-profile": { type: "string" }, "from-cdp": { type: "string" }, "from-file": { type: "string" },
+            login: { type: "string" }, domain: { type: "string", multiple: true }, "all-domains": { type: "boolean" },
+            replace: { type: "boolean" },
+        }, 1, "profile sync");
+        const sources = [v["from-profile"], v["from-cdp"], v["from-file"], v.login].filter(Boolean);
+        if (sources.length !== 1)
+            cloudFail("profile sync needs exactly one of --from-profile, --from-cdp, --from-file or --login", 2);
+        if (v.domain?.length && v["all-domains"])
+            cloudFail("pass --domain or --all-domains, not both", 2);
+        if (!v.domain?.length && !v["all-domains"]) {
+            cloudFail("refusing to upload every cookie: pass --domain <domain> (repeatable, subdomains included) or --all-domains", 2);
+        }
+        const res = (await new Cloud().profiles.sync(pos[0], {
+            fromProfile: v["from-profile"], fromCdp: v["from-cdp"], fromFile: v["from-file"], loginUrl: v.login,
+            domains: v.domain, allDomains: !!v["all-domains"], replace: !!v.replace,
+        })) ?? {};
+        if (v.json) {
+            dump(res);
+            return 0;
+        }
+        out(`imported ${str(res.imported)} cookies into profile ${res.name || pos[0]} (${str(res.cookies)} in total)`);
+        if (res.domains?.length)
+            out(`domains  ${res.domains.join(", ")}`);
+        return 0;
+    }
+    // webhooks
+    const action = rest[0];
+    if (action === "add") {
+        const { values: v, pos } = parse(rest.slice(1), { event: { type: "string", multiple: true } }, 1, "webhooks add");
+        const res = (await new Cloud().webhooks.create(pos[0], { events: v.event })) ?? {};
+        if (v.json) {
+            dump(res);
+            return 0;
+        }
+        out(`webhook ${str(res.id)} -> ${str(res.url)}`);
+        out(`events  ${(res.events ?? []).join(", ") || "all except ping"}`);
+        out(`secret  ${str(res.secret)}`);
+        out("store the secret now: it is not shown again");
+        return 0;
+    }
+    if (action === "list") {
+        const { values: v } = parse(rest.slice(1), {}, 0, "webhooks list");
+        const data = (await new Cloud().webhooks.list()) ?? {};
+        if (v.json) {
+            dump(data);
+            return 0;
+        }
+        const hooks = data.webhooks ?? [];
+        for (const h of hooks) {
+            const ld = h?.lastDelivery;
+            const last = ld ? `  last ${str(ld.status)} ${str(ld.at)}` : "";
+            out(`${str(h?.id)}  ${str(h?.url)}  ${(h?.events ?? []).join(",") || "all"}${last}`);
+        }
+        if (!hooks.length)
+            out("no webhooks");
+        return 0;
+    }
+    if (action === "rm" || action === "test") {
+        const { values: v, pos } = parse(rest.slice(1), {}, 1, `webhooks ${action}`);
+        const cloud = new Cloud();
+        const res = action === "rm" ? await cloud.webhooks.delete(pos[0]) : await cloud.webhooks.test(pos[0]);
+        if (v.json)
+            dump(res);
+        else
+            out(action === "rm" ? `removed ${pos[0]}` : `sent a ping to ${pos[0]}`);
+        return 0;
+    }
+    return cloudFail(`unknown webhooks command '${action}'. Run \`clearcote cloud --help\`.`, 2);
+}
 /** `--proxy scheme://user:pass@host:port` as a launch proxy option with the credentials split out. */
 export function proxyOption(url) {
     let spec;