superbrowser-sdk 2.2.0__tar.gz → 2.3.0__tar.gz

superbrowser_sdk-2.3.0/.github/workflows/adversarial-v3.yml

@@ -0,0 +1,140 @@
+name: Adversarial v3 Tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'tests/adversarial_v3/**'
+  pull_request:
+    paths:
+      - 'tests/adversarial_v3/**'
+  workflow_dispatch:
+    inputs:
+      backend:
+        description: 'Browser backend for real-browser run'
+        required: false
+        default: 'stub'
+        type: choice
+        options:
+          - stub
+          - playwright
+          - superbrowser
+
+jobs:
+  # --- Offline structural tests (always run, merge gate) ---
+  offline:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install test deps
+        run: pip install pytest pytest-asyncio
+      - name: Run offline adversarial v3 suite
+        working-directory: tests/adversarial_v3
+        run: |
+          PYTHONPATH=. python -m pytest tests/ -v --tb=short
+      - name: Verify stub produces no fabricated evidence
+        working-directory: tests/adversarial_v3
+        run: |
+          PYTHONPATH=. python -c "
+          import subprocess, json, sys, tempfile, os
+          out = tempfile.mkdtemp()
+          r = subprocess.run(
+              [sys.executable, 'run.py', '--all', '--backend', 'stub', '--output-dir', out],
+              capture_output=True, text=True
+          )
+          # Always surface subprocess output + report contents so any
+          # assertion failure is diagnosable. Previously capture_output
+          # hid run.py's stdout/stderr, leaving only a bare AssertionError.
+          print('=== run.py return code:', r.returncode, flush=True)
+          print('=== run.py STDOUT ===', flush=True)
+          print(r.stdout, flush=True)
+          print('=== run.py STDERR ===', flush=True)
+          print(r.stderr, flush=True)
+          reports = [f for f in os.listdir(out) if f.endswith('.json')]
+          print('=== report files:', reports, flush=True)
+          assert r.returncode == 0, f'Stub run should exit 0, got {r.returncode}'
+          # The harness writes two JSON files: the run report and
+          # adversarial-history.json (the trend log). Select only the
+          # per-run report; asserting on all *.json matched the history
+          # file too and failed with "Expected 1 report, got 2".
+          reports = [f for f in reports if f != 'adversarial-history.json']
+          assert len(reports) == 1, f'Expected 1 report, got {len(reports)}: {reports}'
+          with open(os.path.join(out, reports[0])) as f:
+              data = json.load(f)
+          clean = [r for r in data['results'] if r['verdict'] == 'clean']
+          flagged = [r for r in data['results'] if r['verdict'] == 'flagged']
+          print('=== verdicts:', [(r['vector_id'], r['verdict']) for r in data['results']], flush=True)
+          assert len(clean) == 0, f'Stub should not produce CLEAN, got {len(clean)}: {[r[\"vector_id\"] for r in clean]}'
+          assert len(flagged) == 0, f'Stub should not produce FLAGGED, got {len(flagged)}: {[r[\"vector_id\"] for r in flagged]}'
+          print(f'Stub honesty verified: 0 CLEAN, 0 FLAGGED, exit 0')
+          "
+
+  # --- Real-browser validation (manual dispatch only) ---
+  real-browser:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install deps
+        run: |
+          pip install playwright pytest pytest-asyncio
+          python -m playwright install --with-deps chromium
+      - name: Install SuperBrowser (for superbrowser backend)
+        if: github.event.inputs.backend == 'superbrowser'
+        run: |
+          # Install the SDK from the checked-out repository, NOT from PyPI.
+          # `pip install superbrowser-sdk[all]` would validate the published
+          # package while the PR's src/ tree went unimported — a false
+          # certification. `.[all]` installs the code under review.
+          pip install '.[all]'
+          python -m patchright install --with-deps chromium
+      - name: Run controlled tier
+        # Diagnostic only. run.py exits non-zero on any CRITICAL+FLAGGED
+        # verdict — which is the *expected* outcome on a bare CI runner
+        # with headless Chromium (the detection tool is doing its job).
+        # A flag here means detection worked, not that the harness broke.
+        # We capture the report but do not let it fail the job; the
+        # smoke-test step below is the actual wiring gate.
+        continue-on-error: true
+        working-directory: tests/adversarial_v3
+        run: |
+          PYTHONPATH=. python run.py \
+            --tier controlled \
+            --backend ${{ github.event.inputs.backend }} \
+            --output-dir /tmp/adv3-reports
+      - name: Run internal vectors
+        # Same rationale as the controlled tier: diagnostic capture.
+        continue-on-error: true
+        working-directory: tests/adversarial_v3
+        run: |
+          PYTHONPATH=. python run.py \
+            --tier fingerprint --tier automation --tier ejector --tier network --tier controlled \
+            --backend ${{ github.event.inputs.backend }} \
+            --output-dir /tmp/adv3-reports
+      - name: Run SuperBrowser backend smoke tests
+        # The real-backend merge gate. SB_AD3_SMOKE=1 un-skips the 8
+        # tests in test_superbrowser_backend.py that instantiate
+        # SuperBrowserBackend against the checked-out SDK. These catch
+        # constructor/lifecycle/evaluate drift. Unlike the diagnostic
+        # tiers above, THIS step is allowed to fail the job — it tests
+        # backend wiring, not stealth outcome.
+        if: github.event.inputs.backend == 'superbrowser'
+        working-directory: tests/adversarial_v3
+        env:
+          SB_AD3_SMOKE: '1'
+        run: |
+          PYTHONPATH=.:../../src python -m pytest tests/test_superbrowser_backend.py -v --tb=short
+      - name: Upload reports
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: adversarial-v3-reports
+          path: /tmp/adv3-reports/

superbrowser_sdk-2.3.0/.github/workflows/adversarial.yml

@@ -0,0 +1,117 @@
+name: Adversarial Stealth Validation
+
+on:
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: "Which tier(s) to run"
+        required: true
+        default: "tier3"
+        type: choice
+        options:
+          - tier3
+          - tier1
+          - tier2
+          - all
+      run_id:
+        description: "Custom run ID (optional)"
+        required: false
+        type: string
+
+concurrency:
+  group: adversarial-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  adversarial:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[all] || pip install -e .
+          pip install pytest pytest-asyncio
+
+      - name: Install browser engine
+        run: |
+          python -m patchright install --with-deps chromium || \
+          python -m playwright install --with-deps chromium || true
+
+      - name: Compute tier env vars
+        id: tiers
+        run: |
+          TIER="${{ inputs.tier }}"
+          if [ "$TIER" = "tier1" ] || [ "$TIER" = "all" ]; then
+            echo "adv=1" >> "$GITHUB_OUTPUT"
+          else
+            echo "adv=0" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$TIER" = "tier2" ] || [ "$TIER" = "all" ]; then
+            echo "vendors=1" >> "$GITHUB_OUTPUT"
+            echo "vendors_ack=1" >> "$GITHUB_OUTPUT"
+          else
+            echo "vendors=0" >> "$GITHUB_OUTPUT"
+            echo "vendors_ack=0" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run adversarial harness
+        env:
+          SB_ADV: ${{ steps.tiers.outputs.adv }}
+          SB_ADV_VENDORS: ${{ steps.tiers.outputs.vendors }}
+          SB_ADV_VENDORS_ACK: ${{ steps.tiers.outputs.vendors_ack }}
+        run: |
+          RUN_ID_ARG=""
+          if [ -n "${{ inputs.run_id }}" ]; then
+            RUN_ID_ARG="--run-id ${{ inputs.run_id }}"
+          fi
+          python scripts/adversarial_run.py \
+            --tier ${{ inputs.tier }} \
+            --output adversarial-results/report.json \
+            --markdown adversarial-results/report.md \
+            --history adversarial-results/adversarial-history.json \
+            $RUN_ID_ARG
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: adversarial-report-${{ github.run_id }}
+          path: adversarial-results/
+
+      - name: Comment on PR (if triggered from a PR branch)
+        if: github.event_name == 'workflow_dispatch' && github.event.inputs.tier != 'tier3'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            // workflow_dispatch from a branch does not populate
+            // context.issue.number. Find the PR for this branch instead.
+            const branch = context.ref.replace('refs/heads/', '');
+            const prs = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              head: `${context.repo.owner}:${branch}`,
+              state: 'open',
+            });
+            if (prs.data.length === 0) {
+              core.info(`No open PR found for branch ${branch}, skipping comment.`);
+              return;
+            }
+            const prNumber = prs.data[0].number;
+            const md = fs.readFileSync('adversarial-results/report.md', 'utf8');
+            await github.rest.issues.createComment({
+              issue_number: prNumber,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## 🤖 Adversarial Stealth Validation Report\n\n${md}`
+            });
+            core.info(`Commented on PR #${prNumber}`);

superbrowser_sdk-2.3.0/.github/workflows/stress.yml

@@ -0,0 +1,64 @@
+name: Stress Test
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "Quick or realistic"
+        required: true
+        default: "quick"
+        type: choice
+        options:
+          - quick
+          - realistic
+      sessions:
+        description: "Number of sessions (realistic mode)"
+        required: false
+        default: "3"
+      concurrency:
+        description: "Concurrency (realistic mode)"
+        required: false
+        default: "2"
+
+permissions:
+  contents: read
+
+jobs:
+  stress:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Super Browser
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[patchright]"
+          python -m patchright install chromium
+
+      - name: Run stress test (quick)
+        if: inputs.mode == 'quick'
+        run: |
+          python scripts/stress_real_world.py --quick \
+            --output stress-results
+
+      - name: Run stress test (realistic)
+        if: inputs.mode == 'realistic'
+        run: |
+          python scripts/stress_real_world.py --realistic \
+            --sessions ${{ inputs.sessions }} \
+            --concurrency ${{ inputs.concurrency }} \
+            --output stress-results
+
+      - name: Upload stress report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: stress-report
+          path: stress-results/
+          retention-days: 90
+          if-no-files-found: warn

{superbrowser_sdk-2.2.0 → superbrowser_sdk-2.3.0}/.github/workflows/test.yml

@@ -67,6 +67,7 @@ jobs:
           --ignore=tests/pattern_validation.py
           --ignore=tests/stealth_detection/
           --ignore=tests/discovery/
+          --ignore=tests/adversarial/
           -q
         env:
           PYTHONIOENCODING: utf-8

{superbrowser_sdk-2.2.0 → superbrowser_sdk-2.3.0}/.gitignore

@@ -70,7 +70,19 @@ benchmarks/results/
 
 # Smoke test results
 smoke-results/
+stress-results/
 
 # E2E trend artifacts
 tests/e2e/artifacts/e2e-history.json
 tests/e2e/artifacts/e2e-trend.md
+adversarial-results/
+
+# Adversarial v3 artifacts
+tests/adversarial_v3/adversarial-results/
+tests/adversarial_v3/.pytest_cache/
+
+# Research / competitive-analysis snapshots (one-time, not living docs)
+analysis/
+
+# Agent UI-state config (workspace-local, not SDK artifacts)
+labels/

{superbrowser_sdk-2.2.0 → superbrowser_sdk-2.3.0}/CHANGELOG.md

@@ -5,7 +5,57 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.3.0] — 2026-06-22
+
+### Bug Fixes
+
+- `BrowserSession.start()` now passes `locale` to `new_context()`, fixing the missing `Accept-Language` header regression (T5-002, #198). Added `locale` field to `SessionConfig` (default `"en-US"`); `locale=None` omits the key for engine defaults.
+
+### MCP Server — Phase 2
+
+- Restored tested MCP server (`superbrowser-mcp`, `python -m super_browser.mcp_server`) over stdio (#179).
+- Permission substrate: `MCPSessionPolicy`, `MCPAuthorizer`, `MCPAuditEntry` — central 5-step authorization path (write-enabled → action-count → timeout → `SecurityManager` → audit) (#183).
+- Write tools: `navigate`, `scroll`, `press_key`, `click`, `fill`, `open_tab`, `close_tab` — all gated by `MCPSessionPolicy.allow_writes` (default `False`) and routed through `SecurityManager` before reaching the facade (#184, #185).
+- `build_server()` now accepts `policy` and `security_manager` kwargs; `list_tools()` advertises write tools only when `allow_writes=True`.
+- Default server behavior is asymmetric: `list_tools()` advertises 6 read-only tools; `call_tool()` recognizes write-tool names and returns a structured policy refusal (not "unknown tool").
+- `fill` sends only the literal caller-supplied value — does not retrieve, infer, store, or auto-fill credentials.
+- Structured refusals, domain allow/block enforcement, audit logging for all write attempts (allowed and denied).
+- Still excluded: `download`, `upload`, `act`, arbitrary JS execution.
+
+## [2.2.1] — 2026-06-17
+
+### Overview
+
+**v2.2.1 — Runtime Correctness**
+
+Patch release fixing three user-facing runtime defects discovered in
+post-release source audit. No new features, no breaking changes.
+
+### Fixed
+
+- **Rich page fingerprint `interactive_count`** (loop.py): Was iterating
+  dict keys instead of `.values()`, calling `.get()` on string keys.
+  The `except` block silently returned `interactive_count=0` every time,
+  weakening page change detection. Now correctly counts interactive
+  nodes via `is_interactive` attribute.
+
+- **iframe action scoping** (controller.py + facade.py): `enter_frame()`
+  pushed a frame locator but no interaction method used it — all actions
+  targeted the top-level page instead of the iframe. New
+  `FrameInteractionTarget` adapter normalizes Playwright's
+  `FrameLocator` API (`.locator(sel).click()`) to match the controller's
+  selector-tier signatures (`.click(sel)`).
+
+- **IPReputationClient async path** (ip_reputation.py): Replaced
+  deprecated `asyncio.get_event_loop()` with `asyncio.get_running_loop()`
+  to fix DeprecationWarning on every call and future RuntimeError risk.
+
+### Internal
+
+- **Stress signal accuracy** (#167): RSS measurement prefers `psutil`
+  with platform-aware fallback; periodic `RSSSampler`; hard sleeps
+  replaced with `_wait_for_condition()` polling; `parallel_profiles`
+  verifies cross-context isolation; `/api/upload` returns real digest.
 
 ## [2.2.0] — 2026-06-16
 

{superbrowser_sdk-2.2.0 → superbrowser_sdk-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.2.0
+Version: 2.3.0
 Summary: Anti-detection agent browser SDK — stealth, budget governance, security guardrails, and structured error recovery behind one async facade
 Project-URL: Homepage, https://github.com/Octo-Lex/Super-Browser
 Project-URL: Documentation, https://github.com/Octo-Lex/Super-Browser#readme
@@ -19,7 +19,6 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
@@ -31,6 +30,7 @@ Requires-Dist: aiohttp>=3.9; extra == 'all'
 Requires-Dist: anthropic>=0.40; extra == 'all'
 Requires-Dist: cryptography>=42.0; extra == 'all'
 Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
 Requires-Dist: openai>=1.0; extra == 'all'
 Requires-Dist: patchright>=1.0; extra == 'all'
 Requires-Dist: pillow>=10.0; extra == 'all'
@@ -57,6 +57,8 @@ Requires-Dist: pytest-cov>=7.0; extra == 'dev'
 Requires-Dist: pytest>=9.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == 'openai'
 Provides-Extra: patchright
@@ -78,7 +80,9 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/superbrowser-sdk?color=blue)](https://pypi.org/project/superbrowser-sdk/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/Octo-Lex/Super-Browser/blob/main/LICENSE)
 
-**Super Browser** is an anti-detection agent browser SDK. It wraps browser automation (Patchright, Playwright, Selenium, or raw CDP) in an agent-first API with stealth, budget governance, security guardrails, and structured error recovery. MCP is a transport, the agent SDK is the user-facing layer, and stealth is the foundation.
+**Super Browser** is an agent-first, security-gated, anti-detection browser SDK built on top of existing automation engines. It wraps Patchright, Playwright, Selenium, or raw CDP behind one async facade with stealth defaults, multi-backend support, structured errors, budget governance, an MCP server with permissioned write tools, and an adversarial detection test suite that measures stealth honestly.
+
+> **Stealth evidence:** The adversarial suite shows Super-Browser at **16/25 clean** vs raw Playwright's **14/25** on controlled server + scanner targets, with `navigator.webdriver` and Sannysoft resolved and **0 regressions**. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md) for the full comparison table and known limitations.
 
 ## Installation
 
@@ -105,6 +109,14 @@ pip install superbrowser-sdk[selenium]        # Enterprise CI
 pip install superbrowser-sdk[all]
 ```
 
+For the MCP server (stdio, for Claude Desktop / Cursor integration):
+
+```bash
+pip install superbrowser-sdk[mcp,patchright]
+```
+
+See [`docs/mcp.md`](docs/mcp.md) for the 13-tool surface and client configuration.
+
 For specific LLM providers:
 
 ```bash
@@ -129,7 +141,7 @@ async def main():
     })
 
     # 3. Create the facade and run
-    async with SuperBrowser(llm_client=llm) as sb:
+    async with SuperBrowser(config=cfg, llm_client=llm) as sb:
         page = await sb.navigate("https://example.com")
         heading = await sb.extract("the page heading", selector="h1")
         print(f"Heading: {heading.data.extracted}")
@@ -250,27 +262,29 @@ Additional subsystems:
 |-----------|---------|
 | **Self-Healing Selectors** | Automatically recovers from broken CSS/XPath selectors using fuzzy matching |
 | **Stealth Mode** | Anti-detection patches (navigator properties, WebDriver flags, viewport fingerprint) |
-| **Output Budget** | Caps token usage per action to prevent runaway LLM costs |
-| **Security Guardrails** | URL allow/deny lists, domain validation, sensitive-input redaction |
+| **Adversarial Detection Suite** | 25-vector test harness that measures stealth honestly against controlled server + real scanners. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md). |
+| **Output Budget** | Caps token usage per action to prevent runaway LLM costs (daily, per-action, per-turn scopes) |
+| **Security Guardrails** | URL allow/deny lists, domain validation, sensitive-input redaction, structured refusals before side effects |
+| **MCP Server** | 13-tool stdio server (6 read-only + 7 write tools behind `MCPSessionPolicy` + `SecurityManager`). See [`docs/mcp.md`](docs/mcp.md). |
 | **Structured Results** | Every action returns a typed `ActionResult` with timing, method used, and error category |
+| **Behavioral Synthesis** | Bézier mouse paths, seeded human-like keystroke timing, inertial scroll from a deterministic seed |
 | **Vision** | Screenshot-based fallback for pages that resist DOM inspection |
 
 Full API documentation lives in [`docs/`](docs/).
 
 ## What's New (Unreleased)
 
-### Agent Streaming, Default Tooling, and Security Perimeter
-
-Nine waves of production-control improvements merged to `main`:
+### MCP Server, Adversarial Suite, Stealth Evidence
 
+- **MCP Server** — Permissioned stdio server with 13 tools (6 read-only + 7 write). Write tools route through `MCPSessionPolicy` → `SecurityManager` → audit before reaching the browser. Default is read-only advertisement; writes opt-in via `build_server(policy=MCPSessionPolicy(allow_writes=True))`. See [`docs/mcp.md`](docs/mcp.md).
+- **Adversarial Detection Suite** — 25-vector assessment harness across 6 tiers (fingerprint, automation, ejecta, behavioral, network, controlled) plus external scanners. Honest stub semantics (`JSUnsupportedError` → INCONCLUSIVE, never fabricated). See [`tests/adversarial_v3/`](tests/adversarial_v3/).
+- **Stealth Evidence** — Published comparison: Super-Browser **16/25 clean** vs raw Playwright **14/25** on controlled server + scanner targets. `navigator.webdriver` and Sannysoft resolved; 0 regressions. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md).
+- **Behavioral Telemetry** — Mouse/keystroke/scroll analysis vectors replace permanent SKIPPED with real telemetry-driven verdicts when `--record-behavior` is enabled.
 - **Streaming API** — `act_stream()` yields `StreamEvent` for real-time agent progress. Provider token streaming for OpenAI and Anthropic.
 - **Default Tooling** — 10 built-in tools auto-registered on startup (7 controller + 3 facade). Agents work out-of-box.
-- **Prompt Isolation** — Tool API removed from `<untrusted-screen-content>` wrappers.
 - **Security Perimeter** — All 12 side-effecting facade methods enforce `SecurityManager` before reaching the browser.
 - **Controller Rebinding** — Tools late-bind to current controller after tab switches.
 
-See the [Security Guardrails](#security-guardrails), [Streaming](#streaming), and [Default Agent Tooling](#default-agent-tooling) sections above.
-
 ## What's New in v1.9
 
 ### Platform Abstraction + Distribution — One API, Any Browser

{superbrowser_sdk-2.2.0 → superbrowser_sdk-2.3.0}/README.md

@@ -4,7 +4,9 @@
 [![PyPI](https://img.shields.io/pypi/v/superbrowser-sdk?color=blue)](https://pypi.org/project/superbrowser-sdk/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/Octo-Lex/Super-Browser/blob/main/LICENSE)
 
-**Super Browser** is an anti-detection agent browser SDK. It wraps browser automation (Patchright, Playwright, Selenium, or raw CDP) in an agent-first API with stealth, budget governance, security guardrails, and structured error recovery. MCP is a transport, the agent SDK is the user-facing layer, and stealth is the foundation.
+**Super Browser** is an agent-first, security-gated, anti-detection browser SDK built on top of existing automation engines. It wraps Patchright, Playwright, Selenium, or raw CDP behind one async facade with stealth defaults, multi-backend support, structured errors, budget governance, an MCP server with permissioned write tools, and an adversarial detection test suite that measures stealth honestly.
+
+> **Stealth evidence:** The adversarial suite shows Super-Browser at **16/25 clean** vs raw Playwright's **14/25** on controlled server + scanner targets, with `navigator.webdriver` and Sannysoft resolved and **0 regressions**. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md) for the full comparison table and known limitations.
 
 ## Installation
 
@@ -31,6 +33,14 @@ pip install superbrowser-sdk[selenium]        # Enterprise CI
 pip install superbrowser-sdk[all]
 ```
 
+For the MCP server (stdio, for Claude Desktop / Cursor integration):
+
+```bash
+pip install superbrowser-sdk[mcp,patchright]
+```
+
+See [`docs/mcp.md`](docs/mcp.md) for the 13-tool surface and client configuration.
+
 For specific LLM providers:
 
 ```bash
@@ -55,7 +65,7 @@ async def main():
     })
 
     # 3. Create the facade and run
-    async with SuperBrowser(llm_client=llm) as sb:
+    async with SuperBrowser(config=cfg, llm_client=llm) as sb:
         page = await sb.navigate("https://example.com")
         heading = await sb.extract("the page heading", selector="h1")
         print(f"Heading: {heading.data.extracted}")
@@ -176,27 +186,29 @@ Additional subsystems:
 |-----------|---------|
 | **Self-Healing Selectors** | Automatically recovers from broken CSS/XPath selectors using fuzzy matching |
 | **Stealth Mode** | Anti-detection patches (navigator properties, WebDriver flags, viewport fingerprint) |
-| **Output Budget** | Caps token usage per action to prevent runaway LLM costs |
-| **Security Guardrails** | URL allow/deny lists, domain validation, sensitive-input redaction |
+| **Adversarial Detection Suite** | 25-vector test harness that measures stealth honestly against controlled server + real scanners. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md). |
+| **Output Budget** | Caps token usage per action to prevent runaway LLM costs (daily, per-action, per-turn scopes) |
+| **Security Guardrails** | URL allow/deny lists, domain validation, sensitive-input redaction, structured refusals before side effects |
+| **MCP Server** | 13-tool stdio server (6 read-only + 7 write tools behind `MCPSessionPolicy` + `SecurityManager`). See [`docs/mcp.md`](docs/mcp.md). |
 | **Structured Results** | Every action returns a typed `ActionResult` with timing, method used, and error category |
+| **Behavioral Synthesis** | Bézier mouse paths, seeded human-like keystroke timing, inertial scroll from a deterministic seed |
 | **Vision** | Screenshot-based fallback for pages that resist DOM inspection |
 
 Full API documentation lives in [`docs/`](docs/).
 
 ## What's New (Unreleased)
 
-### Agent Streaming, Default Tooling, and Security Perimeter
-
-Nine waves of production-control improvements merged to `main`:
+### MCP Server, Adversarial Suite, Stealth Evidence
 
+- **MCP Server** — Permissioned stdio server with 13 tools (6 read-only + 7 write). Write tools route through `MCPSessionPolicy` → `SecurityManager` → audit before reaching the browser. Default is read-only advertisement; writes opt-in via `build_server(policy=MCPSessionPolicy(allow_writes=True))`. See [`docs/mcp.md`](docs/mcp.md).
+- **Adversarial Detection Suite** — 25-vector assessment harness across 6 tiers (fingerprint, automation, ejecta, behavioral, network, controlled) plus external scanners. Honest stub semantics (`JSUnsupportedError` → INCONCLUSIVE, never fabricated). See [`tests/adversarial_v3/`](tests/adversarial_v3/).
+- **Stealth Evidence** — Published comparison: Super-Browser **16/25 clean** vs raw Playwright **14/25** on controlled server + scanner targets. `navigator.webdriver` and Sannysoft resolved; 0 regressions. See [`docs/stealth-evidence.md`](docs/stealth-evidence.md).
+- **Behavioral Telemetry** — Mouse/keystroke/scroll analysis vectors replace permanent SKIPPED with real telemetry-driven verdicts when `--record-behavior` is enabled.
 - **Streaming API** — `act_stream()` yields `StreamEvent` for real-time agent progress. Provider token streaming for OpenAI and Anthropic.
 - **Default Tooling** — 10 built-in tools auto-registered on startup (7 controller + 3 facade). Agents work out-of-box.
-- **Prompt Isolation** — Tool API removed from `<untrusted-screen-content>` wrappers.
 - **Security Perimeter** — All 12 side-effecting facade methods enforce `SecurityManager` before reaching the browser.
 - **Controller Rebinding** — Tools late-bind to current controller after tab switches.
 
-See the [Security Guardrails](#security-guardrails), [Streaming](#streaming), and [Default Agent Tooling](#default-agent-tooling) sections above.
-
 ## What's New in v1.9
 
 ### Platform Abstraction + Distribution — One API, Any Browser