High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat(solver): add human handoff signals to solve responses
Djain91270b88f5bab19
diff --git a/docs/reference/solve.md b/docs/reference/solve.mdindex 39d8a53e..950a6dad 100644--- a/docs/reference/solve.md+++ b/docs/reference/solve.md@@ -77,10 +77,12 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \{"tabId": "DEADBEEF","solver": "cloudflare",- "solved": true,+ "solved": false,"challengeType": "managed","attempts": 1,- "title": "thuisbezorgd.nl"+ "title": "Just a moment...",+ "needsHumanHandoff": true,+ "handoffReason": "challenge_requires_manual_intervention"}```@@ -92,6 +94,8 @@ curl -X POST http://localhost:9867/tabs/{tabId}/solve \| `challengeType` | string | Challenge variant (e.g. `managed`, `embedded`) || `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 Responsesdiff --git a/internal/handlers/solver.go b/internal/handlers/solver.goindex d6ad1a1f..d801d39e 100644--- a/internal/handlers/solver.go+++ b/internal/handlers/solver.go@@ -8,6 +8,7 @@ import ("fmt""io""net/http"+ "strings""time""github.com/pinchtab/pinchtab/internal/activity"@@ -32,7 +33,7 @@ import (// @Param maxAttempts int body Max solve attempts (optional, default: 3)// @Param timeout float64 body Timeout in ms (optional, default: 30000)//-// @Response 200 application/json Returns {tabId, solver, solved, challengeType, attempts, title}+// @Response 200 application/json Returns {tabId, solver, solved, challengeType, attempts, title, needsHumanHandoff, handoffReason}// @Response 400 application/json Invalid request body or unknown solver// @Response 423 application/json Tab is locked by another owner// @Response 500 application/json Chrome/CDP error@@ -114,6 +115,7 @@ func (h *Handlers) HandleSolve(w http.ResponseWriter, r *http.Request) {httpx.Error(w, 500, fmt.Errorf("solve: %w", err))return}+ needsHumanHandoff, handoffReason := deriveHumanHandoff(result)// Re-check domain policy after solve — the page may have redirected// to a different domain once the challenge was resolved.@@ -122,15 +124,49 @@ func (h *Handlers) HandleSolve(w http.ResponseWriter, r *http.Request) {}httpx.JSON(w, 200, map[string]any{- "tabId": resolvedTabID,- "solver": result.Solver,- "solved": result.Solved,- "challengeType": result.ChallengeType,- "attempts": result.Attempts,- "title": result.Title,+ "tabId": resolvedTabID,+ "solver": result.Solver,+ "solved": result.Solved,+ "challengeType": result.ChallengeType,+ "attempts": result.Attempts,+ "title": result.Title,+ "needsHumanHandoff": needsHumanHandoff,+ "handoffReason": handoffReason,})}+func deriveHumanHandoff(result *solver.Result) (bool, string) {+ if result == nil || result.Solved {+ return false, ""+ }++ challengeType := strings.ToLower(strings.TrimSpace(result.ChallengeType))+ title := strings.ToLower(strings.TrimSpace(result.Title))++ if strings.Contains(challengeType, "login") ||+ strings.Contains(challengeType, "auth") ||+ strings.Contains(challengeType, "credential") ||+ strings.Contains(challengeType, "password") ||+ strings.Contains(title, "sign in") ||+ strings.Contains(title, "log in") ||+ strings.Contains(title, "password") {+ return true, "credentials_required"+ }++ if strings.Contains(challengeType, "captcha") ||+ strings.Contains(challengeType, "turnstile") ||+ strings.Contains(challengeType, "recaptcha") ||+ strings.Contains(challengeType, "hcaptcha") ||+ strings.Contains(challengeType, "challenge") ||+ strings.Contains(title, "verify you are human") ||+ strings.Contains(title, "attention required") ||+ strings.Contains(title, "just a moment") {+ return true, "challenge_requires_manual_intervention"+ }++ return false, ""+}+// HandleTabSolve handles POST /tabs/{id}/solve and /tabs/{id}/solve/{name}.//// @Endpoint POST /tabs/{id}/solvediff --git a/internal/handlers/solver_test.go b/internal/handlers/solver_test.goindex f16d6804..7373cf0f 100644--- a/internal/handlers/solver_test.go+++ b/internal/handlers/solver_test.go@@ -2,7 +2,9 @@ package handlersimport ("bytes"+ "context""encoding/json"+ "fmt""net/http""net/http/httptest""testing"@@ -11,6 +13,20 @@ import ("github.com/pinchtab/pinchtab/internal/solver")+type testStaticSolver struct {+ name string+ result *solver.Result+ err error+}++func (s *testStaticSolver) Name() string { return s.name }+func (s *testStaticSolver) CanHandle(context.Context) (bool, error) {+ return true, nil+}+func (s *testStaticSolver) Solve(context.Context, solver.Options) (*solver.Result, error) {+ return s.result, s.err+}+func TestHandleListSolvers(t *testing.T) {h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)@@ -183,3 +199,120 @@ func TestCloudflareSolverRegistered(t *testing.T) {t.Errorf("cloudflare solver not registered: %v", names)}}++func TestDeriveHumanHandoff(t *testing.T) {+ tests := []struct {+ name string+ result *solver.Result+ wantNeeded bool+ wantReason string+ }{+ {+ name: "solved result does not require handoff",+ result: &solver.Result{Solved: true, ChallengeType: "turnstile"},+ wantNeeded: false,+ wantReason: "",+ },+ {+ name: "captcha challenge requires handoff",+ result: &solver.Result{Solved: false, ChallengeType: "cloudflare-turnstile"},+ wantNeeded: true,+ wantReason: "challenge_requires_manual_intervention",+ },+ {+ name: "credential gate requires handoff",+ result: &solver.Result{Solved: false, ChallengeType: "login"},+ wantNeeded: true,+ wantReason: "credentials_required",+ },+ {+ name: "title heuristics detect credentials requirement",+ result: &solver.Result{Solved: false, Title: "Sign In - Example"},+ wantNeeded: true,+ wantReason: "credentials_required",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ gotNeeded, gotReason := deriveHumanHandoff(tt.result)+ if gotNeeded != tt.wantNeeded || gotReason != tt.wantReason {+ t.Fatalf("deriveHumanHandoff() = (%v, %q), want (%v, %q)", gotNeeded, gotReason, tt.wantNeeded, tt.wantReason)+ }+ })+ }+}++func TestHandleSolve_AndTabSolve_IncludeHandoffFields(t *testing.T) {+ name := "test-handoff-static"+ if err := solver.Register(name, &testStaticSolver{+ name: name,+ result: &solver.Result{+ Solver: name,+ Solved: false,+ ChallengeType: "turnstile",+ Attempts: 1,+ Title: "Just a moment...",+ },+ }); err != nil {+ t.Fatalf("register test solver: %v", err)+ }+ t.Cleanup(func() { solver.Unregister(name) })++ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)++ t.Run("solve route", func(t *testing.T) {+ body := fmt.Sprintf(`{"solver": %q, "maxAttempts": 1}`, name)+ req := httptest.NewRequest("POST", "/solve", bytes.NewReader([]byte(body)))+ w := httptest.NewRecorder()+ h.HandleSolve(w, req)++ if w.Code != 200 {+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())+ }++ var resp map[string]any+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatalf("decode response: %v", err)+ }++ if _, ok := resp["needsHumanHandoff"]; !ok {+ t.Fatalf("expected needsHumanHandoff field in response: %#v", resp)+ }+ if _, ok := resp["handoffReason"]; !ok {+ t.Fatalf("expected handoffReason field in response: %#v", resp)+ }+ if needed, _ := resp["needsHumanHandoff"].(bool); !needed {+ t.Fatalf("expected needsHumanHandoff=true, got: %#v", resp["needsHumanHandoff"])+ }+ if reason, _ := resp["handoffReason"].(string); reason != "challenge_requires_manual_intervention" {+ t.Fatalf("expected handoffReason=challenge_requires_manual_intervention, got: %#v", resp["handoffReason"])+ }+ })++ t.Run("tab solve route", func(t *testing.T) {+ mux := http.NewServeMux()+ h.RegisterRoutes(mux, nil)++ body := fmt.Sprintf(`{"solver": %q, "maxAttempts": 1}`, name)+ req := httptest.NewRequest("POST", "/tabs/tab1/solve", bytes.NewReader([]byte(body)))+ w := httptest.NewRecorder()+ mux.ServeHTTP(w, req)++ if w.Code != 200 {+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())+ }++ var resp map[string]any+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatalf("decode response: %v", err)+ }++ if _, ok := resp["needsHumanHandoff"]; !ok {+ t.Fatalf("expected needsHumanHandoff field in response: %#v", resp)+ }+ if _, ok := resp["handoffReason"]; !ok {+ t.Fatalf("expected handoffReason field in response: %#v", resp)+ }+ })+}