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

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

@@ -5,6 +5,51 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.4.0
+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.4.0 → superbrowser_sdk-2.5.0}/docs/mcp.md

@@ -5,9 +5,10 @@ Super Browser exposes its browser inspection and control surface over the
 agents (Claude, Cursor, etc.) can observe and interact with a page without
 scripting Python.
 
-The stdio server advertises **eight tools by default** (six inspect + two
-navigation) — enough to read a URL end-to-end. When action mode is enabled,
-it advertises **six additional action tools**; every action call is checked by
+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
@@ -30,12 +31,12 @@ python -m patchright install chromium
 Either of:
 
 ```bash
-superbrowser-mcp                       # default: 8 tools (inspect + navigation)
+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 8 tools and
+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:
@@ -118,6 +119,21 @@ advertised; the third requires action mode; the fourth is not implemented.
 | `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)
 
@@ -142,6 +158,24 @@ 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 |
@@ -193,7 +227,7 @@ restricts the survivors.
 
 The default server behavior partitions the surface by risk:
 
-- **`list_tools()`** advertises only the Inspect + Navigation tiers (8 tools).
+- **`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.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superbrowser-sdk"
-version = "2.4.0"
+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.4.0 → 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.4.0"
+__version__ = "2.5.0"
 
 __all__ = [
     "SuperBrowser",

superbrowser_sdk-2.5.0/src/super_browser/agent/diagnostics.py

@@ -0,0 +1,287 @@
+"""Session-wide diagnostics capture for page events.
+
+Wires Playwright/Patchright page-event listeners (console, pageerror, request,
+response) into bounded ring buffers that survive tab switches. Read semantics
+are snapshots (non-destructive): callers get list-copies; the bounded deques
+naturally drop the oldest entries.
+
+Designed for the MCP diagnostics tool pack — an inspect-tier explainability
+layer for failed reads/rendering. No action gate, no side effects, no response
+bodies, no raw header values (header keys only).
+"""
+
+from __future__ import annotations
+
+import time
+import weakref
+from collections import deque
+from typing import Any
+
+_DEFAULT_MAX_SIZE = 500
+
+
+def _safe_call(obj: Any, attr: str, *, default: Any = None) -> Any:
+    """Call a sync attr/method on a Playwright object, swallowing errors.
+
+    Many Playwright surfaces expose properties that are sometimes methods,
+    sometimes attributes, and can raise if the underlying handle is gone.
+    Used only in the sync event handlers.
+    """
+    fn = getattr(obj, attr, None)
+    if fn is None:
+        return default
+    try:
+        return fn() if callable(fn) else fn
+    except Exception:  # noqa: BLE001
+        return default
+
+
+# Internal record keys that are never exposed in public snapshots/details.
+_INTERNAL_KEYS = frozenset({"_request_obj_id"})
+
+
+def _strip(record: dict) -> dict:
+    """Return a copy of ``record`` with internal plumbing keys removed."""
+    return {k: v for k, v in record.items() if k not in _INTERNAL_KEYS}
+
+
+class DiagnosticsBuffer:
+    """Session-wide ring buffers for page diagnostic events.
+
+    Three bounded deques (console / errors / requests) plus a monotonic seq
+    counter. Reads are snapshots (non-destructive). ``attach()`` is idempotent
+    by raw-page identity (tracked via a ``WeakSet``), so it is safe to call
+    across repeated tab switches on the same underlying page.
+
+    Event handlers are intentionally sync-safe — they never ``await`` inside
+    ``page.on(...)`` callbacks. All Playwright/Patchright properties read in
+    the handlers (``ConsoleMessage.type/.text``, ``Request.method/.url/...``,
+    ``Request.failure``, ``Request.timing``) are sync.
+    """
+
+    def __init__(self, max_size: int = _DEFAULT_MAX_SIZE) -> None:
+        self.max_size = max_size
+        self._console: deque[dict] = deque(maxlen=max_size)
+        self._errors: deque[dict] = deque(maxlen=max_size)
+        self._requests: deque[dict] = deque(maxlen=max_size)
+        self._seq = 0
+        self._request_counter = 0
+        # request_id -> record, for O(1) request_detail lookup.
+        self._req_index: dict[str, dict] = {}
+        # id(Playwright Request obj) -> request_id, for response correlation
+        # via response.request back-reference. (Request objects are hashable by
+        # identity; we key by id() to avoid holding strong refs in the dict.)
+        self._req_obj_index: dict[int, str] = {}
+        # Idempotent-attach tracking by weak page identity. A WeakSet (rather
+        # than a set[int] of id() values) ensures a page that is GC'd drops
+        # out automatically, eliminating the id()-reuse window in which a
+        # newly-allocated page reusing a freed page's address would be wrongly
+        # treated as already-attached.
+        self._attached: "weakref.WeakSet[Any]" = weakref.WeakSet()
+
+    # --- internal helpers ---
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    @staticmethod
+    def _now_ms() -> float:
+        return time.time() * 1000.0
+
+    def _on_console(self, raw_page: Any, message: Any) -> None:
+        self._console.append({
+            "seq": self._next_seq(),
+            "timestamp_ms": self._now_ms(),
+            "type": getattr(message, "type", None),
+            "text": getattr(message, "text", None),
+            "page_url": getattr(raw_page, "url", None),
+        })
+
+    # --- attach / detach ---
+
+    def attach(self, raw_page: Any) -> None:
+        """Wire console/pageerror/request/response listeners onto ``raw_page``.
+
+        Idempotent by weak page identity: a second call with the same page
+        object is a no-op. The weak reference means a page that is GC'd
+        drops out of the tracking set automatically, so a later page that
+        happens to reuse a freed page's memory address is NOT wrongly treated
+        as already-attached. Safe across repeated tab switches.
+        """
+        if raw_page in self._attached:
+            return
+        self._attached.add(raw_page)
+
+        raw_page.on("console", lambda msg: self._on_console(raw_page, msg))
+        raw_page.on("pageerror", lambda err: self._on_pageerror(raw_page, err))
+        raw_page.on("request", lambda req: self._on_request(raw_page, req))
+        raw_page.on("response", lambda resp: self._on_response(raw_page, resp))
+
+    def detach(self, raw_page: Any) -> None:
+        """Remove a page from the attached set so it can be re-attached.
+
+        Note: Playwright/Patchright does not expose listener removal on the
+        Page object, so this only clears the idempotency guard. Listeners on
+        a page that is being closed are harmless (the page is GC'd, and the
+        WeakSet entry drops out automatically).
+        """
+        self._attached.discard(raw_page)
+
+    # --- placeholders for later tasks ---
+
+    def _on_pageerror(self, raw_page: Any, error: Any) -> None:
+        # Real page errors may carry only .message; .name/.stack are optional.
+        # getattr-with-default keeps the handler robust without swallowing the
+        # event on a missing attribute.
+        self._errors.append({
+            "seq": self._next_seq(),
+            "timestamp_ms": self._now_ms(),
+            "message": getattr(error, "message", str(error)),
+            "name": getattr(error, "name", None),
+            "stack": getattr(error, "stack", None),
+            "page_url": getattr(raw_page, "url", None),
+        })
+
+    def _on_request(self, raw_page: Any, request: Any) -> None:
+        # Assign a stable request_id and capture the request-side fields.
+        # Response-side fields (status/status_text/ok) are filled in by
+        # _on_response via the correlation index. Failure/header enrichment is
+        # captured here (sync) since the Request object is available.
+        self._request_counter += 1
+        request_id = f"r-{self._request_counter}"
+        seq = self._next_seq()
+
+        # redirected_from: a Playwright Request or None. Correlate to our
+        # request_id if we've seen it; else record None.
+        redirected_from_obj = _safe_call(request, "redirected_from", default=None)
+        redirected_from_id = (
+            self._req_obj_index.get(id(redirected_from_obj))
+            if redirected_from_obj is not None else None
+        )
+
+        # Failure text: Request.failure() returns a string or None for net errors.
+        failure_text = _safe_call(request, "failure", default=None)
+
+        # Header NAMES only (keys), never values — sensitivity control.
+        headers = _safe_call(request, "headers", default={}) or {}
+        try:
+            header_names = list(headers.keys())
+        except Exception:  # noqa: BLE001
+            header_names = []
+
+        record = {
+            "seq": seq,
+            "request_id": request_id,
+            "timestamp_ms": self._now_ms(),
+            "method": getattr(request, "method", None),
+            "url": getattr(request, "url", None),
+            "resource_type": getattr(request, "resource_type", None),
+            "is_navigation": bool(_safe_call(request, "is_navigation_request", default=False)),
+            "redirected_from": redirected_from_id,
+            "status": None,
+            "status_text": None,
+            "ok": None,
+            "failed": failure_text is not None,
+            "failure_text": failure_text,
+            "header_names": header_names,
+            "page_url": getattr(raw_page, "url", None),
+            # Internal plumbing key — stripped from public output by _strip().
+            # Stored so the eviction path can prune _req_obj_index.
+            "_request_obj_id": id(request),
+        }
+        # Prune both indexes BEFORE appending if this append will evict the
+        # oldest deque entry. Without this, _req_index/_req_obj_index grow
+        # unbounded for the session and request_detail() returns records that
+        # list_requests() can no longer see (eviction inconsistency).
+        if len(self._requests) == self.max_size:
+            evicted = self._requests[0]
+            evicted_rid = evicted.get("request_id")
+            if evicted_rid is not None:
+                self._req_index.pop(evicted_rid, None)
+            evicted_oid = evicted.get("_request_obj_id")
+            if evicted_oid is not None:
+                self._req_obj_index.pop(evicted_oid, None)
+        self._requests.append(record)
+        self._req_index[request_id] = record
+        self._req_obj_index[id(request)] = request_id
+
+    def _on_response(self, raw_page: Any, response: Any) -> None:
+        # Correlate back to the originating request via response.request, then
+        # enrich the record with status/status_text/ok. If we never buffered
+        # the request (e.g. started mid-session), silently drop.
+        origin = getattr(response, "request", None)
+        if origin is None:
+            return
+        request_id = self._req_obj_index.get(id(origin))
+        if request_id is None:
+            return
+        record = self._req_index.get(request_id)
+        if record is None:
+            return
+        status = _safe_call(response, "status", default=None)
+        record["status"] = status
+        record["status_text"] = _safe_call(response, "status_text", default=None)
+        record["ok"] = _safe_call(response, "ok", default=None)
+        # A response with status>=400 is a failure even if the request had no
+        # net-level failure_text.
+        if status is not None and status >= 400:
+            record["failed"] = True
+
+    # --- snapshot accessors ---
+
+    def last_seq(self) -> int:
+        """The highest seq assigned so far (0 before any event)."""
+        return self._seq
+
+    def console_messages(
+        self, *, level: str | None = None, limit: int = 100,
+    ) -> list[dict]:
+        """Snapshot of console entries (newest-last), optionally filtered by level."""
+        items = list(self._console)
+        if level is not None:
+            items = [e for e in items if e.get("type") == level]
+        return items[-limit:] if limit is not None else items
+
+    def page_errors(self, *, limit: int = 100) -> list[dict]:
+        """Snapshot of uncaught page errors (newest-last)."""
+        items = list(self._errors)
+        return items[-limit:] if limit is not None else items
+
+    def requests(
+        self,
+        *,
+        url_filter: str | None = None,
+        resource_type: str | None = None,
+        failed_only: bool = False,
+        limit: int = 100,
+    ) -> list[dict]:
+        """Snapshot of request records (newest-last).
+
+        - ``url_filter``: substring match against the request URL.
+        - ``resource_type``: exact match (e.g. "fetch", "xhr", "image").
+        - ``failed_only``: requests where failed OR status>=400 OR status is None.
+        - ``limit``: return the last N (None = all).
+        """
+        items = [_strip(r) for r in self._requests]
+        if url_filter is not None:
+            items = [r for r in items if r.get("url") and url_filter in r["url"]]
+        if resource_type is not None:
+            items = [r for r in items if r.get("resource_type") == resource_type]
+        if failed_only:
+            items = [
+                r for r in items
+                if r.get("failed") or (r.get("status") is not None and r["status"] >= 400)
+                or r.get("status") is None
+            ]
+        return items[-limit:] if limit is not None else items
+
+    def request_detail(self, request_id: str) -> dict | None:
+        """One record by request_id, or None if not buffered/evicted.
+
+        Returns the live record (reflects response enrichment that arrived
+        after the request event). The MCP tool layer turns None into a
+        structured ``{ok: false, reason: "not_found"}`` response.
+        """
+        rec = self._req_index.get(request_id)
+        return _strip(rec) if rec is not None else None

{superbrowser_sdk-2.4.0 → superbrowser_sdk-2.5.0}/src/super_browser/agent/facade.py

@@ -80,9 +80,33 @@ class SuperBrowser:
         self._recorder: Any = None  # Optional[SessionRecorder]
         self._event_bus: Any = None  # Optional[EventBus]
         self._memory_store: Optional[MemoryStore] = None  # Set via enable_memory()
+        # Diagnostics: session-wide page-event capture (console/errors/network).
+        # Attached to every raw page via start()/_attach_page(); survives tab
+        # switches because listener closures bind to the raw Page, not PageHandle.
+        from super_browser.agent.diagnostics import DiagnosticsBuffer
+        buf_size = getattr(self._config, "event_buffer_size", 500) if self._config else 500
+        self._diagnostics = DiagnosticsBuffer(max_size=buf_size)
 
     # -- Lifecycle --
 
+    @property
+    def diagnostics(self) -> Any:
+        """Session-wide diagnostics buffer (console/page-errors/network).
+
+        Exposed for the MCP diagnostics tools and direct SDK consumers. Reads
+        are snapshots (non-destructive); see :class:`DiagnosticsBuffer`.
+        """
+        return self._diagnostics
+
+    def _attach_diagnostics(self, raw_page: Any) -> None:
+        """Wire diagnostics listeners onto a raw page.
+
+        Called from :meth:`start` (initial page) and :meth:`_attach_page`
+        (tab open/switch). Idempotent by raw-page identity inside the buffer,
+        so it is safe to call on every tab switch.
+        """
+        self._diagnostics.attach(raw_page)
+
     async def start(self) -> None:
         cfg = self._config
         # -- Determine backend & session config from composition root --
@@ -99,6 +123,8 @@ class SuperBrowser:
             await self._session.start()
             self._page = await self._session.new_page()
         self._controller = MultimodalController(self._page, self._page.engine_page.cdp)
+        # Wire diagnostics listeners onto the initial page.
+        self._attach_diagnostics(self._page.backend_page)
         self._running = True
         self._register_builtin_tools()
         self._configure_verification()
@@ -425,6 +451,8 @@ class SuperBrowser:
         cdp = CDPBridge(cdp_session, _SC())
         self._page = PageHandle(page_obj, cdp)
         self._controller = MultimodalController(self._page, self._page.engine_page.cdp)
+        # Wire diagnostics listeners onto the new tab/switched page.
+        self._attach_diagnostics(self._page.backend_page)
 
     # -- Multi-Tab --
 

{superbrowser_sdk-2.4.0 → superbrowser_sdk-2.5.0}/src/super_browser/mcp_server.py

@@ -242,8 +242,75 @@ _PHASE2B_WAVE2_TOOL_NAMES = frozenset(t.name for t in PHASE2B_WAVE2_TOOLS)
 # redaction, domain policy when configured) but NOT action-gated and does NOT
 # consume the action budget.
 
-# Inspect-tier tools: the existing read-only set.
-INSPECT_TOOLS: list[types.Tool] = list(PHASE1_TOOLS)
+# Diagnostics inspect-tier tools (P2): explainability layer for failed
+# reads/rendering. Read-only snapshots of console/page-error/network buffers.
+# No action gate, no audit, no budget. No response bodies, no raw header
+# values (header NAMES only).
+DIAGNOSTICS_TOOLS: list[types.Tool] = [
+    types.Tool(
+        name="get_console_messages",
+        description="Return buffered browser console messages (snapshot, non-destructive). Inspect-tier.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "level": {"type": "string", "description": "Filter by console type: log, error, warning, info, debug."},
+                "limit": {"type": "integer", "default": 100, "description": "Return the last N entries."},
+            },
+            "required": [],
+        },
+    ),
+    types.Tool(
+        name="get_page_errors",
+        description="Return buffered uncaught page errors with stack traces (snapshot). Inspect-tier.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "limit": {"type": "integer", "default": 100, "description": "Return the last N entries."},
+            },
+            "required": [],
+        },
+    ),
+    types.Tool(
+        name="get_network_errors",
+        description="Return buffered network requests that failed (status>=400, no response, or net error). Inspect-tier.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "url_filter": {"type": "string", "description": "Substring filter on URL."},
+                "limit": {"type": "integer", "default": 100, "description": "Return the last N entries."},
+            },
+            "required": [],
+        },
+    ),
+    types.Tool(
+        name="list_requests",
+        description="Return buffered network request summaries (request_id, method, url, status). Use request_id with get_request for detail. Inspect-tier.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "url_filter": {"type": "string", "description": "Substring filter on URL."},
+                "resource_type": {"type": "string", "description": "Exact resource type: fetch, xhr, document, image, ..."},
+                "limit": {"type": "integer", "default": 100, "description": "Return the last N entries."},
+            },
+            "required": [],
+        },
+    ),
+    types.Tool(
+        name="get_request",
+        description="Return one network request's metadata by request_id (from list_requests). No response body, header names only. Inspect-tier.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "request_id": {"type": "string", "description": "The request_id returned by list_requests."},
+            },
+            "required": ["request_id"],
+        },
+    ),
+]
+_DIAGNOSTICS_TOOL_NAMES = frozenset(t.name for t in DIAGNOSTICS_TOOLS)
+
+# Inspect-tier tools: the existing read-only set + diagnostics.
+INSPECT_TOOLS: list[types.Tool] = [*PHASE1_TOOLS, *DIAGNOSTICS_TOOLS]
 INSPECT_TOOL_NAMES = frozenset(t.name for t in INSPECT_TOOLS)
 
 # Navigation-tier tools: page acquisition (navigate) + read condition (wait_for).
@@ -1057,6 +1124,51 @@ class ToolDispatcher:
         result = await self.runtime.current_url()
         return _text_content({"ok": True, **result})
 
+    # --- Diagnostics handlers (inspect-tier; read from sb.diagnostics) ---
+
+    async def _tool_get_console_messages(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        level = arguments.get("level")
+        limit = arguments.get("limit", 100)
+        messages = sb.diagnostics.console_messages(level=level, limit=limit)
+        return _text_content({"ok": True, "messages": messages, "count": len(messages)})
+
+    async def _tool_get_page_errors(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        limit = arguments.get("limit", 100)
+        errors = sb.diagnostics.page_errors(limit=limit)
+        return _text_content({"ok": True, "errors": errors, "count": len(errors)})
+
+    async def _tool_get_network_errors(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        url_filter = arguments.get("url_filter")
+        limit = arguments.get("limit", 100)
+        reqs = sb.diagnostics.requests(url_filter=url_filter, failed_only=True, limit=limit)
+        return _text_content({"ok": True, "requests": reqs, "count": len(reqs)})
+
+    async def _tool_list_requests(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        url_filter = arguments.get("url_filter")
+        resource_type = arguments.get("resource_type")
+        limit = arguments.get("limit", 100)
+        reqs = sb.diagnostics.requests(
+            url_filter=url_filter, resource_type=resource_type, failed_only=False, limit=limit,
+        )
+        return _text_content({"ok": True, "requests": reqs, "count": len(reqs)})
+
+    async def _tool_get_request(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        request_id = arguments.get("request_id")
+        if not isinstance(request_id, str) or not request_id.strip():
+            return _error_content(
+                "'request_id' is required and must be a non-empty string",
+                kind="invalid_arguments",
+            )
+        sb = await self.runtime.get_browser()
+        detail = sb.diagnostics.request_detail(request_id)
+        if detail is None:
+            return _text_content({"ok": False, "reason": "not_found", "request_id": request_id})
+        return _text_content({"ok": True, "request": detail})
+
     async def _tool_observe(self, arguments: dict[str, Any]) -> list[types.TextContent]:
         _require_no_args(arguments)
         sb = await self.runtime.get_browser()