Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: add solver to SKILL.md and agent reference files

Ariae26baaa570e3
diff --git a/docs/reference/solve.md b/docs/reference/solve.md
index 3ce42425..39d8a53e 100644
--- a/docs/reference/solve.md
+++ b/docs/reference/solve.md
@@ -121,6 +121,8 @@ Handles Cloudflare Turnstile and interstitial challenges.
**Click strategy**: The solver uses human-like mouse input (Bezier curve movement, random delays, press/release offset) to click the Turnstile checkbox. Click coordinates are computed relative to the widget dimensions (not hardcoded pixel offsets) with randomised jitter.
+**Stealth requirement**: The Cloudflare solver works best with `stealthLevel: "full"` in the PinchTab config. Cloudflare evaluates browser fingerprints (CDP detection, WebGL, canvas, navigator properties) before and after the checkbox interaction. Without full stealth, the solver may click correctly but the challenge can still fail fingerprint verification. Check stealth status with `GET /stealth/status`.
+
## Writing a Custom Solver
Implement the `solver.Solver` interface and register it during `init()`:
diff --git a/npm/skills/pinchtab/SKILL.md b/npm/skills/pinchtab/SKILL.md
index 57cdaf9b..2f9e54e4 100644
--- a/npm/skills/pinchtab/SKILL.md
+++ b/npm/skills/pinchtab/SKILL.md
@@ -116,6 +116,53 @@ pinchtab click e7
pinchtab snap -i -c
```
+## Challenge Solving
+
+PinchTab includes a pluggable solver framework that auto-detects and resolves browser challenges (Cloudflare Turnstile, CAPTCHAs, interstitials). Use this **after navigation** when the page shows a challenge instead of the expected content.
+
+**Important:** Solvers work best with `stealthLevel: "full"` in the PinchTab config (or `instanceDefaults.stealthLevel: "full"`). Full stealth mode patches CDP detection vectors, rotates fingerprints, and masks automation signals — all of which challenge providers like Cloudflare check before and after the checkbox click. Without full stealth, the solver may click correctly but the challenge can still fail fingerprint verification.
+
+```bash
+# Auto-detect and solve any challenge on the current page
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3, "timeout": 30000}'
+
+# Use a specific solver
+curl -X POST http://localhost:9867/solve/cloudflare \
+ -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3}'
+
+# Tab-scoped solve
+curl -X POST http://localhost:9867/tabs/TAB_ID/solve \
+ -H 'Content-Type: application/json' \
+ -d '{}'
+
+# List available solvers
+curl http://localhost:9867/solvers
+```
+
+**When to use solve:**
+
+- Page title is "Just a moment..." or similar challenge indicator
+- `pinchtab text` returns empty or challenge-page text after navigation
+- A Cloudflare Turnstile widget blocks the target content
+
+**Workflow pattern:**
+
+```bash
+pinchtab nav https://protected-site.com
+pinchtab text # Check if page loaded or shows challenge
+# If challenge detected:
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' -d '{}'
+pinchtab text # Verify: should now show real page content
+```
+
+**Response fields:** `solver` (which solver handled it), `solved` (bool), `challengeType` (e.g. "managed"), `attempts`, `title` (final page title).
+
+The auto-detect mode (`POST /solve` without specifying a solver) tries each registered solver in order and returns immediately with `solved: true, attempts: 0` if no challenge is present. This makes it safe to call speculatively after any navigation.
+
## Handling Authentication and State
Pick one of these five patterns before you start interacting with the site.
@@ -184,9 +231,12 @@ Use this when the agent cannot call the CLI directly.
```bash
curl http://localhost:9867/health
-curl -X POST http://localhost:9867/instances/launch \
+curl -X POST http://localhost:9867/profiles \
+ -H "Content-Type: application/json" \
+ -d '{"name":"work"}'
+curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"name":"work","headless":true}'
+ -d '{"profileId":"work","mode":"headless"}'
curl -X POST http://localhost:9868/action \
-H "Content-Type: application/json" \
-d '{"kind":"click","selector":"e5"}'
@@ -312,6 +362,12 @@ curl -X POST http://localhost:9868/action \
-d '{"kind":"fill","selector":"e3","text":"[email protected]"}'
curl http://localhost:9868/text
+
+curl -X POST http://localhost:9868/solve \
+ -H "Content-Type: application/json" \
+ -d '{"maxAttempts": 3}'
+
+curl http://localhost:9868/solvers
```
Use the API when:
@@ -368,6 +424,18 @@ pinchtab fill "#search" "quarterly report"
pinchtab click "xpath://button[@type='submit']"
```
+### Navigate through a Cloudflare-protected site
+
+```bash
+pinchtab nav https://protected-site.com
+# Page may show CF challenge ("Just a moment...")
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' -d '{"maxAttempts": 3}'
+# Now the real page is loaded — proceed normally
+pinchtab snap -i -c
+pinchtab text
+```
+
### Bootstrap an authenticated profile
```bash
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 6720a730..2f9e54e4 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -116,6 +116,53 @@ pinchtab click e7
pinchtab snap -i -c
```
+## Challenge Solving
+
+PinchTab includes a pluggable solver framework that auto-detects and resolves browser challenges (Cloudflare Turnstile, CAPTCHAs, interstitials). Use this **after navigation** when the page shows a challenge instead of the expected content.
+
+**Important:** Solvers work best with `stealthLevel: "full"` in the PinchTab config (or `instanceDefaults.stealthLevel: "full"`). Full stealth mode patches CDP detection vectors, rotates fingerprints, and masks automation signals — all of which challenge providers like Cloudflare check before and after the checkbox click. Without full stealth, the solver may click correctly but the challenge can still fail fingerprint verification.
+
+```bash
+# Auto-detect and solve any challenge on the current page
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3, "timeout": 30000}'
+
+# Use a specific solver
+curl -X POST http://localhost:9867/solve/cloudflare \
+ -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3}'
+
+# Tab-scoped solve
+curl -X POST http://localhost:9867/tabs/TAB_ID/solve \
+ -H 'Content-Type: application/json' \
+ -d '{}'
+
+# List available solvers
+curl http://localhost:9867/solvers
+```
+
+**When to use solve:**
+
+- Page title is "Just a moment..." or similar challenge indicator
+- `pinchtab text` returns empty or challenge-page text after navigation
+- A Cloudflare Turnstile widget blocks the target content
+
+**Workflow pattern:**
+
+```bash
+pinchtab nav https://protected-site.com
+pinchtab text # Check if page loaded or shows challenge
+# If challenge detected:
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' -d '{}'
+pinchtab text # Verify: should now show real page content
+```
+
+**Response fields:** `solver` (which solver handled it), `solved` (bool), `challengeType` (e.g. "managed"), `attempts`, `title` (final page title).
+
+The auto-detect mode (`POST /solve` without specifying a solver) tries each registered solver in order and returns immediately with `solved: true, attempts: 0` if no challenge is present. This makes it safe to call speculatively after any navigation.
+
## Handling Authentication and State
Pick one of these five patterns before you start interacting with the site.
@@ -315,6 +362,12 @@ curl -X POST http://localhost:9868/action \
-d '{"kind":"fill","selector":"e3","text":"[email protected]"}'
curl http://localhost:9868/text
+
+curl -X POST http://localhost:9868/solve \
+ -H "Content-Type: application/json" \
+ -d '{"maxAttempts": 3}'
+
+curl http://localhost:9868/solvers
```
Use the API when:
@@ -371,6 +424,18 @@ pinchtab fill "#search" "quarterly report"
pinchtab click "xpath://button[@type='submit']"
```
+### Navigate through a Cloudflare-protected site
+
+```bash
+pinchtab nav https://protected-site.com
+# Page may show CF challenge ("Just a moment...")
+curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' -d '{"maxAttempts": 3}'
+# Now the real page is loaded — proceed normally
+pinchtab snap -i -c
+pinchtab text
+```
+
### Bootstrap an authenticated profile
```bash
diff --git a/skills/pinchtab/references/agent-optimization.md b/skills/pinchtab/references/agent-optimization.md
index c143a0fd..6a527bfd 100644
--- a/skills/pinchtab/references/agent-optimization.md
+++ b/skills/pinchtab/references/agent-optimization.md
@@ -131,15 +131,21 @@ pinchtab snap -i -c # fresh snapshot → new refs
---
-### Bot Detection / CAPTCHA
-**Cause:** Target site detected automated behavior.
+### Bot Detection / CAPTCHA / Cloudflare
+**Cause:** Target site detected automated behavior or uses a challenge gateway.
**Recovery options:**
-1. `pinchtab screenshot` — confirm what's blocking
-2. Slow down: add `pinchtab wait --ms 1500` between interactions
-3. Avoid rapid sequential clicks — space them out
-4. Switch to a profile with existing session cookies
-5. If CAPTCHA: manual intervention required — report to user
+1. Try `POST /solve` first — it auto-detects Cloudflare Turnstile and solves it:
+ ```bash
+ curl -X POST http://localhost:9867/solve \
+ -H 'Content-Type: application/json' -d '{"maxAttempts": 3}'
+ ```
+2. If solve returns `solved: false`, try with more attempts or check `challengeType`
+3. Slow down: add `pinchtab wait --ms 1500` between interactions
+4. Switch to a profile with existing session cookies (CF cookies persist)
+5. If unsupported CAPTCHA (not Cloudflare): report to user for manual intervention
+6. Check `GET /solvers` to see which solver types are available
+7. Verify `stealthLevel: "full"` is active — solvers depend on it. Check with `GET /stealth/status`
---
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index d93be101..1ba922c3 100644
--- a/skills/pinchtab/references/api.md
+++ b/skills/pinchtab/references/api.md
@@ -325,6 +325,59 @@ curl -X POST /cookies -H 'Content-Type: application/json' \
-d '{"url":"https://pinchtab.com","cookies":[{"name":"session","value":"abc123"}]}'
```
+## Solve challenges
+
+PinchTab includes a pluggable solver framework for browser challenges (Cloudflare Turnstile, CAPTCHAs, interstitials). Solvers auto-detect the challenge type and resolve it using human-like interaction.
+
+```bash
+# List available solvers
+curl /solvers
+
+# Auto-detect and solve (tries each solver in order)
+curl -X POST /solve -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3, "timeout": 30000}'
+
+# Use a specific solver by name
+curl -X POST /solve/cloudflare -H 'Content-Type: application/json' \
+ -d '{"maxAttempts": 3}'
+
+# Solve on a specific tab
+curl -X POST /tabs/TAB_ID/solve -H 'Content-Type: application/json' \
+ -d '{"solver": "cloudflare"}'
+
+# Solve on a specific tab with path-based solver
+curl -X POST /tabs/TAB_ID/solve/cloudflare -H 'Content-Type: application/json' \
+ -d '{}'
+```
+
+**Request fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `solver` | string | — | Solver name (omit for auto-detect) |
+| `tabId` | string | — | Target tab (omit for default tab) |
+| `maxAttempts` | int | 3 | Maximum solve attempts |
+| `timeout` | float | 30000 | Overall timeout in ms |
+
+**Response:**
+
+```json
+{
+ "tabId": "DEADBEEF",
+ "solver": "cloudflare",
+ "solved": true,
+ "challengeType": "managed",
+ "attempts": 1,
+ "title": "Example Site"
+}
+```
+
+Returns `solved: true, attempts: 0` when no challenge is detected — safe to call speculatively.
+
+**Built-in solvers:** `cloudflare` (Turnstile/interstitial — detects via page title, clicks checkbox with human-like input).
+
+**Stealth requirement:** Solvers work best with `stealthLevel: "full"`. Cloudflare checks browser fingerprints before and after the checkbox click. Verify stealth is active with `GET /stealth/status`.
+
## Stealth
```bash
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 2bdee7d4..3f0eb2e3 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -102,6 +102,7 @@ The MCP surface is intentionally scoped to browser automation. The following are
|------------|--------|-------------|
| Create/edit/delete profiles | ❌ Not available | Use `pinchtab profile` CLI or HTTP API |
| Configure the scheduler | ❌ Not available | Use `pinchtab schedule` CLI |
+| Solve challenges (Cloudflare, etc.) | ❌ Not available | Use `POST /solve` HTTP API |
| Modify stealth / fingerprint settings | ❌ Not available | Edit config file directly |
| Start or stop the PinchTab server | ❌ Not available | Use `pinchtab start` / `pinchtab stop` CLI |
| Manage fleet instances | ❌ Not available | Use `pinchtab instances` CLI |