/** * Cloudflare / CAPTCHA challenge handling (2026-10). * * The debug browser used to click blindly at a challenge page for as long as * the agent kept trying. A managed challenge is not a button: it either passes * on its own after Cloudflare's JS runs, or it needs a human. This module: * * - DETECTS a challenge from the live DOM (title, challenge form, Turnstile / * reCAPTCHA / hCaptcha iframe, block page); * - makes at most ONE bounded attempt (a single click on a Turnstile widget, * or a passive wait for a managed challenge) within a hard timeout; * - returns a structured verdict so the agent stops and asks a human instead * of sitting on the challenge. * * It is deliberately NOT a CAPTCHA solver: an image grid is never attempted, * and an interactive Turnstile that does not clear after one click is reported * as `CHALLENGE_REQUIRED`. The prompt then pauses the run with `ask_human`; * the human solves the challenge in the visible window and the answer resumes * the same session. */ import type { CdpPage } from './cdp'; export type ChallengeVendor = 'cloudflare' | 'turnstile' | 'recaptcha' | 'hcaptcha' | 'unknown'; export type ChallengeKind = /** "Just a moment..." / "Checking your browser" — usually clears itself. */ 'managed' /** A visible Turnstile checkbox/widget — one bounded click is worth trying. */ | 'turnstile' /** reCAPTCHA / hCaptcha image challenge — never attempted automatically. */ | 'captcha' /** Cloudflare block page (WAF / rate limit) — not a challenge to solve. */ | 'block'; export interface ChallengeState { detected: true; vendor: ChallengeVendor; kind: ChallengeKind; title: string; url: string; /** Widget centre (CSS pixels) when a visible widget was found. */ widget?: { x: number; y: number; width: number; height: number; }; /** Short page excerpt for the agent/human (capped). */ text?: string; } export interface ChallengeResolution { detected: boolean; attempted: boolean; passed: boolean; elapsedMs: number; /** The challenge as detected (first sighting), when one existed. */ challenge?: ChallengeState; /** True when a previous failure parked this host; no attempt was made. */ cooldown?: boolean; /** What the caller should do next when `passed` is false. */ nextStep?: 'ask_human' | 'report_blocked'; } /** * The in-page probe. Exported so the unit test can syntax-check it; it must * stay a self-contained expression returning a JSON string. */ export declare function buildChallengeProbeScript(): string; /** * Read the live page for challenge markers. Never throws — a navigation or a * destroyed execution context simply means "no challenge observed". */ export declare function detectChallenge(page: CdpPage): Promise; /** * Bounded resolution. Callers inject `detect`/`click` so this stays pure with * respect to the CDP client and can be unit-tested. * * - managed / block / captcha: never clicked. Managed may pass on its own. * - turnstile: ONE click on the widget, then wait for clearance. * - Anything still challenged at the deadline returns `passed:false` with * `nextStep` set, so the caller can stop and ask a human. */ export declare function resolveChallenge(opts: { detect: () => Promise; click?: (x: number, y: number) => Promise; attempt?: boolean; timeoutMs?: number; pollMs?: number; }): Promise;