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

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

@@ -5,6 +5,42 @@ 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)
+
+- `reload`, `go_back`, `go_forward` are now navigation-tier MCP tools
+  (default-allowed, not action-budgeted). Each delegates to a new thin facade
+  method that calls the underlying Playwright page method.
+- `go_back` and `go_forward` return a structured error when there is no
+  history entry to navigate to.
+- Default advertised tools: 14 → 17; action mode: 20 → 23.
+- Diagnostics remain session-wide after navigation.
+
 ## [2.6.0] — 2026-06-26
 
 ### Added — MCP switch_tab navigation tool (P3.0A)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superbrowser-sdk
-Version: 2.6.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.6.0 → superbrowser_sdk-2.8.0}/docs/api-reference.md

@@ -101,6 +101,36 @@ if result.ok:
     print(result.data.final_url)  # "https://example.com/"
 ```
 
+#### `reload(*, wait_until="domcontentloaded") → ActionResult`
+
+Reload the current page.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `wait_until` | `str` | `"domcontentloaded"` | Playwright load event to wait for. |
+
+**Returns:** `ActionResult` with `data.url` (the page URL after reload).
+
+#### `go_back(*, wait_until="domcontentloaded") → ActionResult`
+
+Go back one step in browser history.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `wait_until` | `str` | `"domcontentloaded"` | Playwright load event to wait for. |
+
+**Returns:** `ActionResult` with `data.url`, or `ok=False` if there is no previous history entry.
+
+#### `go_forward(*, wait_until="domcontentloaded") → ActionResult`
+
+Go forward one step in browser history.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `wait_until` | `str` | `"domcontentloaded"` | Playwright load event to wait for. |
+
+**Returns:** `ActionResult` with `data.url`, or `ok=False` if there is no next history entry.
+
 ### Interaction
 
 #### `click(target, *, description=None) → ActionResult`

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

@@ -5,9 +5,9 @@ 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 **fourteen tools by default** (six inspect + five
-diagnostics + three navigation) — enough to read a URL end-to-end and explain
-why a read failed. When action mode is enabled, it advertises **six additional
+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 **twelve additional
 action tools**; every action call is checked by
 `MCPSessionPolicy` and `SecurityManager` before it can reach the browser.
 
@@ -31,12 +31,12 @@ python -m patchright install chromium
 Either of:
 
 ```bash
-superbrowser-mcp                       # default: 14 tools (inspect + diagnostics + navigation)
-superbrowser-mcp --allow-actions       # 20 tools (adds the action tier)
+superbrowser-mcp                       # default: 17 tools (inspect + diagnostics + navigation)
+superbrowser-mcp --allow-actions       # 29 tools (adds the action tier)
 python -m super_browser.mcp_server
 ```
 
-Both start a **stdio** server. The default server advertises 14 tools and
+Both start a **stdio** server. The default server advertises 17 tools and
 recognizes (but refuses) action-tool calls with a structured policy refusal.
 
 Action mode can also be enabled via the environment:
@@ -149,6 +149,9 @@ and do **not** require action mode.
 | `navigate` | `url` (required), `wait_until` (optional) | Go to a URL. URL is passed to `SecurityManager` for injection detection, secret redaction, and domain allow/block enforcement. |
 | `wait_for` | exactly one of `selector` / `text` / `url` / `load_state`; `timeout_ms` (optional, 100–60000, default 10000) | Wait for a page condition before the next read. |
 | `switch_tab` | `tab_id` (required, integer) | Switch the active browser tab by ID (from `list_tabs`). Changes the page the agent reads from. Diagnostics remain session-wide after switching; per-tab diagnostics are not supported yet. |
+| `reload` | `wait_until` (optional) | Reload the current page. Returns the URL after reload. |
+| `go_back` | `wait_until` (optional) | Go back one step in browser history. Returns a structured error if there is no previous entry. |
+| `go_forward` | `wait_until` (optional) | Go forward one step in browser history. Returns a structured error if there is no next entry. |
 
 `wait_for` accepts exactly one condition per call (deterministic single
 results; compound waits can be added later as an explicit AND mode).
@@ -189,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
 
@@ -230,7 +241,7 @@ restricts the survivors.
 
 The default server behavior partitions the surface by risk:
 
-- **`list_tools()`** advertises only the Inspect + Navigation tiers (14 tools).
+- **`list_tools()`** advertises only the Inspect + Navigation tiers (17 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.6.0 → superbrowser_sdk-2.8.0}/pyproject.toml

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

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

@@ -240,6 +240,60 @@ class SuperBrowser:
             method=ActionMethod.SELECTOR,
         )
 
+    async def reload(self, *, wait_until: str = "domcontentloaded") -> ActionResult:
+        """Reload the current page."""
+        if not self._page:
+            return action_result(ok=False, error=ActionError(ErrorCategory.BROWSER_CRASH, "Not started"))
+        params = {"wait_until": wait_until}
+        sec = await self._check_facade_security("reload", params, security_level="sensitive")
+        if sec is not None:
+            return sec
+        wait_until = params["wait_until"]
+        start = time.monotonic()
+        await self._page.backend_page.reload(wait_until=wait_until)
+        return timed_action_result(
+            ok=True, start_ns=start, data={"url": self._page.url},
+            method=ActionMethod.SELECTOR,
+        )
+
+    async def go_back(self, *, wait_until: str = "domcontentloaded") -> ActionResult:
+        """Navigate to the previous page in browser history."""
+        if not self._page:
+            return action_result(ok=False, error=ActionError(ErrorCategory.BROWSER_CRASH, "Not started"))
+        params = {"wait_until": wait_until}
+        sec = await self._check_facade_security("go_back", params, security_level="sensitive")
+        if sec is not None:
+            return sec
+        wait_until = params["wait_until"]
+        start = time.monotonic()
+        response = await self._page.backend_page.go_back(wait_until=wait_until)
+        if response is None:
+            return action_result(ok=False, error=ActionError(
+                ErrorCategory.PAGE_ERROR, "No history entry to go back to"))
+        return timed_action_result(
+            ok=True, start_ns=start, data={"url": self._page.url},
+            method=ActionMethod.SELECTOR,
+        )
+
+    async def go_forward(self, *, wait_until: str = "domcontentloaded") -> ActionResult:
+        """Navigate to the next page in browser history."""
+        if not self._page:
+            return action_result(ok=False, error=ActionError(ErrorCategory.BROWSER_CRASH, "Not started"))
+        params = {"wait_until": wait_until}
+        sec = await self._check_facade_security("go_forward", params, security_level="sensitive")
+        if sec is not None:
+            return sec
+        wait_until = params["wait_until"]
+        start = time.monotonic()
+        response = await self._page.backend_page.go_forward(wait_until=wait_until)
+        if response is None:
+            return action_result(ok=False, error=ActionError(
+                ErrorCategory.PAGE_ERROR, "No history entry to go forward to"))
+        return timed_action_result(
+            ok=True, start_ns=start, data={"url": self._page.url},
+            method=ActionMethod.SELECTOR,
+        )
+
     async def click(self, target: str, *, description: Optional[str] = None) -> ActionResult:
         if not self._controller:
             return action_result(ok=False, error=ActionError(ErrorCategory.BROWSER_CRASH, "Browser not started. Call await sb.start() first."))
@@ -949,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.6.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,