Skip to content

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.md
index 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 Responses
diff --git a/internal/handlers/solver.go b/internal/handlers/solver.go
index 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}/solve
diff --git a/internal/handlers/solver_test.go b/internal/handlers/solver_test.go
index f16d6804..7373cf0f 100644
--- a/internal/handlers/solver_test.go
+++ b/internal/handlers/solver_test.go
@@ -2,7 +2,9 @@ package handlers
import (
"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)
+ }
+ })
+}