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

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

@@ -5,6 +5,62 @@ 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)
+
+Six new action-tier MCP tools for form and element interaction:
+
+- `hover` — hover over an element (controller-backed, selector/coordinate/vision cascade)
+- `select_option` — select an option in a `<select>` element (maps to controller `select`, supports `by`: text/value/label)
+- `check` — check a checkbox or radio button (new controller method + cascade)
+- `uncheck` — uncheck a checkbox (new controller method + cascade)
+- `focus` — focus an element (new controller method, selector-tier only)
+- `type_text` — type text character-by-character (per-keystroke), triggering JS key listeners. Unlike `fill` which sets the value atomically. Supports `delay_ms` (0–1000). (new controller method)
+
+All six are action-tier: require `--allow-actions`, consume the action budget,
+pass through `SecurityManager` + audit, and are absent from the default
+advertised surface.
+
+- Default advertised tools: remains 17
+- Action-mode advertised tools: 23 → 29
+
+New controller primitives (`check`, `uncheck`, `focus`, `type_text`) added to
+`MultimodalController` with `@agent_action` decorators and `FrameInteractionTarget`
+adapters. Registered in the facade's builtin-tool loop.
+
 ## [2.7.0] — 2026-06-26
 
 ### Added — MCP reload and history navigation tools (P3.0B)

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

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

@@ -7,7 +7,7 @@ scripting Python.
 
 The stdio server advertises **seventeen tools by default** (six inspect + five
 diagnostics + six navigation) — enough to read a URL end-to-end and explain
-why a read failed. When action mode is enabled, it advertises **six additional
+why a read failed. When action mode is enabled, it advertises **twelve additional
 action tools**; every action call is checked by
 `MCPSessionPolicy` and `SecurityManager` before it can reach the browser.
 
@@ -32,7 +32,7 @@ Either of:
 
 ```bash
 superbrowser-mcp                       # default: 17 tools (inspect + diagnostics + navigation)
-superbrowser-mcp --allow-actions       # 23 tools (adds the action tier)
+superbrowser-mcp --allow-actions       # 29 tools (adds the action tier)
 python -m super_browser.mcp_server
 ```
 
@@ -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
 
@@ -192,9 +202,17 @@ entry, no side effects.
 | `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 |
+| `hover` | `target` (required), `description` (optional) | SENSITIVE |
+| `select_option` | `target` (required), `option` (required), `by` (optional: text/value/label), `description` (optional) | SENSITIVE |
+| `check` | `target` (required), `description` (optional) | SENSITIVE |
+| `uncheck` | `target` (required), `description` (optional) | SENSITIVE |
+| `focus` | `target` (required), `description` (optional) | SENSITIVE |
+| `type_text` | `target` (required), `text` (required), `delay_ms` (optional, 0–1000), `description` (optional) | SENSITIVE |
 
 `fill` sends only the literal value supplied by the caller. It does not
-retrieve, infer, store, or auto-fill credentials.
+retrieve, infer, store, or auto-fill credentials. `type_text` types
+character-by-character (per-keystroke), triggering JS key listeners — unlike
+`fill` which sets the value atomically.
 
 #### Action workflow
 

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

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

{superbrowser_sdk-2.7.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) --
@@ -1003,7 +1042,8 @@ class SuperBrowser:
         # self._controller, the registered tools still route to the current
         # controller. Raw bound methods would capture the old controller
         # instance and act on a stale page after tab switches.
-        for name in ("click", "fill", "select", "hover", "drag", "scroll", "keypress"):
+        for name in ("click", "fill", "select", "hover", "drag", "scroll", "keypress",
+                      "check", "uncheck", "focus", "type_text"):
             method = getattr(self._controller, name, None)
             if method is not None and self._registry.get(name) is None:
                 self._registry.register(self._make_controller_wrapper(name))

{superbrowser_sdk-2.7.0 → superbrowser_sdk-2.9.0}/src/super_browser/interaction/controller.py

@@ -81,6 +81,18 @@ class FrameInteractionTarget:
     async def hover(self, selector: str) -> None:
         await self._frame.locator(selector).hover()
 
+    async def check(self, selector: str) -> None:
+        await self._frame.locator(selector).check()
+
+    async def uncheck(self, selector: str) -> None:
+        await self._frame.locator(selector).uncheck()
+
+    async def focus(self, selector: str) -> None:
+        await self._frame.locator(selector).focus()
+
+    async def type_text(self, selector: str, text: str, *, delay: int = 0) -> None:
+        await self._frame.locator(selector).type(text, delay=delay)
+
     async def drag_and_drop(self, source: str, target: str) -> None:
         src = self._frame.locator(source)
         dst = self._frame.locator(target)
@@ -328,6 +340,108 @@ class MultimodalController:
         result, _ = await self._cascade("hover", target, description, t1, t2, t3)
         return result
 
+    @agent_action(security_level="sensitive")
+    async def check(
+        self,
+        target: str,
+        *,
+        description: Optional[str] = None,
+    ) -> ActionResult:
+        """Check a checkbox or radio button.
+
+        Selector-tier only — coordinate/vision fallbacks would be toggle-like
+        (clicks that can uncheck an already-checked box), violating the
+        idempotent state-enforcing semantics implied by the tool name.
+        """
+
+        async def t1():
+            await self._interaction_target.check(target)
+            return action_result(ok=True, data={"target": target}, method=ActionMethod.SELECTOR)
+
+        result, _ = await self._cascade("check", target, description, t1)
+        return result
+
+    @agent_action(security_level="sensitive")
+    async def uncheck(
+        self,
+        target: str,
+        *,
+        description: Optional[str] = None,
+    ) -> ActionResult:
+        """Uncheck a checkbox.
+
+        Selector-tier only — same rationale as ``check``: coordinate/vision
+        fallbacks would be toggle-like, not state-enforcing.
+        """
+
+        async def t1():
+            await self._interaction_target.uncheck(target)
+            return action_result(ok=True, data={"target": target}, method=ActionMethod.SELECTOR)
+
+        result, _ = await self._cascade("uncheck", target, description, t1)
+        return result
+
+    @agent_action(security_level="sensitive")
+    async def focus(
+        self,
+        target: str,
+        *,
+        description: Optional[str] = None,
+    ) -> ActionResult:
+        """Focus an element."""
+
+        async def t1():
+            await self._interaction_target.focus(target)
+            return action_result(ok=True, data={"target": target}, method=ActionMethod.SELECTOR)
+
+        # Focus has no meaningful coordinate/vision fallback — a click would be
+        # a different action, not a focus. Only selector-tier.
+        result, _ = await self._cascade("focus", target, description, t1)
+        return result
+
+    @agent_action(security_level="sensitive")
+    async def type_text(
+        self,
+        target: str,
+        text: str,
+        *,
+        delay: int = 0,
+        description: Optional[str] = None,
+    ) -> ActionResult:
+        """Type text character-by-character (per-keystroke), unlike fill.
+
+        Triggers JS keydown/keypress/keyup listeners, suitable for autocomplete,
+        masked inputs, and debounce handlers.
+        """
+
+        async def t1():
+            await self._interaction_target.type_text(target, text, delay=delay)
+            return action_result(ok=True, data={"target": target, "text_length": len(text)}, method=ActionMethod.SELECTOR)
+
+        async def t2():
+            coords = await self._resolve_to_coordinates(target)
+            if coords is None:
+                return action_result(ok=False, error=ActionError(ErrorCategory.SELECTOR_NOT_FOUND, f"Cannot resolve '{target}'"))
+            # Click to focus, then type via CDP.
+            await self._cdp.send("Input.dispatchMouseEvent", {
+                "type": "mousePressed", "x": coords[0], "y": coords[1],
+                "button": "left", "clickCount": 1,
+            })
+            await self._cdp.send("Input.dispatchMouseEvent", {
+                "type": "mouseReleased", "x": coords[0], "y": coords[1],
+                "button": "left", "clickCount": 1,
+            })
+            for char in text:
+                await self._cdp.send("Input.dispatchKeyEvent", {
+                    "type": "char", "text": char,
+                })
+                if delay:
+                    await asyncio.sleep(delay / 1000)
+            return action_result(ok=True, data={"target": target, "method": "coordinate"}, method=ActionMethod.COORDINATE)
+
+        result, _ = await self._cascade("type_text", target, description, t1, t2)
+        return result
+
     @agent_action(security_level="dangerous")
     async def drag(
         self,