captchakraken 2.3.0 → 2.6.0

package/python/src/captchakraken/tool_calls/track_piece.py

@@ -0,0 +1,96 @@
+"""Track the puzzle piece of a slide captcha by what MOVED, not by what it is.
+
+A puzzle-piece slider gives the model one thing to say — where the gap is — and
+gives the driver no way to act on it directly. You drag a handle somewhere else
+on the widget; the piece follows at a ratio nobody publishes, clamped to a track
+whose ends you cannot read off the picture. Vendors vary the ratio precisely so
+that a solver cannot compute the handle offset from the gap position.
+
+So the driver does not compute it. It presses the handle, nudges, looks at what
+changed on screen, and closes the loop. This module is the "looks at what
+changed" step, and nothing more: one function, one bounding box.
+
+    changed_bbox(before, after, exclude=...) -> [x1, y1, x2, y2] | None
+
+The box is the union of every pixel that differs between two screenshots of the
+same widget. During a slider drag exactly one thing has moved — the piece — so
+that union is:
+
+    left edge  = the piece's ORIGINAL left edge   (the vacated ground)
+    right edge = the piece's CURRENT right edge
+
+which is what makes it useful: neither edge alone gives the piece's centre, but
+two of these boxes at two known handle offsets give both the piece's width and
+the handle-to-piece ratio, by simple algebra the caller does. See
+`PageSolver._execute_slide`.
+
+`exclude` is the reason this takes an argument at all. The handle is also
+moving, and on most vendors so is a filled progress bar behind it, and both are
+inside the same screenshot. Left in, they would dominate the union and the
+tracked "piece" would just be the handle. The caller passes the handle's own
+rectangle — it has the element, so it knows exactly where it is — and this masks
+it out. Everything else in the frame is static during a drag.
+
+Pure OpenCV, no network, byte-deterministic.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+import cv2
+import numpy as np
+
+# A pixel counts as changed at this 0–255 grayscale delta. Low enough to catch a
+# piece sliding over background of similar luminance, high enough to ignore JPEG
+# ringing and the 1–2 level jitter of an antialiased edge redrawn a subpixel
+# over.
+_DIFF_THRESHOLD = 18
+
+# Below this many changed pixels the frame is treated as UNCHANGED. A press that
+# has not moved yet, or a drag against the end of the track, produces a handful
+# of stray pixels; calling that a piece would hand the caller a garbage box and
+# it would steer by it.
+_MIN_CHANGED_PIXELS = 40
+
+
+def changed_bbox(
+    before_path: str,
+    after_path: str,
+    exclude: Optional[Sequence[float]] = None,
+) -> Optional[list]:
+    """Bounding box of everything that moved between two shots of one widget.
+
+    `exclude` is an [x1, y1, x2, y2] rectangle in the same pixel space, masked
+    out before measuring — pass the slider handle's own box.
+
+    Returns [x1, y1, x2, y2] in pixels, or None when nothing moved (or the
+    images are unreadable / mismatched, which is the same answer to the caller:
+    steer by the last good reading instead of by noise).
+    """
+    a = cv2.imread(before_path, cv2.IMREAD_GRAYSCALE)
+    b = cv2.imread(after_path, cv2.IMREAD_GRAYSCALE)
+    if a is None or b is None or a.shape != b.shape:
+        return None
+
+    mask = (cv2.absdiff(a, b) > _DIFF_THRESHOLD).astype(np.uint8)
+
+    if exclude is not None:
+        x1, y1, x2, y2 = (int(round(float(v))) for v in exclude)
+        # Clamp to the frame — a handle drawn flush with the widget edge, or one
+        # whose box is reported a pixel outside it, must still mask.
+        x1, y1 = max(0, x1), max(0, y1)
+        x2, y2 = min(mask.shape[1], x2), min(mask.shape[0], y2)
+        if x2 > x1 and y2 > y1:
+            mask[y1:y2, x1:x2] = 0
+
+    # Erode away single-pixel speckle (compression noise, cursor artifacts)
+    # before measuring: the box is an EXTREME of the mask, so one stray pixel in
+    # the corner moves it as much as the piece does.
+    mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, np.ones((3, 3), np.uint8))
+
+    if int(mask.sum()) < _MIN_CHANGED_PIXELS:
+        return None
+
+    ys, xs = np.nonzero(mask)
+    return [int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1]

package/python/src/captchakraken/trajectory.py

@@ -1,11 +1,8 @@
 """
 Human-like mouse trajectories for the page driver.
 
-MIRRORS, DOES NOT PORT, `cursory-ts`. The TypeScript driver calls
-`generate_trajectory()` from cursory-ts, which selects and warps a real recorded
-human trace out of a bundled ~MB corpus (`data/trajectories.json.gz`). That
-corpus is the package's own asset, so the Python port synthesises comparable
-motion instead of shipping a second copy of someone else's data.
+The Python side of `js/src/trajectory.ts`; the two are one implementation in
+two languages, pinned by `test_trajectory_parity.py`.
 
 The CONTRACT is identical, which is what matters for keeping the two drivers in
 step: given a start point, an end point and a sampling frequency, return
@@ -89,8 +86,6 @@ def generate_trajectory(
     frequency_randomizer: float = 0.12,
 ) -> Tuple[List[Point], List[float]]:
     """
-    Mirror of cursory-ts `generate_trajectory`.
-
     Returns `(points, timings)`. `timings` is CUMULATIVE milliseconds from the
     gesture start — not per-step deltas — because that is what the TS driver's
     `tracePath` sleeps against, and the two must pace identically.

package/python/src/captchakraken/watcher.py

@@ -0,0 +1,193 @@
+"""
+Auto-solve watcher — the Python mirror of `js/src/watcher.ts`.
+
+Install it once and captchas are solved as they appear, instead of the caller
+having to know where in their script a challenge might show up.
+
+WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
+The obvious implementation is a `MutationObserver` in the page that calls out
+through an exposed binding. That reacts faster, and it is also the one design
+that cannot be made stealthy everywhere: an exposed binding puts a function on
+`window`, and an observer is script the page can enumerate. Under Camoufox both
+are sandboxed and invisible; under vanilla Playwright or patchright they are
+not, and a captcha vendor is precisely the party that looks.
+
+So this injects NOTHING. It drives the same `detect_captcha()` the solver
+already uses, from the driver side, on a timer:
+
+  - nothing is added to the page on ANY launcher, so there is no new detection
+    surface to reason about per platform;
+  - under Camoufox the probe's DOM reads land in its isolated Juggler world for
+    free — that is Camoufox's default for all Playwright evaluation, with
+    `main_world_eval` / an "mw:" prefix as the opt-OUT. This never opts out, so
+    it is isolated there by construction rather than by special-casing;
+  - reaction time is bounded by `interval_ms`, not by the mutation.
+
+ONE WATCHER COVERS THE WHOLE PAGE, FOR ITS WHOLE LIFE
+A page outlives navigation, and so does the watcher holding it: install it once
+and it keeps probing across every `goto`, staying quiet while there is nothing
+to solve and re-arming after each solve. That is deliberately the whole API --
+the case that motivates a browser-wide installer is almost always a challenge
+appearing on request 40 of a run, on the SAME page object the run started with,
+and that is already covered by one line. Pinned in test_browser_compat.py.
+
+WHY IT BLOCKS, WHERE THE TS PORT DOES NOT (CLAUDE.md 1c)
+`solver.watch(page)` in TypeScript returns immediately and watches in the
+background. It cannot here, and the reason is Playwright's, not ours: a SYNC
+Playwright handle is bound to the greenlet that created it, so driving the page
+from a worker thread raises. `threading` would not buy a background watcher, it
+would buy an exception on the first probe.
+
+The two shapes offered instead:
+
+    solver.watch(page).run()          # blocking: hold this page clean
+    watcher = solver.watch(page)
+    while my_own_loop():
+        watcher.poll_once()           # cooperative: you own the cadence
+
+`poll_once()` is the one to reach for inside an existing automation loop; it
+does exactly one probe, solves if there is something to solve, and returns.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Tuple
+
+__all__ = ["CaptchaWatcher"]
+
+
+def _page_is_closed(page: Any) -> bool:
+    """True when the launcher says the page is gone.
+
+    Duck-typed like everything else that touches the page: Playwright and
+    Puppeteer both expose `is_closed`/`isClosed`, but this module refuses to
+    depend on either, and a launcher without it is simply treated as open.
+    """
+    for name in ("is_closed", "isClosed"):
+        probe = getattr(page, name, None)
+        if callable(probe):
+            try:
+                return bool(probe())
+            except Exception:
+                return False
+    return False
+
+
+def _report(callback: Optional[Callable[[Any], Any]], value: Any) -> None:
+    """Hand a value to a user callback without letting its failure reach the loop."""
+    if callback is None:
+        return
+    try:
+        callback(value)
+    except Exception:
+        # A throwing callback is the caller's bug, not a reason to stop watching.
+        pass
+
+
+@dataclass
+class CaptchaWatcher:
+    """Polls one page and solves whatever captcha becomes visible on it."""
+
+    solver: Any
+    page: Any
+    #: Milliseconds between probes. Each tick costs one `detect_captcha()` — a
+    #: handful of selector queries. Below ~250ms you pay real CPU for latency
+    #: the solve itself (seconds) makes irrelevant.
+    interval_ms: int = 1000
+    #: Stop after this many successful solves. None means unlimited.
+    max_solves: Optional[int] = None
+    #: Wait this long after a solve RAISES before probing again. Without it a
+    #: permanently unsupported challenge — an invisible reCAPTCHA v3, say —
+    #: becomes a hot loop that re-attempts and re-bills every interval forever.
+    error_backoff_ms: int = 5000
+    #: Called with the `SolveResult` of each completed solve.
+    on_solved: Optional[Callable[[Any], Any]] = None
+    #: Called with any exception from detection or solving. Errors are reported,
+    #: never fatal: `NoCaptchaFoundError` fires routinely when a widget vanishes
+    #: between the probe and the solve, and a watcher that died on it would be
+    #: useless.
+    on_error: Optional[Callable[[BaseException], Any]] = None
+
+    solves: int = field(default=0, init=False)
+    _stopped: bool = field(default=False, init=False)
+
+    @property
+    def running(self) -> bool:
+        """False once stopped, the page closed, or `max_solves` was reached."""
+        if self._stopped or _page_is_closed(self.page):
+            return False
+        return self.max_solves is None or self.solves < self.max_solves
+
+    def stop(self) -> None:
+        """End the loop. Safe to call from `on_solved` / `on_error`, or twice."""
+        self._stopped = True
+
+    def poll_once(self) -> Optional[Any]:
+        """
+        One probe. Solves if a captcha is visible; returns its `SolveResult`,
+        or None when there was nothing to do (or the attempt failed and was
+        reported to `on_error`).
+
+        Does NOT sleep — the caller owns the cadence. `run()` is this plus the
+        waiting and the backoff.
+        """
+        return self._attempt()[0]
+
+    def _attempt(self) -> Tuple[Optional[Any], bool]:
+        """
+        `(result, failed)`.
+
+        The second element is the whole reason this is not just `poll_once`:
+        that method returns None both for "no captcha on the page" and for "a
+        solve was attempted and raised", and `run()` must back off after the
+        second while re-probing cheaply after the first. Collapsing the two
+        either hot-loops on an unsupported challenge or adds a five-second
+        stall to every idle tick.
+        """
+        if not self.running:
+            return None, False
+        try:
+            if not self.solver.detect_captcha(self.page):
+                return None, False
+            result = self.solver.solve(self.page)
+        except Exception as exc:  # noqa: BLE001 - reported, never fatal
+            # KeyboardInterrupt / SystemExit are deliberately NOT caught: a
+            # Ctrl-C during a long solve must reach the caller.
+            if _page_is_closed(self.page):
+                self.stop()
+                return None, False
+            _report(self.on_error, exc)
+            return None, True
+        if result is not None:
+            self.solves += 1
+            _report(self.on_solved, result)
+        return result, False
+
+    def _sleep(self, ms: float) -> None:
+        """Sleep in slices so `stop()` and Ctrl-C are not held for a whole interval."""
+        deadline = time.monotonic() + ms / 1000.0
+        while time.monotonic() < deadline:
+            if self._stopped:
+                return
+            time.sleep(min(0.1, max(0.0, deadline - time.monotonic())))
+
+    def run(self, timeout_ms: Optional[int] = None) -> int:
+        """
+        Watch until `stop()`, the page closes, `max_solves` is hit, or
+        `timeout_ms` elapses. Returns the number of captchas solved.
+
+        Blocking by design — see this module's docstring on why the TypeScript
+        port can hand back a background handle and this cannot.
+        """
+        deadline = None if timeout_ms is None else time.monotonic() + timeout_ms / 1000.0
+        while self.running:
+            if deadline is not None and time.monotonic() >= deadline:
+                break
+            self._sleep(self.interval_ms)
+            if not self.running:
+                break
+            if self._attempt()[1]:
+                self._sleep(self.error_backoff_ms)
+        return self.solves

package/python/src/captchakraken/planner_types.py

@@ -1,74 +0,0 @@
-from typing import List, Literal, Optional, Union, Dict
-from pydantic import BaseModel, Field, model_validator
-
-
-class PlannerAction(BaseModel):
-    goal: Optional[str] = Field(None, description="Description of the visual goal")
-
-
-class PlannerClickAction(PlannerAction):
-    action: Literal["click"]
-    target_ids: List[int] = Field(description="List of object IDs or grid cell numbers to click")
-
-
-class PlannerDragAction(PlannerAction):
-    action: Literal["drag"]
-    source_id: int = Field(description="Object ID of item to drag")
-    target_id: int = Field(description="Object ID of destination")
-
-
-class PlannerTypeAction(PlannerAction):
-    action: Literal["type"]
-    text: str = Field(description="Text to type into the input")
-    target_id: int = Field(description="Object ID of the input field")
-
-
-class PlannerWaitAction(PlannerAction):
-    action: Literal["wait"]
-    duration_ms: int = Field(default=500, description="Duration to wait in milliseconds")
-
-
-class PlannerDoneAction(PlannerAction):
-    action: Literal["done"]
-
-
-class DragGuess(BaseModel):
-    Action: Literal["simulate_drag"]
-    SourceID: int
-    DestinationDescription: str
-    EstimatedPosition: Dict[str, int] = Field(description="{'x': 1-1000, 'y': 1-1000}")
-
-
-class DragRefineResult(BaseModel):
-    SourceId: int
-    estimatedVerticalDistanceFromTarget: int = Field(description="negative = above, positive = below")
-    estimatedHorizontalDistanceFromTarget: int = Field(description="negative = left, positive = right")
-
-
-class PlannerDragRefineAction(PlannerAction):
-    # This is for Step 3: Verification and adjustment
-    output: List[DragRefineResult]
-
-
-class PlannerToolCall(BaseModel):
-    name: Literal["detect", "simulate_drag"]
-    args: dict
-
-
-class PlannerPlan(BaseModel):
-    goal: Optional[str] = None
-    tool_calls: Optional[List[PlannerToolCall]] = None
-    # Step 1: Detect all draggable items
-    objectDescription: Optional[str] = None
-    # Step 2: Initial guess (general LoRa) uses output
-    output: Optional[List[DragGuess]] = None
-    # We allow the planner to return either a direct action or tool calls or new output format
-    action: Optional[Union[PlannerClickAction, PlannerDragAction, PlannerTypeAction, PlannerWaitAction, PlannerDoneAction]] = None
-
-    @model_validator(mode="after")
-    def check_exclusive(self) -> "PlannerPlan":
-        # At least one must be provided
-        if not any([self.action, self.tool_calls, self.output, self.objectDescription]):
-            raise ValueError("Provide EITHER 'action', 'tool_calls', 'output', OR 'objectDescription'.")
-        return self
-