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 +161 -9
- package/bin/cdpilot.js +78 -13
- package/package.json +14 -3
- package/src/cdpilot.py +2735 -177
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
|
-
- **
|
|
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
|
|
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
|
-
│
|
|
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 |
|
|
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]
|
|
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]
|
|
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
|
|
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
|
-
|
|
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])
|
|
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:
|
|
92
|
-
console.log(` Profile:
|
|
93
|
-
console.log(` CDP Port:
|
|
94
|
-
console.log(` Project:
|
|
95
|
-
console.log(` Python:
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
4
|
-
"
|
|
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
|
},
|