thunder-agent 0.2.2__tar.gz → 0.4.0__tar.gz

thunder_agent-0.4.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: thunder-agent
+Version: 0.4.0
+Summary: Thunder — the human engine for AI agents: stealth browser body, human hands, TLS ghost, CAPTCHA bridge, and a stewmind thought layer.
+Author-email: Emmanuel Ene Rejoice <emmanuelerogian723@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/emmanuelerogian723-alt/thunder
+Project-URL: Powered by, https://huggingface.co/Erog0291/stewmind-1.7b
+Keywords: ai-agents,browser-automation,stealth,mcp,anti-detection,human-like,scraping,stewmind
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi>=0.7
+Requires-Dist: playwright>=1.40
+Provides-Extra: mind
+Requires-Dist: transformers>=4.44; extra == "mind"
+Requires-Dist: torch; extra == "mind"
+Provides-Extra: solver
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="site/assets/thunder-logo.png" width="220" alt="Thunder logo"/>
+
+# ⚡ Thunder
+
+**The human engine for AI agents.**
+
+Give any software a human body: a real browser with a real fingerprint,
+a mouse that trembles like a hand, keystrokes at human cadence, and a
+TLS handshake indistinguishable from Chrome's.
+
+*A bot that walks like a person.*
+
+[![PyPI](https://img.shields.io/pypi/v/thunder-agent?color=%23ffd447&label=pypi%3A%20thunder-agent)](https://pypi.org/project/thunder-agent/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3ddc84)](https://pypi.org/project/thunder-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4c8dff)](LICENSE)
+[![Tests](https://img.shields.io/badge/stealth%20suite-passing-3ddc84)](tests/)
+
+**[Install](#-install-in-30-seconds)** · **[Watch the proof](https://emmanuelerogian723-alt.github.io/thunder/)** · **[MCP for any software](#-mcp-give-any-software-a-human-body)**
+
+</div>
+
+---
+
+## Why Thunder exists
+
+Every anti-bot system on Earth looks for the same three tells:
+
+1. *Protocol tells* — a Python scraper's TLS/HTTP-2 handshake screams "bot" before a byte of JS runs.
+2. *Fingerprint tells* — `navigator.webdriver`, headless quirks, software-rendered WebGL, empty plugin arrays.
+3. *Behavioral tells* — perfectly straight mouse paths, instant typing, zero reading pauses.
+
+Thunder is a body for your AI that has **none of them**. Not patched over — *absent*, the way a real human's browser is.
+
+```python
+pip install thunder-agent
+```
+
+```python
+import thunder
+
+body = thunder.Body(profile="ada")          # a persistent human named Ada
+await body.warmup()                         # age the session like a returning user
+await body.go("https://protected-site.com")
+await body.type("#email", "ada@example.com")   # typed like a person. Typos included.
+await body.look("proof.png")                    # screenshot evidence
+await body.rest()                              # close, keep the identity
+```
+
+Ada comes back tomorrow with the same cookies, same screen, same GPU string, same timezone. The site sees a returning regular.
+
+---
+
+## 📦 Install in 30 seconds
+
+```bash
+pip install thunder-agent
+```
+
+Works on Linux, macOS, Windows. Real-Chrome engine auto-detected; falls back to bundled Chromium.
+
+```bash
+thunder demo        # watch it browse like a human, right now
+thunder ghost https://nowsecure.nl    # TLS-level fetch that passes the gate
+```
+
+---
+
+## ⚡ The five layers
+
+| Layer | What it does | The tell it kills |
+|---|---|---|
+| **Body** | Stealth browser: real Google Chrome, persistent profiles | headless shells, disposable identities |
+| **Skin** | One consistent identity: UA, platform, GPU, screen, timezone, locale | fingerprint mismatches, `SwiftShader` WebGL |
+| **Hand** | Bézier mouse with *hand tremor*, human keystroke cadence, typos it fixes | straight-line paths, machine-perfect timing |
+| **Ghost** | Pure HTTP with Chrome's exact TLS/JA3 fingerprint + full header orchestration + human-style retries | Python-scrape handshake = instant 403 |
+| **Pool** | Thunder's own proxy pool: auto-fetched, Ghost-validated egress, sticky per profile | shared/flagged datacenter IPs |
+| **Warmup** | Organic light browsing before your target | cold first-hit sessions |
+
+Verified live: `bot.sannysoft.com` under Thunder — **WebDriver missing (passed) · WebDriver Advanced passed · Chrome present (passed) · PluginArray passed** — *4 passed, 0 failed* with headed real Chrome. Ghost pulls a **200** from a Cloudflare gate that 403s plain Python, same minute.
+
+---
+
+## 🔌 MCP: give ANY software a human body
+
+**Zero-install, zero-account — paste this URL into Claude** (Settings → Connectors → Add custom connector, or claude.ai/mcp):
+
+```
+https://thunder-mcp.onrender.com/mcp
+```
+
+That's it. No signup, no keys. Thunder-hosted, always on. You get `thunder_search`, `thunder_read`, `thunder_ghost`, `thunder_feel`, `thunder_solve`, `thunder_open` — search, clean extraction and bot-gate-safe fetches through Chrome's exact TLS handshake, from inside Claude.
+
+Want the *full* human body (stealth Chrome, mouse tremor, human typing) under MCP? Run it locally — same 10-tool MCP server:
+
+Thunder ships an MCP server (10 tools). Paste one config and Claude, Cursor, Cline, Windsurf — anything that speaks MCP — browses as a human:
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "pipx", "args": ["run", "thunder-agent", "thunder-mcp"] } } }
+```
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "uvx", "args": ["--from", "thunder-agent", "thunder-mcp"] } } }
+```
+
+Tools: `thunder_open` · `thunder_read` · `thunder_search` · `thunder_click` · `thunder_type` · `thunder_scroll` · `thunder_ghost` · `thunder_solve` · `thunder_feel` · `thunder_close` — each one moves like a person, never like a script.
+
+---
+
+## 🚫 The blocker table — what used to stop bots, and Thunder's answer
+
+| Blocker | Thunder's counter |
+|---|---|
+| Datacenter IP suspicion | `ProxyManager`: sticky per-profile residential proxies, health-checked, auto-rotation — `THUNDER_PROXY` env or `ProxyManager.from_env()` |
+| No GPU / software WebGL | Full WebGL1 **and** WebGL2 spoof: vendor + renderer read as a real consumer GPU, on every API path detectors use |
+| Headless leaks | Headless-evasion pack: `outerWidth/Height`, `colorDepth`, broken-image dimensions, full `window.chrome` shape, battery API |
+| Advanced CAPTCHAs | Keyless `soft_solve` (human-hand click inside challenges) + `ocr_solve` (local OCR for image/math) + CapSolver/2Captcha bridge for the hardest |
+| Behavioral ML | Hand tremor + micro-corrections + warmup sessions + thinking pauses — entropy that reads as a person, because it moves like one |
+
+## 🔒 CAPTCHAs without a subscription
+
+```python
+from thunder.captcha import soft_solve, ocr_solve
+result = await soft_solve(body.page)     # human-hand click, no keys needed
+```
+
+Non-interactive challenges often pass on a warmed-up session. For Turnstile/reCAPTCHA Enterprise, wire your own CapSolver or 2Captcha key — Thunder senses the challenge type and routes it.
+
+---
+
+## 🧠 Pair with any mind
+
+Thunder is the body; bring any brain. Works with stewmind, Ollama, LM Studio, vLLM, OpenAI-compatible APIs, or fully offline transformers.
+
+```python
+from thunder.mind import Mind
+mind = Mind(provider="ollama", model="llama3")
+plan = await mind.think("find the pricing page and extract the tiers", body)
+```
+
+---
+
+## 🧪 Tested, not promised
+
+```bash
+git clone https://github.com/emmanuelerogian723-alt/thunder
+cd thunder && pip install -e ".[dev]" && pytest
+```
+
+Stealth regression suite: webdriver erased + scan-invisible · genuine PluginArray · headless pack · WebGL skin-consistency · proxy rotation. Each one fails loudly if a future commit breaks the human illusion.
+
+---
+
+## ⚖️ The honest limits (why people trust Thunder)
+
+- No tool on Earth is "undetectable." Anyone selling that is lying to you.
+- Cloud IPs still look like clouds — pair Thunder with a residential proxy for the hardest targets.
+- Google-scale behavioral ML scores the whole session. Thunder's warmup + hand give you a real chance; it's not a magic key.
+- **Use Thunder only where you're authorized.** Your accounts, your tests, your sites. That's the license, and it's the line.
+
+MIT licensed. Built in the open — every claim on this page has a script in `tests/` or a screenshot in `proofs/`.
+
+---
+
+<div align="center">
+
+**Watch Thunder beat the bot-detection gauntlet, live:**
+
+**https://emmanuelerogian723-alt.github.io/thunder/**
+
+⭐ If this saved you a month of anti-detect work, star the repo — it helps others find it.
+
+*Thunder — built so software can finally act human.* 🌩️
+
+</div>

thunder_agent-0.4.0/README.md

@@ -0,0 +1,178 @@
+<div align="center">
+
+<img src="site/assets/thunder-logo.png" width="220" alt="Thunder logo"/>
+
+# ⚡ Thunder
+
+**The human engine for AI agents.**
+
+Give any software a human body: a real browser with a real fingerprint,
+a mouse that trembles like a hand, keystrokes at human cadence, and a
+TLS handshake indistinguishable from Chrome's.
+
+*A bot that walks like a person.*
+
+[![PyPI](https://img.shields.io/pypi/v/thunder-agent?color=%23ffd447&label=pypi%3A%20thunder-agent)](https://pypi.org/project/thunder-agent/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3ddc84)](https://pypi.org/project/thunder-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4c8dff)](LICENSE)
+[![Tests](https://img.shields.io/badge/stealth%20suite-passing-3ddc84)](tests/)
+
+**[Install](#-install-in-30-seconds)** · **[Watch the proof](https://emmanuelerogian723-alt.github.io/thunder/)** · **[MCP for any software](#-mcp-give-any-software-a-human-body)**
+
+</div>
+
+---
+
+## Why Thunder exists
+
+Every anti-bot system on Earth looks for the same three tells:
+
+1. *Protocol tells* — a Python scraper's TLS/HTTP-2 handshake screams "bot" before a byte of JS runs.
+2. *Fingerprint tells* — `navigator.webdriver`, headless quirks, software-rendered WebGL, empty plugin arrays.
+3. *Behavioral tells* — perfectly straight mouse paths, instant typing, zero reading pauses.
+
+Thunder is a body for your AI that has **none of them**. Not patched over — *absent*, the way a real human's browser is.
+
+```python
+pip install thunder-agent
+```
+
+```python
+import thunder
+
+body = thunder.Body(profile="ada")          # a persistent human named Ada
+await body.warmup()                         # age the session like a returning user
+await body.go("https://protected-site.com")
+await body.type("#email", "ada@example.com")   # typed like a person. Typos included.
+await body.look("proof.png")                    # screenshot evidence
+await body.rest()                              # close, keep the identity
+```
+
+Ada comes back tomorrow with the same cookies, same screen, same GPU string, same timezone. The site sees a returning regular.
+
+---
+
+## 📦 Install in 30 seconds
+
+```bash
+pip install thunder-agent
+```
+
+Works on Linux, macOS, Windows. Real-Chrome engine auto-detected; falls back to bundled Chromium.
+
+```bash
+thunder demo        # watch it browse like a human, right now
+thunder ghost https://nowsecure.nl    # TLS-level fetch that passes the gate
+```
+
+---
+
+## ⚡ The five layers
+
+| Layer | What it does | The tell it kills |
+|---|---|---|
+| **Body** | Stealth browser: real Google Chrome, persistent profiles | headless shells, disposable identities |
+| **Skin** | One consistent identity: UA, platform, GPU, screen, timezone, locale | fingerprint mismatches, `SwiftShader` WebGL |
+| **Hand** | Bézier mouse with *hand tremor*, human keystroke cadence, typos it fixes | straight-line paths, machine-perfect timing |
+| **Ghost** | Pure HTTP with Chrome's exact TLS/JA3 fingerprint + full header orchestration + human-style retries | Python-scrape handshake = instant 403 |
+| **Pool** | Thunder's own proxy pool: auto-fetched, Ghost-validated egress, sticky per profile | shared/flagged datacenter IPs |
+| **Warmup** | Organic light browsing before your target | cold first-hit sessions |
+
+Verified live: `bot.sannysoft.com` under Thunder — **WebDriver missing (passed) · WebDriver Advanced passed · Chrome present (passed) · PluginArray passed** — *4 passed, 0 failed* with headed real Chrome. Ghost pulls a **200** from a Cloudflare gate that 403s plain Python, same minute.
+
+---
+
+## 🔌 MCP: give ANY software a human body
+
+**Zero-install, zero-account — paste this URL into Claude** (Settings → Connectors → Add custom connector, or claude.ai/mcp):
+
+```
+https://thunder-mcp.onrender.com/mcp
+```
+
+That's it. No signup, no keys. Thunder-hosted, always on. You get `thunder_search`, `thunder_read`, `thunder_ghost`, `thunder_feel`, `thunder_solve`, `thunder_open` — search, clean extraction and bot-gate-safe fetches through Chrome's exact TLS handshake, from inside Claude.
+
+Want the *full* human body (stealth Chrome, mouse tremor, human typing) under MCP? Run it locally — same 10-tool MCP server:
+
+Thunder ships an MCP server (10 tools). Paste one config and Claude, Cursor, Cline, Windsurf — anything that speaks MCP — browses as a human:
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "pipx", "args": ["run", "thunder-agent", "thunder-mcp"] } } }
+```
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "uvx", "args": ["--from", "thunder-agent", "thunder-mcp"] } } }
+```
+
+Tools: `thunder_open` · `thunder_read` · `thunder_search` · `thunder_click` · `thunder_type` · `thunder_scroll` · `thunder_ghost` · `thunder_solve` · `thunder_feel` · `thunder_close` — each one moves like a person, never like a script.
+
+---
+
+## 🚫 The blocker table — what used to stop bots, and Thunder's answer
+
+| Blocker | Thunder's counter |
+|---|---|
+| Datacenter IP suspicion | `ProxyManager`: sticky per-profile residential proxies, health-checked, auto-rotation — `THUNDER_PROXY` env or `ProxyManager.from_env()` |
+| No GPU / software WebGL | Full WebGL1 **and** WebGL2 spoof: vendor + renderer read as a real consumer GPU, on every API path detectors use |
+| Headless leaks | Headless-evasion pack: `outerWidth/Height`, `colorDepth`, broken-image dimensions, full `window.chrome` shape, battery API |
+| Advanced CAPTCHAs | Keyless `soft_solve` (human-hand click inside challenges) + `ocr_solve` (local OCR for image/math) + CapSolver/2Captcha bridge for the hardest |
+| Behavioral ML | Hand tremor + micro-corrections + warmup sessions + thinking pauses — entropy that reads as a person, because it moves like one |
+
+## 🔒 CAPTCHAs without a subscription
+
+```python
+from thunder.captcha import soft_solve, ocr_solve
+result = await soft_solve(body.page)     # human-hand click, no keys needed
+```
+
+Non-interactive challenges often pass on a warmed-up session. For Turnstile/reCAPTCHA Enterprise, wire your own CapSolver or 2Captcha key — Thunder senses the challenge type and routes it.
+
+---
+
+## 🧠 Pair with any mind
+
+Thunder is the body; bring any brain. Works with stewmind, Ollama, LM Studio, vLLM, OpenAI-compatible APIs, or fully offline transformers.
+
+```python
+from thunder.mind import Mind
+mind = Mind(provider="ollama", model="llama3")
+plan = await mind.think("find the pricing page and extract the tiers", body)
+```
+
+---
+
+## 🧪 Tested, not promised
+
+```bash
+git clone https://github.com/emmanuelerogian723-alt/thunder
+cd thunder && pip install -e ".[dev]" && pytest
+```
+
+Stealth regression suite: webdriver erased + scan-invisible · genuine PluginArray · headless pack · WebGL skin-consistency · proxy rotation. Each one fails loudly if a future commit breaks the human illusion.
+
+---
+
+## ⚖️ The honest limits (why people trust Thunder)
+
+- No tool on Earth is "undetectable." Anyone selling that is lying to you.
+- Cloud IPs still look like clouds — pair Thunder with a residential proxy for the hardest targets.
+- Google-scale behavioral ML scores the whole session. Thunder's warmup + hand give you a real chance; it's not a magic key.
+- **Use Thunder only where you're authorized.** Your accounts, your tests, your sites. That's the license, and it's the line.
+
+MIT licensed. Built in the open — every claim on this page has a script in `tests/` or a screenshot in `proofs/`.
+
+---
+
+<div align="center">
+
+**Watch Thunder beat the bot-detection gauntlet, live:**
+
+**https://emmanuelerogian723-alt.github.io/thunder/**
+
+⭐ If this saved you a month of anti-detect work, star the repo — it helps others find it.
+
+*Thunder — built so software can finally act human.* 🌩️
+
+</div>

{thunder_agent-0.2.2 → thunder_agent-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "thunder-agent"
-version = "0.2.2"
+version = "0.4.0"
 description = "Thunder — the human engine for AI agents: stealth browser body, human hands, TLS ghost, CAPTCHA bridge, and a stewmind thought layer."
 readme = "README.md"
 requires-python = ">=3.10"

thunder_agent-0.4.0/tests/test_stealth.py

@@ -0,0 +1,60 @@
+"""Stealth regression: every known tell must stay covered. (sync, no pytest-asyncio)"""
+import asyncio
+import pytest
+from thunder.body import Body
+from thunder.proxy import _normalize, ProxyManager
+
+@pytest.fixture(scope="module")
+def body():
+    b = Body(profile="stealth-test", headless=True)
+    asyncio.run(b.wake("https://example.com"))
+    yield b
+    asyncio.run(b.rest())
+
+def test_webdriver_erased(body):
+    r = asyncio.run(body.page.evaluate(
+        "(() => ({w: navigator.webdriver, scan: (() => { let f=null;"
+        " for (const k in navigator) if (/web/i.test(k)&&/driver/i.test(k)) f=k;"
+        " return f; })()}))()"))
+    assert r["w"] in (None, False) and r["scan"] is None
+
+def test_plugins(body):
+    r = asyncio.run(body.page.evaluate(
+        "(() => ({pa: navigator.plugins instanceof PluginArray,"
+        " l: navigator.plugins.length}))()"))
+    assert r["pa"] is True and r["l"] == 5
+
+def test_headless_pack(body):
+    r = asyncio.run(body.page.evaluate(
+        "(() => ({ow: window.outerWidth, oh: window.outerHeight,"
+        " cd: screen.colorDepth, ch: !!window.chrome,"
+        " bt: typeof navigator.getBattery}))()"))
+    assert r["ow"] > 0 and r["oh"] > 0 and r["cd"] == 24 and r["ch"] is True
+    assert r["bt"] == "function"
+
+def test_webgl(body):
+    r = asyncio.run(body.page.evaluate(
+        """(() => { const c=document.createElement('canvas');
+        const gl=c.getContext('webgl2')||c.getContext('webgl');
+        const ext=gl.getExtension('WEBGL_debug_renderer_info');
+        return {v: gl.getParameter(ext.UNMASKED_VENDOR_WEBGL),
+                r: gl.getParameter(ext.UNMASKED_RENDERER_WEBGL),
+                d: gl.getParameter(37446)}; })()"""))
+    assert r["v"] == body.skin.webgl_vendor
+    assert r["d"] == r["r"]
+    assert "SwiftShader" not in r["r"]
+
+def test_proxy_normalize():
+    assert _normalize("host:1234")["server"] == "http://host:1234"
+    p = _normalize("user:pass@1.2.3.4:8080")
+    assert p["server"] == "http://1.2.3.4:8080" and p["username"] == "user"
+    assert _normalize("socks5://h:1")["server"] == "socks5://h:1"
+
+def test_proxy_sticky_rotation():
+    pm = ProxyManager([{"server": "http://a:1"}, {"server": "http://b:2"}])
+    a = pm.pick("ada"); b = pm.pick("ada")
+    assert a == b
+    c = pm.pick("bob")
+    assert c["server"] != a["server"]
+    pm.mark_bad(a, cooldown=9999)
+    assert pm.pick("ada")["server"] == c["server"]

{thunder_agent-0.2.2 → thunder_agent-0.4.0}/thunder/__init__.py

@@ -24,5 +24,5 @@ from thunder.ghost import Ghost
 from thunder.mind import StewMind
 from thunder.fingerprint import Skin, random_skin
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"
 __all__ = ["Body", "Ghost", "StewMind", "Skin", "random_skin", "NodriverBody", "__version__"]

{thunder_agent-0.2.2 → thunder_agent-0.4.0}/thunder/body.py

@@ -42,10 +42,12 @@ class Body:
     def __init__(self, profile: str = "default", skin: Optional[Skin] = None,
                  engine: str = "playwright-stealth", headless: bool = True,
                  record_video: bool = False, viewport: Optional[dict] = None,
-                 locale: str = "en-US", timezone: str = "Africa/Lagos"):
+                 locale: str = "en-US", timezone: str = "Africa/Lagos",
+                 proxy=None):
         self.profile = profile
         self.engine = engine
         self.headless = headless
+        self.proxy = proxy
         self.viewport = viewport
         self.record = record_video
         self.locale = locale
@@ -93,6 +95,13 @@ class Body:
             # nodriver is a stronger, separate engine; supported via
             # thunder.nodriver_engine when installed (AGPL-3).
             raise ValueError("use thunder.nodriver_engine.NodriverBody for the nodriver engine")
+        if self.proxy:
+            p = self.proxy
+            if isinstance(p, str):
+                from .proxy import _normalize
+                p = _normalize(p)
+            if p:
+                launch_kw["proxy"] = p
         launch_kw.update({
             "user_agent": self.skin.user_agent,     # header + JS always match the Skin
             "viewport": {"width": self.skin.window_w, "height": self.skin.window_h},
@@ -132,6 +141,13 @@ class Body:
         except Exception:
             pass
 
+    async def warmup(self, visits: int = 2) -> dict:
+        """Age the session with organic light browsing so arriving at
+        your target reads like a returning human, not a cold first hit.
+        Big targets score the WHOLE session — this is the counter."""
+        from .warmup import warmup
+        return await warmup(self, visits=visits)
+
     async def rest(self):
         """Close the body gracefully (context persists to disk)."""
         try:

{thunder_agent-0.2.2 → thunder_agent-0.4.0}/thunder/captcha.py

@@ -151,3 +151,76 @@ async def describe_challenge(page, mind=None) -> str:
     if mind is None:
         return prompt  # caller routes screenshot + prompt to a vision model
     return prompt
+
+
+# ── KEYLESS FALLBACKS ─────────────────────────────────────────────
+# Thunder avoids most challenges with skin + hand. These two give you
+# a real shot at the rest WITHOUT any solver subscription.
+
+async def soft_solve(page, wait_after: float = 8.0) -> Dict[str, Any]:
+    """Human-hand click inside the challenge — no solver key needed.
+
+    Non-interactive Turnstile and 'just click the box' reCAPTCHA often
+    pass when the click comes from a human-shaped hand on a warmed-up
+    session instead of an instant synthetic one.
+    """
+    frames = page.frames
+    target = None
+    for f in frames:
+        if any(k in (f.url or "") for k in ("turnstile", "recaptcha", "hcaptcha")):
+            target = f
+            break
+    if target is None:
+        return {"solved": False, "error": "no challenge frame found"}
+    try:
+        box = await target.locator("body").bounding_box()
+        if not box:
+            return {"solved": False, "error": "no clickable area"}
+        from .human import Hand
+        hand = Hand(page)
+        # human approach: drift in from nearby, pause, click
+        await hand.idle(1.5)
+        await hand.click((box["x"] + box["width"] * 0.5 + 15,
+                          box["y"] + box["height"] * 0.5))
+        await page.wait_for_timeout(int(wait_after * 1000))
+        token = await page.evaluate("""(() => {
+          const el = document.querySelector(
+            '[name=cf-turnstile-response],textarea#g-recaptcha-response,[name=h-captcha-response]');
+          return el ? el.value : window.turnbridge_token || null; })()""")
+        return {"solved": bool(token), "token": (token or "")[:24] + "..."}
+    except Exception as e:
+        return {"solved": False, "error": str(e)[:120]}
+
+
+async def ocr_solve(page, input_selector: str = "input",
+                     img_selector: str = "img") -> Dict[str, Any]:
+    """Local OCR for simple image/math CAPTCHAs — still keyless.
+
+    Uses tesseract when installed (apt install tesseract-ocr).
+    Reads the challenge image, types the answer with the human hand.
+    """
+    try:
+        import pytesseract         # optional; pip install pytesseract
+    except ImportError:
+        return {"solved": False,
+                "error": "install pytesseract + tesseract-ocr for local OCR"}
+    import base64
+    img = page.locator(img_selector).first
+    data = await img.screenshot()
+    import io
+    from PIL import Image
+    text_img = Image.open(io.BytesIO(data)).convert("L")
+    answer = pytesseract.image_to_string(
+        text_img, config="--psm 7 -c tessedit_char_whitelist=0123456789+-*=ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    ).strip()
+    if not answer:
+        return {"solved": False, "error": "OCR read nothing"}
+    # simple arithmetic like "7 + 4 ="
+    import re
+    m = re.search(r"(\d+)\s*([+\-x*])\s*(\d+)", answer)
+    if m:
+        a, op, c = int(m.group(1)), m.group(2), int(m.group(3))
+        answer = str(a + c if op == "+" else a - c if op == "-" else a * c)
+    from .human import Hand
+    await Hand(page).type(input_selector, answer)
+    return {"solved": True, "answer": answer}