superbrowser-sdk 2.0.0__py3-none-any.whl

super_browser/__init__.py

@@ -0,0 +1,17 @@
+"""Super Browser — Comprehensive browser control for AI agents."""
+
+from super_browser.agent.facade import SuperBrowser as SuperBrowser  # noqa: F401
+from super_browser.agent.llm import create_llm as create_llm  # noqa: F401
+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.0.0"
+
+__all__ = [
+    "SuperBrowser",
+    "Config",
+    "ActionResult",
+    "create_llm",
+    "StreamEvent",
+]

super_browser/agent/__init__.py

@@ -0,0 +1,37 @@
+"""GAP-07: Agent Orchestration & Facade."""
+
+from super_browser.agent.delegator import SubagentDelegator
+from super_browser.agent.facade import SuperBrowser
+from super_browser.agent.llm import LLMClient, create_llm
+from super_browser.agent.loop import AgentLoop
+from super_browser.agent.loop_detector import ActionLoopDetector
+from super_browser.agent.plugins import PluginRegistry, PluginSlot
+from super_browser.agent.registry import ToolDefinition, ToolParameter, ToolRegistry, Toolset
+from super_browser.agent.types import (
+    ChildTask,
+    DelegationResult,
+    DelegationStatus,
+    LoopNudge,
+    LoopResult,
+    PlanItem,
+    PlanStatus,
+    PluginSlotKey,
+    StepEvent,
+    StepResult,
+)
+from super_browser.config import AgentConfig
+
+__all__ = [
+    "AgentConfig",
+    "ChildTask", "DelegationResult", "DelegationStatus",
+    "LoopNudge", "LoopResult",
+    "PlanItem", "PlanStatus", "PluginSlotKey",
+    "StepEvent", "StepResult",
+    "ActionLoopDetector",
+    "ToolDefinition", "ToolParameter", "ToolRegistry", "Toolset",
+    "AgentLoop",
+    "SuperBrowser",
+    "SubagentDelegator",
+    "PluginRegistry", "PluginSlot",
+    "LLMClient", "create_llm",
+]

super_browser/agent/config.py

@@ -0,0 +1,18 @@
+"""Agent configuration types.
+
+``SuperBrowserConfig`` was removed in v2.0. Its fields are now flattened
+onto :class:`AgentConfig` in ``config.py``.
+
+This module provides ``AgentConfig`` via lazy import to avoid circular
+dependency issues.
+"""
+
+from __future__ import annotations
+
+
+def __getattr__(name: str):
+    """Lazy re-export for backward-compatible import path."""
+    if name == "AgentConfig":
+        from super_browser.config import AgentConfig
+        return AgentConfig
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

super_browser/agent/debug.py

@@ -0,0 +1,201 @@
+"""Interactive debug session for agent failures.
+
+When debug mode is enabled, the agent can pause on failure to allow
+interactive inspection of browser state, capture error artifacts
+(screenshot + DOM snapshot), and resume or abort execution.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from super_browser.agent.types import DebugConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DebugSnapshot:
+    """Captured debug state at point of failure."""
+
+    url: str = ""
+    title: str = ""
+    screenshot_path: str = ""
+    dom_path: str = ""
+    visible_text_summary: str = ""
+    error_message: str = ""
+    timestamp: float = field(default_factory=time.time)
+
+
+class InteractiveDebugSession:
+    """Manages interactive debugging when an agent step fails.
+
+    In interactive mode (default), the session pauses and waits for user
+    input before continuing. In non-interactive environments the session
+    logs state and auto-continues.
+    """
+
+    def __init__(
+        self,
+        config: DebugConfig,
+        *,
+        interactive: bool = True,
+        input_reader: Optional[Any] = None,
+        output_writer: Optional[Any] = None,
+    ) -> None:
+        self._config = config
+        self._interactive = interactive
+        self._input_reader = input_reader
+        self._output_writer = output_writer
+        self._snapshots: list[DebugSnapshot] = []
+
+    # -- Public API --
+
+    async def pause_on_failure(
+        self,
+        page: Any,
+        error: Exception,
+        *,
+        step_number: int = 0,
+    ) -> str:
+        """Pause execution on failure for inspection.
+
+        Returns user command: ``"continue"``, ``"abort"``, or ``"inspect"``.
+        In non-interactive mode, always returns ``"continue"``.
+        """
+        snapshot = await self._capture_snapshot(page, error)
+        self._snapshots.append(snapshot)
+
+        logger.warning(
+            "Debug pause on step %d: %s  url=%s",
+            step_number,
+            str(error),
+            snapshot.url,
+        )
+
+        if not self._interactive:
+            return "continue"
+
+        # Interactive: prompt user
+        self._write(f"\n🔴 STEP {step_number} FAILED: {error}")
+        self._write(f"   URL: {snapshot.url}")
+        self._write("   Commands: [c]ontinue, [a]bort, [i]nspect → ")
+
+        command = await self._read_input()
+        if command is None:
+            return "continue"
+
+        cmd = command.strip().lower()
+        if cmd in ("a", "abort"):
+            return "abort"
+        if cmd in ("i", "inspect"):
+            state = await self.inspect_state(page)
+            self._write(f"   Title: {state['title']}")
+            self._write(f"   URL: {state['url']}")
+            self._write(f"   Visible text (first 200 chars): {state['visible_text_summary'][:200]}")
+            return "continue"
+        return "continue"
+
+    async def capture_error_artifacts(
+        self,
+        page: Any,
+        error: Exception,
+        config: DebugConfig,
+    ) -> DebugSnapshot:
+        """Capture screenshot and optional DOM snapshot for an error."""
+        snapshot = await self._capture_snapshot(page, error)
+
+        screenshot_dir = Path(config.screenshot_dir)
+        screenshot_dir.mkdir(parents=True, exist_ok=True)
+
+        ts = int(time.time() * 1000)
+
+        # Screenshot
+        try:
+            screenshot_path = screenshot_dir / f"error_{ts}.png"
+            if page and hasattr(page, "screenshot"):
+                await page.screenshot(path=str(screenshot_path))
+                snapshot.screenshot_path = str(screenshot_path)
+                logger.info("Debug screenshot saved: %s", screenshot_path)
+        except Exception as exc:
+            logger.warning("Failed to capture screenshot: %s", exc)
+
+        # DOM snapshot
+        if config.capture_dom:
+            try:
+                dom_path = screenshot_dir / f"error_{ts}.dom.html"
+                if page and hasattr(page, "content"):
+                    content = await page.content()
+                    dom_path.write_text(content, encoding="utf-8")
+                    snapshot.dom_path = str(dom_path)
+                    logger.info("Debug DOM snapshot saved: %s", dom_path)
+            except Exception as exc:
+                logger.warning("Failed to capture DOM snapshot: %s", exc)
+
+        self._snapshots.append(snapshot)
+        return snapshot
+
+    async def inspect_state(self, page: Any) -> dict[str, str]:
+        """Return current page state: URL, title, visible text summary."""
+        state: dict[str, str] = {
+            "url": "",
+            "title": "",
+            "visible_text_summary": "",
+        }
+        if page is None:
+            return state
+        try:
+            state["url"] = page.url if hasattr(page, "url") else ""
+        except Exception:
+            pass
+        try:
+            if hasattr(page, "title"):
+                title_result = page.title()
+                if asyncio.iscoroutine(title_result):
+                    title_result = await title_result
+                state["title"] = title_result
+        except Exception:
+            pass
+        try:
+            if hasattr(page, "evaluate"):
+                text = await page.evaluate("() => document.body?.innerText?.substring(0, 500) || ''")
+                state["visible_text_summary"] = text or ""
+        except Exception:
+            pass
+        return state
+
+    @property
+    def snapshots(self) -> list[DebugSnapshot]:
+        return list(self._snapshots)
+
+    # -- Internals --
+
+    async def _capture_snapshot(self, page: Any, error: Exception) -> DebugSnapshot:
+        state = await self.inspect_state(page)
+        return DebugSnapshot(
+            url=state["url"],
+            title=state["title"],
+            visible_text_summary=state["visible_text_summary"],
+            error_message=str(error),
+            timestamp=time.time(),
+        )
+
+    def _write(self, message: str) -> None:
+        if self._output_writer:
+            self._output_writer(message)
+        else:
+            # Default: just log
+            logger.info("Debug: %s", message)
+
+    async def _read_input(self) -> Optional[str]:
+        if self._input_reader:
+            result = self._input_reader()
+            if asyncio.iscoroutine(result):
+                return await result
+            return result
+        return None

super_browser/agent/delegator.py

@@ -0,0 +1,145 @@
+"""SubagentDelegator — parallel child agents with isolated browser contexts."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Optional
+
+from super_browser.agent.loop import AgentLoop
+from super_browser.agent.registry import ToolRegistry
+from super_browser.agent.types import ChildTask, DelegationResult, DelegationStatus
+
+logger = logging.getLogger(__name__)
+
+
+class SubagentDelegator:
+
+    def __init__(
+        self,
+        browser_session: Any,
+        registry: ToolRegistry,
+        llm_client: Any,
+        *,
+        max_concurrency: int = 4,
+        max_steps_per_child: int = 50,
+        recovery_coordinator: Optional[Any] = None,
+        budget_client: Optional[Any] = None,
+        flow_logger: Optional[Any] = None,
+        security_manager: Optional[Any] = None,
+        stealth_manager: Optional[Any] = None,
+    ) -> None:
+        self._session = browser_session
+        self._registry = registry
+        self._llm = llm_client
+        self._max_concurrency = max_concurrency
+        self._max_steps = max_steps_per_child
+        self._recovery_coordinator = recovery_coordinator
+        self._budget_client = budget_client
+        self._flow_logger = flow_logger
+        self._security_manager = security_manager
+        self._stealth_manager = stealth_manager
+        self._open_tabs = 0
+
+    @property
+    def open_tabs(self) -> int:
+        """Current number of open child tabs (read-only)."""
+        return self._open_tabs
+
+    async def delegate(
+        self,
+        tasks: list[str],
+        *,
+        max_concurrency: Optional[int] = None,
+        abort_signal: Optional[asyncio.Event] = None,
+    ) -> DelegationResult:
+        start = time.monotonic()
+        concurrency = max_concurrency or self._max_concurrency
+        semaphore = asyncio.Semaphore(concurrency)
+
+        children = [ChildTask(instruction=instr) for instr in tasks]
+
+        async def _run_with_semaphore(task: ChildTask) -> ChildTask:
+            async with semaphore:
+                if abort_signal and abort_signal.is_set():
+                    task.status = DelegationStatus.CANCELLED
+                    return task
+                return await self._run_child(task)
+
+        results = await asyncio.gather(
+            *[_run_with_semaphore(c) for c in children],
+            return_exceptions=True,
+        )
+
+        final_tasks: list[ChildTask] = []
+        for r in results:
+            if isinstance(r, Exception):
+                failed = ChildTask(instruction="error", status=DelegationStatus.FAILED, result=str(r))
+                final_tasks.append(failed)
+            else:
+                final_tasks.append(r)
+
+        duration = (time.monotonic() - start) * 1000
+        completed = sum(1 for t in final_tasks if t.status == DelegationStatus.COMPLETED)
+        failed = sum(1 for t in final_tasks if t.status == DelegationStatus.FAILED)
+        cancelled = sum(1 for t in final_tasks if t.status == DelegationStatus.CANCELLED)
+
+        # Sanity check — should never happen, but catch programming errors.
+        assert self._open_tabs <= concurrency, (
+            f"Tab cap violated: {self._open_tabs} open tabs > {concurrency} max_concurrency"
+        )
+
+        return DelegationResult(
+            tasks=final_tasks,
+            total_duration_ms=duration,
+            completed_count=completed,
+            failed_count=failed,
+            cancelled_count=cancelled,
+        )
+
+    async def _run_child(self, task: ChildTask) -> ChildTask:
+        task.status = DelegationStatus.RUNNING
+        task.started_at = time.monotonic()
+
+        page = None
+        try:
+            self._open_tabs += 1
+            assert self._open_tabs <= self._max_concurrency, (
+                f"Hard tab cap violated: {self._open_tabs} > {self._max_concurrency}"
+            )
+            page = await self._session.new_page()
+
+            from super_browser.interaction.controller import MultimodalController
+            controller = MultimodalController(page, page.cdp)
+
+            child_loop = AgentLoop(
+                controller=controller,
+                registry=self._registry,
+                llm_client=self._llm,
+                max_steps=self._max_steps,
+                recovery_coordinator=self._recovery_coordinator,
+                budget_client=self._budget_client,
+                flow_logger=self._flow_logger,
+                security_manager=self._security_manager,
+                stealth_manager=self._stealth_manager,
+            )
+            loop_result = await child_loop.run(task.instruction)
+
+            task.result = loop_result
+            task.status = DelegationStatus.COMPLETED
+
+        except Exception as exc:
+            logger.warning("Child task %s failed: %s", task.task_id[:8], exc)
+            task.result = str(exc)
+            task.status = DelegationStatus.FAILED
+        finally:
+            if page:
+                try:
+                    await page.close()
+                except Exception:
+                    pass
+            self._open_tabs -= 1
+
+        task.completed_at = time.monotonic()
+        return task