Skip to content

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

7.8 KB
Raw Blame
package autosolver

import (
	"strings"
	"time"
)

// SemanticSolverName is what the built-in semantic stage answers to. It is a
// stage rather than a registry solver, so it has no Name() method to own its
// name — this constant is that owner, and catalog reads it to include the stage
// among the names autoSolver.solvers accepts.
const SemanticSolverName = "semantic"

// CloudflareSolverName is the registry name solvers.Cloudflare answers to. It
// lives beside SemanticSolverName because both are CONFIG-SELECTABLE: catalog
// collects them, so both are legal values of autoSolver.solvers. The LLM
// fallback's "llm" label is deliberately not in this group — see
// llmFallbackSolverLabel.
const CloudflareSolverName = "cloudflare"

// IntentType classifies the detected page state.
type IntentType string

const (
	IntentNormal     IntentType = "normal"     // No challenge or blocker detected
	IntentCaptcha    IntentType = "captcha"    // CAPTCHA challenge (Turnstile, reCAPTCHA, hCaptcha)
	IntentLogin      IntentType = "login"      // Login form detected
	IntentSignup     IntentType = "signup"     // Signup/registration form detected
	IntentForm       IntentType = "form"       // Generic form-filling flow detected
	IntentBlocked    IntentType = "blocked"    // Navigation blocked (interstitial, bot gate)
	IntentOnboarding IntentType = "onboarding" // Multi-step onboarding flow
	IntentNavigation IntentType = "navigation" // Multi-step navigation task
	IntentUnknown    IntentType = "unknown"    // Page state unclear
)

// ActionType describes the kind of browser action to perform.
type ActionType string

const (
	ActionClick    ActionType = "click"
	ActionType_    ActionType = "type"
	ActionWait     ActionType = "wait"
	ActionNavigate ActionType = "navigate"
	ActionEvaluate ActionType = "evaluate"
	ActionNone     ActionType = "none" // No action needed
)

// SolverStatus indicates the outcome of a solver attempt.
type SolverStatus string

const (
	StatusSolved  SolverStatus = "solved"
	StatusFailed  SolverStatus = "failed"
	StatusSkipped SolverStatus = "skipped"
	StatusTimeout SolverStatus = "timeout"
)

// Result is the outcome of an autosolver run.
type Result struct {
	Solved        bool           `json:"solved"`
	SolverUsed    string         `json:"solverUsed,omitempty"`
	Intent        IntentType     `json:"intent,omitempty"`
	Attempts      int            `json:"attempts"`
	TotalDuration time.Duration  `json:"totalDuration"`
	History       []AttemptEntry `json:"history,omitempty"`
	FinalTitle    string         `json:"finalTitle,omitempty"`
	FinalURL      string         `json:"finalURL,omitempty"`
	Error         string         `json:"error,omitempty"`
}

// AttemptEntry records a single solver attempt within the fallback chain.
type AttemptEntry struct {
	Solver   string        `json:"solver"`
	Status   SolverStatus  `json:"status"`
	Duration time.Duration `json:"duration"`
	Error    string        `json:"error,omitempty"`
}

// Intent represents the autosolver's understanding of the current page.
type Intent struct {
	Type       IntentType `json:"type"`
	Confidence float64    `json:"confidence"` // 0.0 to 1.0
	Details    string     `json:"details,omitempty"`

	// ChallengeType provides extra detail for captcha/blocked intents
	// (e.g., "turnstile", "recaptcha-v2", "hcaptcha", "interstitial").
	ChallengeType string `json:"challengeType,omitempty"`
}

// ElementMatch represents a matched UI element on the page.
type ElementMatch struct {
	Ref        string  `json:"ref,omitempty"`
	Role       string  `json:"role,omitempty"`
	Name       string  `json:"name,omitempty"`
	Selector   string  `json:"selector,omitempty"`
	Score      float64 `json:"score"`
	Confidence string  `json:"confidence,omitempty"` // "high", "medium", "low"
	X          float64 `json:"x,omitempty"`
	Y          float64 `json:"y,omitempty"`
}

// SuggestedAction is the autosolver's recommended next step.
type SuggestedAction struct {
	Action   ActionType `json:"action"`
	Selector string     `json:"selector,omitempty"`
	Text     string     `json:"text,omitempty"`
	URL      string     `json:"url,omitempty"`
	Expr     string     `json:"expr,omitempty"`
	X        float64    `json:"x,omitempty"`
	Y        float64    `json:"y,omitempty"`
	Reason   string     `json:"reason,omitempty"` // Why this action was chosen
}

// LLMRequest is the input to the LLM fallback provider.
// Fields are designed to minimize token usage.
type LLMRequest struct {
	PageTitle    string         `json:"pageTitle"`
	PageURL      string         `json:"pageUrl"`
	TrimmedHTML  string         `json:"trimmedHtml"`  // Stripped of scripts/styles
	DetectedType IntentType     `json:"detectedType"` // What we think the page is
	PrevAttempts []AttemptEntry `json:"prevAttempts"` // Failed attempts so far
}

// LLMResponse is the LLM's recommended action.
type LLMResponse struct {
	Action     ActionType `json:"action"`
	Selector   string     `json:"selector,omitempty"`
	Text       string     `json:"text,omitempty"`
	URL        string     `json:"url,omitempty"`
	Reasoning  string     `json:"reasoning,omitempty"`
	Confidence float64    `json:"confidence"`
}

// Credentials supplies values the semantic solver injects into recognised
// login/signup/form fields. They live in pinchtab config (write-only,
// redacted on dashboard read) and are passed through Config rather than
// pulled from process env vars.
type Credentials struct {
	Login  LoginCredentials  `json:"login"`
	Signup SignupCredentials `json:"signup"`
	Form   FormCredentials   `json:"form"`
}

type LoginCredentials struct {
	User     string `json:"user"`
	Password string `json:"password"`
}

type SignupCredentials struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	Password string `json:"password"`
}

type FormCredentials struct {
	Field1 string `json:"field1"`
	Field2 string `json:"field2"`
	Email  string `json:"email"`
}

// Config holds autosolver runtime configuration.
type Config struct {
	Enabled        bool          `json:"enabled"`
	MaxAttempts    int           `json:"maxAttempts"`
	SolverTimeout  time.Duration `json:"solverTimeout"`
	Solvers        []string      `json:"solvers"`        // Ordered solver names to try
	LLMFallback    bool          `json:"llmFallback"`    // Enable LLM as last resort
	RetryBaseDelay time.Duration `json:"retryBaseDelay"` // Base delay for exponential backoff
	RetryMaxDelay  time.Duration `json:"retryMaxDelay"`  // Cap for exponential backoff
	Credentials    Credentials   `json:"-"`              // Never serialised: redacted secrets

	// APIKeys carries the key for each key-gated solver, keyed by SOLVER NAME. A map
	// rather than a field per solver: KeyGatedSolvers owns that set, so a third gated
	// solver must not need a new field here, in the catalog, or in the handler that
	// fills this. Never serialised — these are secrets.
	APIKeys map[string]string `json:"-"`
}

// APIKey returns the configured key for a solver name, blank when unset. Trimming
// here is what makes "configured but blank" mean the same as absent everywhere that
// asks, instead of each caller remembering to trim.
func (c Config) APIKey(name string) string {
	return strings.TrimSpace(c.APIKeys[name])
}

// DefaultConfig returns a Config with sensible defaults. Enabled is false to match
// the config default: normalizedAutoSolverConfig overwrites Enabled unconditionally,
// so the only path where this value is observable is its h.Config == nil early
// return, and a core default of true would silently enable solving on the one
// configuration-free path while every configured path leaves it off.
func DefaultConfig() Config {
	return Config{
		Enabled:        false,
		MaxAttempts:    8,
		SolverTimeout:  30 * time.Second,
		Solvers:        []string{CloudflareSolverName, SemanticSolverName},
		LLMFallback:    false,
		RetryBaseDelay: 500 * time.Millisecond,
		RetryMaxDelay:  10 * time.Second,
	}
}