superbrowser-sdk 2.3.1__tar.gz → 2.5.0__tar.gz

{superbrowser_sdk-2.3.1 → superbrowser_sdk-2.5.0}/CHANGELOG.md

@@ -5,6 +5,128 @@ 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).
 
+## [2.5.0] — 2026-06-25
+
+### Added — MCP Server P2: Diagnostics Pack
+
+An explainability layer for failed reads/rendering. Five new inspect-tier
+tools let an agent inspect browser/page/network evidence when
+`navigate → wait_for → extract_text` returns unexpected content — without
+expanding the action surface. No `--allow-actions`, no action budget, no audit
+entry, no side effects.
+
+- `get_console_messages` — buffered browser console messages, filterable by
+  level.
+- `get_page_errors` — buffered uncaught page errors with stack traces.
+- `get_network_errors` — requests that failed (status ≥ 400, no response, or
+  net error).
+- `list_requests` — all buffered request summaries; returns `request_id` for
+  `get_request` follow-up.
+- `get_request` — one request's metadata by `request_id`.
+
+New `DiagnosticsBuffer` (`super_browser.agent.diagnostics`): session-wide ring
+buffers for console / page-error / network events, wired into the facade
+lifecycle (`start()` + `_attach_page()`). Survives tab switches. Exposed as
+`SuperBrowser.diagnostics`. Reads are snapshots (non-destructive); bounded
+deques (default 500, via `config.event_buffer_size`).
+
+### Design constraints (P2)
+
+- Diagnostics entries carry a monotonic `seq`, `timestamp_ms`, and `page_url`.
+- Request records use a stable `request_id` (assigned by the buffer). A URL can
+  have multiple requests (redirects, retries), so retrieval is always by
+  `request_id`, never by URL.
+- **No response bodies** and **no raw header values** are returned. `get_request`
+  exposes `header_names` (keys) only. Console text, page errors, and URLs are
+  returned as-is, matching the existing inspect-tool posture.
+- `get_request` returns a structured `{ok: false, reason: "not_found"}` when the
+  request was never buffered or evicted; it never raises.
+
+### Compatibility notes
+
+- The default stdio server now advertises **13 tools** (was 8): the 5
+  diagnostics tools are inspect-tier and always advertised. Clients asserting
+  on the advertised count should update. This is additive — no tools were
+  removed and no refusal strings changed.
+- Action mode advertises **19 tools** (was 14).
+
+## [2.4.0] — 2026-06-23
+
+### Added — MCP Server P1: Navigation Workflows
+
+The default MCP server can now read a URL end-to-end (`navigate → wait_for →
+observe/extract_text/screenshot`) without action mode. The tool surface was
+re-partitioned into a **four-tier model**:
+
+- **Inspect tier** (always advertised): `browser_status`, `current_url`,
+  `observe`, `extract_text`, `screenshot`, `list_tabs`.
+- **Navigation tier** (always advertised): `navigate`, `wait_for` (new).
+  Navigation mutates browser state (page acquisition) but is default-allowed
+  because reading requires a page to read. It is `SecurityManager`-checked and
+  audited (both approvals and denials) in the default stdio / `build_server()`
+  path, but it does **not** consume the action budget. Bare
+  `ToolDispatcher(runtime)` integrations may navigate without an attached
+  authorizer; in that case no audit/security check is performed.
+- **Action tier** (requires `--allow-actions` / `SB_MCP_ALLOW_ACTIONS=1`):
+  `scroll`, `press_key`, `click`, `fill`, `open_tab`, `close_tab`.
+- **High-risk tier** (not implemented): `download`, `upload`, `act`, arbitrary JS.
+
+New APIs:
+
+- `wait_for` tool: wait for exactly one page condition (`selector` / `text` /
+  `url` / `load_state`) with `timeout_ms` (100–60000, default 10000).
+- `MCPSessionPolicy.allow_actions` (primary) with `allow_writes` retained as a
+  backward-compatibility alias.
+- `MCPAuthorizer.record_audit()` — public audit helper for navigation-tier
+  entries; returns the `MCPAuthorizationResult` it constructed.
+- `--allow-actions` CLI flag and `SB_MCP_ALLOW_ACTIONS` env var
+  (truthy sentinels: `1`, `true`, `yes`, `on`).
+- `SB_MCP_DOMAIN_ALLOWLIST` / `SB_MCP_DOMAIN_BLOCKLIST` env vars for opt-in
+  domain filtering on the default stdio server (comma- or whitespace-separated;
+  glob patterns supported).
+- `run_server()` now constructs a default `SecurityManager` so navigation is
+  security-checked in the default stdio path; callers may pass
+  `security_manager=` to override (or `None` to disable).
+
+### Changed
+
+- **Default advertised tool count: 6 → 8** (adds `navigate` and `wait_for`).
+- `navigate` moved from the action-gated write tier to the default-allowed
+  navigation tier.
+- Action-gate refusal message changed from `"writes are disabled"` to
+  `"actions are disabled"` (the gate protects the Action tier).
+- `_tools_for_policy()` now advertises `DEFAULT_TOOLS` (inspect + navigation)
+  by default and adds `ACTION_TOOLS` when `allow_actions` is set.
+- `main()` now uses `argparse` (previously raw `sys.argv` substring matching).
+
+### Compatibility notes
+
+- The action-gate refusal `reason` changed from `"writes are disabled"` to
+  `"actions are disabled"`. Clients/docs pattern-matching the old string should
+  update. (`MCPSessionPolicy(allow_writes=True)` callers are otherwise
+  unaffected — the flag still enables action tools via the compat alias.)
+- The default stdio server now advertises 8 tools, not 6. Clients asserting on
+  the advertised count should update.
+
+### Fixed
+
+- Fixed default navigation dispatch so bare `ToolDispatcher(runtime)`
+  integrations can use `navigate` without requiring an authorizer; security
+  checks and audit still run when an authorizer/security manager is attached,
+  including the default stdio server path.
+
+### Internal
+
+- Tier constants: `INSPECT_TOOLS` / `NAVIGATION_TOOLS` / `ACTION_TOOLS` /
+  `DEFAULT_TOOLS` and their `_NAME` frozensets. (`PHASE1_TOOLS`,
+  `PHASE2B_TOOLS`, `PHASE2B_WAVE2_TOOLS`, and `WRITE_TOOL_NAMES` retained as
+  aliases for backward-compat imports.)
+- `_validate_write_args` split into `_validate_navigation_args` and
+  `_validate_action_args`; the old name remains as a routing alias.
+- `wait_for` reaches the raw Patchright/Playwright page via
+  `sb._page.backend_page` (one hop); the deprecated `.raw_page` accessor is
+  not used.
+
 ## [2.3.1] — 2026-06-22
 
 ### Fixed

{superbrowser_sdk-2.3.1 → superbrowser_sdk-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.3.1
+Version: 2.5.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

superbrowser_sdk-2.5.0/docs/mcp.md

@@ -0,0 +1,325 @@
+# Super Browser MCP Server
+
+Super Browser exposes its browser inspection and control surface over the
+[Model Context Protocol](https://modelcontextprotocol.io) so that AI coding
+agents (Claude, Cursor, etc.) can observe and interact with a page without
+scripting Python.
+
+The stdio server advertises **thirteen tools by default** (six inspect + five
+diagnostics + two navigation) — enough to read a URL end-to-end and explain
+why a read failed. When action mode is enabled, it advertises **six additional
+action tools**; every action call is checked by
+`MCPSessionPolicy` and `SecurityManager` before it can reach the browser.
+
+See [RFC #178](https://github.com/Octo-Lex/Super-Browser/issues/178) for the
+design history.
+
+> `screenshot` captures the rendered page contents as the browser sees them. There is no automatic redaction; callers decide when to invoke it.
+
+## Install
+
+```bash
+pip install 'superbrowser-sdk[mcp,patchright]'
+python -m patchright install chromium
+```
+
+`[mcp]` pulls the lightweight `mcp` SDK (no browser deps of its own).
+`[patchright]` provides the browser backend the server drives.
+
+## Run
+
+Either of:
+
+```bash
+superbrowser-mcp                       # default: 13 tools (inspect + diagnostics + navigation)
+superbrowser-mcp --allow-actions       # 14 tools (adds the action tier)
+python -m super_browser.mcp_server
+```
+
+Both start a **stdio** server. The default server advertises 13 tools and
+recognizes (but refuses) action-tool calls with a structured policy refusal.
+
+Action mode can also be enabled via the environment:
+
+```bash
+SB_MCP_ALLOW_ACTIONS=1 superstl-browser-mcp
+```
+
+Accepted truthy values: `1`, `true`, `yes`, `on` (case-insensitive).
+
+## Client configuration
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json` or the equivalent):
+
+```json
+{
+  "mcpServers": {
+    "super-browser": {
+      "command": "superbrowser-mcp"
+    }
+  }
+}
+```
+
+Or, if you prefer the module form:
+
+```json
+{
+  "mcpServers": {
+    "super-browser": {
+      "command": "python",
+      "args": ["-m", "super_browser.mcp_server"]
+    }
+  }
+}
+```
+
+To enable action tools:
+
+```json
+{
+  "mcpServers": {
+    "super-browser": {
+      "command": "superbrowser-mcp",
+      "args": ["--allow-actions"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "super-browser": {
+      "command": "superbrowser-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+All tools return structured JSON (`{"ok": bool, ...}`) as `TextContent`. The
+screenshot tool additionally returns an `ImageContent` block.
+
+The tool surface is partitioned into four tiers. The first two are always
+advertised; the third requires action mode; the fourth is not implemented.
+
+### Inspect tier (always advertised)
+
+| Tool | Args | Behavior | Lazy-starts browser? |
+|---|---|---|---|
+| `browser_status` | none | Runtime status (running, backend). | No |
+| `current_url` | none | Current URL, or a structured "not started" state. | No |
+| `observe` | none | Page state: URL, title, interactive/total element counts. | Yes |
+| `extract_text` | `query` (required), `selector` (optional) | Text content, optionally scoped to a CSS selector. | Yes |
+| `screenshot` | `full_page` (optional, default `false`) | Base64 PNG of the viewport or full page. | Yes |
+| `list_tabs` | none | Snapshot of open tabs. | Yes |
+| `get_console_messages` | `level` (optional), `limit` (optional, default 100) | Buffered browser console messages (snapshot, non-destructive). | Yes |
+| `get_page_errors` | `limit` (optional, default 100) | Buffered uncaught page errors with stack traces. | Yes |
+| `get_network_errors` | `url_filter` (optional), `limit` (optional, default 100) | Requests that failed (status ≥ 400, no response, or net error). | Yes |
+| `list_requests` | `url_filter` (optional), `resource_type` (optional), `limit` (optional, default 100) | All buffered request summaries; returns `request_id` for `get_request`. | Yes |
+| `get_request` | `request_id` (required) | One request's metadata (method, url, status, `header_names` — keys only, no values, no body). | Yes |
+
+The five diagnostics tools read from a session-wide ring buffer that captures
+console messages, page errors, and network requests via page-event listeners.
+Reads are **snapshots** (non-destructive): the buffer is not cleared on read.
+Diagnostics entries carry a monotonic `seq`, a `timestamp_ms`, and the
+`page_url` at the time of the event. Request records use a stable `request_id`
+(assigned by the buffer); a URL can have multiple requests, so always retrieve
+via `request_id` from `list_requests`, not by URL. **No response bodies and no
+raw header values** are returned — `get_request` exposes `header_names` (keys)
+only.
+
+### Navigation tier (always advertised)
+
+Navigation mutates browser state (page acquisition) but is default-allowed
+because reading requires a page to read. It is always checked by the
+`SecurityManager` and is audited, but it does **not** consume the action
+budget and does **not** require action mode.
+
+| Tool | Args | Behavior |
+|---|---|---|
+| `navigate` | `url` (required), `wait_until` (optional) | Go to a URL. URL is passed to `SecurityManager` for injection detection, secret redaction, and domain allow/block enforcement. |
+| `wait_for` | exactly one of `selector` / `text` / `url` / `load_state`; `timeout_ms` (optional, 100–60000, default 10000) | Wait for a page condition before the next read. |
+
+`wait_for` accepts exactly one condition per call (deterministic single
+results; compound waits can be added later as an explicit AND mode).
+
+#### Read workflow
+
+```text
+navigate → wait_for → observe / extract_text / screenshot
+```
+
+This is the default-mode loop an agent uses to read a page.
+
+#### Debugging workflow
+
+When a read returns unexpected or empty content, the diagnostics tools explain
+why — without expanding the action surface:
+
+```text
+navigate → wait_for → extract_text / observe
+        ↓ (unexpected / empty / errored)
+get_console_messages → get_page_errors → get_network_errors
+        ↓ (inspect the evidence)
+list_requests → get_request(request_id=...)   (drill into one request)
+        ↓
+adjust selector / report failure / retry
+```
+
+Diagnostics are inspect-tier: no `--allow-actions`, no action budget, no audit
+entry, no side effects.
+
+### Action tier (advertised when action mode is enabled)
+
+| Tool | Args | Security level |
+|---|---|---|
+| `scroll` | `direction` (optional), `amount` (optional) | SENSITIVE |
+| `press_key` | `key` (required) | SENSITIVE |
+| `click` | `target` (required), `description` (optional) | SENSITIVE |
+| `fill` | `target` (required), `value` (required), `clear_first` (optional), `description` (optional) | SENSITIVE |
+| `open_tab` | `url` (optional) | SENSITIVE — URL passed to `SecurityManager` when provided |
+| `close_tab` | `tab_id` (required) | SENSITIVE |
+
+`fill` sends only the literal value supplied by the caller. It does not
+retrieve, infer, store, or auto-fill credentials.
+
+#### Action workflow
+
+```bash
+superbrowser-mcp --allow-actions
+```
+
+Action calls pass through the full authorization path (action gate →
+action-count budget → timeout budget → `SecurityManager` → audit) before
+reaching the browser.
+
+### High-risk tier (not implemented)
+
+`download`, `upload`, `act` (the LLM agent loop), and arbitrary JS execution
+are not implemented. They will return a structured "Unknown tool" error and
+will require a separate design pass before implementation.
+
+## Domain filtering
+
+Navigation is always security-checked, but domain allow/block enforcement is
+**opt-in** via environment variables. With neither set, the domain filter is
+allow-all (injection detection and secret redaction still run).
+
+```bash
+# Block specific hosts (comma- or whitespace-separated; glob patterns allowed)
+SB_MCP_DOMAIN_BLOCKLIST="evil.com, *.test" superstl-browser-mcp
+
+# Restrict to an allowlist (anything not matching is denied)
+SB_MCP_DOMAIN_ALLOWLIST="example.com, docs.example.com" superstl-browser-mcp
+```
+
+When both are set, the blocklist is evaluated first; the allowlist then
+restricts the survivors.
+
+## Four-tier tool model
+
+The default server behavior partitions the surface by risk:
+
+- **`list_tools()`** advertises only the Inspect + Navigation tiers (13 tools).
+- **`call_tool()`** still recognizes action-tool names and returns a structured
+  policy refusal (`refusal.reason = "actions are disabled"`), not an "Unknown
+  tool" error.
+
+This means clients don't see action tools by default, but manual or
+unadvertised action calls are handled cleanly rather than misclassified.
+
+### Permission model (action tools)
+
+Every action-tier call passes through a central authorization path before
+reaching the browser:
+
+1. **Action-enabled check** — `MCPSessionPolicy.allow_actions` must be `True`
+2. **Action-count check** — `actions_used` must not exceed `max_actions`
+3. **Timeout-budget check** — session elapsed time must not exceed `timeout_seconds`
+4. **`SecurityManager.check_action()`** — domain allow/block lists, action policy, injection detection, redaction
+5. **Audit log** — every action attempt (allowed or denied) is recorded
+
+Navigation-tier calls use a lighter path: argument validation →
+`SecurityManager.check_action()` (navigate only) → audit (both approvals and
+denials) → handler. They bypass the action gate, action-count budget, and
+timeout budget.
+
+All denials return structured JSON as normal MCP content, never raised:
+
+```json
+{
+  "ok": false,
+  "refusal": {
+    "tool": "navigate",
+    "blocked_by": "security_manager",
+    "reason": "domain_filter",
+    "security_level": "sensitive"
+  }
+}
+```
+
+### Lifecycle
+
+- One browser per server process.
+- The browser lazy-starts on the first browser-dependent tool call
+  (`navigate`, `wait_for`, `observe`, `extract_text`, `screenshot`,
+  `list_tabs`, or any action tool that reaches the facade after authorization).
+- `browser_status` and `current_url` are safe to call before startup and do
+  **not** force a launch.
+- On server close, the runtime calls `SuperBrowser.stop()` to tear down.
+
+## Errors
+
+Errors are returned as structured JSON, never raised across the MCP boundary:
+
+```json
+{"ok": false, "error": "Unknown tool: '__missing__'. Available: [...]" }
+```
+
+Argument-validation errors use the `invalid_arguments` key:
+
+```json
+{"ok": false, "invalid_arguments": "'query' is required and must be a non-empty string"}
+```
+
+`wait_for` timeouts return a structured timeout result:
+
+```json
+{"ok": false, "timeout": true, "reason": "Timeout 10000ms exceeded"}
+```
+
+## Behavior changes
+
+### `superbrowser-sdk` 2.4 — navigation tier
+
+Prior to 2.4, the default MCP server advertised 6 read-only tools and gated
+**all** side-effecting tools (including `navigate`) behind `allow_writes=True`.
+
+In 2.4 the tool surface was re-partitioned into four tiers:
+
+- `navigate` moved into a default-allowed **Navigation tier** (reading requires
+  page acquisition). It is still `SecurityManager`-checked and audited.
+- `wait_for` was added (navigation tier).
+- The former "write tools" became the **Action tier**, gated by
+  `allow_actions` (`--allow-actions` / `SB_MCP_ALLOW_ACTIONS`).
+- The action-gate refusal message changed from `"writes are disabled"` to
+  `"actions are disabled"`. Clients pattern-matching the old string must update.
+
+`allow_writes` remains as a backward-compatibility alias for `allow_actions`
+in `MCPSessionPolicy`; existing callers using `MCPSessionPolicy(allow_writes=True)`
+continue to work.
+
+## Reference
+
+- Design: [RFC #178](https://github.com/Octo-Lex/Super-Browser/issues/178)
+- The deleted prior server (`a370cf9`) is recoverable from git history for
+  reference — it shipped 10 tools including 6 side-effecting ones with no
+  permission model and no tests. The current server is the deliberate
+  correction: tested, permissioned, tiered, with structured refusals and audit logging.

{superbrowser_sdk-2.3.1 → superbrowser_sdk-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superbrowser-sdk"
-version = "2.3.1"
+version = "2.5.0"
 description = "Anti-detection agent browser SDK — stealth, budget governance, security guardrails, and structured error recovery behind one async facade"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{superbrowser_sdk-2.3.1 → superbrowser_sdk-2.5.0}/src/super_browser/__init__.py

@@ -6,7 +6,7 @@ from super_browser.agent.types import StreamEvent as StreamEvent  # noqa: F401
 from super_browser.config import Config as Config  # noqa: F401
 from super_browser.results.types import ActionResult as ActionResult  # noqa: F401
 
-__version__ = "2.3.1"
+__version__ = "2.5.0"
 
 __all__ = [
     "SuperBrowser",