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

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

@@ -5,6 +5,30 @@ 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.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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.7.0
+Version: 2.8.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.7.0 → superbrowser_sdk-2.8.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
 ```
 
@@ -192,9 +192,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.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superbrowser-sdk"
-version = "2.7.0"
+version = "2.8.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.8.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.8.0"
 
 __all__ = [
     "SuperBrowser",

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

@@ -1003,7 +1003,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.8.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,

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

@@ -385,7 +385,88 @@ NAVIGATION_TOOL_NAMES = frozenset(t.name for t in NAVIGATION_TOOLS)
 
 # Action-tier tools: page interaction (requires allow_actions).
 # navigate is removed from the action set; scroll/press_key remain.
-ACTION_TOOLS: list[types.Tool] = [*PHASE2B_TOOLS[1:], *PHASE2B_WAVE2_TOOLS]
+# P3.1 adds: hover, select_option, check, uncheck, focus, type_text.
+INTERACTION_TOOLS: list[types.Tool] = [
+    types.Tool(
+        name="hover",
+        description="Hover over an element by selector. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the element to hover."},
+                "description": {"type": "string", "description": "Optional natural-language description for vision-based fallback."},
+            },
+            "required": ["target"],
+        },
+    ),
+    types.Tool(
+        name="select_option",
+        description="Select an option in a <select> element by selector. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the <select> element."},
+                "option": {"type": "string", "description": "The option value to select."},
+                "by": {"type": "string", "enum": ["text", "value", "label"], "default": "text",
+                        "description": "How to match the option."},
+                "description": {"type": "string", "description": "Optional natural-language description."},
+            },
+            "required": ["target", "option"],
+        },
+    ),
+    types.Tool(
+        name="check",
+        description="Check a checkbox or radio button by selector. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the checkbox/radio."},
+                "description": {"type": "string", "description": "Optional natural-language description."},
+            },
+            "required": ["target"],
+        },
+    ),
+    types.Tool(
+        name="uncheck",
+        description="Uncheck a checkbox by selector. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the checkbox."},
+                "description": {"type": "string", "description": "Optional natural-language description."},
+            },
+            "required": ["target"],
+        },
+    ),
+    types.Tool(
+        name="focus",
+        description="Focus an element by selector. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the element to focus."},
+                "description": {"type": "string", "description": "Optional natural-language description."},
+            },
+            "required": ["target"],
+        },
+    ),
+    types.Tool(
+        name="type_text",
+        description="Type text character-by-character (per-keystroke) into an element. Unlike fill, this triggers JS key listeners. Action-tier (requires --allow-actions).",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "CSS selector for the input element."},
+                "text": {"type": "string", "description": "The text to type."},
+                "delay_ms": {"type": "integer", "default": 0, "description": "Delay between keystrokes in ms (0-1000)."},
+                "description": {"type": "string", "description": "Optional natural-language description."},
+            },
+            "required": ["target", "text"],
+        },
+    ),
+]
+
+ACTION_TOOLS: list[types.Tool] = [*PHASE2B_TOOLS[1:], *PHASE2B_WAVE2_TOOLS, *INTERACTION_TOOLS]
 ACTION_TOOL_NAMES = frozenset(t.name for t in ACTION_TOOLS)
 
 # Default advertised surface: Inspect + Navigation.
@@ -890,8 +971,9 @@ class ToolDispatcher:
         """Action-tier dispatch: validate → action gate → authorize → handler.
 
         Authorization happens before ANY facade/browser call. If denied, the
-        facade is never touched. All 6 action tools (scroll, press_key, click,
-        fill, open_tab, close_tab) have real handlers that call the facade
+        facade is never touched. All 12 action tools (scroll, press_key, click,
+        fill, open_tab, close_tab, hover, select_option, check, uncheck, focus,
+        type_text) have real handlers that call the facade/controller
         after the authorizer approves.
         """
         # 1. Validate args before authorization (invalid args must not consume
@@ -1075,6 +1157,51 @@ class ToolDispatcher:
                     "'tab_id' is required and must be a non-negative integer",
                     kind="invalid_arguments",
                 )
+        elif name in ("hover", "check", "uncheck", "focus"):
+            target = arguments.get("target")
+            if not isinstance(target, str) or not target.strip():
+                return _error_content(
+                    "'target' is required and must be a non-empty string",
+                    kind="invalid_arguments",
+                )
+        elif name == "select_option":
+            target = arguments.get("target")
+            if not isinstance(target, str) or not target.strip():
+                return _error_content(
+                    "'target' is required and must be a non-empty string",
+                    kind="invalid_arguments",
+                )
+            option = arguments.get("option")
+            if not isinstance(option, str) or not option.strip():
+                return _error_content(
+                    "'option' is required and must be a non-empty string",
+                    kind="invalid_arguments",
+                )
+            by = arguments.get("by", "text")
+            if by not in ("text", "value", "label"):
+                return _error_content(
+                    "'by' must be one of: text, value, label",
+                    kind="invalid_arguments",
+                )
+        elif name == "type_text":
+            target = arguments.get("target")
+            if not isinstance(target, str) or not target.strip():
+                return _error_content(
+                    "'target' is required and must be a non-empty string",
+                    kind="invalid_arguments",
+                )
+            text = arguments.get("text")
+            if not isinstance(text, str):
+                return _error_content(
+                    "'text' is required and must be a string",
+                    kind="invalid_arguments",
+                )
+            delay_ms = arguments.get("delay_ms", 0)
+            if not isinstance(delay_ms, int) or isinstance(delay_ms, bool) or delay_ms < 0 or delay_ms > 1000:
+                return _error_content(
+                    "'delay_ms' must be an integer between 0 and 1000",
+                    kind="invalid_arguments",
+                )
         return None
 
     @staticmethod
@@ -1214,6 +1341,64 @@ class ToolDispatcher:
         ar = await sb.close_tab(arguments["tab_id"])
         return _text_content(_serialize_action_result(ar))
 
+    # --- P3.1 interaction handlers (action-tier; delegate to controller) ---
+
+    async def _tool_hover(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.hover(arguments["target"], description=arguments.get("description"))
+        return _text_content(_serialize_action_result(ar))
+
+    async def _tool_select_option(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.select(
+            arguments["target"], arguments["option"],
+            by=arguments.get("by", "text"),
+            description=arguments.get("description"),
+        )
+        return _text_content(_serialize_action_result(ar))
+
+    async def _tool_check(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.check(arguments["target"], description=arguments.get("description"))
+        return _text_content(_serialize_action_result(ar))
+
+    async def _tool_uncheck(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.uncheck(arguments["target"], description=arguments.get("description"))
+        return _text_content(_serialize_action_result(ar))
+
+    async def _tool_focus(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.focus(arguments["target"], description=arguments.get("description"))
+        return _text_content(_serialize_action_result(ar))
+
+    async def _tool_type_text(self, arguments: dict[str, Any]) -> list[types.TextContent]:
+        sb = await self.runtime.get_browser()
+        controller = getattr(sb, "_controller", None)
+        if controller is None:
+            return _error_content("browser has no active controller", kind="error")
+        ar = await controller.type_text(
+            arguments["target"], arguments["text"],
+            delay=arguments.get("delay_ms", 0),
+            description=arguments.get("description"),
+        )
+        return _text_content(_serialize_action_result(ar))
+
     # --- read-only tools (none of these lazy-start except where noted) ---
 
     async def _tool_browser_status(self, arguments: dict[str, Any]) -> list[types.TextContent]:

{superbrowser_sdk-2.7.0 → superbrowser_sdk-2.8.0}/tests/test_agent/test_controller_rebinding.py

@@ -156,8 +156,9 @@ class TestRegistryIntegrity:
         browser = _make_browser_with_mocks()
         browser._register_builtin_tools()
 
-        # 7 controller + navigate + extract + observe = 10
-        assert browser._registry.tool_count == 10
+        # 11 controller (7 original + check/uncheck/focus/type_text)
+        # + navigate + extract + observe = 14
+        assert browser._registry.tool_count == 14
 
 
 # ---------------------------------------------------------------------------

{superbrowser_sdk-2.7.0 → superbrowser_sdk-2.8.0}/tests/test_mcp_diagnostics.py

@@ -80,11 +80,11 @@ class TestDiagnosticsAdvertisement:
                      "list_requests", "get_request"):
             assert diag in names
 
-    def test_action_mode_advertises_23_tools(self):
+    def test_action_mode_advertises_29_tools(self):
         from super_browser.mcp_server import MCPSessionPolicy, _tools_for_policy
 
         names = {t.name for t in _tools_for_policy(MCPSessionPolicy(allow_actions=True))}
-        assert len(names) == 23
+        assert len(names) == 29
 
     def test_diagnostics_are_inspect_tier(self):
         """Diagnostics tools are in INSPECT_TOOL_NAMES (no action gate)."""