agentic-stealth-browser 2.4.0__tar.gz → 2.5.0__tar.gz

{agentic_stealth_browser-2.4.0 → agentic_stealth_browser-2.5.0}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+## [2.5.0] — Real Dashboard Backend Adapters (#444) (2026-06-07)
+
+### Added
+- **`BackendAdapter` Protocol + `Capability` enum** (`production/adapters/base.py:84`): runtime-checkable protocol with `launch`/`close`/`navigate`/`click`/`fill`/`screenshot`/`status`/`capabilities` surface. All three backends (M1/M2/M3) implement it. New `AdapterLaunchError` and `AdapterCapabilityError` exception types; `register_adapter` enforces non-empty string names. (#444 M0)
+- **`CDPBridgeAdapter`** (`production/adapters/cdp_bridge.py`): Playwright `connect_over_cdp` over WebSocket. Used for adopted-context / WSL-host workflows where the operator already owns a browser process. (#444 M1)
+- **`PlaywrightMCPAdapter`** (`production/adapters/playwright_mcp.py`): stdio subprocess + MCP JSON-RPC. Spawns `npx @playwright/mcp` with an explicit env allowlist (PATH, HOME) and a 16 MB `MAX_FRAME_BYTES` frame cap. (#444 M2)
+- **`AgenticStealthMCPAdapter`** (`production/adapters/agentic_stealth_mcp.py`): stdio subprocess + MCP JSON-RPC, round-trips through the bundled `production.mcp_server` runtime. Same env allowlist, frame cap, and stderr-drain guarantees as M2. (#444 M3)
+- **Dashboard backend wiring (M4)**: `BrowserRuntimeManager` resolves the configured backend through the adapter registry, records an audit event on backend switch, surfaces negotiated capabilities in dashboard status, and rejects unsupported actions with a backend-specific error. `production/dashboard_adapter_bridge.py` is now a thin shim that re-exports the three M1–M3 adapters. (#444 M4)
+
+### Changed
+- `production/hermes_dashboard.py` re-exports `BackendAdapter` from `production/adapters/`.
+- `production/dashboard_adapter_bridge.py` thin shim replaces the three alias backends.
+- `MANIFEST.in`: ships `assets/*.{gif,png,jpg,svg}` (demo GIF), `docs/`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md` (sdist previously dropped the demo GIF and the entire `docs/` tree).
+- `README.md`: added "What is this / When to use / When NOT to use" block at top, honest comparison table (region client-hello profiles, not full uTLS), install-from-source section, full project tree + doc index. Dropped unverified test-count badge and Buy Me A Coffee. 177 → 238 lines.
+- New `docs/README.md` operator/reference/planning index. Root-level `*PLAN.md` / `*READINESS.md` / `*DASHBOARD.md` / `HN_POST.md` moved to `docs/plans/misc/` as historical.
+- Examples rewritten for honesty and reproducibility: `01_cloudflare_bypass.py` (nowsecure.nl + screenshot), `02_linkedin_search.py` (`linkedin_2026` preset + webdriver check + DDG), `03_amazon_product.py` (product → title + price). `recipes/README.md` table updated.
+- `pyproject.toml` version 2.4.1 → 2.5.0.
+
+### Fixed
+- **#444 M0 review (showstoppers)**:
+  - **S1 capability gating**: M2/M3 `navigate`/`click`/`fill`/`screenshot` now call `self.supports()` and raise `AdapterCapabilityError` if the adapter doesn't declare the capability (enforces `base.py:84` protocol contract). New `_require_capability()` helper on each adapter.
+  - **S2 stderr drain**: M2/M3 `stderr=PIPE` is now drained by a background task started right after `spawn` and cancelled in `close()`. A noisy child no longer fills the ~64 KB kernel pipe buffer, blocks on its next stderr write, hangs the handshake, and triggers a slow SIGKILL on close.
+  - **F1 stale state on retry**: after MCP handshake failure, `terminate_subprocess()` is called and `self._proc` / `self._client` are cleared. A caller that catches `AdapterLaunchError` and then calls `close()` no longer operates on a dead `Process` handle.
+- **#444 M0 review (smaller)**:
+  - **F2 frame cap**: `_jsonrpc_stdio.readline()` now enforces `MAX_FRAME_BYTES = 16 MB` and raises `ConnectionError` on overflow. A misbehaving server emitting a multi-GB line no longer OOMs the client.
+  - **F3 env allowlist**: both stdio adapters now pass an explicit `env={PATH, HOME}` to `asyncio.create_subprocess_exec` instead of inheriting the operator's full environment (`OPENAI_API_KEY`, `AWS_*`, `DATABASE_URL`, ...).
+  - **A3 dead tautology**: `cdp_bridge.screenshot()` had a defensive `Capability.SCREENSHOT` check that could never fire (always in `capabilities()`). Branch removed; M0 contract is the only contract that matters.
+  - **M0 code-quality review (17abc50)**: exception types narrowed to library-specific where appropriate, `isinstance` coverage tightened, defensive tautology branches removed, transport teardown made symmetric with launch.
+- **Adapter capability gating**: now consistent across M1/M2/M3 — each action is contractually declared, not assumed.
+- **Ruff/format housekeeping** (4432701): 12 ruff format issues + 1 unused import fixed.
+
+### Tests / CI
+- `tests/test_backend_adapter_contract.py` — new contract test pinning the M0 Protocol surface, `Capability` enum members, and `register_adapter` duplicate/empty/non-string rejection.
+- `tests/test_adapter_cdp_bridge.py`, `tests/test_adapter_playwright_mcp.py`, `tests/test_adapter_agentic_stealth_mcp.py` — new per-adapter tests covering launch, capability negotiation, action gating, stderr drain, env allowlist, and close lifecycle.
+- `tests/test_dashboard_protocol_bridge.py` — new dashboard-wiring test (M4): audit event on backend switch, capability surface, unsupported-action rejection.
+- `pytest -q`: 1025 collected, 1023 passed, 2 e2e skipped, 0 failed (139 s; baseline maintained).
+- `ruff check` + `ruff format --check` clean across 159 Python files.
+
+Closes #444.
+
+---
+
+## [2.4.1] — v2.4.0 Stabilization Patch (2026-06-03)
+
+### Fixed / Security / Reliability (P0/P1 per #459)
+- **#454** MCP nav/scrape: `is_url_safe` now fails closed for non-http(s) schemes (`file:`, `javascript:`, `data:`, `ftp:`, ...), missing hosts, DNS errors, and empty resolutions. Unsafe inputs raise `MCP_SSRF_BLOCKED` before any browser navigation. Added unit matrix + dispatch regression tests.
+- **#455** MCP runtime: declarative input validation from `production/mcp_input_validator.py` is now enforced in `tools/call` dispatch (types, lengths, ranges, required, patterns, `additionalProperties: false`). Validation errors return stable `MCP_VALIDATION_ERROR` without invoking handlers. Schema/validator parity and dispatch tests added.
+- **#451** CDP attach: adopted user tabs (`new_context=False`) are no longer closed on `close()`. New `_owns_page` tracking + conditional teardown; adopted contexts/pages preserved per contract. Updated tests + docs.
+- **#452** CDP attach: post-`connect_over_cdp` failures (bad context_index, new_context, page create, stealth) now best-effort rollback `_pw`, `_remote_browser`, owned ctxs (never adopted), and reset attach flags for clean retry.
+- **#453** CDP attach: attach path now initializes `human`, `orchestrator`, `logger`, `scraper`, `ai`, `recovery` (with attach degradation notes). `safe_goto`/`safe_click`/`safe_type` + MCP `stealth_scrape` now operational on attached sessions.
+- **#458** Hermes dashboard: startup rejects default/empty/`change-me` password when binding to non-loopback (0.0.0.0, RFC1918, public, IPv6 non-loop). Loopback dev still convenient. Added guard tests.
+- **#457** CLI `scrape`: removed double `launch()` (async-with already launches; now passes preset/region via ctor so aenter applies them). Exactly one launch + one close. Aligned all user-facing names/help/examples to `agentic-stealth-browser`. Mocked regression test.
+- **#456** Packaging: `pyproject.toml` now includes `production.*`, `workflows.*`, `plugins.*`. `MANIFEST.in` extended. CI verify expanded for SDK import + bundled workflow discovery from clean cwd. MCP server workflow root switched to user-writable `~/.agentic-browser/...` + bundled discovery fallback for install safety.
+- **#447** MCP version: `SERVER_VERSION` now derives from `importlib.metadata.version("agentic-stealth-browser")` (falls back to 2.4.1); no longer stale.
+- **#448** CDP attach gate: relaxed RFC1918 rejection under `allow_remote=true` for attach (WSL host IPs are intentionally private); link-local/cloud still blocked. Nav remains strict. Reconciled docs + tests with real WSL workflow.
+- **#450** Docs/metadata: toned down TLS/JA3/JA4 claims to "region client-hello profiles (process-level)"; attach degradation already documented the limits. No wire-level full-stack spoofing claimed.
+- **#449** Release hygiene: refreshed counts, changelog, version to 2.4.1, support notes, publish smoke.
+
+### Added
+- Runtime helpers and ownership tracking for attach mode.
+- Validation dispatch + matrix tests; single-launch CLI mock test; dashboard bind security tests.
+
+### Changed
+- `pyproject.toml` version 2.4.0 → 2.4.1; packages.find + MANIFEST.in for full artifacts.
+- Attach lifecycle docs/examples (no more auto-launch + attach in same `async with`).
+- MCP attach remote safety contract + tests for WSL compatibility.
+
+### Tests / CI
+- All non-e2e/non-live green.
+- Focused attach + MCP safety + validation + CLI mocks + dashboard guard.
+- `ruff check` + `ruff format --check` pass.
+- Wheel build + import + discovery smoke updated in publish.yml.
+
+Closes #447, #448, #449, #450, #451, #452, #453, #454, #455, #456, #457, #458, #459 (patch scope).
+
+---
+
 ## [2.4.0] — Attach-Mode Hardening (2026-06-01)
 
 ### Fixed
@@ -35,24 +114,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
-
-### Added
-- **`AgentBrowser.attach_over_cdp(cdp_url, ...)`**: connect to an already-running
-  browser exposed via Chrome DevTools Protocol (e.g. Chrome launched with
-  `--remote-debugging-port=9222`) instead of spawning a new Chromium. Complements
-  the existing `debug_cdp=True` launch flag — that one *exposes* an endpoint, this
-  one *consumes* one. Primary use case: drive a real desktop browser from a
-  different host (WSL → Windows, container → host, dev box → remote display).
-  Runtime stealth init scripts (navigator/canvas/WebGL/audio patches) are still
-  injected on the chosen context; launch-time stealth (TLS/JA3, regional preset,
-  user-data-dir) is unavailable in attach mode and listed in the return payload's
-  `degradation` field. `close()` disconnects without terminating the external
-  browser. (#attach-cdp)
-- **MCP tool `stealth_attach_over_cdp`**: surfaces `attach_over_cdp` through the
-  MCP server. Defaults to loopback-only; non-loopback hosts require explicit
-  `allow_remote=true` and raise `MCP_REMOTE_CDP_BLOCKED` otherwise. (#attach-cdp)
-
 ## [2.3.0] — Show HN & Community Launch (2026-05-28)
 
 ### Added

agentic_stealth_browser-2.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,70 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[GitHub Issues](https://github.com/shanewas/agentic-stealth-browser/issues).
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

agentic_stealth_browser-2.5.0/CONTRIBUTING.md

@@ -0,0 +1,237 @@
+# CONTRIBUTING.md (#55)
+
+Thank you for your interest in contributing to the Agentic Stealth Browser! This guide will help you get started.
+
+---
+
+## Development Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/shanewas/agentic-stealth-browser.git
+cd agentic-stealth-browser
+```
+
+### 2. Create a Virtual Environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+```
+
+### 4. Run Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test files
+pytest tests/test_stealth_modules.py -v
+pytest tests/test_contract_agent_browser.py -v
+pytest tests/test_recovery_phase1.py -v
+
+# Run with coverage
+pytest tests/ --cov=core --cov=stealth --cov=recovery --cov=behavior
+```
+
+---
+
+## Code Style
+
+### Formatting
+
+We use standard Python conventions:
+- 4-space indentation
+- Maximum line length: 120 characters
+- Type hints for all public APIs
+- Docstrings for all public methods
+
+### Naming Conventions
+
+- Classes: `PascalCase` (e.g., `AgentBrowser`, `StealthConfig`)
+- Functions/Methods: `snake_case` (e.g., `safe_goto`, `warm_up_before_work`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_PERSONA`, `MAX_RETRIES`)
+- Private methods: Leading underscore (e.g., `_run_step`, `_check_circuit_breaker`)
+
+---
+
+## Making Changes
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feat/your-feature-name
+# or
+git checkout -b fix/issue-description
+```
+
+### 2. Make Your Changes
+
+- Follow the existing code style
+- Add tests for new functionality
+- Update documentation if needed
+
+### 3. Run Tests
+
+```bash
+# Ensure all tests pass
+pytest tests/ -v
+
+# Check for any import issues
+python -c "from core.agent_browser import AgentBrowser"
+python -c "from stealth.advanced_stealth import get_stealth_script"
+```
+
+### 4. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: description of your change
+
+More detailed description if needed.
+
+Closes #123"
+```
+
+### 5. Push and Create a Pull Request
+
+```bash
+git push origin your-branch-name
+```
+
+Then open a PR on GitHub.
+
+---
+
+## Pull Request Guidelines
+
+### Title Format
+
+- `feat: ` for new features
+- `fix: ` for bug fixes
+- `docs: ` for documentation changes
+- `test: ` for test additions/changes
+- `refactor: ` for code refactoring
+- `perf: ` for performance improvements
+- `security: ` for security fixes
+
+### Description
+
+Include:
+- What this PR does
+- Why this change is needed
+- Any related issues (e.g., "Closes #123")
+- Testing instructions
+
+### Requirements
+
+- [ ] All tests pass
+- [ ] New code has tests
+- [ ] Documentation is updated (if applicable)
+- [ ] No sensitive data in code or commits
+
+---
+
+## Architecture Overview
+
+```
+agentic-stealth-browser/
+├── core/
+│   ├── agent_browser.py      # Main AgentBrowser class
+│   ├── error_messages.py     # User-friendly error messages
+│   └── types.py              # Type hints and stubs
+├── stealth/
+│   ├── advanced_stealth.py   # Stealth script generation
+│   ├── tls_fingerprint.py    # TLS profile management
+│   ├── headers.py            # HTTP header spoofing
+│   ├── profiles.py           # Persona/DeviceProfile system
+│   └── presets.py            # Platform presets
+├── behavior/
+│   ├── human_behavior.py     # Human-like behavior simulation
+│   └── orchestration.py      # Behavior orchestration
+├── recovery/
+│   ├── anti_block_orchestrator.py  # Block detection & recovery
+│   └── explain_blocked.py          # Block explanation
+├── proxy/
+│   └── proxy_manager.py      # Proxy management & rotation
+├── sessions/
+│   ├── session_manager.py    # Session management
+│   └── cookie_manager.py     # Cookie management
+├── production/
+│   ├── metrics.py            # Metrics collection
+│   ├── rate_limiter.py       # Rate limiting
+│   ├── cli.py                # CLI entry point
+│   └── agent_orchestrator.py # Multi-agent orchestration
+├── audit/
+│   └── logger.py             # Audit logging
+├── scraping/
+│   └── scraper.py            # Stealth scraping
+├── ai/
+│   └── ai_hooks.py           # AI integration hooks
+├── tests/                    # Test suite
+# (documentation lives in README.md and git history)
+└── mcp_security.py           # MCP security hardening
+```
+
+---
+
+## Adding New Features
+
+### New Stealth Patches
+
+1. Add the patch to `stealth/advanced_stealth.py`
+2. Add tests to `tests/test_stealth_modules.py`
+3. Update relevant sections in README.md if behavior changes
+
+### New Platform Preset
+
+1. Add the preset to `stealth/presets.py`
+2. Add a recipe to `README.md`
+3. Test against the target site
+
+### New Recovery Strategy
+
+1. Update `PLATFORM_STRATEGIES` in `recovery/anti_block_orchestrator.py`
+2. Add tests to `tests/test_recovery_phase1.py`
+3. Document rate limiting behavior changes in README.md or relevant code comments
+
+### New Human Behavior
+
+1. Add the behavior to `behavior/human_behavior.py`
+2. Respect `self.realism_level` for CI/light mode
+3. Add tests
+
+---
+
+## Reporting Issues
+
+When reporting a bug, include:
+- Python version
+- Playwright version
+- Error message and stack trace
+- Code snippet that reproduces the issue
+- Debug report (`await browser.debug_report(print_report=True)`)
+- Health status (`await browser.get_health_status()`)
+
+---
+
+## Security
+
+If you discover a security vulnerability:
+1. **Do not** open a public issue
+2. Email the maintainer directly
+3. Include steps to reproduce and potential impact
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

agentic_stealth_browser-2.5.0/MANIFEST.in

@@ -0,0 +1,19 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+include .env.example
+
+include assets/*.gif assets/*.png assets/*.jpg assets/*.svg
+
+recursive-include docs *.md *.html *.svg *.jsonl
+recursive-include stealth *.js *.json
+recursive-include production Dockerfile docker-healthcheck.py
+recursive-include examples *.md *.py *.txt
+recursive-include tests *.py *.json
+recursive-include workflows *.yaml *.yml
+recursive-include plugins *.py
+recursive-include production/sdk *.py
+recursive-include scripts *.sh *.py

{agentic_stealth_browser-2.4.0 → agentic_stealth_browser-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-stealth-browser
-Version: 2.4.0
+Version: 2.5.0
 Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
 Author-email: Shane W <shanewas@users.noreply.github.com>
 License-Expression: MIT
@@ -45,15 +45,25 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/agentic-stealth-browser.svg)](https://pypi.org/project/agentic-stealth-browser/)
-[![Tests](https://img.shields.io/badge/tests-890%2B%20passing-brightgreen)](tests/)
 [![GitHub Stars](https://img.shields.io/github/stars/shanewas/agentic-stealth-browser?style=flat&logo=github)](https://github.com/shanewas/agentic-stealth-browser)
-[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/shanewas)
 
 <p align="center">
   <img src="assets/hn-demo.gif" alt="Agentic Stealth Browser Demo" width="90%">
 </p>
 
-Production-grade stealth browser automation that **survives Cloudflare, LinkedIn, Amazon, and other anti-bot systems** by looking convincingly human at every layer.
+## What is this
+
+A production-grade stealth browser automation library for Python, built on Playwright.
+It survives modern anti-bot systems (Cloudflare, LinkedIn, Amazon, etc.) by looking
+convincingly human at every layer — TLS, navigator, WebGL/Canvas, behavior, recovery.
+
+**When to use it** — you are building an autonomous agent, scraper, or operator tool
+that needs to pass bot detection in headless mode on protected sites.
+
+**When NOT to use it** — you only need to scrape public, unprotected pages (use
+`httpx` + `selectolax` or `playwright` directly). You need a real uTLS stack at the
+wire level (use `curl_cffi`). You need CAPTCHA solving (this project intentionally
+stops at detection + intervention; see Limitations below).
 
 ```bash
 pip install agentic-stealth-browser
@@ -66,7 +76,7 @@ from core.agent_browser import AgentBrowser
 async with AgentBrowser(session_name="demo") as browser:
     await browser.launch(headless=True)
     await browser.safe_goto("https://bot.sannysoft.com")
-    # ✓ passes WebGL, Canvas, AudioContext, WebRTC, and TLS fingerprinting
+    # passes WebGL, Canvas, AudioContext, WebRTC, and TLS fingerprint checks
 ```
 
 ---
@@ -77,14 +87,39 @@ Sites don't just check your User-Agent anymore. They check *everything*:
 
 | Attack Surface | Vanilla Playwright | This library |
 |---|---|---|
-| **TLS handshake** (JA3/JA4 fingerprint) | Standard Python TLS — instantly identifiable | Region-spoofed profiles (US, Japan, EU, Korea) |
+| **TLS handshake** (client hello / JA3/JA4-ish) | Standard Python TLS — instantly identifiable | Region-spoofed TLS profile (process-level, not custom uTLS) |
 | **Navigator APIs** (`navigator.webdriver`, `plugins`, `languages`) | Leaks automation flags everywhere | Every property patched before first paint |
 | **WebGL / Canvas fingerprint** | Headless GPU renders differently | Consistent buffers across sessions |
 | **Human behavior** | Robotic clicks, instant typing | Bézier mouse curves, variable speed, fatigue simulation |
 | **Auto-recovery** | None — blocks = failure | CAPTCHA detection → proxy rotation → retry chain |
 | **Account warming** | Nothing | 14-day graduated ramp-up per account |
 
-Result: **passes bot.sannysoft.com, pixelscan.net, and CreepJS** with zero flags in headless mode.
+Result: **passes bot.sannysoft.com, pixelscan.net, and CreepJS** with zero flags in
+headless mode (detection canaries run every 4 hours via `docs/canary.md`).
+
+---
+
+## Limitations & honest claims
+
+This library is opinionated and has real limits. Operators should know them up front:
+
+- **Not a real uTLS stack.** TLS fingerprinting is process-level (region-matched
+  client-hello, init-script negotiation). It is *not* `curl_cffi`-grade wire-level
+  impersonation. Attach mode (CDP) degrades further: the host browser's TLS is whatever
+  the user already has.
+- **Headless detection is a moving target.** Detection vendors change heuristics
+  weekly. This project runs a 4-hourly detection canary
+  ([docs/canary.md](docs/canary.md)) and patches regressions, but zero-flag is a
+  snapshot, not a guarantee.
+- **No CAPTCHA solving.** The recovery chain *detects* CAPTCHAs and surfaces them to
+  the operator dashboard for manual intervention. It does not call solving services.
+  If you need solver integration, build a `BasePlugin` that calls your provider and
+  drops the cookie back into the session.
+- **E2E tests against live protected sites are opt-in.** The default CI runs
+  contract + mocked integration tests. Live-site E2E (`RUN_E2E_ANTI_BLOCK=1`) is
+  flaky by nature and skipped on PRs.
+- **Login credentials are not shipped.** Examples that touch authenticated endpoints
+  stop at the search/listing stage.
 
 ---
 
@@ -136,13 +171,15 @@ Instead of launching a new Chromium, you can attach to a Chrome you already
 have running with `--remote-debugging-port=9222`:
 
 ```python
-async with AgentBrowser(session_name="attached") as browser:
-    await browser.attach_over_cdp(
-        "http://127.0.0.1:9222",   # or the Windows host IP from WSL
-        new_context=True,           # don't disturb the user's tabs
-    )
-    await browser.safe_goto("https://bot.sannysoft.com")
-    # close() will NOT terminate the external browser
+# Attach mode: use a fresh instance (async-with auto-launches a new browser first).
+browser = AgentBrowser(session_name="attached")
+await browser.attach_over_cdp(
+    "http://127.0.0.1:9222",   # or the Windows host IP from WSL
+    new_context=True,           # don't disturb the user's tabs
+)
+await browser.safe_goto("https://bot.sannysoft.com")
+# safe actions + MCP scrape now operational on attached; close() leaves external browser running.
+await browser.close()
 ```
 
 See [docs/ATTACH_OVER_CDP.md](docs/ATTACH_OVER_CDP.md) for the WSL→Windows
@@ -151,11 +188,28 @@ degradation matrix (init-script stealth still applies; TLS/JA3 does not).
 
 ---
 
+## Install from source
+
+```bash
+git clone https://github.com/shanewas/agentic-stealth-browser.git
+cd agentic-stealth-browser
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+playwright install chromium
+pytest tests/ -q
+```
+
+The dev extras pull in `pytest`, `pytest-asyncio`, `ruff`, and the test fixture
+deps. The full suite takes ~2 minutes on a warm cache; the default run skips
+live E2E (`RUN_E2E_ANTI_BLOCK=1` to enable).
+
+---
+
 ## Key Features
 
 | Feature | What It Does |
 |---|---|
-| **TLS Fingerprinting** | JA3/JA4 region profiles |
+| **TLS Fingerprinting** | Region client-hello profiles (JA3/JA4 surface); attach mode degrades (process-level) |
 | **Human Behavior** | Mouse wobble, typing mistakes, fatigue, distraction |
 | **Auto Recovery** | Block detection → proxy/session rotation → retry |
 | **Account Warming** | 14-day gradual ramp-up for new accounts |
@@ -170,12 +224,17 @@ degradation matrix (init-script stealth still applies; TLS/JA3 does not).
 
 ---
 
-## New in v2.3.0
+## New in v2.5.0
 
-- **Show HN launch** — README overhaul, demo GIF, streamlined community onboarding
-- **Buy Me A Coffee** — sponsor the project directly
-- **PID tracking** — `AgentBrowser._browser_process` for external process monitoring
-- **PyPI publish automation** — OIDC trusted publishing on every release tag
+- **BackendAdapter protocol** — pluggable execution backends (M0–M4 shipped)
+  across CDP-bridge, playwright-mcp, and agentic-stealth-mcp
+- **Real dashboard backends** — the Hermes dashboard now wires a thin shim over
+  the adapter protocol, so the same UI drives all three backends
+- **Attach-mode hardening** — adopted tabs are preserved on `close()`; bad
+  context/stealth installs roll back cleanly; `human`/`scraper`/`recovery`
+  initialized for attach
+- **CLI `status`** — added `--headless` and `--session` flags for headless
+  operator checks against a named session
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
@@ -190,6 +249,8 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 - **[Plugins](plugins/)** — lifecycle hooks for custom behavior
 - **[VPS Deployment](scripts/setup_rbb.sh)** — systemd, Caddy reverse proxy, Cloudflare Tunnel patterns
 - **[Migration v1 → v2](scripts/migrate_v1_to_v2.py)** — deprecation shims, migration guide, script
+- **[Documentation index](docs/README.md)** — full docs/ tree: attach-over-CDP, canary, plans, analysis
+- **[Examples](examples/recipes/)** — runnable recipes for Cloudflare, LinkedIn, Amazon
 
 Additional references: [CHANGELOG.md](CHANGELOG.md) · [Workflow Library](workflows/library/) · [Migration Guide](scripts/migrate_v1_to_v2.py)
 
@@ -206,7 +267,9 @@ Additional references: [CHANGELOG.md](CHANGELOG.md) · [Workflow Library](workfl
 ├── production/     MCP server, SDK, orchestrator, security, profiler
 ├── plugins/        Plugin system with template
 ├── scripts/        Migration, evaluation, benchmarking
-└── tests/          890+ contract + integration tests
+├── docs/           Attach-over-CDP, canary, plans, analysis
+├── examples/       Runnable recipes (Cloudflare, LinkedIn, Amazon)
+└── tests/          Contract + integration tests (live E2E opt-in)
 ```
 
 ## License