cdpilot 0.5.0 → 0.9.0

package/README.md

@@ -29,7 +29,7 @@ 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
-- **40+ commands** — Navigate, click, type, screenshot, network, console, accessibility, and more
+- **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
@@ -213,10 +213,34 @@ cdpilot throttle slow3g       # Simulate slow 3G
 cdpilot throttle fast3g       # Simulate fast 3G
 cdpilot throttle offline      # Go offline
 cdpilot throttle off          # Back to normal
-cdpilot proxy <url>           # Set proxy
+cdpilot proxy <url>           # Set proxy (legacy single-URL form)
 cdpilot proxy off             # Remove proxy
+
+# v0.7.0: named pools (BrightData, IPRoyal, Anchor, etc.)
+cdpilot proxy add brd "http://USER:PASS@brd.superproxy.io:22225" --geo us
+cdpilot proxy add ipr "http://USER:PASS@geo.iproyal.com:12321" --sticky
+cdpilot proxy use brd         # Activate one pool
+cdpilot proxy list            # Show pools (credentials redacted)
+cdpilot proxy show [<name>]   # Active or named pool URL (redacted)
+cdpilot proxy remove <name>   # Drop a pool
+```
+
+### TLS Fingerprint (v0.8.0)
+
+```bash
+cdpilot tls-check                        # Probe JA3/JA4/H2 via tls.peet.ws
+cdpilot tls-check --service browserleaks # Alternate echo
+cdpilot tls-check --json                 # Raw JSON
 ```
 
+**Known limitation:** v0.8.0 ships the **probe** (`tls-check`) but no in-tree TLS fix.
+There is no Chromium-based TLS-corrected browser that ships as a standalone binary
+exposing `--remote-debugging-port`. Camoufox is Firefox+Juggler (no CDP);
+Patchright / undetected-chromedriver / nodriver are Python/Playwright libraries,
+not standalone browsers. cdpilot's CDP-only architecture is incompatible with all
+of them without a protocol adapter. **Tracking:** v0.9 roadmap (TLS-MITM plugin
+using curl-impersonate semantics, OR BoringSSL-patched Chromium fork).
+
 ### Request Interception
 
 ```bash
@@ -264,10 +288,22 @@ cdpilot session-close [id]    # Close session
 ### Advanced
 
 ```bash
-cdpilot cookies [domain]      # List cookies (filter by domain)
-cdpilot cookies save <file> [<domain>]
-                              # Export cookies as JSON (optional domain filter)
-cdpilot cookies load <file>   # Import cookies (replay CF clearance across runs)
+cdpilot cookies [domain]             # List cookies (filter by domain)
+cdpilot cookies save <file> [<domain>]  # Export cookies as JSON
+cdpilot cookies load <file>          # Import cookies (replay CF clearance)
+cdpilot cookies save --host x.com    # Save to per-host cache
+cdpilot cookies load --host x.com    # Load from per-host cache
+cdpilot cookies list                 # Cached hosts + age + CF clearance flag
+cdpilot cookies clear --host x.com   # Remove one host
+cdpilot cookies clear --all          # Wipe entire cache
+cdpilot cookies clear --older-than 7d  # Remove stale entries
+cdpilot cookies auto on              # Toggle global auto-save/replay flag (v0.6.1: requires safe-list)
+cdpilot cookies auto add <host>      # Opt host into auto save/replay (v0.6.1)
+cdpilot cookies auto remove <host>   # Remove host from safe-list
+cdpilot cookies auto list            # Enable flag + current safe-list
+cdpilot cookies cf-replay <url>      # Inject cached CF clearance before nav
+cdpilot wipe [--cookies|--storage|--tabs|--keep h1,h2]
+                                     # v0.6.2: per-task state hygiene (cross-task contamination)
 cdpilot storage               # localStorage contents
 cdpilot upload <sel> <file>   # Upload file to input
 cdpilot multi-eval <js>       # Execute JS in all tabs
@@ -307,6 +343,42 @@ cdpilot dismiss aggressive    # Handle chained modals (cookie banner → signup)
 > lookalikes (Delete account, Sign out, Subscribe) — safe to chain into a
 > query workflow.
 
+### Video Understanding
+
+A single screenshot can't see motion. `cdpilot watch` runs a continuous
+screencast (`Page.startScreencast`) into a ring buffer of JPEG frames, so an
+AI agent can query a time window and actually *watch* what happened —
+animations, mouse cursor movement, scroll, an explosion effect — instead of
+guessing from one still frame.
+
+```bash
+cdpilot watch start <url|file://...>   # Begin screencast, play the video
+cdpilot watch query --at 1:23 --window 5s  # Frames around a timestamp
+cdpilot watch ask "did the menu animate open?"  # Ask about recent frames
+cdpilot watch status          # Show capture state + buffer size
+cdpilot watch stop            # Stop the screencast
+```
+
+Works on both local files (`file://...`) and online video (YouTube, Vimeo,
+Twitter, Facebook, Instagram). Zero dependency — Pillow is optional and only
+used for motion-detection between frames.
+
+> **DRM limitation:** DRM-protected players (Netflix and similar) render as
+> black frames at the CDP layer — cdpilot cannot capture them. Everything
+> non-DRM works.
+
+MCP exposes this as `browser_watch_*` tools for AI agents.
+
+### Video Understanding (commands)
+
+```bash
+cdpilot watch start <url|file://>     # Start screencast, play video
+cdpilot watch query --at 1:23 --window 5s  # Frames around a timestamp
+cdpilot watch ask "did the modal slide in?"  # Ask about recent frames
+cdpilot watch status                   # Capture state + buffer size
+cdpilot watch stop                     # Stop screencast
+```
+
 ### Stealth & CAPTCHA
 
 Zero-dependency anti-fingerprint layer — patches `navigator.webdriver`,
@@ -315,6 +387,30 @@ vendor/renderer, permissions, hardware concurrency, and the `Worker`
 constructor. Injected via `Page.addScriptToEvaluateOnNewDocument` before
 any page script runs. Disabled by default; opt-in.
 
+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.
+
+#### Three-tier stealth mode
+
+`cdpilot mode` is the recommended entry point — one switch that sets how much
+fingerprint surface cdpilot touches, lightest to heaviest:
+
+```bash
+cdpilot mode             # show current tier + what it injects
+cdpilot mode regular     # no fingerprint patch — cleanest, fastest (default)
+cdpilot mode stealth     # light patch: webdriver / chrome.runtime / permissions
+cdpilot mode undetected  # full patch: + plugin array + WebGL + Worker
+```
+
+`regular` is the default because Stealth Bench V1 found the full patch set
+*alone* lowered scores — a synthetic plugin array is itself a tell. The
+`stealth` tier deliberately omits plugin spoofing; escalate to `undetected`
+only for hard targets. The adaptive layer learns the right tier per host and
+escalates on CAPTCHA. Effect applies on the next navigation. Env override:
+`CDPILOT_MODE=<tier>`. The legacy `stealth on/off` toggle still works and stays
+coherent with the tier:
+
 ```bash
 cdpilot stealth on            # enable fingerprint patches (opt-in)
 cdpilot stealth off           # disable (default)
@@ -338,6 +434,109 @@ 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.
 
+### Friction Ladder (progressive anti-bot detection)
+
+Real sites don't just throw a CAPTCHA — they stack defenses incrementally.
+`cdpilot friction` reports which rung is currently active so an agent can react
+appropriately instead of guessing. Six levels, lowest to highest:
+
+```
+none → rate_limited → soft_captcha → login_wall → otp_sms → hard_block
+```
+
+```bash
+cdpilot friction              # JSON: current rung + recommended response policy
+```
+
+Bilingual (English + Turkish) DOM heuristics. The detection is **read-only — it
+never bypasses anything.** The response policy is deliberately conservative:
+
+- `rate_limited` → automatic exponential backoff + retry
+- `soft_captcha` → defer to the captcha tools
+- `login_wall` / `otp_sms` / `hard_block` → flagged for **human handoff, not
+  autonomously solved**
+
+That last line is an ethics boundary, not a missing feature: cdpilot will not
+attempt to defeat a login, an OTP/SMS gate, or an outright block on its own.
+MCP exposes this as `browser_friction`.
+
+### Press-and-Hold (PerimeterX / HUMAN behavioral challenge)
+
+PerimeterX's "Press & Hold" is a *behavioral* challenge, not a token — there's
+no provider to call. The only solution is a real press → hold → release
+gesture, which cdpilot emits via the CDP Input domain: a Gaussian-randomized
+~3–7s hold with ±1–2px micro-jitter while the button is held.
+
+```bash
+cdpilot press-hold                       # auto-find the px-captcha target
+cdpilot press-hold "#px-captcha button"  # explicit selector
+```
+
+`captcha-solve` auto-routes here when it detects a `perimeterx` challenge.
+MCP exposes this as `browser_press_hold`.
+
+### Captcha Solver Plugins (v0.6+)
+
+Optional integration with 2captcha, anti-captcha, and capmonster. Per-solve
+cost ~$0.001–0.003. API keys stored in `~/.cdpilot/captcha-providers.json`
+(chmod 600) — **never committed to git**.
+
+```bash
+# One-time setup
+cdpilot captcha config --provider 2captcha --api-key YOUR_KEY
+cdpilot captcha config --provider anticaptcha --api-key YOUR_KEY  # fallback
+
+# Enable auto-solve (adaptive layer auto-solves on detect)
+cdpilot captcha auto on
+
+# Manual solve (debug / scripting)
+cdpilot captcha solve --type recaptcha-v2 --site-key SK --url https://example.com
+# returns: {"token": "03AGdBq2...", "duration_ms": 12500, "cost": 0.003, "provider": "2captcha"}
+
+cdpilot captcha solve --type hcaptcha --site-key SK --url URL
+cdpilot captcha solve --type turnstile --site-key SK --url URL
+cdpilot captcha solve --type funcaptcha --site-key SK --url URL
+
+# Status & balance
+cdpilot captcha status   # {"configured": [...], "preferred": "2captcha", "auto_enabled": true}
+cdpilot captcha balance  # {"2captcha": 1.23, "anticaptcha": 0.50}
+```
+
+Supported types: `recaptcha-v2`, `recaptcha-v3`, `hcaptcha`, `turnstile`, `funcaptcha`
+
+Tokens are injected via `Runtime.evaluate` CDP — no browser-side libraries required.
+When `captcha auto on` is set, the adaptive layer detects and solves automatically
+after each navigation. Without auto-on, detection still works but solving is manual.
+
+> **Expected bench improvement (v0.6):** reCaptcha 2/6 → 5+/6, hCaptcha 2/3 → 3/3
+
+#### Image CAPTCHA + profile warming
+
+`captcha-solve` handles the image-based rate-limit CAPTCHAs that the token
+solvers above don't cover:
+
+```bash
+cdpilot captcha-solve                       # auto-detect + route (incl. press-hold)
+cdpilot captcha-solve --provider amazon-local  # offline OCR (default)
+cdpilot captcha-solve --provider capsolver   # BYOK image-to-text
+cdpilot captcha-solve --provider 2captcha    # BYOK image-to-text
+```
+
+- **Amazon classic image CAPTCHA** (the "Type the characters you see" page) is
+  OCR'd offline via the **optional** `amazoncaptcha` library
+  (`pip install amazoncaptcha` — pure-Python + Pillow, MIT). Not installed = the
+  command reports it and exits cleanly; no hard dependency added.
+- **BYOK providers** (`capsolver`, `2captcha`) use their image-to-text APIs via
+  `CAPSOLVER_API_KEY` / `TWOCAPTCHA_API_KEY`.
+
+```bash
+cdpilot profile warm          # age the profile for reCAPTCHA v3 score
+```
+
+`profile warm` browses a set of low-risk sites to build cookie/history age,
+which nudges reCAPTCHA v3's behavioral score upward over time. Slow by
+design — run it ahead of a session, not inline.
+
 Verified against public bot-detection panels:
 - **bot.sannysoft.com:** 24/24 PASS (WebDriver, Chrome obj, Plugins as PluginArray, WebGL, PHANTOM_*, HEADCHR_*, SELENIUM_DRIVER)
 - **bot.incolumitas.com** intoli: 6/6 OK — new-tests: 6/7 OK (one FAIL = pure CDP presence, cannot be JS-patched)
@@ -360,6 +559,24 @@ until cdpilot health >/dev/null; do cdpilot launch; sleep 2; done
 Surfaces today's Brave crash count from `~/Library/Logs/DiagnosticReports/`
 on macOS — spot degradation before your automation silently stalls.
 
+### Scaling & Workstation Use
+
+```bash
+CDPILOT_POOL_SIZE=4 cdpilot launch   # 4 separate browser processes
+CDPILOT_OFFSCREEN=1 cdpilot launch   # headed, but no window on your screen
+```
+
+- **Multi-instance pool** (`CDPILOT_POOL_SIZE=N`) starts N independent browser
+  processes and dispatches work to the least-loaded one, for `N × per-instance`
+  parallelism. Default is `1` — single instance, no change for existing users.
+- **Off-screen mode** (`CDPILOT_OFFSCREEN=1`) keeps the browser headed (real
+  rendering, no headless fingerprint) but positions the window where it can't
+  steal focus — meant for automating on a workstation you're also using.
+- **Docker + Xvfb harness** (`cdpilot-bench/docker/`) runs headed-in-Xvfb so
+  bench/automation runs never pop a window on the host display. CI-ready. Note
+  that software rendering (no GPU) lowers anti-bot scores versus native — it's
+  an isolated environment for reproducibility, not the headline configuration.
+
 ## Use with AI Agents
 
 cdpilot is designed to be called by AI agents as a tool:
@@ -405,6 +622,9 @@ print(result.stdout)
 | `CHROME_BIN` | Auto-detect | Browser binary path |
 | `CDPILOT_PROFILE` | `~/.cdpilot/profile` | Isolated browser profile |
 | `BROWSER_SESSION` | Auto | Session identifier |
+| `CDPILOT_MODE` | `regular` | Stealth tier override (`regular`/`stealth`/`undetected`) |
+| `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
+| `CDPILOT_POOL_SIZE` | `1` | N separate browser processes, least-loaded dispatch |
 
 ## How It Works
 
@@ -422,6 +642,54 @@ print(result.stdout)
 
 **No Puppeteer. No Playwright. No Selenium.** Just direct CDP communication.
 
+## Stealth Bench V1
+
+`cdpilot` is benchmarked against a suite of 80 high-friction web tasks to measure success rates against modern anti-bot systems. Gemini 2.5 Flash drives `cdpilot` as the controller; success is defined as full task completion without interception.
+
+### v0.5.3 Results (current)
+
+| Category | Success / Total | Rate |
+| :--- | :--- | :--- |
+| Custom Antibot | 5 / 5 | 100.0% |
+| Temu Slider | 1 / 1 | 100.0% |
+| hCaptcha | 2 / 3 | 67.0% |
+| Cloudflare | 12 / 22 | 55.0% |
+| DataDome | 5 / 13 | 38.0% |
+| reCaptcha | 2 / 6 | 33.0% |
+| Akamai | 1 / 6 | 17.0% |
+| PerimeterX | 2 / 18 | 11.0% |
+| GeeTest | 0 / 4 | 0.0% |
+| Shape | 0 / 1 | 0.0% |
+| Kasada | 0 / 1 | 0.0% |
+| **Total** | **30 / 80** | **37.5%** |
+
+### Version history
+
+| Version | Mode | Total | Rate |
+| :--- | :--- | :--- | :--- |
+| v0.5.0 | Baseline (stealth off / adaptive off) | 30 / 80 | 37.5% |
+| v0.5.0 | Stealth only (stealth on / adaptive off) | 32 / 80 | 40.0% |
+| v0.5.0 | Full (stealth on / adaptive on) | 26 / 80 | 32.5% |
+| v0.5.1 | Full — regression fix | 29 / 80 | 36.25% |
+| v0.5.2 | Full — entropy auto-hook | 28 / 80 | 35.0% |
+| v0.5.3 | Full — entropy scope tightened | 30 / 80 | 37.5% |
+| 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_ | — |
+
+**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.
+
+## Recommended Configuration
+
+Based on Stealth Bench V1 results:
+
+- **Speed-first** (most use cases): `cdpilot launch` — default browser behavior, no patches
+- **Stealth-on** (RECOMMENDED, best overall): `cdpilot launch && cdpilot stealth on`
+- **Full adaptive** (specific captcha-heavy workflows): `cdpilot launch && cdpilot stealth on && cdpilot adaptive on`
+
+The full adaptive layer is bench-neutral vs baseline (30/80 vs 30/80) for Stealth Bench V1's task mix. Stealth-only (32/80 = 40%) is still the best-performing single variant. For your specific workload, profile both and pick.
+
 ## Comparison
 
 | Feature | cdpilot | Puppeteer | Playwright | Selenium |
@@ -453,13 +721,36 @@ Future paid offerings:
 
 Found a vulnerability? Please email the maintainer directly instead of opening a public issue.
 
+## Cookie Persistence (v0.6+)
+
+Per-host cookie cache with auto-replay before navigation. Particularly useful for
+sites with expensive challenges (Cloudflare, DataDome) — once passed, clearance
+cookies (`cf_clearance`, `__cf_bm`) are cached and replayed on next visit.
+
+```bash
+# Enable auto-mode — cookies saved/replayed on every navigate
+cdpilot cookies auto on
+
+# Manual per-host workflow
+cdpilot cookies save --host x.com   # cache current session cookies
+cdpilot cookies load --host x.com   # inject before navigating
+cdpilot cookies cf-replay https://x.com  # explicit CF clearance injection
+
+# Inspect and clean
+cdpilot cookies list                     # all cached hosts + age + CF flag
+cdpilot cookies clear --older-than 7d   # prune stale cache
+```
+
+Storage: `~/.cdpilot/cookies/<host>/cookies.json` (chmod 600, never committed to git).
+Expired cookies are filtered automatically on load.
+
 ## Roadmap
 
 The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:
 
 ### Shipped
 
-- [x] 60+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
+- [x] 70+ CLI commands (navigate, click, fill, screenshot, PDF, console, network, video understanding, friction ladder...)
 - [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
 - [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] **Accessibility tree snapshot** (`a11y-snapshot`) — structured data with @ref references, 500x fewer tokens than screenshots
@@ -483,14 +774,20 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [x] Pre-flight wizard (auto-installs dependencies on first run)
 - [x] Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
 - [x] DevExtension system (native JS injection without browser store)
-- [x] **Smart commands** — `smart-click`, `smart-fill`, `smart-select` — interact by visible text, no CSS selectors needed, no LLM required
+- [x] **Smart commands** — `smart-click`, `smart-fill`, `smart-select` — interact by visible text, no CSS selectors needed, no LLM required. Now with a disabled-element guard (no more false "clicked" on disabled buttons), Shadow DOM traversal (Lightning, Polymer, lit-element widgets), locale-aware text matching (Turkish İ/i, German ß), and floating-label support for `smart-fill` (Material / Ant / Chakra via `aria-labelledby` and `closest` label resolution)
+- [x] **Video understanding** (`watch`) — continuous screencast into a ring buffer so an AI agent can query a time window and see motion (animation, cursor, scroll), not just one still frame. Local `file://` and online video (YouTube/Vimeo/Twitter/etc.); DRM players (Netflix) excluded
+- [x] **Friction ladder** (`friction`) — 6-level progressive anti-bot detection (none → rate_limited → soft_captcha → login_wall → otp_sms → hard_block), bilingual EN+TR, read-only; rate-limit auto-backoff, login/OTP/hard-block flagged for human handoff (no autonomous bypass)
+- [x] **Three-tier stealth mode** (`mode regular|stealth|undetected`) — single switch over fingerprint surface, with per-host adaptive tier learning
+- [x] **Press-and-hold solver** (`press-hold`) — humanized press → hold → release gesture (Gaussian 3–7s + micro-jitter) for PerimeterX/HUMAN behavioral challenges; `captcha-solve` auto-routes here
+- [x] **Image CAPTCHA + profile warming** — offline Amazon image OCR (optional `amazoncaptcha` lib) + BYOK image-to-text (capsolver/2captcha); `profile warm` ages the profile for reCAPTCHA v3 score
+- [x] **Multi-instance pool + off-screen mode** (`CDPILOT_POOL_SIZE`, `CDPILOT_OFFSCREEN`) — N parallel browser processes; headed rendering without stealing window focus
 - [x] **Data extraction** (`extract`) — structured DOM data in text, JSON, or list format
 - [x] **Page observation** (`observe`) — list all interactive elements with available actions
 - [x] **Script runner** (`run`) — execute `.cdp` script files with pass/fail reporting
 
 ### Coming Soon
 
-- [ ] **iframe & Shadow DOM** support — interact with elements inside iframes and shadow roots
+- [ ] **iframe** support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
 - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
 - [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
 - [ ] **cdpilot Cloud** — hosted browser sessions API, REST + WebSocket MCP endpoint