superbrowser-sdk 2.8.0__tar.gz → 2.9.0__tar.gz

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.9.0] — 2026-06-27
+
+### Added — MCP observe actionable targets
+
+`observe` now returns a `targets` array of actionable element references
+extracted from the accessibility snapshot. Each target includes:
+
+- `target` — a ref string (e.g. `@e0`) usable as the `target` argument for
+  coordinate-tier action tools: `click`, `fill`, `type_text`, `hover`,
+  `select_option`. Checkbox/radio targets map to `click` (toggle-like) because
+  `check`/`uncheck` are selector-tier only and cannot resolve `@refs`.
+- `role` — the AX role (button, textbox, checkbox, combobox, link, etc.)
+- `name` — the accessible name (subject to inspect-output redaction)
+- `action_hint` — recommended action for the role (`click`, `fill`,
+  select_option)
+
+Targets are capped at 50 interactive, non-disabled elements.
+`targets_truncated` indicates when more exist. This closes the gap where
+agents had to guess CSS selectors — they can now go `observe → action`
+deterministically using the refs returned by `observe`.
+
+### Documentation — MCP tool metadata design note (P4)
+
+Added `docs/design/mcp_tool_metadata.md` — a design note analyzing whether
+MCP tool schemas, tiers, validation, and docs should be unified onto the
+existing `ToolDefinition` registry. **Decision: defer full unification.** The
+current `ToolDefinition` cannot express MCP-specific metadata (tiers, enums,
+ranges, validation hooks, bool-as-int rejection) without lossy flattening. Keep
+`mcp_server.py` as the MCP source of truth until tool count or a production
+mismatch justifies change. Trigger conditions and three future options
+documented.
+
 ## [2.8.0] — 2026-06-26
 
 ### Added — MCP interaction tools (P3.1)

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.8.0
+Version: 2.9.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.9.0/docs/design/mcp_tool_metadata.md

@@ -0,0 +1,199 @@
+# Design Note: MCP Tool Metadata Unification
+
+> **Status:** Design note. No implementation.
+> **Decision:** Defer full unification. Document the metadata contract; keep
+> `mcp_server.py` as the MCP source of truth until pressure justifies change.
+> **Date:** 2026-06-26
+
+## Core question
+
+Should Super-Browser extend `ToolDefinition` to become the single source of
+truth for MCP schemas, tiers, validation, and docs — or should MCP remain
+hand-curated until there is stronger pressure?
+
+## Current state (v2.8.0)
+
+The MCP server advertises **29 tools** in action mode (17 default). Tool
+metadata is maintained in three parallel places:
+
+```text
+1. ToolRegistry / ToolDefinition / ToolParameter  (agent-loop path)
+   - src/super_browser/agent/registry.py
+   - Typed specs, handlers, JSON schemas, toolsets, security_level
+   - Used by AgentLoop for the embedded act() path
+
+2. MCP types.Tool definitions + _tool_* handlers   (MCP path)
+   - src/super_browser/mcp_server.py
+   - Hand-maintained lists: PHASE1_TOOLS, NAVIGATION_AUX_TOOLS,
+     DIAGNOSTICS_TOOLS, INTERACTION_TOOLS, PHASE2B_TOOLS, PHASE2B_WAVE2_TOOLS
+   - Handlers wired by name-string convention: getattr(self, f"_tool_{name}")
+
+3. MCP tier names + validation + authorization path   (MCP path)
+   - INSPECT_TOOL_NAMES, NAVIGATION_TOOL_NAMES, ACTION_TOOL_NAMES frozensets
+   - Tool-tier list membership determines advertised/default/action behavior
+   - _validate_navigation_args / _validate_action_args (hand-written Python)
+   - MCPAuthorizer / SecurityManager path for action authorization
+```
+
+These three sources are synchronized manually. Tests assert advertised counts
+and tier membership, but there is no compile-time guarantee they agree.
+
+## Problem
+
+Duplication is growing. Each new MCP tool requires:
+
+- A `types.Tool` definition (schema, description)
+- A `_tool_*` handler method
+- An entry in the right `*_TOOLS` list (which determines tier membership)
+- An entry in `_validate_action_args` or `_validate_navigation_args` (hand-written validation)
+- An entry in the `ACTION_TOOL_NAMES` / `NAVIGATION_TOOL_NAMES` frozenset
+- Updates to count assertions across 4+ test files
+- Updates to `docs/mcp.md` (tool table + counts)
+- Updates to `CHANGELOG.md`
+
+That is 8 touch points per tool. With 29 tools now and P5/P6 work still ahead,
+the maintenance surface is real.
+
+## Why current ToolDefinition cannot serve as MCP source of truth
+
+Fact-checked against `src/super_browser/agent/registry.py` (lines 17-63):
+
+### 1. Schema expressiveness is too flat
+
+`ToolDefinition.to_json_schema()` produces a flat type system:
+`str→string, int→integer, float→number, bool→boolean`. It cannot express:
+
+- **Enums** — used heavily: `scroll.direction`, `wait_for.load_state`,
+  `select_option.by`, `reload.wait_until`
+- **Defaults** — MCP uses `"default": false`, `"default": 10000`;
+  `ToolParameter` stores a default but `to_json_schema()` never emits it
+- **Numeric ranges** — `wait_for.timeout_ms` (100–60000),
+  `type_text.delay_ms` (0–1000)
+- **Bool-as-int rejection** — MCP validation explicitly rejects `bool` where
+  `int` is expected; `ToolParameter` has no concept of this
+- **Nested objects / arrays** — MCP `inputSchema.properties` can nest
+
+### 2. Tier metadata is a different axis
+
+`ToolDefinition.security_level` takes values `safe`/`sensitive`/`dangerous`
+(a risk scale). MCP tiers are `inspect`/`navigation`/`action` (permission
+buckets, assigned by list membership). There is no automatic mapping:
+
+- `navigate` is `sensitive` but navigation-tier (default-allowed)
+- `scroll` is `safe` but action-tier (gated)
+- `screenshot` is `sensitive` but inspect-tier (no security check)
+
+`ToolDefinition` has no `tier` field. Its `toolsets` field is a grouping
+concept unrelated to MCP permission tiers.
+
+### 3. Validation hooks are hand-written Python
+
+MCP argument validation (`_validate_navigation_args`,
+`_validate_action_args`) contains logic that no schema can express:
+non-empty string checks, bool-as-int rejection, range bounds, exactly-one-
+condition constraints (`wait_for`). This logic cannot be generated from any
+data structure — it requires executable validation hooks.
+
+### 4. Handler dispatch is name-string convention
+
+MCP dispatches via `getattr(self, f"_tool_{name}")`. This is a runtime
+convention with no type safety. `ToolDefinition.handler` is a callable
+reference, but the MCP path doesn't use it — it uses its own dispatch table.
+
+## What MCP metadata would need (the full contract)
+
+```text
+Per-tool metadata required:
+  - tool name (str)
+  - tier: inspect | navigation | action | high_risk
+  - advertised_by_default: bool (derived from tier)
+  - security_level: safe | sensitive | dangerous
+  - action_budget: consumes | does_not_consume
+  - input schema:
+      - parameter name
+      - type (str, int, bool, str-enum, ...)
+      - required: bool
+      - default value
+      - enum values (where applicable)
+      - numeric range (min, max)
+      - reject_bool_as_int: bool
+  - validation hook: callable(args) -> error | None
+  - handler binding: callable or name convention
+  - description (for MCP tool listing)
+  - redaction policy: which output fields to redact, text vs URL
+```
+
+This is substantially richer than what `ToolDefinition` carries today.
+
+## Decision: defer full unification
+
+```text
+Do not implement automatic MCP schema generation now.
+
+Reasons:
+  1. Current ToolDefinition cannot express MCP metadata without lossy flattening.
+  2. Forcing MCP schemas through it would damage validation, enums, ranges.
+  3. The maintenance pain (8 touch points per tool) is real but manageable
+     at 29 tools.
+  4. A partial generator that can't express tier/validation/security
+     faithfully is worse than hand-curated — it would create a false sense
+     of single-source-of-truth while silently diverging.
+```
+
+## What to do instead
+
+### Now (no code change)
+
+Keep `mcp_server.py` as the MCP source of truth. Document this design note
+as the contract for what a future unification would require.
+
+### Trigger conditions for revisiting
+
+Re-evaluate when any of these become true:
+
+```text
+1. MCP tool count exceeds ~40 (currently 29)
+2. A tool is added with the wrong tier and isn't caught until production
+3. Validation logic is duplicated between MCP and SDK paths
+4. A third consumer (e.g. external-agent API) needs the same metadata
+```
+
+### Future options (when triggered)
+
+```text
+Option A — MCPToolDefinition wrapper:
+  A new dataclass that wraps ToolDefinition and adds MCP-specific fields
+  (tier, advertised_by_default, validation_hook, redaction_policy).
+  Pro: doesn't pollute the SDK registry.
+  Con: still two definitions per tool.
+
+Option B — Extend ToolDefinition:
+  Add tier, enum_constraints, defaults, ranges, validation_hook fields.
+  Pro: true single source of truth.
+  Con: makes the SDK registry awkward for non-MCP consumers; schema migration.
+
+Option C — Generate MCP from a new tool-spec module:
+  A dedicated mcp_tools.py that defines tool specs with full metadata,
+  generates types.Tool objects, validation functions, and docs entries.
+  Pro: MCP owns its own metadata; no SDK pollution.
+  Con: doesn't unify with the SDK registry (but that may be acceptable).
+```
+
+The design note recommends **Option C** if/when triggered — it keeps MCP
+and SDK concerns separate while reducing MCP's internal duplication.
+
+## Comparison to existing inspect-redaction design
+
+The P2.3 redaction design (`docs/design/inspect_redaction.md`) took a
+similar approach: document the boundary, reuse existing machinery, defer
+per-tool overrides. This note follows the same pattern for tool metadata.
+
+## Summary
+
+```text
+Problem:   8 touch points per MCP tool; metadata in 3+ places.
+Root cause: ToolDefinition is too flat for MCP's needs.
+Decision:  Defer unification. Keep hand-curated MCP.
+Trigger:   ~40 tools, or a tier-mismatch production incident.
+Preferred future path: Option C (dedicated MCP tool-spec module).
+```

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/docs/mcp.md

@@ -115,7 +115,7 @@ advertised; the third requires action mode; the fourth is not implemented.
 |---|---|---|---|
 | `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 |
+| `observe` | none | Page state: URL, title, interactive/total element counts, and a `targets` array of actionable element references (capped at 50). Each target includes `target` (a ref like `@e0`, usable as the `target` argument for coordinate-tier action tools: `click`, `fill`, `type_text`, `hover`, `select_option`), `role`, `name`, and `action_hint`. | 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 |
@@ -162,7 +162,17 @@ results; compound waits can be added later as an explicit AND mode).
 navigate → wait_for → observe / extract_text / screenshot
 ```
 
-This is the default-mode loop an agent uses to read a page.
+This is the default-mode loop an agent uses to read a page. `observe` returns
+actionable targets (`@e0` refs) that can be passed directly as the `target`
+argument to coordinate-tier action tools (`click`, `fill`, `type_text`,
+`hover`, `select_option`):
+
+```text
+navigate → wait_for → observe → click(target="@e0")
+```
+
+The `targets` array is capped at 50; `targets_truncated` indicates whether more
+interactive elements exist. Target names are subject to inspect-output redaction.
 
 #### Debugging workflow
 

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superbrowser-sdk"
-version = "2.8.0"
+version = "2.9.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.8.0 → superbrowser_sdk-2.9.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.8.0"
+__version__ = "2.9.0"
 
 __all__ = [
     "SuperBrowser",

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/src/super_browser/agent/facade.py

@@ -482,10 +482,49 @@ class SuperBrowser:
         snap = await self._controller.capture_ax_snapshot()
         interactive_count = sum(1 for n in snap.nodes.values() if n.is_interactive)
 
+        # Build actionable targets from the AX snapshot.
+        # The ref (e.g. "@e0") is directly usable as a `target` argument for
+        # click/fill/type_text/etc. — the controller's coordinate tier resolves
+        # @refs to element coordinates via the snapshot.
+        _ROLE_ACTION_MAP = {
+            "button": "click", "link": "click", "menuitem": "click",
+            "tab": "click", "treeitem": "click", "option": "click",
+            "textbox": "fill", "searchbox": "fill", "spinbutton": "fill",
+            "combobox": "select_option", "checkbox": "click", "radio": "click",
+            "slider": "fill", "switch": "click",
+        }
+
+        # Only include nodes whose center is resolvable (bounds present),
+        # because @refs are resolved via the coordinate tier. Nodes without
+        # bounds cannot be acted on and would produce a confusing target.
+        # Checkbox/radio map to "click" (not "check") because check/uncheck
+        # are selector-tier only and cannot resolve @refs.
+        all_interactive = [
+            n for n in snap.nodes.values()
+            if n.is_interactive and not n.disabled and n.center is not None
+        ]
+        _MAX_TARGETS = 50
+        capped = all_interactive[:_MAX_TARGETS]
+        targets = [
+            {
+                "target": n.ref if n.ref.startswith("@") else f"@{n.ref}",
+                "role": n.role,
+                "name": n.name,
+                "action_hint": _ROLE_ACTION_MAP.get(n.role, "click"),
+            }
+            for n in capped
+        ]
+
         return timed_action_result(
             ok=True,
             start_ns=start,
-            data={"url": url, "title": title, "interactive_elements": interactive_count, "total_elements": len(snap.nodes)},
+            data={
+                "url": url, "title": title,
+                "interactive_elements": interactive_count,
+                "total_elements": len(snap.nodes),
+                "targets": targets,
+                "targets_truncated": len(all_interactive) > _MAX_TARGETS,
+            },
         )
 
     # -- Tab helper (CHK-07) --

{superbrowser_sdk-2.8.0 → superbrowser_sdk-2.9.0}/src/super_browser/mcp_server.py

@@ -1489,9 +1489,17 @@ class ToolDispatcher:
             _redact_field(payload, field, is_url=True)
 
         # Redact list-of-dicts entries.
+        # Supports dotted paths like "data.targets" for lists nested under a dict.
         if list_keys:
             for list_key, inner_fields in list_keys.items():
-                items = payload.get(list_key)
+                # Navigate dotted path (e.g. "data.targets" → payload["data"]["targets"])
+                items = payload
+                for part in list_key.split("."):
+                    if isinstance(items, dict):
+                        items = items.get(part)
+                    else:
+                        items = None
+                        break
                 if not isinstance(items, list):
                     continue
                 for item in items:
@@ -1579,10 +1587,13 @@ class ToolDispatcher:
         sb = await self.runtime.get_browser()
         ar = await sb.observe()
         payload = _serialize_action_result(ar)
-        # observe nests URL/title under data dict
-        nested = {"data": ("url", "title")} if isinstance(payload.get("data"), dict) else None
+        # observe nests URL/title/targets under data dict.
+        # Redact url/title (nested fields) and target names (nested list-of-dicts).
+        data = payload.get("data")
+        nested = {"data": ("url", "title")} if isinstance(data, dict) else None
         return _text_content(self._redact_inspect_output(
             payload, nested_keys=nested,
+            list_keys={"data.targets": ("name",)} if isinstance(data, dict) and isinstance(data.get("targets"), list) else None,
         ))
 
     async def _tool_extract_text(self, arguments: dict[str, Any]) -> list[types.TextContent]: