cdpilot 0.8.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,7 +29,7 @@ AI agents and developers need browser control that **just works**:
29
29
 
30
30
  - **Zero config** — `npx cdpilot launch` starts an isolated browser session
31
31
  - **Zero dependency** — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP
32
- - **40+ commands** — Navigate, click, type, screenshot, network, console, accessibility, and more
32
+ - **70+ commands** — Navigate, click, type, screenshot, network, console, accessibility, video understanding, progressive anti-bot resilience, and more
33
33
  - **AI-agent friendly** — Designed for Claude, GPT, Gemini, and any LLM tool-use workflow
34
34
  - **Isolated sessions** — Your personal browser stays untouched. cdpilot runs in its own profile
35
35
  - **Visual feedback** — Green glow overlay, cursor visualization, click ripples, and keystroke display keep you informed during automation
@@ -76,7 +76,7 @@ npx cdpilot <command>
76
76
  npm i -g cdpilot
77
77
  ```
78
78
 
79
- **Requirements:** Node.js 18+ and one of: Brave Browser, Google Chrome, or Chromium.
79
+ **Requirements:** Node.js 18+, Python 3.10+, and one of: Brave Browser, Google Chrome, or Chromium. (The Python `websockets` module is auto-installed by the pre-flight wizard on first launch.)
80
80
 
81
81
  ### First-time setup
82
82
 
@@ -343,6 +343,42 @@ cdpilot dismiss aggressive # Handle chained modals (cookie banner → signup)
343
343
  > lookalikes (Delete account, Sign out, Subscribe) — safe to chain into a
344
344
  > query workflow.
345
345
 
346
+ ### Video Understanding
347
+
348
+ A single screenshot can't see motion. `cdpilot watch` runs a continuous
349
+ screencast (`Page.startScreencast`) into a ring buffer of JPEG frames, so an
350
+ AI agent can query a time window and actually *watch* what happened —
351
+ animations, mouse cursor movement, scroll, an explosion effect — instead of
352
+ guessing from one still frame.
353
+
354
+ ```bash
355
+ cdpilot watch start <url|file://...> # Begin screencast, play the video
356
+ cdpilot watch query --at 1:23 --window 5s # Frames around a timestamp
357
+ cdpilot watch ask "did the menu animate open?" # Ask about recent frames
358
+ cdpilot watch status # Show capture state + buffer size
359
+ cdpilot watch stop # Stop the screencast
360
+ ```
361
+
362
+ Works on both local files (`file://...`) and online video (YouTube, Vimeo,
363
+ Twitter, Facebook, Instagram). Zero dependency — Pillow is optional and only
364
+ used for motion-detection between frames.
365
+
366
+ > **DRM limitation:** DRM-protected players (Netflix and similar) render as
367
+ > black frames at the CDP layer — cdpilot cannot capture them. Everything
368
+ > non-DRM works.
369
+
370
+ MCP exposes this as `browser_watch_*` tools for AI agents.
371
+
372
+ ### Video Understanding (commands)
373
+
374
+ ```bash
375
+ cdpilot watch start <url|file://> # Start screencast, play video
376
+ cdpilot watch query --at 1:23 --window 5s # Frames around a timestamp
377
+ cdpilot watch ask "did the modal slide in?" # Ask about recent frames
378
+ cdpilot watch status # Capture state + buffer size
379
+ cdpilot watch stop # Stop screencast
380
+ ```
381
+
346
382
  ### Stealth & CAPTCHA
347
383
 
348
384
  Zero-dependency anti-fingerprint layer — patches `navigator.webdriver`,
@@ -351,6 +387,30 @@ vendor/renderer, permissions, hardware concurrency, and the `Worker`
351
387
  constructor. Injected via `Page.addScriptToEvaluateOnNewDocument` before
352
388
  any page script runs. Disabled by default; opt-in.
353
389
 
390
+ At launch, cdpilot also passes `--disable-blink-features=AutomationControlled`,
391
+ which closes the Blink runtime flag that Cloudflare and DataDome probe to detect
392
+ an automated browser.
393
+
394
+ #### Three-tier stealth mode
395
+
396
+ `cdpilot mode` is the recommended entry point — one switch that sets how much
397
+ fingerprint surface cdpilot touches, lightest to heaviest:
398
+
399
+ ```bash
400
+ cdpilot mode # show current tier + what it injects
401
+ cdpilot mode regular # no fingerprint patch — cleanest, fastest (default)
402
+ cdpilot mode stealth # light patch: webdriver / chrome.runtime / permissions
403
+ cdpilot mode undetected # full patch: + plugin array + WebGL + Worker
404
+ ```
405
+
406
+ `regular` is the default because Stealth Bench V1 found the full patch set
407
+ *alone* lowered scores — a synthetic plugin array is itself a tell. The
408
+ `stealth` tier deliberately omits plugin spoofing; escalate to `undetected`
409
+ only for hard targets. The adaptive layer learns the right tier per host and
410
+ escalates on CAPTCHA. Effect applies on the next navigation. Env override:
411
+ `CDPILOT_MODE=<tier>`. The legacy `stealth on/off` toggle still works and stays
412
+ coherent with the tier:
413
+
354
414
  ```bash
355
415
  cdpilot stealth on # enable fingerprint patches (opt-in)
356
416
  cdpilot stealth off # disable (default)
@@ -374,6 +434,47 @@ cdpilot adaptive clear # Drop the stealth host memory entirely
374
434
  > when it sees one — adds the host to a persistent list, retries once with
375
435
  > stealth on. Never auto-demotes. Conservative by design.
376
436
 
437
+ ### Friction Ladder (progressive anti-bot detection)
438
+
439
+ Real sites don't just throw a CAPTCHA — they stack defenses incrementally.
440
+ `cdpilot friction` reports which rung is currently active so an agent can react
441
+ appropriately instead of guessing. Six levels, lowest to highest:
442
+
443
+ ```
444
+ none → rate_limited → soft_captcha → login_wall → otp_sms → hard_block
445
+ ```
446
+
447
+ ```bash
448
+ cdpilot friction # JSON: current rung + recommended response policy
449
+ ```
450
+
451
+ Bilingual (English + Turkish) DOM heuristics. The detection is **read-only — it
452
+ never bypasses anything.** The response policy is deliberately conservative:
453
+
454
+ - `rate_limited` → automatic exponential backoff + retry
455
+ - `soft_captcha` → defer to the captcha tools
456
+ - `login_wall` / `otp_sms` / `hard_block` → flagged for **human handoff, not
457
+ autonomously solved**
458
+
459
+ That last line is an ethics boundary, not a missing feature: cdpilot will not
460
+ attempt to defeat a login, an OTP/SMS gate, or an outright block on its own.
461
+ MCP exposes this as `browser_friction`.
462
+
463
+ ### Press-and-Hold (PerimeterX / HUMAN behavioral challenge)
464
+
465
+ PerimeterX's "Press & Hold" is a *behavioral* challenge, not a token — there's
466
+ no provider to call. The only solution is a real press → hold → release
467
+ gesture, which cdpilot emits via the CDP Input domain: a Gaussian-randomized
468
+ ~3–7s hold with ±1–2px micro-jitter while the button is held.
469
+
470
+ ```bash
471
+ cdpilot press-hold # auto-find the px-captcha target
472
+ cdpilot press-hold "#px-captcha button" # explicit selector
473
+ ```
474
+
475
+ `captcha-solve` auto-routes here when it detects a `perimeterx` challenge.
476
+ MCP exposes this as `browser_press_hold`.
477
+
377
478
  ### Captcha Solver Plugins (v0.6+)
378
479
 
379
480
  Optional integration with 2captcha, anti-captcha, and capmonster. Per-solve
@@ -409,6 +510,33 @@ after each navigation. Without auto-on, detection still works but solving is man
409
510
 
410
511
  > **Expected bench improvement (v0.6):** reCaptcha 2/6 → 5+/6, hCaptcha 2/3 → 3/3
411
512
 
513
+ #### Image CAPTCHA + profile warming
514
+
515
+ `captcha-solve` handles the image-based rate-limit CAPTCHAs that the token
516
+ solvers above don't cover:
517
+
518
+ ```bash
519
+ cdpilot captcha-solve # auto-detect + route (incl. press-hold)
520
+ cdpilot captcha-solve --provider amazon-local # offline OCR (default)
521
+ cdpilot captcha-solve --provider capsolver # BYOK image-to-text
522
+ cdpilot captcha-solve --provider 2captcha # BYOK image-to-text
523
+ ```
524
+
525
+ - **Amazon classic image CAPTCHA** (the "Type the characters you see" page) is
526
+ OCR'd offline via the **optional** `amazoncaptcha` library
527
+ (`pip install amazoncaptcha` — pure-Python + Pillow, MIT). Not installed = the
528
+ command reports it and exits cleanly; no hard dependency added.
529
+ - **BYOK providers** (`capsolver`, `2captcha`) use their image-to-text APIs via
530
+ `CAPSOLVER_API_KEY` / `TWOCAPTCHA_API_KEY`.
531
+
532
+ ```bash
533
+ cdpilot profile warm # age the profile for reCAPTCHA v3 score
534
+ ```
535
+
536
+ `profile warm` browses a set of low-risk sites to build cookie/history age,
537
+ which nudges reCAPTCHA v3's behavioral score upward over time. Slow by
538
+ design — run it ahead of a session, not inline.
539
+
412
540
  Verified against public bot-detection panels:
413
541
  - **bot.sannysoft.com:** 24/24 PASS (WebDriver, Chrome obj, Plugins as PluginArray, WebGL, PHANTOM_*, HEADCHR_*, SELENIUM_DRIVER)
414
542
  - **bot.incolumitas.com** intoli: 6/6 OK — new-tests: 6/7 OK (one FAIL = pure CDP presence, cannot be JS-patched)
@@ -431,6 +559,20 @@ until cdpilot health >/dev/null; do cdpilot launch; sleep 2; done
431
559
  Surfaces today's Brave crash count from `~/Library/Logs/DiagnosticReports/`
432
560
  on macOS — spot degradation before your automation silently stalls.
433
561
 
562
+ ### Scaling & Workstation Use
563
+
564
+ ```bash
565
+ CDPILOT_OFFSCREEN=1 cdpilot launch # headed, but no window on your screen
566
+ ```
567
+
568
+ - **Off-screen mode** (`CDPILOT_OFFSCREEN=1`) keeps the browser headed (real
569
+ rendering, no headless fingerprint) but positions the window where it can't
570
+ steal focus — meant for automating on a workstation you're also using.
571
+ - **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — planned, not shipped yet.
572
+ See [Roadmap](#coming-soon).
573
+ - **Docker + Xvfb harness** — used in a separate, private benchmark
574
+ repo (`cdpilot-bench`), not part of this package.
575
+
434
576
  ## Use with AI Agents
435
577
 
436
578
  cdpilot is designed to be called by AI agents as a tool:
@@ -476,6 +618,8 @@ print(result.stdout)
476
618
  | `CHROME_BIN` | Auto-detect | Browser binary path |
477
619
  | `CDPILOT_PROFILE` | `~/.cdpilot/profile` | Isolated browser profile |
478
620
  | `BROWSER_SESSION` | Auto | Session identifier |
621
+ | `CDPILOT_MODE` | `regular` | Stealth tier override (`regular`/`stealth`/`undetected`) |
622
+ | `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
479
623
 
480
624
  ## How It Works
481
625
 
@@ -487,7 +631,7 @@ print(result.stdout)
487
631
  │ │
488
632
  │ Zero dependencies │ Isolated profile
489
633
  │ Pure HTTP + WebSocket │ Separate from your
490
- │ ~2500 lines, single file │ personal browser
634
+ │ single file, stdlib + websockets │ personal browser
491
635
  └────────────────────────────────────────┘
492
636
  ```
493
637
 
@@ -545,8 +689,8 @@ The full adaptive layer is bench-neutral vs baseline (30/80 vs 30/80) for Stealt
545
689
 
546
690
  | Feature | cdpilot | Puppeteer | Playwright | Selenium |
547
691
  |---------|-----------|-----------|------------|----------|
548
- | Install size | **~50KB** | 400MB+ | 200MB+ | 100MB+ |
549
- | Dependencies | **0** | 50+ | 30+ | Java + drivers |
692
+ | Install size | **one Python file + a small Node launcher, no node_modules** | 400MB+ | 200MB+ | 100MB+ |
693
+ | Dependencies | **0 npm** (Python: `websockets`, auto-installed) | 50+ | 30+ | Java + drivers |
550
694
  | Setup time | **instant** | minutes | minutes | painful |
551
695
  | AI-agent ready | **yes** | manual | manual | manual |
552
696
  | Browser download | **no** | yes (Chromium) | yes (3 browsers) | no |
@@ -601,10 +745,11 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
601
745
 
602
746
  ### Shipped
603
747
 
604
- - [x] 60+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
748
+ - [x] 70+ CLI commands (navigate, click, fill, screenshot, PDF, console, network, video understanding, friction ladder...)
605
749
  - [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
606
750
  - [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
607
- - [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured data with @ref references, 500x fewer tokens than screenshots
751
+ - [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
752
+ - [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
608
753
  - [x] **Token-efficient screenshots** — element-level crop (13x smaller), JPEG quality control, format selection
609
754
  - [x] **Vision fallback** (`describe`) — a11y + screenshot + text in one call
610
755
  - [x] **Annotated screenshots** — @N badge overlays on interactive elements
@@ -625,14 +770,21 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
625
770
  - [x] Pre-flight wizard (auto-installs dependencies on first run)
626
771
  - [x] Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
627
772
  - [x] DevExtension system (native JS injection without browser store)
628
- - [x] **Smart commands** — `smart-click`, `smart-fill`, `smart-select` — interact by visible text, no CSS selectors needed, no LLM required
773
+ - [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)
774
+ - [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
775
+ - [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)
776
+ - [x] **Three-tier stealth mode** (`mode regular|stealth|undetected`) — single switch over fingerprint surface, with per-host adaptive tier learning
777
+ - [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
778
+ - [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
779
+ - [x] **Off-screen mode** (`CDPILOT_OFFSCREEN`) — headed rendering without stealing window focus
629
780
  - [x] **Data extraction** (`extract`) — structured DOM data in text, JSON, or list format
630
781
  - [x] **Page observation** (`observe`) — list all interactive elements with available actions
631
782
  - [x] **Script runner** (`run`) — execute `.cdp` script files with pass/fail reporting
632
783
 
633
784
  ### Coming Soon
634
785
 
635
- - [ ] **iframe & Shadow DOM** support — interact with elements inside iframes and shadow roots
786
+ - [ ] **iframe** support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
787
+ - [ ] **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — N independent browser processes with least-loaded dispatch
636
788
  - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
637
789
  - [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
638
790
  - [ ] **cdpilot Cloud** — hosted browser sessions API, REST + WebSocket MCP endpoint
package/bin/cdpilot.js CHANGED
@@ -69,11 +69,20 @@ function findBrowser() {
69
69
  // ── Python Detection ──
70
70
 
71
71
  function findPython() {
72
- for (const cmd of ['python3', 'python']) {
72
+ // cdpilot.py uses PEP 604 unions (dict | None) → requires Python 3.10+.
73
+ // Prefer version-specific + Homebrew interpreters so a stale default python3
74
+ // (e.g. macOS 3.9) is skipped instead of selected and crashing at runtime.
75
+ const candidates = [
76
+ process.env.CDPILOT_PYTHON,
77
+ 'python3.13', 'python3.12', 'python3.11', 'python3.10',
78
+ '/opt/homebrew/bin/python3', '/usr/local/bin/python3',
79
+ 'python3', 'python',
80
+ ].filter(Boolean);
81
+ for (const cmd of candidates) {
73
82
  try {
74
83
  const ver = execSync(`${cmd} --version 2>&1`, { stdio: 'pipe' }).toString().trim();
75
84
  const match = ver.match(/(\d+)\.(\d+)/);
76
- if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 8) {
85
+ if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
77
86
  return cmd;
78
87
  }
79
88
  } catch {}
@@ -81,6 +90,21 @@ function findPython() {
81
90
  return null;
82
91
  }
83
92
 
93
+ // ── Python websockets Detection ──
94
+
95
+ function findWebsockets() {
96
+ // Import via the interpreter cdpilot actually selects — pip metadata can
97
+ // point at a different Python than findPython() resolves.
98
+ const python = findPython();
99
+ if (!python) return null;
100
+ try {
101
+ const out = execSync(`${python} -c "import websockets; print(getattr(websockets, '__version__', 'installed'))"`, { stdio: 'pipe' }).toString().trim();
102
+ return out || 'installed';
103
+ } catch {
104
+ return null;
105
+ }
106
+ }
107
+
84
108
  // ── Setup Command ──
85
109
 
86
110
  function runSetup() {
@@ -88,11 +112,12 @@ function runSetup() {
88
112
  const config = resolveProjectConfig();
89
113
 
90
114
  console.log('\n cdpilot setup\n');
91
- console.log(` Browser: ${browser || '❌ Not found'}`);
92
- console.log(` Profile: ${config.profileDir}`);
93
- console.log(` CDP Port: ${config.port === '0' ? 'auto' : config.port}`);
94
- console.log(` Project: ${config.projectId || 'manual mode'}`);
95
- console.log(` Python: ${findPython() || '❌ Not found'}`);
115
+ console.log(` Browser: ${browser || '❌ Not found'}`);
116
+ console.log(` Profile: ${config.profileDir}`);
117
+ console.log(` CDP Port: ${config.port === '0' ? 'auto' : config.port}`);
118
+ console.log(` Project: ${config.projectId || 'manual mode'}`);
119
+ console.log(` Python: ${findPython() || '❌ Not found'}`);
120
+ console.log(` websockets: ${findWebsockets() || '❌ Not found'}`);
96
121
 
97
122
  if (!browser) {
98
123
  console.log('\n ❌ No compatible browser found.');
@@ -102,11 +127,17 @@ function runSetup() {
102
127
  }
103
128
 
104
129
  if (!findPython()) {
105
- console.log('\n ❌ Python 3.8+ not found.');
130
+ console.log('\n ❌ Python 3.10+ not found.');
106
131
  console.log(' Install: https://www.python.org/downloads/\n');
107
132
  process.exit(1);
108
133
  }
109
134
 
135
+ if (!findWebsockets()) {
136
+ console.log('\n ❌ Python websockets not found.');
137
+ console.log(' Install: pip install websockets\n');
138
+ process.exit(1);
139
+ }
140
+
110
141
  // Create profile directory
111
142
  if (!fs.existsSync(config.profileDir)) {
112
143
  fs.mkdirSync(config.profileDir, { recursive: true });
@@ -147,7 +178,7 @@ function preflight() {
147
178
  const ver = execSync(`${python} --version 2>&1`, { stdio: 'pipe' }).toString().trim();
148
179
  console.log(` ✓ ${ver}`);
149
180
  } else {
150
- console.log(' ✗ Python 3.8+ not found');
181
+ console.log(' ✗ Python 3.10+ not found');
151
182
  console.log(' → Install: https://www.python.org/downloads/\n');
152
183
  process.exit(1);
153
184
  }
@@ -296,7 +327,9 @@ function showHelp() {
296
327
  setup Auto-detect browser, create isolated profile
297
328
  launch Start browser with CDP enabled
298
329
  status Check browser connection
299
- stop Stop browser
330
+ stop [--smart] Stop browser (--smart = close owned tabs, quit if empty)
331
+ close [--force|--keep] Smart close: close cdpilot's tabs; quit browser only
332
+ if no user tabs remain (--force quits anyway, --keep never quits)
300
333
 
301
334
  NAVIGATION
302
335
  go <url> Navigate to URL
@@ -347,9 +380,29 @@ function showHelp() {
347
380
  (Address a context's tab in subsequent commands via CDPILOT_TARGET=<tgt-id>)
348
381
 
349
382
  STEALTH & CAPTCHA
350
- stealth [on|off] Toggle anti-fingerprint patches (opt-in)
383
+ mode [regular|stealth|undetected]
384
+ Three-tier stealth (crawl4ai-style). regular = no patch
385
+ (cleanest, default); stealth = light patch (webdriver/
386
+ chrome.runtime/permissions); undetected = full patch
387
+ (+ plugins + WebGL + Worker). Adaptive auto-escalates.
388
+ stealth [on|off] Legacy binary toggle (on -> undetected tier)
351
389
  captcha-check Detect CAPTCHA on active page (JSON output)
352
390
  captcha-wait [s] Pause until user solves CAPTCHA (default 300s)
391
+ captcha-solve [--provider P]
392
+ Solve Amazon classic image CAPTCHA (opt-in). amazon-local
393
+ (optional amazoncaptcha lib) or BYOK capsolver/2captcha.
394
+ Auto-routes PerimeterX 'Press & Hold' to press-hold.
395
+ press-hold [selector]
396
+ Solve a PerimeterX/HUMAN 'Press & Hold' challenge with a
397
+ humanized press->hold(jitter)->release gesture (no token,
398
+ no provider). Auto-finds #px-captcha if no selector given.
399
+ friction Detect highest anti-bot rung (none/rate_limited/
400
+ soft_captcha/login_wall/otp_sms/hard_block) + policy.
401
+ rate_limit auto-backoff in 'go'; login/OTP/block = human
402
+ handoff (no autonomous bypass). Env: CDPILOT_FRICTION_BACKOFF,
403
+ CDPILOT_FRICTION_MAX_RETRY.
404
+ profile warm [--minutes N]
405
+ Age cookies/history on safe sites to boost reCAPTCHA v3 score.
353
406
  adaptive [on|off] Auto-escalate to stealth on hosts that show CAPTCHA.
354
407
  Remembers per-host. Use 'adaptive forget <host>' to reset.
355
408
  cookies save <file> [<dom>]
@@ -370,6 +423,18 @@ function showHelp() {
370
423
  AI AGENT
371
424
  mcp Start MCP server (stdin/stdout JSON-RPC)
372
425
 
426
+ WATCH (continuous screencast for AI video understanding)
427
+ watch start <url> Begin JPEG screencast at N fps to a disk ring buffer
428
+ (default 10fps, 5min retention, 100MB cap). Background
429
+ daemon — command returns immediately.
430
+ watch query --at MM:SS --window 5s
431
+ Return JSON list of frame paths around a video time.
432
+ watch query --last 5s | --since-last
433
+ Recent frames or everything new since the last query.
434
+ watch status Daemon state, frame count, disk usage.
435
+ watch stop Stop daemon + clean up frames (--keep-frames to retain).
436
+ watch ask "<q>" Tiny NL parser: extracts time window from a question.
437
+
373
438
  More: https://github.com/mehmetnadir/cdpilot#commands
374
439
  `);
375
440
  }
@@ -402,7 +467,7 @@ function runInternalTestRunner(testFile, traceDir, traceMode, grepPattern) {
402
467
  const results = { passed: 0, failed: 0, skipped: 0, tests: [] };
403
468
  const cdpPort = process.env.CDP_PORT || '9222';
404
469
  const SCRIPT = path.join(__dirname, '..', 'src', 'cdpilot.py');
405
- const python = 'python3';
470
+ const python = findPython() || 'python3';
406
471
  let stepIdx = 0;
407
472
 
408
473
  const makeT = () => {
@@ -555,7 +620,7 @@ if (cmd === 'status') {
555
620
  // Delegate to Python
556
621
  const python = findPython();
557
622
  if (!python) {
558
- console.error('Error: Python 3.8+ required. Install: https://www.python.org/downloads/');
623
+ console.error('Error: Python 3.10+ required. Install: https://www.python.org/downloads/');
559
624
  process.exit(1);
560
625
  }
561
626
 
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "cdpilot",
3
- "version": "0.8.0",
4
- "description": "Zero-dependency browser automation CLI. Raw CDP, 60+ commands, stealth + adaptive escalation, CAPTCHA solvers, proxy pools, TLS probe, MCP server. No Puppeteer/Playwright/Selenium.",
3
+ "version": "0.9.1",
4
+ "mcpName": "io.github.mehmetnadir/cdpilot",
5
+ "description": "Zero-dependency browser automation CLI. Raw CDP, 70+ commands, friction ladder, 3-tier stealth, CAPTCHA + press-and-hold solvers, proxy pools, MCP server. No Puppeteer/Playwright/Selenium.",
5
6
  "bin": {
6
7
  "cdpilot": "./bin/cdpilot.js",
7
8
  "bctl": "./bin/cdpilot.js"
@@ -42,14 +43,24 @@
42
43
  "adaptive-escalation",
43
44
  "proxy-rotation",
44
45
  "tls-fingerprint",
45
- "cookie-management"
46
+ "cookie-management",
47
+ "video-understanding",
48
+ "screencast",
49
+ "shadow-dom",
50
+ "perimeterx",
51
+ "press-and-hold",
52
+ "progressive-resilience"
46
53
  ],
47
54
  "author": "Mehmet Nadir",
48
55
  "license": "MIT",
56
+ "homepage": "https://cdpilot.ndr.ist",
49
57
  "repository": {
50
58
  "type": "git",
51
59
  "url": "https://github.com/mehmetnadir/cdpilot"
52
60
  },
61
+ "bugs": {
62
+ "url": "https://github.com/mehmetnadir/cdpilot/issues"
63
+ },
53
64
  "engines": {
54
65
  "node": ">=18.0.0"
55
66
  },