cdpilot 0.9.1 → 0.9.3

package/README.md

@@ -124,7 +124,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full list with rationale.
 ### Navigation & Content
 
 ```bash
-cdpilot go <url>              # Navigate to URL
+cdpilot go <url>              # Navigate to URL (alias: open <url>)
 cdpilot content               # Get page text content
 cdpilot html                  # Get page HTML
 cdpilot shot [file]           # Take screenshot (PNG)
@@ -144,6 +144,76 @@ cdpilot scroll-to <selector>  # Scroll element into view
 cdpilot drag <from> <to>      # Drag and drop
 ```
 
+### Element targeting inside iframes
+
+Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA
+checkbox live inside `<iframe>`s. Name the frame chain before the element
+selector with `>>>`, or pass `--frame`:
+
+```bash
+# Payment-style page: the card fields are inside <iframe id="card" title="Secure card payment">
+cdpilot fill  "iframe#card >>> input[name=cardnumber]" "4242424242424242"
+cdpilot type  --frame "#card" "input[name=cvc]" "123"
+cdpilot click "iframe[title='Secure card payment'] >>> button#pay-btn"
+
+# Nested frames: outermost first
+cdpilot click "iframe.checkout >>> iframe.card >>> button"
+
+# --frame <selector|index|url-substring>, nestable with >>>
+cdpilot click --frame 0 "button.submit"                   # first iframe (same order as `frame list`)
+cdpilot fill  --frame "url=js.stripe.com" "input[name=cardnumber]" "4242424242424242"
+cdpilot frame list --frame "#card"                        # iframes inside that frame
+cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's own page context
+```
+
+- Works for `click`, `fill`, `type`, `submit`, `hover`, `dblclick`, `rightclick`,
+  `smart-click`, `smart-fill`, `smart-select` and `frame list|eval|shadow`.
+- A frame hop is a CSS selector, a 0-based index, a `name`/`id`, or
+  `url=<src substring>`. `--frame` also takes a bare `src` substring.
+  `>>>` inside quotes or `[...]` is literal. A selector that matches an
+  element *wrapping* an iframe (Stripe's `#card-element`) enters the iframe
+  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
+  (`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`.
+  `--frame` never falls back: a frame it cannot find is an error (exit 1).
+- 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.
+  `smart-click "Main >>> Settings"` clicks the page's "Main >>> Settings"
+  link even when a `<main>` element holds an iframe. For a frame index or a
+  bare name use `--frame`.
+- Same-origin **and cross-origin** frames work, including out-of-process
+  iframes (site isolation): cdpilot resolves each hop over CDP
+  (`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.
+- `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
+  query is used. If the page's only such elements are disabled, the command
+  fails as before (`no enabled element matches …`) without looking in frames.
+  Otherwise the visible frames are searched breadth-first for a whole-query
+  match (at most 20 frames, and 2 s for all of the search's CDP calls) and the
+  match is reported on stderr:
+  `smart-click: matched inside frame iframe#card (https://…)`. The search only
+  looks (no click, no typing); the command then acts once, in the chosen
+  frame. With no frame match, the page's partial (word) match is used as
+  before. When the 2 s run out:
+  `smart-click: frame search stopped after 2s (3 of 7 frames)`; a frame that
+  had not answered by then has not been touched.
+- `smart-fill` and `smart-select` search automatically only frames of the
+  page's own origin, so a typed value never lands in a third-party frame (an
+  ad, chat or payment widget) by accident; reach a cross-origin frame with
+  `>>>` or `--frame`. `smart-click` searches all visible frames.
+- `frame list` without `--frame` prints the same list as before.
+
 ### Debugging
 
 ```bash
@@ -308,7 +378,8 @@ cdpilot storage               # localStorage contents
 cdpilot upload <sel> <file>   # Upload file to input
 cdpilot multi-eval <js>       # Execute JS in all tabs
 cdpilot headless [on|off]     # Toggle headless mode
-cdpilot frame list            # List iframes
+cdpilot frame list            # List iframes (index = --frame <index>)
+cdpilot frame eval --frame <f> <js>  # Run JS inside an iframe (cross-origin too)
 cdpilot dialog auto-accept    # Auto-accept dialogs
 cdpilot permission grant geo  # Grant geolocation
 ```
@@ -537,17 +608,32 @@ cdpilot profile warm          # age the profile for reCAPTCHA v3 score
 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)
-- **nowsecure.nl** (Cloudflare full challenge): passed
-- **arh.antoinevastel.com/areyouheadless:** "You are not Chrome headless"
+Public bot-detection panels, measured 2026-09-27, **headless** Brave (Chrome 154)
+([method and raw results](.claude/docs/stealth-panel-olcumu-2026-09-27.md)):
+
+| `mode` | bot.sannysoft.com (31 rows) | incolumitas intoli | incolumitas fpscanner | incolumitas new-tests |
+|---|---|---|---|---|
+| `regular` (no patches, default) | 28 pass / 3 fail | 5/6 | 17 ok / 3 fail / 1 warn | all ok |
+| `stealth` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+| `undetected` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+
+- The remaining fpscanner fail is `'webdriver' in navigator`, which is true in every modern
+  Chrome; faking it away would make cdpilot the odd one out.
+- `regular`'s fails all come from the `HeadlessChrome` user agent. `stealth`/`undetected`
+  rewrite it for the page load that `go` starts; a later, separate command in the same page
+  can still read `HeadlessChrome`.
+- new-tests: every key is ok; `connectionRTT` is reported as unknown in all tiers.
+- nowsecure.nl and areyouheadless could not be measured (a fixed always-interactive
+  Turnstile test key; HTTP 502).
+
+Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4.x in April
+2026; they are replaced by the table above.
 
 ### Reliability
 
 ```bash
 cdpilot browser [name|auto]   # workload-aware browser selection
-cdpilot health                # JSON: alive, port, tabs, browser, today's crashes
+cdpilot health                # JSON: alive, port, tabs, browser, today's crashes, idle close
 ```
 
 `cdpilot health` is designed for shell watchdogs:
@@ -559,6 +645,89 @@ 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.
 
+**Auto-launch.** A page command (`go`, `content`, `click`, `shot`, …) that finds
+the browser not running starts it the same way `cdpilot launch` does (same
+profile, same headless/visible setting), then carries on, printing one line to
+stderr: `cdpilot: browser was not running — launched it (CDPILOT_NO_AUTOLAUNCH=1 to disable)`.
+Lifecycle, status and configuration commands (`launch`, `stop`, `close`,
+`close-tab`, `stop-all`, `project-stop`, `session-close`, `status`, `health`,
+`tabs`, `sessions`, `projects`, `headless`, `proxy`, `browser`, `extensions`,
+`mcp`, `serve`, …) never launch. `CDPILOT_NO_AUTOLAUNCH=1` restores the old
+"CDP connection error. Is the browser running?" error and exit code 1.
+
+**Idle auto-close.** A browser that a page command auto-launched, or that the
+MCP server launched (`browser_launch` included), closes itself after
+**15 minutes** without a cdpilot command or a visible page change, so a
+finished agent task does not leave it holding memory. An explicit CLI
+`cdpilot launch` stays open (you may be browsing in it by hand) unless you ask:
+`cdpilot launch --idle-close 30` or `CDPILOT_IDLE_CLOSE=30`. The env var also
+sets the auto-launch delay (read when the browser starts; fractions allowed);
+`0` turns idle close off. A browser you started yourself, or one cdpilot merely
+attached to, is never closed.
+
+What counts as use: any cdpilot command except the read-only checks (`status`,
+`health`, `projects`, `version` — a `cdpilot health` watchdog loop does not keep
+the browser alive), MCP tool calls, `serve` requests, a CDP client still
+attached to a page (a long-running command, `watch`, Playwright via
+`connectOverCDP`), and any change in the open pages' URLs or in the set of
+tabs (someone navigating, a tab opened or closed). Title changes do not count,
+so a page that rewrites its own title (a clock, an unread counter) cannot keep
+the browser alive. `cdpilot status` and
+`cdpilot health` show `idle close in 12m` or `idle close off`.
+
+How: every command stamps `~/.cdpilot/projects/<id>/last-activity`; the launch
+starts a small detached watcher (one per port, no console window on Windows)
+that checks every ≤30 s, stops the browser like `cdpilot stop`, marks it
+stopped in the registry and exits — it also exits as soon as the browser is
+gone for any other reason. Browsers started by `serve --api` are managed by the
+server and have no idle close.
+
+**Timeouts.** Any command takes `--timeout <seconds>`, before or after the
+command name, or a default from `CDPILOT_TIMEOUT` (the flag wins; `0`
+disables). It bounds the whole command's wall-clock: on expiry cdpilot prints
+`cdpilot: timed out after <N>s (<command>)` to stderr, kills the child processes
+it started and exits with code **124** (like GNU `timeout`). A browser that was
+already up and registered is left running.
+
+```bash
+cdpilot --timeout 10 click "#submit"      # before the command...
+cdpilot shot page.png --timeout 30        # ...or after it
+CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each script line)
+```
+
+For `mcp` and `serve` the value is not applied to the long-running server
+itself; it is passed on to every tool call / request it runs.
+
+### Session log
+
+Every command (and every MCP tool call) appends one JSON line to a local,
+per-project log, so when a browser task is done there is a record of what was
+done and found. Nothing leaves the machine.
+
+```bash
+cdpilot log                 # today's commands: time, exit, command, url, result
+cdpilot log --md            # Markdown report: pages visited, actions, errors, files produced
+cdpilot log --json          # raw lines (one JSON object per command)
+cdpilot log --days 3        # include the last 3 days
+cdpilot log --path          # where the files are
+```
+
+Each line has `ts`, `cmd`, `args`, `exit`, `duration_ms`, the page `url` and
+`title` after the command (when the command already had them), a ~200-char
+`summary` of its output, the `error` line, and `files` it wrote (screenshots,
+PDFs). Files live in `~/.cdpilot/projects/<project-id>/log/<YYYY-MM-DD>.jsonl`.
+
+Redaction happens before anything is written: values given to `fill`, `type`,
+`smart-fill`, `smart-select`, `assert-value` and `dialog prompt` become
+`«redacted:N chars»`; so do values of password/token/key/secret/cookie/auth
+flags and headers, token-shaped arguments, and URL query/fragment values whose
+names contain token, key, secret, password, auth, code or session. `cookies`
+and `storage` output is never logged; `eval` source is, with string literals
+over 40 chars cut and secret-looking ones replaced. Logging is best effort: it
+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`.
+
 ### Scaling & Workstation Use
 
 ```bash
@@ -620,6 +789,11 @@ print(result.stdout)
 | `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_TIMEOUT` | unset | Default `--timeout` in seconds for every command (flag wins, `0` disables); expiry exits 124 |
+| `CDPILOT_NO_AUTOLAUNCH` | `0` | `1` = page commands fail with the old "Is the browser running?" error instead of launching the browser |
+| `CDPILOT_IDLE_CLOSE` | `15` | Minutes without a cdpilot command or page change before a browser cdpilot launched closes itself (fractions allowed, `0` = never; read at launch). Default applies to auto-launch and MCP launches; an explicit CLI `launch` is off unless this is set or `--idle-close <min>` is given |
+| `CDPILOT_LOG` | `1` | `0` = do not write the session log (`cdpilot log`) |
+| `CDPILOT_LOG_DAYS` | `14` | Days of session log to keep; older day files are deleted on the first write of a day (`0` keeps all) |
 
 ## How It Works
 
@@ -780,10 +954,10 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [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
+- [x] **iframe targeting** — `"iframe#card >>> input"` / `--frame` for element commands, same-origin and cross-origin (out-of-process) frames; smart commands search frames automatically
 
 ### Coming Soon
 
-- [ ] **iframe** support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
 - [ ] **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — N independent browser processes with least-loaded dispatch
 - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
 - [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving

package/bin/cdpilot.js

@@ -242,7 +242,8 @@ function runStatus() {
           console.log(`  ✓ Connected`);
           console.log(`  Browser: ${info.Browser || 'Unknown'}`);
           console.log(`  Protocol: ${info['Protocol-Version'] || 'Unknown'}`);
-          console.log(`  WebSocket: ${info.webSocketDebuggerUrl || 'N/A'}\n`);
+          console.log(`  WebSocket: ${info.webSocketDebuggerUrl || 'N/A'}`);
+          console.log(`  ${idleCloseLabel(port)}\n`);
         } catch {
           console.log('  ✓ CDP responding but version info unavailable\n');
         }
@@ -262,6 +263,33 @@ function runStatus() {
   }
 }
 
+// Idle auto-close countdown, from the files src/cdpilot.py keeps (see
+// _idle_status there): CDPILOT_HOME/idle/<port>.json names the watcher and its
+// minutes, CDPILOT_HOME/projects/<id>/last-activity the last command.
+function idleCloseLabel(port) {
+  const home = process.env.CDPILOT_HOME || path.join(os.homedir(), '.cdpilot');
+  try {
+    const st = JSON.parse(fs.readFileSync(path.join(home, 'idle', `${port}.json`), 'utf-8'));
+    const minutes = Number(st.minutes) || 0;
+    if (minutes <= 0 || !st.pid) return 'idle close off';
+    try {
+      process.kill(st.pid, 0); // existence probe; safe on Windows in Node
+    } catch (e) {
+      if (e.code !== 'EPERM') return 'idle close off';
+    }
+    let last = Number(st.started) || Date.now() / 1000;
+    try {
+      const file = path.join(home, 'projects', String(st.project_id), 'last-activity');
+      const t = parseFloat(fs.readFileSync(file, 'utf-8'));
+      if (t > last) last = t;
+    } catch {}
+    const left = Math.max(0, Math.floor(minutes * 60 - (Date.now() / 1000 - last)));
+    return `idle close in ${Math.ceil(left / 60)}m`;
+  } catch {
+    return 'idle close off';
+  }
+}
+
 // ── Version ──
 
 function showVersion() {
@@ -321,18 +349,29 @@ function showHelp() {
   cdpilot v${VERSION} — Zero-dependency browser automation
 
   USAGE
-    cdpilot <command> [args]
+    cdpilot [--timeout <s>] <command> [args]
+
+  GLOBAL OPTIONS
+    --timeout <s>      Abort the command after <s> seconds (exit 124). Before or
+                       after the command; env CDPILOT_TIMEOUT sets a default
+                       (the flag wins, 0 disables).
+    Page commands start the browser if it is not running
+                       (set CDPILOT_NO_AUTOLAUNCH=1 to get an error instead).
+    An auto-launched (or MCP-launched) browser closes after 15 min without a
+                       cdpilot command or page change (CDPILOT_IDLE_CLOSE=<minutes>,
+                       0 = never); an explicit launch stays open unless asked (below).
 
   SETUP
     setup              Auto-detect browser, create isolated profile
-    launch             Start browser with CDP enabled
+    launch [--idle-close <min>]  Start browser with CDP enabled (--idle-close or
+                       CDPILOT_IDLE_CLOSE: close it after <min> idle minutes)
     status             Check browser connection
     stop [--smart]     Stop browser (--smart = close owned tabs, quit if empty)
     close [--force|--keep]  Smart close: close cdpilot's tabs; quit browser only
                        if no user tabs remain (--force quits anyway, --keep never quits)
 
   NAVIGATION
-    go <url>           Navigate to URL
+    go <url>           Navigate to URL (alias: open)
     content            Get page text content
     html               Get page HTML
     shot [file]        Take screenshot
@@ -345,6 +384,14 @@ function showHelp() {
     submit <form>      Submit form
     hover <sel>        Hover element
     keys <combo>       Keyboard shortcut
+    Inside an iframe:  click "iframe#card >>> input[name=cardnumber]"
+                       (nest: "iframe.a >>> iframe.b >>> button") or
+                       --frame <selector|index|url-substring>; same-origin and
+                       cross-origin frames. With no match in the page,
+                       smart-click searches all frames, smart-fill and
+                       smart-select only frames of the page's origin.
+    frame list|eval [--frame <f>]
+                       List iframes / run JS inside a frame
 
   DEBUGGING
     console [url]      Capture console logs
@@ -423,6 +470,16 @@ function showHelp() {
   AI AGENT
     mcp                Start MCP server (stdin/stdout JSON-RPC)
 
+  SESSION LOG (always on, local, redacted)
+    log                Today's commands for this project: time, exit, command,
+                       url, result
+    log --md           Markdown report (pages visited, actions, errors, files
+                       produced) to paste into an issue or PR
+    log --json         Raw JSON lines · log --days N · log --path (log directory)
+                       Typed values, secret-looking args and token/key/secret URL
+                       params are redacted. CDPILOT_LOG=0 turns it off;
+                       CDPILOT_LOG_DAYS (default 14) sets how many days are kept.
+
   WATCH (continuous screencast for AI video understanding)
     watch start <url>  Begin JPEG screencast at N fps to a disk ring buffer
                        (default 10fps, 5min retention, 100MB cap). Background
@@ -590,8 +647,23 @@ if (process.argv.includes('--internal-test-runner')) {
   return; // runAll() is async, this exits via process.exit
 }
 
+// Global flags may precede the command name (`cdpilot --timeout 10 click "#x"`).
+// src/cdpilot.py parses and validates them (it is also run directly, without
+// this launcher); here they only have to be skipped to find the command that
+// the launcher answers itself (help / --version / setup / status). args are
+// passed to Python unchanged.
+function commandIndex(argv) {
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--timeout') { i += 2; continue; }
+    if (argv[i].startsWith('--timeout=')) { i += 1; continue; }
+    break;
+  }
+  return i;
+}
+
 const args = process.argv.slice(2);
-const cmd = args[0];
+const cmd = args[commandIndex(args)];
 
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showHelp();
@@ -650,7 +722,14 @@ if (cmd === 'status') {
     env,
   });
 
-  child.on('close', (code) => {
-    process.exit(code || 0);
+  // A child killed by a signal reports code === null. `code || 0` turned that
+  // into success, so an OOM-killed or SIGKILLed run looked fine to scripts
+  // and agents. Use the shell convention 128 + signal number instead.
+  child.on('close', (code, signal) => {
+    if (code === null && signal) {
+      console.error(`cdpilot: python was terminated by ${signal}`);
+      process.exit(128 + (os.constants.signals[signal] || 0));
+    }
+    process.exit(code ?? 0);
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "mcpName": "io.github.mehmetnadir/cdpilot",
   "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.",
   "bin": {