cdpilot 0.9.3 → 0.9.5

package/README.md

@@ -28,14 +28,14 @@ No config files. No boilerplate. Just `npx` and go.
 AI agents and developers need browser control that **just works**:
 
 - **Zero config** — `npx cdpilot launch` starts an isolated browser session
-- **Zero dependency** — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP
+- **Zero npm dependencies** — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP/WebSocket; the Python side needs one package, `websockets` (the setup wizard installs it)
 - **70+ commands** — Navigate, click, type, screenshot, network, console, accessibility, video understanding, progressive anti-bot resilience, and more
 - **AI-agent friendly** — Designed for Claude, GPT, Gemini, and any LLM tool-use workflow
 - **Isolated sessions** — Your personal browser stays untouched. cdpilot runs in its own profile
 - **Visual feedback** — Green glow overlay, cursor visualization, click ripples, and keystroke display keep you informed during automation
 - **Multi-project isolation** — Each project gets its own browser instance and port automatically, no conflicts
 - **AI control warning** — Red toast notification appears when you hover during active automation
-- **Privacy-first** — Everything runs locally. No data leaves your machine
+- **Privacy-first** — Everything runs locally; nothing leaves your machine unless you opt in (CAPTCHA solver keys, `tls-check`, proxies)
 
 ### Browser Selection (Workload-Aware Auto-Pick)
 
@@ -44,7 +44,7 @@ two-axis policy — extension workload × platform stability:
 
 | Your workload | Auto-pick order |
 |---|---|
-| Has extensions registered (`ext-install`) | vivaldi → brave → edge → chromium → chrome |
+| Has extensions registered (`ext-install`) | vivaldi → brave → edge → chromium → chrome (→ Chrome for Testing, if installed) |
 | No extensions (pure automation) | chrome → vivaldi → edge → chromium → brave |
 
 Override anytime:
@@ -52,13 +52,16 @@ Override anytime:
 ```bash
 cdpilot browser            # show current pick + reason
 cdpilot browser vivaldi    # pin to Vivaldi
+cdpilot browser chrome-for-testing   # pin to Chrome for Testing (after installing it, below)
 cdpilot browser auto       # restore smart default
 ```
 
 **Why the split?**
-- **Chrome 147+ silently drops `--load-extension`** for unpacked extensions
-  (no error, no warning). Verified — `chrome://extensions` shows 0 items.
-- **Vivaldi, Brave, Edge, Chromium** honor `--load-extension` (tested).
+- **Chrome 137+ silently drops `--load-extension`** for unpacked extensions
+  (no error, no warning) — Google removed it from branded Chrome builds
+  ([PSA](https://groups.google.com/a/chromium.org/g/chromium-extensions/c/1-g8EFx2BBY/m/S0ET5wPjCAAJ)).
+  Verified — `chrome://extensions` shows 0 items.
+- **Vivaldi, Brave, Edge, Chromium and Chrome for Testing** honor `--load-extension` (tested).
 - On **macOS 26 (Tahoe)** Brave 1.89 crashes deterministically at ~7min
   uptime (SIGTRAP in ThreadPoolForegroundWorker). cdpilot detects the OS
   and demotes Brave automatically until a fixed Brave release ships.
@@ -66,6 +69,43 @@ cdpilot browser auto       # restore smart default
 Each browser gets its own isolated profile (`~/.cdpilot/.../profile-vivaldi`
 etc.) so switching never causes prefs corruption.
 
+### Extension development: Chrome for Testing
+
+If you develop an extension against Chrome itself, install
+[Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) (CfT) —
+the Chrome team's versioned, non-auto-updating Chrome build for automation, which
+still loads unpacked extensions:
+
+```bash
+cdpilot browser install chrome-for-testing                    # latest Stable
+cdpilot browser install chrome-for-testing --channel beta     # stable | beta | dev | canary
+cdpilot browser install chrome-for-testing --version 154      # a milestone, or a full version (154.0.8037.57)
+cdpilot ext-install ./my-extension/                           # register your unpacked extension
+cdpilot browser status                                        # shows the CfT version and path
+```
+
+- **Download only on that command.** It is a one-time ~150-190 MB zip (mac-arm64 at
+  154.0.8037.57: 191,429,663 bytes); cdpilot never fetches it by itself. The build comes
+  from the official [CfT JSON endpoints](https://googlechromelabs.github.io/chrome-for-testing/)
+  (`last-known-good-versions-with-downloads.json`, per-version and per-milestone files).
+  Those list URLs only, no hash, so the download is checked against the server's
+  `Content-Length` and its `x-goog-hash` md5; the zip's SHA-256 is recorded.
+- It is extracted to `$CDPILOT_HOME/browsers/chrome-for-testing/<version>/` (on macOS the
+  quarantine attribute is cleared on that directory only) and recorded in `installed.json`.
+- **Used automatically for extension work:** while dev extensions are registered, a
+  branded Chrome pick (`cdpilot browser chrome`, or `auto` with Chrome the only
+  extension-capable choice) becomes Chrome for Testing, with one stderr line saying so.
+  Without CfT installed, `ext-install` on Chrome prints the install command and keeps
+  Vivaldi/Brave as the alternative. `cdpilot browser chrome-for-testing` selects it
+  always. An explicit `CHROME_BIN` is never replaced.
+- It runs with cdpilot's usual per-project isolated profile (`profile-cft`).
+- **It is for extension development and testing — not a stealth browser.** cdpilot
+  makes no anti-bot claims for it; use your regular browser setup for that.
+- **Linux (Ubuntu 23.10+):** AppArmor blocks unprivileged user namespaces, and CfT
+  (unlike the distro's Chrome package) has no profile allowing them, so it exits at
+  start. cdpilot prints this hint; allow them with
+  `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`.
+
 ## Installation
 
 ```bash
@@ -86,6 +126,46 @@ npx cdpilot launch    # Start browser with CDP enabled
 npx cdpilot status    # Check connection
 ```
 
+### Claude Code plugin marketplace
+
+Install cdpilot's MCP server and its skill straight into Claude Code, no
+`.mcp.json` editing required:
+
+```bash
+/plugin marketplace add mehmetnadir/cdpilot
+/plugin install cdpilot@cdpilot
+```
+
+This registers the `cdpilot` MCP server (`npx cdpilot mcp`) and a short skill
+that teaches Claude Code when and how to reach for cdpilot's commands. See
+[`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and
+[`plugins/cdpilot/`](plugins/cdpilot/).
+
+### Smaller MCP tool list
+
+`cdpilot mcp --tools core` (or `CDPILOT_MCP_TOOLS=core`; the flag wins) lists 10 core
+tools (navigate, click, fill, content, screenshot, eval, wait_for, assert, tabs, connect)
+plus `browser_tools`. The agent calls `browser_tools` with `list` to see the other
+tools, or `enable` to add some (the server sends `tools/list_changed`). `--tools a,b,c`
+picks tools by name; `all` (default) is unchanged. Schema size of `tools/list`
+(tiktoken `o200k_base`): 45 tools = 5,769 tokens, `core` = 11 tools = 1,342 tokens.
+
+### MCP Bundle (.mcpb)
+
+For MCP clients that support one-click local server installation (Claude
+Desktop and others), download the `.mcpb` file attached to the
+[latest release](https://github.com/mehmetnadir/cdpilot/releases/latest) and
+open it, or build it yourself:
+
+```bash
+npm run build:mcpb   # writes cdpilot.mcpb at the repo root
+```
+
+The bundle still needs the same runtime on the machine that runs it: Node.js
+18+, Python 3.10+, and Brave/Chrome/Chromium installed. See
+[`manifest.json`](manifest.json) for the bundle's MCP Bundle manifest
+([spec](https://github.com/modelcontextprotocol/mcpb)).
+
 ### Upgrading from 0.4.x → 0.5.0 — read this first
 
 **One breaking change**, the rest is additive.
@@ -144,6 +224,8 @@ cdpilot scroll-to <selector>  # Scroll element into view
 cdpilot drag <from> <to>      # Drag and drop
 ```
 
+A real mouse click (inside a frame, or `--entropy=on`) whose target moves or gets covered while the button is held is not clicked again by script: `click` prints `Pressed (released elsewhere, not clicked): …` and ends with **exit 3** (pressed, release missed the target, not clicked; `1` stays "error"). A target the page replaced or navigated away from on mousedown prints `Pressed (the page replaced or left it, not clicked): …` and exits 0. MCP (`browser_click`, `browser_smart_click`) returns `isError: false` with a first line `{"clicked": false, "reason": "moved"|"gone"|"unknown"}`. `batch` and `run` finish every step, then exit 1 if a step failed, else 3 if a click was not clicked, else 0.
+
 ### Element targeting inside iframes
 
 Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA
@@ -175,11 +257,19 @@ cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's
   inside it and says so on stderr:
   `note: '#card-element' is not an iframe; using the iframe inside it`.
 - Selectors and texts that already contain `>>>` keep working: when the part
-  before the first `>>>` finds no iframe in the page, or a segment is empty
+  before the first `>>>` finds no iframe or shadow host in the page, or a segment is empty
   (`click "Next >>>"`), the whole string is used as written, exactly as
   before. If that fails too, one stderr line explains:
-  `note: 'Home' matched no iframe; used the selector as written`.
+  `note: 'Home' matched no iframe or shadow host; used the selector as written`.
   `--frame` never falls back: a frame it cannot find is an error (exit 1).
+- **Shadow DOM support**: `>>>` hops also pierce open shadow roots (`host.shadowRoot.querySelector(next)`).
+  Chains mix freely with iframes: `cdpilot click "iframe#pay >>> my-card >>> button.inner"` or
+  `cdpilot click "my-app >>> my-panel >>> input"`. A closed shadow root is unreachable by design
+  and fails with `'X' has a closed shadow root; cdpilot cannot reach inside it`.
+  When a plain CSS selector matches nothing at document level, cdpilot automatically falls back
+  to a depth-first search across all open shadow roots, printing one stderr note:
+  `note: '<sel>' found inside the shadow root of <host tag#id>`. Explicit `>>>` hops do not print this note.
+  `wait` and `wait-for` poll shadow roots every 200 ms alongside the document MutationObserver.
 - For `smart-click` / `smart-fill` / `smart-select` the part before the first
   `>>>` is a frame only if it looks like a selector (it has `#`, `.` or `[`,
   or starts with an `iframe`/`frame` tag) or is `url=…`; words stay text.
@@ -191,9 +281,17 @@ cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's
   (`DOM.describeNode` → frame id → the frame's execution context, or
   `Target.attachToTarget` with a flat session for an out-of-process frame),
   never through `contentDocument`, which the browser blocks cross-origin.
-- Real mouse input (`hover`, `dblclick`, `rightclick`, `--entropy=on` clicks)
-  is dispatched at page coordinates: the frame's offset in the page is added
-  automatically, so the browser hit-tests into the right frame.
+- Inside a frame, `click` and `smart-click` are real mouse input
+  (`isTrusted: true`), like `hover`, `dblclick`, `rightclick` and
+  `--entropy=on` clicks; an element with no box falls back to a script click.
+  Mouse input is dispatched at page coordinates: each frame's offset and scale
+  (`transform: scale()`, `zoom`) in the page is applied automatically, so the
+  browser hit-tests into the right frame. Before pressing, cdpilot checks the
+  point (`elementFromPoint` in each document on the way); if something covers
+  the target, such as a cookie banner, it clicks the target by script instead
+  and says so on one stderr line (`note: … is covered by div#cookie at the
+  click point; used a script click`). cdpilot's own input blocker (`show on`,
+  MCP sessions) lets only cdpilot's click through, for the click itself.
 - `smart-click` / `smart-fill` / `smart-select` look in the page first and
   compare texts with whitespace collapsed (`&nbsp;` and line breaks count as
   one space). An enabled page element whose text or label contains the whole
@@ -217,14 +315,22 @@ cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's
 ### Debugging
 
 ```bash
-cdpilot console [url]         # Capture console logs
-cdpilot network [url]         # Monitor network requests
-cdpilot debug [url]           # Full diagnostic (console+network+perf+shot)
-cdpilot perf                  # Performance metrics
-cdpilot eval <js>             # Execute JavaScript
-cdpilot eval-batch <json>     # Run N JS expressions in 1 roundtrip (5-30x faster)
+cdpilot console [url]                 # Capture console logs
+cdpilot network [url]                 # Monitor network requests
+cdpilot network <url> --har trace.har # Export navigation traffic as HAR 1.2 JSON (--har - for stdout)
+cdpilot debug [url]                   # Full diagnostic (console+network+perf+shot)
+cdpilot perf                          # Performance metrics
+cdpilot eval <js>                     # Execute JavaScript
+cdpilot eval-batch <json>             # Run N JS expressions in 1 roundtrip (5-30x faster)
 ```
 
+#### Network monitoring & HAR export
+
+`cdpilot network <url> --har <file>` exports all HTTP requests of a navigation as standard HAR 1.2 JSON (`--har -` writes to stdout).
+- **Included:** URLs, methods, headers, status codes, query strings, and CDP timing breakdowns (DNS, connect, SSL, send, wait, receive).
+- **Omitted:** Response bodies are not fetched or stored (avoids memory bloat and round-trip overhead); content.size reflects transfer length; bodySize is -1.
+- **Masking:** Sensitive header values matching security patterns (`Cookie`, `Set-Cookie`, `Authorization`, `X-Api-Key`, token, secret) are replaced with `"«masked»"`. URLs are masked the same way as the session log: userinfo passwords and query/fragment parameters named like secrets (`token`, `key`, `code`, `session`, …) in `request.url`, `queryString`, `redirectURL` and URL-bearing header values (`Location`, `Referer`, `Link`); a `data:` URL keeps only its media type.
+
 ```bash
 # Example: read 4 DOM values in a single CDP roundtrip instead of 4
 cdpilot eval-batch '["document.title","location.href","document.links.length","document.images.length"]'
@@ -462,6 +568,8 @@ At launch, cdpilot also passes `--disable-blink-features=AutomationControlled`,
 which closes the Blink runtime flag that Cloudflare and DataDome probe to detect
 an automated browser.
 
+Real mouse clicks (frames, `--entropy=on`, `click @ref`, `dblclick`, `rightclick`) hold the button 40-120 ms like a person's press; `CDPILOT_PRESS_MS=min-max` changes the range (`0-0` = instant).
+
 #### Three-tier stealth mode
 
 `cdpilot mode` is the recommended entry point — one switch that sets how much
@@ -505,6 +613,145 @@ cdpilot adaptive clear        # Drop the stealth host memory entirely
 > when it sees one — adds the host to a persistent list, retries once with
 > stealth on. Never auto-demotes. Conservative by design.
 
+### Web Bot Auth (signed agent)
+
+The opposite of stealth. Stealth tries to make the browser look like a person;
+Web Bot Auth says "this is an automated agent, and here is proof of which one".
+Every request the browser makes carries an Ed25519
+[HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)
+that a site, or Cloudflare in front of it, checks against a key directory you
+publish on your own domain. The format follows
+[draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/)
+and [draft-meunier-http-message-signatures-directory](https://datatracker.ietf.org/doc/draft-meunier-http-message-signatures-directory/),
+and reproduces the Ed25519 test vectors of Cloudflare's reference
+implementation ([cloudflare/web-bot-auth](https://github.com/cloudflare/web-bot-auth)).
+
+**Optional dependency.** Signing needs the `cryptography` package, for the Python cdpilot runs
+on (`CDPILOT_PYTHON` if you set it):
+
+```bash
+pip install cryptography
+```
+
+Without it, the `bot-auth` commands and `launch --bot-auth` print that hint and exit 2. Every
+other command works as before.
+
+**1. Generate the key** (once):
+
+```bash
+cdpilot bot-auth init --agent-url https://your-domain.com
+```
+
+This writes an Ed25519 private key to `CDPILOT_HOME/bot-auth/ed25519.key` (default
+`~/.cdpilot`), created with mode `0600`. cdpilot never prints or logs the key, and it warns
+when the file is readable by others. The agent URL must be an `https://` origin (no path). A
+second `init` refuses to replace the key unless you pass `--force`, because the new key would no
+longer match the directory you published.
+
+**2. Host the directory on your own domain, signed.** `cdpilot bot-auth directory` prints the
+public key as a JWKS, where `kid` is the key's RFC 7638 JWK thumbprint. Cloudflare also requires
+the directory *response* to be signed, so `--headers` prints the headers to serve with it:
+
+```bash
+cdpilot bot-auth directory --headers        # headers, a blank line, then the JSON body
+cdpilot bot-auth directory --headers --json # the same as {"authority", "headers", "body"}
+```
+
+```
+Content-Type: application/http-message-signatures-directory+json
+Signature-Input: sig1=("@authority";req);created=…;keyid="<thumbprint>";alg="ed25519";expires=…;nonce="…";tag="http-message-signatures-directory"
+Signature: sig1=:<base64 Ed25519 signature>:
+
+{ "keys": [ … ] }
+```
+
+Serve that body at `https://your-domain.com/.well-known/http-message-signatures-directory` with
+those three headers. The signature covers `("@authority";req)`, the host the directory is fetched
+from: by default the agent URL's host, or `--authority <host>`. There is one signature per key in
+the directory. It is valid for 24 hours (`--ttl <seconds>`), so a static host needs it refreshed
+daily, from cron or an edge function that runs the same signing. A cron example that rewrites the
+headers file and the body your web server serves:
+
+```bash
+# m h dom mon dow  — every day at 03:17, 48 h validity so one missed run does not break it
+17 3 * * *  cdpilot bot-auth directory --headers --ttl 172800 --json > /var/www/wba/directory.json.tmp \
+            && mv /var/www/wba/directory.json.tmp /var/www/wba/directory.json
+```
+
+Your server (or an edge function) reads `headers` and `body` from that JSON and serves them at
+the well-known path. `--content-digest` also covers the body (`Content-Digest`, RFC 9530), as
+in Cloudflare's reference vector; then the body must be served byte for byte as printed.
+
+**3. Launch a signing browser:**
+
+```bash
+cdpilot launch --bot-auth        # or: CDPILOT_BOT_AUTH=1 cdpilot launch
+cdpilot status                   # ... bot-auth: on (keyid <thumbprint>)
+cdpilot go https://example.com   # this request is signed, and so is everything after it
+cdpilot stop                     # stops the browser and the signer
+```
+
+`launch --bot-auth` starts a small detached signer next to the browser. It uses the same
+self-fork as the idle-close watcher and lives exactly as long as the browser. It holds one CDP
+connection and auto-attaches to every page, popup, new tab, out-of-process iframe and worker. It
+signs each request at the Fetch "Request" stage, including every redirect hop. So requests the page makes on its own are
+signed as well: timers, `fetch()` after your cdpilot command has returned, a tab the page opens.
+`data:`, `blob:` and `chrome-extension:` requests never leave the browser, so they pass through
+unchanged. If signing a request fails, that request goes out unsigned, one line is written to
+`CDPILOT_HOME/bot-auth/signers/<port>.log` (host only), and the page is never held up. Running
+`launch --bot-auth` against a browser that is already up adds the signer to it.
+
+Each request gets three headers:
+
+| Header | Value |
+|--------|-------|
+| `Signature-Agent` | `"https://your-domain.com"` |
+| `Signature-Input` | `sig1=("@authority" "signature-agent");created=…;keyid="<thumbprint>";alg="ed25519";expires=…;nonce="…";tag="web-bot-auth"` |
+| `Signature` | `sig1=:<base64 Ed25519 signature>:` |
+
+`expires` is `created` + 5 minutes. The `nonce` is 64 random bytes, base64-encoded, and new for
+every request.
+
+This is the **legacy** `Signature-Agent` form (draft-05 A.2.3), and it is the default because it
+is the form Cloudflare's verifier accepts: Cloudflare rejects the dictionary form of later drafts.
+To send the dictionary form instead (`Signature-Agent: sig1="https://your-domain.com"`, covered as
+`"signature-agent";key="sig1"`), run `cdpilot bot-auth format dict` (`bot-auth format legacy`
+switches back, `bot-auth format` shows it, `bot-auth init --agent-format dict` sets it at
+creation). It applies from the next `launch --bot-auth`.
+
+**What is not signed.** WebSocket handshakes are not signed: the browser does not pass them
+through CDP's `Fetch` domain, so a `wss://` connection the page opens goes out without the
+headers. Service-worker-internal cache hits and `data:`/`blob:` URLs never reach a server.
+
+**If the signer dies or hangs.** While it runs, the signer holds every request of the browser at
+the Fetch stage until it has added the headers. If it is killed, requests go out unsigned; `cdpilot
+status` and `cdpilot go` then print one stderr line (signer not running, requests go out unsigned,
+run `cdpilot launch --bot-auth` again) until you do, or `stop`. If it is frozen (a
+stopped process, a debugger), requests hang: `cdpilot stop` and `launch --bot-auth` again.
+cdpilot trusts its signer state only for the process whose command line is that port's signer and
+only for the browser it attached to, so a stale state file whose pid was reused by another program
+is dropped, never signalled.
+
+**Idle close** still works while the signer runs: the signer is attached to every page, so instead
+of "a page is attached" cdpilot counts the CDP clients other than the signer (by socket owner:
+`netstat` with an `lsof` fallback on macOS, `netstat` on Windows, `ss` on Linux), and a `watch` daemon or a Playwright session keeps
+the browser open. On Linux, `ss -tnp` shows only your own processes' sockets, so a client running
+as another user is not counted and idle close may close the browser under it.
+
+**Stealth conflict.** Signing says "I am an agent", and stealth says "I am not". If you pass
+`--bot-auth` together with `--stealth`/`--undetected`, or while `cdpilot mode` is `stealth` or
+`undetected`, cdpilot prints one warning line and applies bot-auth. While the signer runs, no
+stealth script or user-agent override is injected, and adaptive escalation does not retry at a
+stealth tier.
+
+**Register with Cloudflare.** Once the directory is live, submit it through the Bot Submission
+Form in the Cloudflare dashboard as a *signed agent* (an agent acting for its users) or a
+*verified bot*; see Cloudflare's
+[signed agents](https://blog.cloudflare.com/signed-agents/) and
+[verified bots with cryptography](https://blog.cloudflare.com/verified-bots-with-cryptography/)
+posts. Sites behind Cloudflare then see your requests as coming from your agent. Sites that
+don't check Web Bot Auth ignore the headers.
+
 ### Friction Ladder (progressive anti-bot detection)
 
 Real sites don't just throw a CAPTCHA — they stack defenses incrementally.
@@ -633,6 +880,7 @@ Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4
 
 ```bash
 cdpilot browser [name|auto]   # workload-aware browser selection
+cdpilot browser install chrome-for-testing   # for extension development (see above)
 cdpilot health                # JSON: alive, port, tabs, browser, today's crashes, idle close
 ```
 
@@ -728,6 +976,187 @@ never changes a command's output or exit code, and a failed write costs one
 stderr line. `CDPILOT_LOG=0` turns it off; `CDPILOT_LOG_DAYS` (default 14)
 sets how many days are kept. The MCP server exposes it as `browser_log`.
 
+### Record & replay
+
+Record sequences of CLI commands into a portable flow JSON file and replay them with variable substitution:
+
+```bash
+cdpilot record start [--name <n>]
+cdpilot record status
+cdpilot record cancel
+cdpilot go https://example.com
+cdpilot click "#login"
+cdpilot fill "#email" test@test.com
+cdpilot record stop [--save login-flow.json]
+cdpilot replay login-flow.json [--var k=v ...] [--delay real|none|<ms>] [--dry-run] [--continue]
+```
+
+Commands that run while recording is active are appended to `$CDPILOT_HOME/record/active.json`; secrets are replaced by `{{name}}` placeholders before a step is written to active.json. `CDPILOT_LOG=0` does not turn recording off, and steps run by `replay` are not recorded. Failed steps (`exit != 0`) are dropped at `record stop`. A value becomes a placeholder `{{name}}` cataloged under `vars` if the selector/label is secret-shaped (`#password`, `input[type=password]`, API key), or the value matches a token/bearer pattern or secret URL parameter. Other typed values (emails, search terms, anything the rules do not recognise) are stored verbatim, so review a flow before sharing it; `--save` files are created with mode 0600. In `replay`, `--delay real` reproduces recorded inter-step timing (capped at 10 s per gap), while `--delay none` or a fixed millisecond delay skips waiting. Variables are supplied via `--var k=v` or `CDPILOT_VAR_<NAME>`; missing variables halt replay before any step runs.
+
+### Use your own browser (human-in-the-loop)
+
+An agent hits a CAPTCHA or a login wall it cannot get past. A person solves it,
+and the agent carries on in the same browser.
+
+**The simplest way needs no `connect`.** cdpilot's own browser is a normal,
+visible window unless you launch it headless (`cdpilot headless on` /
+`CHROME_HEADLESS=1`). The person solves the CAPTCHA or logs in right there, and
+the agent continues:
+
+```bash
+cdpilot go https://example.com/dashboard   # agent: "captcha detected" / login wall
+cdpilot captcha-wait 300                   # agent waits while the person solves it
+cdpilot go https://example.com/dashboard   # agent continues in the same window
+```
+
+That window uses cdpilot's own profile, so the login stays for later runs.
+
+**`connect` is for a browser you start yourself**, with a debugging port and
+your own profile directory (log into it once; it keeps its cookies):
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9450 --user-data-dir="$HOME/cdpilot-chrome"
+# Linux
+google-chrome --remote-debugging-port=9450 --user-data-dir="$HOME/cdpilot-chrome"
+# Windows
+"%ProgramFiles%\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9450 --user-data-dir="%USERPROFILE%\cdpilot-chrome"
+
+cdpilot connect 9450          # or: cdpilot connect ws://127.0.0.1:9450/devtools/browser/<id>
+cdpilot connect --auto        # or: find it via a DevToolsActivePort file
+cdpilot go https://example.com/dashboard
+cdpilot disconnect            # forget it; the browser keeps running
+```
+
+Since Chrome 136, `--remote-debugging-port` is ignored on the default profile,
+so the separate `--user-data-dir` is required. `connect --auto` reads the
+DevToolsActivePort file of each known profile directory (`~/cdpilot-chrome`
+from the command above, Chrome stable/beta/dev/canary, Chromium, Brave,
+Vivaldi, Edge), skips files left over from a browser that is gone or was
+replaced on that port (the browser id in the file must match), and connects to
+the first live one. It asks over HTTP only; a WebSocket probe (which Chrome's
+chrome://inspect mode may answer with a permission prompt) is sent only when no
+live browser was found.
+
+**Not supported yet: Chrome's `chrome://inspect/#remote-debugging` toggle**
+(Chrome 144+, your everyday logged-in profile). In that mode Chrome answers
+only on its WebSocket (`/json/version` and `/json` return 404) and may ask you
+to allow every new debugging connection, while cdpilot lists tabs over `/json`
+and opens a new connection per command. `connect --auto` recognises the mode
+and exits with code 2 and the start command above instead of half-working.
+
+**What cdpilot does with a connected browser:**
+
+- Page commands (`go`, `click`, `fill`, `shot`, …) run in a tab cdpilot opens
+  for itself in a new window that does not take the focus
+  (`Target.createTarget` with `newWindow` + `background`, so your window and
+  tab keep it) on the first page command, and keep using that tab. `close`,
+  `session-close` and the idle session cleanup close only such tabs, the ones
+  cdpilot opened in this browser run, never the last one. Your own tabs are
+  never navigated or typed into; only a command that names a tab touches it
+  (`switch-tab`, `close-tab <index|id>`, `CDPILOT_TARGET`, and `multi-eval`,
+  which runs its script in every open tab).
+- It never closes or kills the browser. `close`, `close --force`, `stop`,
+  `stop --smart [--force]`, `project-stop`, `stop-all`, `session-close` and MCP
+  `browser_close` close at most cdpilot's own tabs (above) and print
+  "connected browser left running; run `cdpilot disconnect` to forget it".
+  The idle auto-close never touches it,
+  `tabs --reap` closes nothing, `wipe`, `permission`, `cookies load` and `cf-replay` are refused (add `--allow-external` to load/replay cookies anyway),
+  `context close` only destroys a context `context create` made, and `launch` /
+  MCP `browser_launch` start nothing.
+- `close-tab` is an explicit command and **can close your tabs**: the active
+  (cdpilot) tab with no argument, or any tab you name by index or id. It never
+  closes the last tab, which would quit the browser on Windows and Linux.
+- It injects nothing into it: no stealth patch or user-agent override (whatever
+  `cdpilot mode` / `stealth` says), no glow, no input blocker, no dev-extension
+  scripts, no auto-cookie restore.
+- The registration stays until you run `cdpilot disconnect`. If the browser is
+  closed, page commands exit 1 with "your connected browser is gone; run
+  `cdpilot connect` again or `cdpilot disconnect`", and cdpilot never launches a
+  browser in its place.
+- `connect` refuses when this project already has a browser cdpilot launched
+  ("stop it first (`cdpilot stop`) or use another project"), and only
+  `127.0.0.1` / `localhost` is accepted (anything else exits 2). `disconnect`
+  also stops this project's `watch` daemon.
+- cdpilot treats a browser as its own only with proof: the browser id it
+  recorded at `launch` (or, for older entries, a live recorded pid that holds
+  the debug port). A busy port is not proof, so a leftover registry entry never
+  makes `stop` / `close` touch your own Chrome on port 9222.
+
+**Risks:**
+
+- Every cdpilot command, and any agent that can run cdpilot, can read and act
+  with the cookies and sessions of that profile (mail, banking, admin panels).
+  Use a profile that is logged into only what the task needs.
+- The debugging port is open to every local program for as long as that browser
+  runs, not just to cdpilot. Close the browser when you are done.
+- Sites can tell automation more easily: cdpilot applies no stealth to a
+  connected browser.
+- cdpilot's tab sits next to yours in the same window, and an agent may
+  still act in one of your tabs when it names it (`switch-tab`,
+  `close-tab <n>`, `multi-eval`).
+
+### WebMCP tools (opt-in)
+
+[WebMCP](https://webmachinelearning.github.io/webmcp/) lets a page register
+"tools" on `document.modelContext`: imperatively with `registerTool()`, or
+declaratively with `<form toolname tooldescription>` (inputs described by
+`toolparamdescription`). cdpilot lists and calls them through the browser's own
+API, `getTools()` and `executeTool()`. In Chrome the API is behind
+`chrome://flags/#enable-webmcp-testing` (Chromium 146+), so start the browser
+with it:
+
+```bash
+cdpilot launch --webmcp        # saved for this project: later launches (auto-launch too) keep it
+cdpilot go https://example.com/shop
+cdpilot tools list             # name, title, description, annotations, input schema
+cdpilot tools list --json
+cdpilot tools call add_to_cart '{"sku":"A1","qty":2}'
+cdpilot tools call add_to_cart --arg sku=A1 --arg qty=2
+cdpilot launch --no-webmcp     # turn it off again (applies at the next start)
+```
+
+- `launch --webmcp` adds `--enable-features=WebMCP` to the browser's command
+  line and saves the mode next to the stealth mode (`webmcp.json` in the
+  project profile); `CDPILOT_WEBMCP=1|0` overrides it. `cdpilot status` shows a
+  WebMCP line while the mode is on.
+  Chrome reads feature flags only at startup: a browser that is already running
+  keeps its flags until `cdpilot stop`.
+- `tools list` shows the tools of the page and of its same-origin iframes
+  (with the frame URL; every readable frame is asked for its own tools, so a
+  frame tool missing from the top document's `getTools()` is still listed and
+  runs in its frame), marks form tools and whether the form submits itself
+  (`toolautosubmit`), and shows `title` and the `readOnlyHint` /
+  `consequentialHint` / `untrustedContentHint` annotations. Nothing is injected
+  into the page: the list is the browser's registry at that moment, so it
+  follows reloads and navigations. Both commands run in cdpilot's own isolated
+  world (no `Runtime.enable`), so a page script that wraps `getTools()` /
+  `executeTool()` cannot add tools, change results or see the calls; only if
+  that world cannot see `document.modelContext` does cdpilot use the page's
+  main world, and it says so on stderr. With no tools it says why (WebMCP not
+  enabled in the running browser, not a secure context, browser too old,
+  document not origin-keyed, or the page registered none) and exits 0.
+- `tools call` checks the arguments against the tool's `inputSchema` first
+  (`required`, `type` — `true` is not an integer —, `enum`, `const`, nested
+  `properties` and `items`; other keywords are left to the page) and exits 1
+  on a mismatch, an unknown tool or a tool error. It passes an `AbortSignal`
+  and aborts it when `--timeout` (default 20 s) runs out, then exits 124
+  with `timed out after <N>s (--timeout); its execution was aborted`. The
+  signal fires at the `--timeout` deadline; the watchdog waits 3 s more so
+  that report is printed.
+  A form tool without `toolautosubmit` waits for a person to submit the form.
+  When several frames register the same name, `--frame <url-part>` picks one
+  (an exact frame URL wins); without it the top document's tool is used, and
+  if there is none the call stops and lists the frames.
+- MCP: `browser_site_tools` and `browser_site_tool_call` are listed only while
+  the project's WebMCP mode is on (or `CDPILOT_WEBMCP=1` for the server).
+
+> **Security**: `tools call` runs the page's own code, and tool names,
+> descriptions and results are page content: treat them as untrusted.
+> Arguments and results are written to the session log with secret-named
+> fields (password, token, key, secret, auth, ...) redacted at any depth.
+
 ### Scaling & Workstation Use
 
 ```bash
@@ -845,9 +1274,9 @@ print(result.stdout)
 | v0.6.0 | + captcha solver + cookies-auto (regression) | 15 / 80 | 18.75% |
 | **v0.8.0** | **Full — cookies safe-host scoped + per-task wipe (no proxy, no TLS fork)** | **29 / 80** | **36.25%** |
 | v0.7.0 (slot) | + named proxy pools | _depends on user proxy_ | — |
-| v0.8.0 (slot) | + TLS-aware launcher (camoufox/undetected-chrome) | _depends on browser choice_ | — |
+| v0.8.0 (slot) | TLS-aware launcher — withdrawn: camoufox / undetected-chrome do not speak CDP (CHANGELOG 0.8.0) | — | — |
 
-**What cdpilot does not do:** `cdpilot` is an avoidance engine, not a CAPTCHA solver. We prioritize structural stealth (JS fingerprinting, behavioral entropy) to prevent challenges from appearing. When a CAPTCHA blocks progress and cannot be bypassed, the task fails — that is the honest definition of our success rate. PerimeterX (2/18), GeeTest (0/4) and Akamai (1/6) are known weaknesses; v0.7+ (residential proxy) and v0.8+ (TLS fingerprint correction via camoufox) target these directly.
+**What cdpilot does not do:** `cdpilot` is an avoidance engine first; the solver plugins above (`cdpilot captcha`, bring your own key, off by default) are a fallback, not the strategy. We prioritize structural stealth (JS fingerprinting, behavioral entropy) to prevent challenges from appearing. When a CAPTCHA blocks progress and cannot be avoided, the task fails — that is the honest definition of our success rate. PerimeterX (2/18), GeeTest (0/4) and Akamai (1/6) are known weaknesses; named proxy pools (v0.7) help where the block is IP-based, while TLS-level fingerprinting cannot be fixed from inside a CDP-driven browser and remains open.
 
 ## Recommended Configuration
 
@@ -886,7 +1315,7 @@ Future paid offerings:
 - **No arbitrary file access** — MCP screenshot filenames are sanitized and restricted to the screenshots directory. Path traversal is blocked.
 - **Safe CSS selectors** — All selectors passed to `querySelector` are JSON-escaped to prevent injection.
 - **No network exposure** — CDP listens on `127.0.0.1` only. Remote connections are not possible by default.
-- **No dependencies** — Zero npm/Python runtime dependencies means zero supply-chain attack surface.
+- **One dependency** — zero npm packages; the Python side needs only `websockets`. A one-package supply chain is small enough to audit.
 
 Found a vulnerability? Please email the maintainer directly instead of opening a public issue.
 
@@ -924,13 +1353,13 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [x] **10 built-in test assertions** — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff
 - [x] **`test` runner + `trace` viewer** — `cdpilot test [--watch]` runs `*.cdpt.js` files; `cdpilot trace open <run>` opens a time-travel trace viewer for a run
 - [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured text with @ref handles the agent can act on directly, no vision model needed; 1.4–42× smaller than the page's raw HTML on the four pages we measured (2026-09-27). Not always cheaper than a screenshot: link-heavy pages produce more text than a small screenshot costs
-- [x] **Token-efficient screenshots** — element-level crop (13x smaller), JPEG quality control, format selection
+- [x] **Token-efficient screenshots** — element-level crop, JPEG quality control, format selection
 - [x] **Vision fallback** (`describe`) — a11y + screenshot + text in one call
 - [x] **Annotated screenshots** — @N badge overlays on interactive elements
 - [x] **Auto-wait** — MutationObserver-based, 5s automatic element waiting
 - [x] **`wait-for-text`** — adaptive text-based waiting (subtree + characterData) for streaming AI responses, async toasts, and selector-less synchronization
 - [x] **`eval-batch`** — run N JS expressions in 1 CDP roundtrip (5-30x speedup vs sequential `eval`)
-- [x] **`block`** — request blocking via `Network.setBlockedURLs` with built-in presets (images/fonts/ads/media), 3-10x faster page loads on opt-in
+- [x] **`block`** — request blocking via `Network.setBlockedURLs` with built-in presets (images/fonts/ads/media); fewer bytes and faster loads on opt-in (measure on your own pages)
 - [x] **`dismiss`** — heuristic auto-click for LLM chat sign-up walls (EN+TR pattern library, destructive-action guards)
 - [x] **`adaptive`** — auto-escalate to stealth on CAPTCHA-protected hosts, persistent per-host memory ("run fast, climb walls")
 - [x] **`cookies save/load`** — export/import cookies as JSON (replay CF/DataDome clearance across runs)