High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs(dashboard): expose expanded autosolver settings
Marioa143ff2a12cb
diff --git a/dashboard/src/pages/settings/AutoSolverSettingsSection.tsx b/dashboard/src/pages/settings/AutoSolverSettingsSection.tsxindex c9e2cd9d..ce8d74b9 100644--- a/dashboard/src/pages/settings/AutoSolverSettingsSection.tsx+++ b/dashboard/src/pages/settings/AutoSolverSettingsSection.tsx@@ -45,6 +45,60 @@ export function AutoSolverSettingsSection({{backendConfig.autoSolver.enabled ? "Enabled" : "Disabled"}</label></SettingRow>+ <SettingRow+ label="Auto trigger"+ description="Automatically run autosolver after supported navigation and action requests."+ >+ <label className="flex items-center justify-end gap-3 text-sm text-text-secondary">+ <input+ type="checkbox"+ checked={backendConfig.autoSolver.autoTrigger}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ autoTrigger: e.target.checked,+ })+ }+ className="h-4 w-4"+ />+ {backendConfig.autoSolver.autoTrigger ? "Enabled" : "Disabled"}+ </label>+ </SettingRow>+ <SettingRow+ label="Trigger on navigate"+ description="Run autosolver checks after successful navigation calls."+ >+ <label className="flex items-center justify-end gap-3 text-sm text-text-secondary">+ <input+ type="checkbox"+ checked={backendConfig.autoSolver.triggerOnNavigate}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ triggerOnNavigate: e.target.checked,+ })+ }+ className="h-4 w-4"+ />+ {backendConfig.autoSolver.triggerOnNavigate ? "Enabled" : "Disabled"}+ </label>+ </SettingRow>+ <SettingRow+ label="Trigger on action"+ description="Run autosolver checks after successful action calls."+ >+ <label className="flex items-center justify-end gap-3 text-sm text-text-secondary">+ <input+ type="checkbox"+ checked={backendConfig.autoSolver.triggerOnAction}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ triggerOnAction: e.target.checked,+ })+ }+ className="h-4 w-4"+ />+ {backendConfig.autoSolver.triggerOnAction ? "Enabled" : "Disabled"}+ </label>+ </SettingRow><SettingRowlabel="Max attempts"description="Maximum autosolver retries before the pipeline gives up."@@ -61,9 +115,57 @@ export function AutoSolverSettingsSection({className={fieldClass}/></SettingRow>+ <SettingRow+ label="Solver timeout (sec)"+ description="Per-solver timeout for each attempt."+ >+ <input+ type="number"+ min={1}+ value={backendConfig.autoSolver.solverTimeoutSec}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ solverTimeoutSec: Number(e.target.value),+ })+ }+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Retry base delay (ms)"+ description="Base retry backoff delay between autosolver attempts."+ >+ <input+ type="number"+ min={0}+ value={backendConfig.autoSolver.retryBaseDelayMs}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ retryBaseDelayMs: Number(e.target.value),+ })+ }+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Retry max delay (ms)"+ description="Maximum retry backoff delay cap between autosolver attempts."+ >+ <input+ type="number"+ min={0}+ value={backendConfig.autoSolver.retryMaxDelayMs}+ onChange={(e) =>+ updateBackendSection("autoSolver", {+ retryMaxDelayMs: Number(e.target.value),+ })+ }+ className={fieldClass}+ />+ </SettingRow><SettingRowlabel="Solvers"- description="Comma-separated ordered list of solver names to try."+ description="Comma-separated ordered list of solver names to try. Use GET /solvers or GET /config/autosolver to confirm runtime-available names."><inputvalue={listToCsv(backendConfig.autoSolver.solvers)}@@ -109,7 +211,7 @@ export function AutoSolverSettingsSection({</SettingRow><SettingRowlabel="External provider keys"- description="Capsolver and 2Captcha credentials are not shown in the dashboard and must be managed in the config file."+ description="Capsolver and 2Captcha credentials are not shown in the dashboard and must be managed in the config file. Those providers appear in runtime solver lists only when keys are configured."><div className="rounded-sm border border-warning/25 bg-warning/10 px-3 py-2 text-xs leading-5 text-warning">Open the config file above and set{" "}diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.tsindex 7607883e..9874bf94 100644--- a/dashboard/src/types/index.ts+++ b/dashboard/src/types/index.ts@@ -180,7 +180,13 @@ export interface BackendTimeoutsConfig {export interface BackendAutoSolverConfig {enabled: boolean;+ autoTrigger: boolean;+ triggerOnNavigate: boolean;+ triggerOnAction: boolean;maxAttempts: number;+ solverTimeoutSec: number;+ retryBaseDelayMs: number;+ retryMaxDelayMs: number;solvers: string[];llmProvider: string;llmFallback: boolean;@@ -309,8 +315,14 @@ export const defaultBackendConfig: BackendConfig = {},autoSolver: {enabled: false,+ autoTrigger: true,+ triggerOnNavigate: true,+ triggerOnAction: true,maxAttempts: 8,- solvers: ["cloudflare", "semantic"],+ solverTimeoutSec: 30,+ retryBaseDelayMs: 500,+ retryMaxDelayMs: 10000,+ solvers: ["cloudflare", "semantic", "capsolver", "twocaptcha"],llmProvider: "",llmFallback: false,},diff --git a/docs/architecture/autosolver.md b/docs/architecture/autosolver.mdindex ca70f79c..a4bd9bb0 100644--- a/docs/architecture/autosolver.md+++ b/docs/architecture/autosolver.md@@ -27,8 +27,8 @@ The AutoSolver system provides modular, semantic-first browser automation for Pi│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ││ │ Registry │───▶│Core Loop │───▶│ Fallback │ ││ │ (solvers)│ │(detect + │ │ Chain: │ │-│ └──────────┘ │ dispatch)│ │ built-in → │ │-│ └────┬─────┘ │ semantic → │ │+│ └──────────┘ │ dispatch)│ │ semantic → │ │+│ └────┬─────┘ │ rule-based → │ ││ │ │ external → │ ││ ▼ │ LLM │ ││ ┌────────────────┐ └──────────────┘ │@@ -56,10 +56,12 @@ internal/autosolver/├── interfaces.go # Page, ActionExecutor, Solver, SemanticEngine, LLMProvider├── types.go # Result, Intent, Config, enums├── autosolver.go # Core orchestrator with fallback chain+├── challenge_detection.go # Shared challenge classification (title/URL/HTML)├── heuristics.go # Title-based intent detection fallback├── registry.go # Instance-level solver registry with priority ordering-├── autosolver_test.go # Core loop tests (7 test cases)-├── registry_test.go # Registry tests (8 test cases)+├── autosolver_test.go # Core loop tests+├── challenge_detection_test.go+├── registry_test.go├── adapters/│ └── pinchtab.go # Bridge adapter (ONLY chromedp import)├── semantic/@@ -72,6 +74,8 @@ internal/autosolver/│ └── trim.go # HTML trimming for token efficiency└── solvers/├── cloudflare.go # Cloudflare Turnstile (new interface, no chromedp)+ ├── jschallenge.go # Generic JavaScript challenge/interstitial solver+ ├── jschallenge_test.go└── legacy.go # Compatibility shim for existing solver.Solver```@@ -132,16 +136,16 @@ The core loop executes this chain per attempt:```1. Detect intent (semantic engine → title heuristics)2. If intent = normal → return solved-3. Find matching solvers (CanHandle = true, sorted by priority)-4. Try each solver:- a. Built-in (cloudflare, priority 10)- b. External (capsolver priority 200, twocaptcha priority 210)-5. If all fail AND LLM enabled:+3. Try semantic-first action planning (`/find` + self-healing)+4. If still unresolved, find matching solvers (CanHandle = true)+5. Execute solvers in configured order (`autoSolver.solvers`), falling back to+ priority order when configuration does not match available solvers+6. If all fail AND LLM enabled:a. Trim HTML to ~4KBb. Build structured prompt with attempt historyc. Execute LLM-suggested action-6. Retry with exponential backoff (500ms → 10s cap)-7. Stop after MaxAttempts (default: 8)+7. Retry with exponential backoff (500ms → 10s cap)+8. Stop after MaxAttempts (default: 8)```## Configuration@@ -152,7 +156,13 @@ The core loop executes this chain per attempt:{"autoSolver": {"enabled": true,+ "autoTrigger": true,+ "triggerOnNavigate": true,+ "triggerOnAction": true,"maxAttempts": 8,+ "solverTimeoutSec": 30,+ "retryBaseDelayMs": 500,+ "retryMaxDelayMs": 10000,"solvers": ["cloudflare", "semantic", "capsolver", "twocaptcha"],"llmProvider": "openai","llmFallback": false,@@ -230,4 +240,4 @@ if result.Solved {## Backward Compatibility-The existing `internal/solver` package (PR #395) is **not modified**. The `CloudflareSolver` in `bridge/cloudflare.go` continues to work as-is. A `LegacyAdapter` shim (`solvers/legacy.go`) wraps old `solver.Solver` implementations to work with the new `autosolver.Solver` interface.+The existing `internal/solver` package (PR #395) is still present for compatibility, but challenge APIs are now backed by `internal/autosolver`. The `CloudflareSolver` in `bridge/cloudflare.go` remains available, and a `LegacyAdapter` shim (`solvers/legacy.go`) can wrap legacy `solver.Solver` implementations into the new `autosolver.Solver` interface.diff --git a/docs/endpoints.md b/docs/endpoints.mdindex a55117c2..4c40e78d 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -104,10 +104,11 @@ Notes:- these routes are tab-scoped only- `POST /tabs/{id}/handoff` marks the tab as `paused_handoff` and records a reason-- `GET /tabs/{id}/handoff` returns the current handoff state, or `active` when no handoff is set (includes `expiresAt` and `timeoutMs` when timeout is configured)+- `GET /tabs/{id}/handoff` returns the current handoff state, or `active` when no handoff is set- `POST /tabs/{id}/resume` clears the handoff state and can carry resume metadata for the caller-- action execution routes (`/action`, `/actions`, `/macro`) reject paused tabs with `409 tab_paused_handoff`-- CLI wrappers are available: `pinchtab tab handoff`, `pinchtab tab handoff-status`, and `pinchtab tab resume`+- current behavior is advisory only: handoff state is not yet a hard block on subsequent automation requests+- treat the current implementation as temporary coordination state, not as a security boundary+- there is currently no dedicated CLI wrapper for handoff or resume; use the HTTP API## Tab Locking@@ -436,20 +437,46 @@ Console and error routes use query parameters:```textGET /solvers+GET /config/autosolverPOST /solvePOST /solve/{name}POST /tabs/{id}/solvePOST /tabs/{id}/solve/{name}```-The solver framework auto-detects and resolves browser challenges (Cloudflare Turnstile, etc.). See [Solve reference](./reference/solve.md) for details.+The autosolver framework auto-detects and resolves browser challenges (Cloudflare Turnstile, CAPTCHAs, interstitials, etc.). See [Solve reference](./reference/solve.md) for details.Solve body fields:- `solver` optional solver name (auto-detect when omitted)- `tabId` optional-- `maxAttempts` optional (default: 3)-- `timeout` optional in ms (default: 30000)+- `maxAttempts` optional (defaults to `autoSolver.maxAttempts`, default `8`)+- `timeout` optional in ms (auto-estimated when omitted, minimum `30000`)++`GET /config/autosolver` returns effective autosolver runtime settings and the+currently available solver list.++Example response:++```json+{+ "enabled": true,+ "autoTrigger": true,+ "triggerOnNavigate": true,+ "triggerOnAction": true,+ "maxAttempts": 8,+ "solverTimeoutSec": 30,+ "retryBaseDelayMs": 500,+ "retryMaxDelayMs": 10000,+ "solvers": ["cloudflare", "semantic", "jschallenge"],+ "llmProvider": "",+ "llmFallback": false+}+```++Notes:++- `capsolver` and `twocaptcha` appear in `solvers` only when their API keys are configured.## Profiles And Instancesdiff --git a/docs/reference/config.md b/docs/reference/config.mdindex b1779e78..7acb40b2 100644--- a/docs/reference/config.md+++ b/docs/reference/config.md@@ -231,7 +231,13 @@ Current nested file-config shape:},"autoSolver": {"enabled": false,+ "autoTrigger": true,+ "triggerOnNavigate": true,+ "triggerOnAction": true,"maxAttempts": 8,+ "solverTimeoutSec": 30,+ "retryBaseDelayMs": 500,+ "retryMaxDelayMs": 10000,"solvers": ["cloudflare", "semantic", "capsolver", "twocaptcha"],"llmProvider": "","llmFallback": false,@@ -272,6 +278,19 @@ Current nested file-config shape:`autoSolver.external` is config-file-only. Capsolver and 2Captcha credentialsare stored there.+### Semantic Flow Environment Variables++The semantic-first autosolver flow can consume optional environment variables+for login/signup/form-filling steps:++- `PINCHTAB_AUTOSOLVER_LOGIN_USER` or `PINCHTAB_AUTOSOLVER_LOGIN_EMAIL`: login username/email value+- `PINCHTAB_AUTOSOLVER_LOGIN_PASS` or `PINCHTAB_AUTOSOLVER_LOGIN_PASSWORD`: login password value+- `PINCHTAB_AUTOSOLVER_SIGNUP_NAME`: signup full-name value+- `PINCHTAB_AUTOSOLVER_SIGNUP_EMAIL`: signup email value+- `PINCHTAB_AUTOSOLVER_SIGNUP_PASSWORD`: signup password value+- `PINCHTAB_AUTOSOLVER_FORM_FIELD1`: generic form field value (step 1)+- `PINCHTAB_AUTOSOLVER_FORM_FIELD2` or `PINCHTAB_AUTOSOLVER_FORM_EMAIL`: generic form field/email value (step 2)+The dashboard Settings page exposes the non-secret AutoSolver settings andshows the active config file path. Provider keys remain managed directly in theconfig file.diff --git a/docs/reference/solve.md b/docs/reference/solve.mdindex 950a6dad..0242cf89 100644--- a/docs/reference/solve.md+++ b/docs/reference/solve.md@@ -2,7 +2,7 @@Detect and solve browser challenges (Cloudflare Turnstile, CAPTCHAs, interstitials, etc.) on the current page.-PinchTab ships with a pluggable **solver framework**. Each solver targets a specific provider (e.g. Cloudflare). Solvers are registered at startup and can be invoked explicitly by name or discovered automatically.+These endpoints are powered by the `internal/autosolver` pipeline. In auto mode, PinchTab runs semantic intent detection first, then tries configured solvers in order, and optionally falls back to LLM when enabled.## Endpoints@@ -22,13 +22,15 @@ curl http://localhost:9867/solvers```json{- "solvers": ["cloudflare"]+ "solvers": ["cloudflare", "semantic", "jschallenge"]}```+`capsolver` and `twocaptcha` are included when their API keys are configured.+## Auto-Detect Solve-When no `solver` field is provided, PinchTab tries each registered solver in order. The first one whose `CanHandle` returns true is used.+When no `solver` field is provided, PinchTab runs the autosolver chain using the configured order (`autoSolver.solvers`).```bashcurl -X POST http://localhost:9867/solve \@@ -68,8 +70,8 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \|--------------|--------|---------|------------------------------------------|| `tabId` | string | — | Tab ID (optional, uses default tab) || `solver` | string | — | Solver name (optional, auto-detect) |-| `maxAttempts`| int | 3 | Maximum solve attempts |-| `timeout` | float | 30000 | Overall timeout in milliseconds |+| `maxAttempts`| int | config (`autoSolver.maxAttempts`, default 8) | Maximum solve attempts |+| `timeout` | float | auto-estimated (minimum 30000) | Overall timeout in milliseconds |## Response@@ -77,12 +79,10 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \{"tabId": "DEADBEEF","solver": "cloudflare",- "solved": false,- "challengeType": "managed",+ "solved": true,+ "challengeType": "turnstile","attempts": 1,- "title": "Just a moment...",- "needsHumanHandoff": true,- "handoffReason": "challenge_requires_manual_intervention"+ "title": "thuisbezorgd.nl"}```@@ -91,11 +91,9 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \| `tabId` | string | Tab the solve ran on || `solver` | string | Which solver handled the challenge || `solved` | bool | Whether the challenge was resolved |-| `challengeType` | string | Challenge variant (e.g. `managed`, `embedded`) |+| `challengeType` | string | Challenge variant (`turnstile`, `recaptcha-v2`, `hcaptcha`) or broad intent (`captcha`, `blocked`) || `attempts` | int | Number of attempts made || `title` | string | Final page title |-| `needsHumanHandoff` | bool | Whether manual intervention is required to continue |-| `handoffReason` | string | Reason for handoff (`challenge_requires_manual_intervention`, `credentials_required`, or empty when not needed) |## Error Responses@@ -108,6 +106,14 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \## Built-In Solvers+### Semantic (`semantic`)++Semantic-first solver that uses `/find`-style matching and multi-step action planning for challenge and flow resolution.++### JS Challenge (`jschallenge`)++Generic JavaScript anti-bot/interstitial solver that waits, probes common verification controls, and polls for challenge resolution.+### Cloudflare (`cloudflare`)Handles Cloudflare Turnstile and interstitial challenges.@@ -127,35 +133,38 @@ Handles Cloudflare Turnstile and interstitial challenges.**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`.+### External Solvers++- `capsolver` (requires `autoSolver.external.capsolverKey`)+- `twocaptcha` (requires `autoSolver.external.twoCaptchaKey`)+## Writing a Custom Solver-Implement the `solver.Solver` interface and register it during `init()`:+Implement the `autosolver.Solver` interface and register it where the autosolver registry is constructed:```gopackage mygatewayimport ("context"- "github.com/pinchtab/pinchtab/internal/solver"+ "github.com/pinchtab/pinchtab/internal/autosolver")-func init() {- solver.MustRegister("mygateway", &MyGatewaySolver{})-}-type MyGatewaySolver struct{}func (s *MyGatewaySolver) Name() string { return "mygateway" }-func (s *MyGatewaySolver) CanHandle(ctx context.Context) (bool, error) {+func (s *MyGatewaySolver) Priority() int { return 150 }++func (s *MyGatewaySolver) CanHandle(ctx context.Context, page autosolver.Page) (bool, error) {// Check page markers (title, DOM elements, etc.)return false, nil}-func (s *MyGatewaySolver) Solve(ctx context.Context, opts solver.Options) (*solver.Result, error) {+func (s *MyGatewaySolver) Solve(ctx context.Context, page autosolver.Page, exec autosolver.ActionExecutor) (*autosolver.Result, error) {// Detect, interact, and resolve the challenge.- return &solver.Result{Solver: "mygateway", Solved: true}, nil+ return &autosolver.Result{SolverUsed: "mygateway", Solved: true}, nil}```-The solver has access to the full chromedp context for CDP operations.+Then add it to the handler autosolver registry setup.