camel-ai 0.2.72a10__py3-none-any.whl → 0.2.73__py3-none-any.whl

camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit.py

@@ -12,79 +12,25 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
-import base64
-import datetime
-import io
-import json
-import os
-import time
-import urllib.parse
-from functools import wraps
-from typing import Any, Callable, ClassVar, Dict, List, Optional, cast
+from typing import Any, List, Literal, Optional
 
-from camel.logger import get_logger
 from camel.models import BaseModelBackend
 from camel.toolkits.base import BaseToolkit
-from camel.toolkits.function_tool import FunctionTool
-from camel.utils import sanitize_filename
-from camel.utils.commons import dependencies_required
-from camel.utils.tool_result import ToolResult
-
-from .agent import PlaywrightLLMAgent
-from .browser_session import HybridBrowserSession
-from .config_loader import ConfigLoader
-
-logger = get_logger(__name__)
 
 
 class HybridBrowserToolkit(BaseToolkit):
-    r"""A hybrid browser toolkit that combines non-visual, DOM-based browser
-    automation with visual, screenshot-based capabilities.
+    r"""A hybrid browser toolkit that can switch between TypeScript and Python
+    implementations.
 
-    This toolkit exposes a set of actions as CAMEL FunctionTools for agents
-    to interact with web pages. It can operate in headless mode and supports
-    both programmatic control of browser actions (like clicking and typing)
-    and visual analysis of the page layout through screenshots with marked
-    interactive elements.
+    This wrapper allows users to choose between:
+    - 'typescript': WebSocket-based implementation using TypeScript/Node.js
+    - 'python': Pure Python implementation using Playwright directly
     """
 
-    # Default tool list - core browser functionality
-    DEFAULT_TOOLS: ClassVar[List[str]] = [
-        "open_browser",
-        "close_browser",
-        "visit_page",
-        "back",
-        "forward",
-        "click",
-        "type",
-        "switch_tab",
-    ]
-
-    # All available tools
-    ALL_TOOLS: ClassVar[List[str]] = [
-        "open_browser",
-        "close_browser",
-        "visit_page",
-        "back",
-        "forward",
-        "get_page_snapshot",
-        "get_som_screenshot",
-        "get_page_links",
-        "click",
-        "type",
-        "select",
-        "scroll",
-        "enter",
-        "wait_user",
-        "solve_task",
-        "switch_tab",
-        "close_tab",
-        "get_tab_info",
-    ]
-
-    def __init__(
-        self,
+    def __new__(
+        cls,
         *,
+        mode: Literal["typescript", "python"] = "typescript",
         headless: bool = True,
         user_data_dir: Optional[str] = None,
         stealth: bool = False,
@@ -101,1912 +47,131 @@ class HybridBrowserToolkit(BaseToolkit):
         screenshot_timeout: Optional[int] = None,
         page_stability_timeout: Optional[int] = None,
         dom_content_loaded_timeout: Optional[int] = None,
-    ) -> None:
-        r"""Initialize the HybridBrowserToolkit.
+        viewport_limit: bool = False,
+        connect_over_cdp: bool = False,
+        cdp_url: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        r"""Create a HybridBrowserToolkit instance with the specified mode.
 
         Args:
-            headless (bool): Whether to run the browser in headless mode.
-                Defaults to `True`.
-            user_data_dir (Optional[str]): Path to a directory for storing
-                browser data like cookies and local storage. Useful for
-                maintaining sessions across runs. Defaults to `None` (a
-                temporary directory is used).
-            stealth (bool): Whether to run the browser in stealth mode to avoid
-                bot detection. When enabled, hides WebDriver characteristics,
-                spoofs navigator properties, and implements various
-                anti-detection
-                measures. Highly recommended for production use and when
-                accessing sites with bot detection. Defaults to `False`.
-            web_agent_model (Optional[BaseModelBackend]): The language model
-                backend to use for the high-level `solve_task` agent. This is
-                required only if you plan to use `solve_task`.
-                Defaults to `None`.
-            cache_dir (str): The directory to store cached files, such as
-                screenshots. Defaults to `"tmp/"`.
-            enabled_tools (Optional[List[str]]): List of tool names to enable.
-                If None, uses DEFAULT_TOOLS. Available tools: open_browser,
-                close_browser, visit_page, back, forward, get_page_snapshot,
-                get_som_screenshot, get_page_links, click, type, select,
-                scroll, enter, wait_user, solve_task.
-                Defaults to `None`.
-            browser_log_to_file (bool): Whether to save detailed browser
-            action logs to file.
-                When enabled, logs action inputs/outputs, execution times,
-                and page loading times.
-                Logs are saved to an auto-generated timestamped file.
-                Defaults to `False`.
-            session_id (Optional[str]): A unique identifier for this browser
-                session. When multiple HybridBrowserToolkit instances are used
-                concurrently, different session IDs prevent them from sharing
-                the same browser session and causing conflicts. If None, a
-                default session will be used. Defaults to `None`.
-            default_start_url (str): The default URL to navigate to when
-                open_browser() is called without a start_url parameter or with
-                None. Defaults to `"https://google.com/"`.
-            default_timeout (Optional[int]): Default timeout in milliseconds
-                for browser actions. If None, uses environment variable
-                HYBRID_BROWSER_DEFAULT_TIMEOUT or defaults to 3000ms.
-                Defaults to `None`.
-            short_timeout (Optional[int]): Short timeout in milliseconds
-                for quick browser actions. If None, uses environment variable
-                HYBRID_BROWSER_SHORT_TIMEOUT or defaults to 1000ms.
-                Defaults to `None`.
-            navigation_timeout (Optional[int]): Custom navigation timeout in
-            milliseconds.
-                If None, uses environment variable
-                HYBRID_BROWSER_NAVIGATION_TIMEOUT or defaults to 10000ms.
-                Defaults to `None`.
-            network_idle_timeout (Optional[int]): Custom network idle
-            timeout in milliseconds.
-                If None, uses environment variable
-                HYBRID_BROWSER_NETWORK_IDLE_TIMEOUT or defaults to 5000ms.
-                Defaults to `None`.
-            screenshot_timeout (Optional[int]): Custom screenshot timeout in
-            milliseconds.
-                If None, uses environment variable
-                HYBRID_BROWSER_SCREENSHOT_TIMEOUT or defaults to 15000ms.
-                Defaults to `None`.
-            page_stability_timeout (Optional[int]): Custom page stability
-            timeout in milliseconds.
-                If None, uses environment variable
-                HYBRID_BROWSER_PAGE_STABILITY_TIMEOUT or defaults to 1500ms.
-                Defaults to `None`.
-            dom_content_loaded_timeout (Optional[int]): Custom DOM content
-            loaded timeout in milliseconds.
-                If None, uses environment variable
-                HYBRID_BROWSER_DOM_CONTENT_LOADED_TIMEOUT or defaults to
-                5000ms.
-                Defaults to `None`.
-        """
-        super().__init__()
-        self._headless = headless
-        self._user_data_dir = user_data_dir
-        self._stealth = stealth
-        self._web_agent_model = web_agent_model
-        self._cache_dir = cache_dir
-        self._browser_log_to_file = browser_log_to_file
-        self._default_start_url = default_start_url
-        self._session_id = session_id or "default"
-
-        # Store timeout configuration
-        self._default_timeout = default_timeout
-        self._short_timeout = short_timeout
-        self._navigation_timeout = ConfigLoader.get_navigation_timeout(
-            navigation_timeout
-        )
-        self._network_idle_timeout = ConfigLoader.get_network_idle_timeout(
-            network_idle_timeout
-        )
-        self._screenshot_timeout = ConfigLoader.get_screenshot_timeout(
-            screenshot_timeout
-        )
-        self._page_stability_timeout = ConfigLoader.get_page_stability_timeout(
-            page_stability_timeout
-        )
-        self._dom_content_loaded_timeout = (
-            ConfigLoader.get_dom_content_loaded_timeout(
-                dom_content_loaded_timeout
-            )
-        )
-
-        # Logging configuration - fixed values for simplicity
-        self.enable_action_logging = True
-        self.enable_timing_logging = True
-        self.enable_page_loading_logging = True
-        self.log_to_console = False  # Always disabled for cleaner output
-        self.log_to_file = browser_log_to_file
-        self.max_log_length = None  # No truncation for file logs
-
-        # Set up log file if needed
-        if self.log_to_file:
-            # Create log directory if it doesn't exist
-            log_dir = "browser_log"
-            os.makedirs(log_dir, exist_ok=True)
-
-            timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
-            self.log_file_path: Optional[str] = os.path.join(
-                log_dir, f"hybrid_browser_toolkit_{timestamp}_{session_id}.log"
-            )
-        else:
-            self.log_file_path = None
-
-        # Initialize log buffer for in-memory storage
-        self.log_buffer: List[Dict[str, Any]] = []
-
-        # Configure enabled tools
-        if enabled_tools is None:
-            self.enabled_tools = self.DEFAULT_TOOLS.copy()
-        else:
-            # Validate enabled tools
-            invalid_tools = [
-                tool for tool in enabled_tools if tool not in self.ALL_TOOLS
-            ]
-            if invalid_tools:
+            mode (Literal["typescript", "python"]): Implementation mode.
+                - 'typescript': Uses WebSocket-based TypeScript implementation
+                - 'python': Uses pure Python Playwright implementation
+                Defaults to "typescript".
+            headless (bool): Whether to run browser in headless mode.
+                Defaults to True.
+            user_data_dir (Optional[str]): Directory for user data
+                persistence. Defaults to None.
+            stealth (bool): Whether to enable stealth mode. Defaults to
+                False.
+            web_agent_model (Optional[BaseModelBackend]): Model for web
+                agent operations. Defaults to None.
+            cache_dir (str): Directory for caching. Defaults to "tmp/".
+            enabled_tools (Optional[List[str]]): List of enabled tools.
+                Defaults to None.
+            browser_log_to_file (bool): Whether to log browser actions to
+                file. Defaults to False.
+            session_id (Optional[str]): Session identifier. Defaults to None.
+            default_start_url (str): Default URL to start with. Defaults
+                to "https://google.com/".
+            default_timeout (Optional[int]): Default timeout in
+                milliseconds. Defaults to None.
+            short_timeout (Optional[int]): Short timeout in milliseconds.
+                Defaults to None.
+            navigation_timeout (Optional[int]): Navigation timeout in
+                milliseconds. Defaults to None.
+            network_idle_timeout (Optional[int]): Network idle timeout in
+                milliseconds. Defaults to None.
+            screenshot_timeout (Optional[int]): Screenshot timeout in
+                milliseconds. Defaults to None.
+            page_stability_timeout (Optional[int]): Page stability timeout
+                in milliseconds. Defaults to None.
+            dom_content_loaded_timeout (Optional[int]): DOM content loaded
+                timeout in milliseconds. Defaults to None.
+            viewport_limit (bool): Whether to filter page snapshot
+                elements to only those visible in the current viewport.
+                Defaults to False.
+            connect_over_cdp (bool): Whether to connect to an existing
+                browser via Chrome DevTools Protocol. Defaults to False.
+                (Only supported in TypeScript mode)
+            cdp_url (Optional[str]): WebSocket endpoint URL for CDP
+                connection. Required when connect_over_cdp is True.
+                Defaults to None. (Only supported in TypeScript mode)
+            **kwargs: Additional keyword arguments passed to the
+                implementation.
+
+        Returns:
+            HybridBrowserToolkit instance of the specified implementation.
+        """
+        if mode == "typescript":
+            from .hybrid_browser_toolkit_ts import (
+                HybridBrowserToolkit as TSToolkit,
+            )
+
+            return TSToolkit(
+                headless=headless,
+                user_data_dir=user_data_dir,
+                stealth=stealth,
+                web_agent_model=web_agent_model,
+                cache_dir=cache_dir,
+                enabled_tools=enabled_tools,
+                browser_log_to_file=browser_log_to_file,
+                session_id=session_id,
+                default_start_url=default_start_url,
+                default_timeout=default_timeout,
+                short_timeout=short_timeout,
+                navigation_timeout=navigation_timeout,
+                network_idle_timeout=network_idle_timeout,
+                screenshot_timeout=screenshot_timeout,
+                page_stability_timeout=page_stability_timeout,
+                dom_content_loaded_timeout=dom_content_loaded_timeout,
+                viewport_limit=viewport_limit,
+                connect_over_cdp=connect_over_cdp,
+                cdp_url=cdp_url,
+                **kwargs,
+            )
+        elif mode == "python":
+            from ..hybrid_browser_toolkit_py import (
+                HybridBrowserToolkit as PyToolkit,
+            )
+
+            # Note: Python implementation doesn't support CDP connection
+            if connect_over_cdp:
                 raise ValueError(
-                    f"Invalid tools specified: {invalid_tools}. "
-                    f"Available tools: {self.ALL_TOOLS}"
-                )
-            self.enabled_tools = enabled_tools.copy()
-
-        logger.info(f"Enabled tools: {self.enabled_tools}")
-
-        # Log initialization if file logging is enabled
-        if self.log_to_file:
-            logger.info(
-                "HybridBrowserToolkit initialized with file logging enabled"
-            )
-            logger.info(f"Log file path: {self.log_file_path}")
-
-        # Core components
-        temp_session = HybridBrowserSession(
-            headless=headless,
-            user_data_dir=user_data_dir,
-            stealth=stealth,
-            session_id=session_id,
-            default_timeout=default_timeout,
-            short_timeout=short_timeout,
-        )
-        # Use the session directly - singleton logic is handled in
-        # ensure_browser
-        self._session = temp_session
-        self._agent: Optional[PlaywrightLLMAgent] = None
-        self._unified_script = self._load_unified_analyzer()
-
-    @property
-    def web_agent_model(self) -> Optional[BaseModelBackend]:
-        """Get the web agent model."""
-        return self._web_agent_model
-
-    @web_agent_model.setter
-    def web_agent_model(self, value: Optional[BaseModelBackend]) -> None:
-        """Set the web agent model."""
-        self._web_agent_model = value
-
-    @property
-    def cache_dir(self) -> str:
-        """Get the cache directory."""
-        return self._cache_dir
-
-    def __del__(self):
-        r"""Cleanup browser resources on garbage collection."""
-        try:
-            import sys
-
-            if getattr(sys, "is_finalizing", lambda: False)():
-                return
-
-            import asyncio
-
-            try:
-                loop = asyncio.get_event_loop()
-                if not loop.is_closed() and not loop.is_running():
-                    # Try to close browser with a timeout to prevent hanging
-                    try:
-                        loop.run_until_complete(
-                            asyncio.wait_for(self.close_browser(), timeout=2.0)
-                        )
-                    except asyncio.TimeoutError:
-                        pass  # Skip cleanup if it takes too long
-            except (RuntimeError, ImportError):
-                pass  # Event loop unavailable, skip cleanup
-        except Exception:
-            pass  # Suppress all errors during garbage collection
-
-    def _load_unified_analyzer(self) -> str:
-        r"""Load the unified analyzer JavaScript script."""
-        script_path = os.path.join(
-            os.path.dirname(os.path.abspath(__file__)), "unified_analyzer.js"
-        )
-
-        try:
-            with open(
-                script_path, "r", encoding='utf-8', errors='replace'
-            ) as f:
-                script_content = f.read()
-
-            if not script_content.strip():
-                raise ValueError(f"Script is empty: {script_path}")
-
-            logger.debug(
-                f"Loaded unified analyzer ({len(script_content)} chars)"
-            )
-            return script_content
-        except FileNotFoundError:
-            raise FileNotFoundError(f"Script not found: {script_path}")
-
-    def _validate_ref(self, ref: str, method_name: str) -> None:
-        r"""Validate ref parameter."""
-        if not ref or not isinstance(ref, str):
-            raise ValueError(
-                f"{method_name}: 'ref' must be a non-empty string"
-            )
-
-    def _truncate_if_needed(self, content: Any) -> str:
-        r"""Truncate content if max_log_length is set."""
-        content_str = str(content)
-        if (
-            self.max_log_length is not None
-            and len(content_str) > self.max_log_length
-        ):
-            return content_str[: self.max_log_length] + "... [TRUNCATED]"
-        return content_str
-
-    async def _get_current_url(self) -> Optional[str]:
-        r"""Safely get the current URL of the active page."""
-        try:
-            page = await self._session.get_page()
-            if page and not page.is_closed():
-                return page.url
-            return None  # Return None if page is closed
-        except Exception:
-            # This can happen if browser is not open.
-            return None
-
-    async def _log_action(
-        self,
-        action_name: str,
-        inputs: Dict[str, Any],
-        outputs: Any,
-        execution_time: float,
-        page_load_time: Optional[float] = None,
-        error: Optional[str] = None,
-    ) -> None:
-        r"""Log action details with comprehensive information."""
-        if not (self.enable_action_logging or self.enable_timing_logging):
-            return
-
-        current_url = await self._get_current_url()
-
-        log_entry: Dict[str, Any] = {
-            "timestamp": datetime.datetime.now().isoformat(),
-            "action": action_name,
-            "url": current_url,
-            "execution_time_ms": round(execution_time * 1000, 2),
-        }
-
-        if self.enable_action_logging:
-            log_entry["inputs"] = inputs
-            if error:
-                log_entry["error"] = str(error)
-            elif isinstance(outputs, dict):
-                # Unpack dictionary items into the log entry
-                log_entry.update(outputs)
-            elif isinstance(outputs, ToolResult):
-                log_entry["outputs"] = {
-                    "text": outputs.text,
-                    "images": outputs.images,
-                }
-            else:
-                # For non-dict outputs, assign to 'outputs' key
-                log_entry["outputs"] = outputs
-
-        if page_load_time is not None and self.enable_page_loading_logging:
-            log_entry["page_load_time_ms"] = round(page_load_time * 1000, 2)
-
-        # Add to buffer
-        self.log_buffer.append(log_entry)
-
-        # Console logging
-        if self.log_to_console:
-            log_msg = f"[BROWSER ACTION] {action_name}"
-            if self.enable_timing_logging:
-                log_msg += f" | Execution: {log_entry['execution_time_ms']}ms"
-            if page_load_time is not None and self.enable_page_loading_logging:
-                log_msg += f" | Page Load: {log_entry['page_load_time_ms']}ms"
-            if error:
-                log_msg += f" | ERROR: {error}"
-
-            logger.info(log_msg)
-
-            if self.enable_action_logging:
-                logger.info(f"  Inputs: {self._truncate_if_needed(inputs)}")
-                if not error:
-                    if isinstance(outputs, dict):
-                        for key, value in outputs.items():
-                            logger.info(
-                                f"  - {key}: "
-                                f"{self._truncate_if_needed(value)}"
-                            )
-                    else:
-                        logger.info(
-                            f"  Outputs: {self._truncate_if_needed(outputs)}"
-                        )
-
-        # File logging
-        if self.log_to_file and self.log_file_path:
-            try:
-                with open(self.log_file_path, 'a', encoding='utf-8') as f:
-                    # Write full log entry to file without truncation
-                    f.write(
-                        json.dumps(log_entry, ensure_ascii=False, indent=2)
-                        + '\n'
-                    )
-            except Exception as e:
-                logger.error(f"Failed to write to log file: {e}")
-
-    @staticmethod
-    def action_logger(func: Callable[..., Any]) -> Callable[..., Any]:
-        r"""Decorator to add logging to action methods."""
-
-        @wraps(func)
-        async def wrapper(self, *args, **kwargs):
-            action_name = func.__name__
-            start_time = time.time()
-
-            # Log inputs
-            inputs = {
-                "args": args,  # Don't skip self since it's already handled
-                "kwargs": kwargs,
-            }
-
-            try:
-                # Execute the original function
-                result = await func(self, *args, **kwargs)
-                execution_time = time.time() - start_time
-
-                # Log success
-                await self._log_action(
-                    action_name=action_name,
-                    inputs=inputs,
-                    outputs=result,
-                    execution_time=execution_time,
-                )
-
-                return result
-
-            except Exception as e:
-                execution_time = time.time() - start_time
-                error_msg = f"{type(e).__name__}: {e!s}"
-
-                # Log error
-                await self._log_action(
-                    action_name=action_name,
-                    inputs=inputs,
-                    outputs=None,
-                    execution_time=execution_time,
-                    error=error_msg,
-                )
-
-                raise
-
-        return wrapper
-
-    async def _get_session(self) -> "HybridBrowserSession":
-        """Get the correct singleton session instance."""
-        singleton = await HybridBrowserSession._get_or_create_instance(
-            self._session
-        )
-        if singleton is not self._session:
-            logger.debug("Updating to singleton session instance")
-            self._session = singleton
-        return self._session
-
-    async def _ensure_browser(self):
-        # Get singleton instance and update self._session if needed
-        session = await self._get_session()
-        await session.ensure_browser()
-
-    async def _require_page(self):
-        # Get singleton instance and update self._session if needed
-        session = await self._get_session()
-        await session.ensure_browser()
-        return await session.get_page()
-
-    async def _wait_for_page_stability(self):
-        r"""Wait for page to become stable after actions that might trigger
-        updates. Optimized with shorter timeouts.
-        """
-        page = await self._require_page()
-        import asyncio
-
-        try:
-            # Wait for DOM content to be loaded (reduced timeout)
-            await page.wait_for_load_state(
-                'domcontentloaded', timeout=self._page_stability_timeout
-            )
-            logger.debug("DOM content loaded")
-
-            # Try to wait for network idle with shorter timeout
-            try:
-                await page.wait_for_load_state(
-                    'networkidle', timeout=self._network_idle_timeout
-                )
-                logger.debug("Network idle achieved")
-            except Exception:
-                logger.debug("Network idle timeout - continuing anyway")
-
-            # Reduced delay for JavaScript execution
-            await asyncio.sleep(0.2)  # Reduced from 0.5s
-            logger.debug("Page stability wait completed")
-
-        except Exception as e:
-            logger.debug(
-                f"Page stability wait failed: {e} - continuing anyway"
-            )
-
-    async def _get_unified_analysis(
-        self, max_retries: int = 3
-    ) -> Dict[str, Any]:
-        r"""Get unified analysis data from the page with retry mechanism for
-        navigation issues."""
-        page = await self._require_page()
-
-        for attempt in range(max_retries):
-            try:
-                if not self._unified_script:
-                    logger.error("Unified analyzer script not loaded")
-                    return {"elements": {}, "metadata": {"elementCount": 0}}
-
-                # Wait for DOM stability before each attempt (with optimized
-                # timeout)
-                try:
-                    await page.wait_for_load_state(
-                        'domcontentloaded',
-                        timeout=self._dom_content_loaded_timeout,
-                    )
-                except Exception:
-                    # Don't fail if DOM wait times out
-                    pass
-
-                result = await page.evaluate(self._unified_script)
-
-                if not isinstance(result, dict):
-                    logger.warning(f"Invalid result type: {type(result)}")
-                    return {"elements": {}, "metadata": {"elementCount": 0}}
-
-                # Success - return result
-                if attempt > 0:
-                    logger.debug(
-                        f"Unified analysis succeeded on attempt {attempt + 1}"
-                    )
-                return result
-
-            except Exception as e:
-                error_msg = str(e)
-
-                # Check if this is a navigation-related error
-                is_navigation_error = (
-                    "Execution context was destroyed" in error_msg
-                    or "Most likely because of a navigation" in error_msg
-                    or "Target page, context or browser has been closed"
-                    in error_msg
-                )
-
-                if is_navigation_error and attempt < max_retries - 1:
-                    logger.debug(
-                        f"Navigation error in unified analysis (attempt "
-                        f"{attempt + 1}/{max_retries}): {e}. Retrying..."
-                    )
-
-                    # Wait a bit for page stability before retrying (optimized)
-                    try:
-                        await page.wait_for_load_state(
-                            'domcontentloaded',
-                            timeout=self._page_stability_timeout,
-                        )
-                        # Reduced delay for JS context to stabilize
-                        import asyncio
-
-                        await asyncio.sleep(0.1)  # Reduced from 0.2s
-                    except Exception:
-                        # Continue even if wait fails
-                        pass
-
-                    continue
-
-                # Non-navigation error or final attempt - log and return
-                # empty result
-                if attempt == max_retries - 1:
-                    logger.warning(
-                        f"Error in unified analysis after {max_retries} "
-                        f"attempts: {e}"
-                    )
-                else:
-                    logger.warning(
-                        f"Non-retryable error in unified analysis: {e}"
-                    )
-
-                return {"elements": {}, "metadata": {"elementCount": 0}}
-
-        # Should not reach here, but just in case
-        return {"elements": {}, "metadata": {"elementCount": 0}}
-
-    def _convert_analysis_to_rects(
-        self, analysis_data: Dict[str, Any]
-    ) -> Dict[str, Any]:
-        r"""Convert analysis data to rect format for visual marking."""
-        rects = {}
-        elements = analysis_data.get("elements", {})
-
-        for ref, element_data in elements.items():
-            coordinates = element_data.get("coordinates", [])
-            if coordinates:
-                rects[ref] = {
-                    "role": element_data.get("role", "generic"),
-                    "aria-name": element_data.get("name", ""),
-                    "rects": [coordinates[0]],
-                }
-        return rects
-
-    def _add_set_of_mark(self, image, rects):
-        r"""Add visual marks to the image."""
-        try:
-            from PIL import ImageDraw, ImageFont
-        except ImportError:
-            logger.warning("PIL not available, returning original image")
-            return image
-
-        marked_image = image.copy()
-        draw = ImageDraw.Draw(marked_image)
-
-        # Try to get font
-        try:
-            font = ImageFont.truetype("arial.ttf", 16)
-        except (OSError, IOError):
-            try:
-                font = ImageFont.load_default()
-            except (OSError, IOError):
-                font = None
-
-        # Color scheme
-        colors = {
-            "button": "#FF6B6B",
-            "link": "#4ECDC4",
-            "textbox": "#45B7D1",
-            "select": "#96CEB4",
-            "checkbox": "#FECA57",
-            "radio": "#FF9FF3",
-            "default": "#DDA0DD",
-        }
-
-        for ref, rect_data in rects.items():
-            rects_list = rect_data.get("rects", [])
-            role = rect_data.get("role", "generic")
-            color = colors.get(role, colors["default"])
-
-            for rect in rects_list:
-                x, y = rect.get("x", 0), rect.get("y", 0)
-                width, height = rect.get("width", 0), rect.get("height", 0)
-
-                # Draw rectangle outline
-                draw.rectangle(
-                    [x, y, x + width, y + height], outline=color, width=2
-                )
-
-                # Draw reference label
-                label_text = ref
-                if font:
-                    bbox = draw.textbbox((0, 0), label_text, font=font)
-                    text_width, text_height = (
-                        bbox[2] - bbox[0],
-                        bbox[3] - bbox[1],
-                    )
-                else:
-                    text_width, text_height = len(label_text) * 8, 16
-
-                label_x, label_y = max(0, x - 2), max(0, y - text_height - 2)
-
-                # Background and text
-                draw.rectangle(
-                    [
-                        label_x,
-                        label_y,
-                        label_x + text_width + 4,
-                        label_y + text_height + 2,
-                    ],
-                    fill=color,
-                )
-                draw.text(
-                    (label_x + 2, label_y + 1),
-                    label_text,
-                    fill="white",
-                    font=font,
-                )
-
-        return marked_image
-
-    def _format_snapshot_from_analysis(
-        self, analysis_data: Dict[str, Any]
-    ) -> str:
-        r"""Format analysis data into snapshot string."""
-        lines = []
-        elements = analysis_data.get("elements", {})
-
-        for ref, element_data in elements.items():
-            role = element_data.get("role", "generic")
-            name = element_data.get("name", "")
-
-            line = f"- {role}"
-            if name:
-                line += f' "{name}"'
-
-            # Add properties
-            props = []
-            for prop in ["disabled", "checked", "expanded"]:
-                value = element_data.get(prop)
-                if value is True:
-                    props.append(prop)
-                elif value is not None and prop in ["checked", "expanded"]:
-                    props.append(f"{prop}={value}")
-
-            if props:
-                line += f" {' '.join(props)}"
-
-            line += f" [ref={ref}]"
-            lines.append(line)
-
-        return "\n".join(lines)
-
-    async def _get_tab_info_for_output(self) -> Dict[str, Any]:
-        r"""Get tab information to include in action outputs."""
-        try:
-            # Ensure we have the correct singleton session instance first
-            session = await self._get_session()
-
-            # Add debug info for tab info retrieval
-            logger.debug("Attempting to get tab info from session...")
-            tab_info = await session.get_tab_info()
-            current_tab_index = await session.get_current_tab_id()
-
-            # Debug log the successful retrieval
-            logger.debug(
-                f"Successfully retrieved {len(tab_info)} tabs, current: "
-                f"{current_tab_index}"
-            )
-
-            return {
-                "tabs": tab_info,
-                "current_tab": current_tab_index,
-                "total_tabs": len(tab_info),
-            }
-        except Exception as e:
-            logger.warning(
-                f"Failed to get tab info from session: {type(e).__name__}: {e}"
-            )
-
-            # Try to get actual tab count from session pages directly
-            try:
-                # Get the correct session instance for fallback
-                fallback_session = await self._get_session()
-
-                # Check browser session state
-                session_state = {
-                    "has_session": fallback_session is not None,
-                    "has_pages_attr": hasattr(fallback_session, '_pages'),
-                    "pages_count": len(fallback_session._pages)
-                    if hasattr(fallback_session, '_pages')
-                    else "unknown",
-                    "has_page": hasattr(fallback_session, '_page')
-                    and fallback_session._page is not None,
-                    "session_id": getattr(
-                        fallback_session, '_session_id', 'unknown'
-                    ),
-                }
-                logger.debug(f"Browser session state: {session_state}")
-
-                actual_tab_count = 0
-                if (
-                    hasattr(fallback_session, '_pages')
-                    and fallback_session._pages
-                ):
-                    actual_tab_count = len(fallback_session._pages)
-                    # Also try to filter out closed pages
-                    try:
-                        open_pages = [
-                            p
-                            for p in fallback_session._pages.values()
-                            if not p.is_closed()
-                        ]
-                        actual_tab_count = len(open_pages)
-                        logger.debug(
-                            f"Found {actual_tab_count} open tabs out of "
-                            f"{len(fallback_session._pages)} total"
-                        )
-                    except Exception:
-                        # Keep the original count if we can't check page status
-                        pass
-
-                if actual_tab_count == 0:
-                    # If no pages, check if browser is even initialized
-                    if (
-                        hasattr(fallback_session, '_page')
-                        and fallback_session._page is not None
-                    ):
-                        actual_tab_count = 1
-                        logger.debug(
-                            "No pages in list but main page exists, assuming "
-                            "1 tab"
-                        )
-                    else:
-                        actual_tab_count = 1
-                        logger.debug("No pages found, defaulting to 1 tab")
-
-                logger.debug(f"Using fallback tab count: {actual_tab_count}")
-                return {
-                    "tabs": [],
-                    "current_tab": 0,
-                    "total_tabs": actual_tab_count,
-                }
-
-            except Exception as fallback_error:
-                logger.warning(
-                    f"Fallback tab count also failed: "
-                    f"{type(fallback_error).__name__}: {fallback_error}"
-                )
-                return {"tabs": [], "current_tab": 0, "total_tabs": 1}
-
-    async def _exec_with_snapshot(
-        self,
-        action: Dict[str, Any],
-        element_details: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, str]:
-        r"""Execute action and return result with snapshot comparison."""
-
-        # Log action execution start
-        action_type = action.get("type", "unknown")
-        logger.info(f"Executing action: {action_type}")
-
-        action_start_time = time.time()
-        inputs: Dict[str, Any] = {"action": action}
-        page_load_time = None
-
-        try:
-            # Get before snapshot
-            logger.info("Capturing pre-action snapshot...")
-            snapshot_start_before = time.time()
-            before_snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            before_snapshot_time = time.time() - snapshot_start_before
-            logger.info(
-                f"Pre-action snapshot captured in {before_snapshot_time:.2f}s"
-            )
-
-            # Execute action
-            logger.info(f"Executing {action_type} action...")
-            exec_start = time.time()
-            exec_result = await self._session.exec_action(action)
-            exec_time = time.time() - exec_start
-            logger.info(f"Action {action_type} completed in {exec_time:.2f}s")
-
-            # Parse the detailed result from ActionExecutor
-            if isinstance(exec_result, dict):
-                result_message = exec_result.get("message", str(exec_result))
-                action_details = exec_result.get("details", {})
-                success = exec_result.get("success", True)
-            else:
-                result_message = str(exec_result)
-                action_details = {}
-                success = True
-
-            # Wait for page stability after action (especially important for
-            # click)
-            stability_time: float = 0.0
-            if action_type in ["click", "type", "select", "enter"]:
-                logger.info(
-                    f"Waiting for page stability " f"after {action_type}..."
-                )
-                stability_start = time.time()
-                await self._wait_for_page_stability()
-                stability_time = time.time() - stability_start
-                logger.info(
-                    f"Page stability wait "
-                    f"completed in "
-                    f"{stability_time:.2f}s"
-                )
-                page_load_time = stability_time
-
-                # Enhanced logging for page loading times
-                if self.enable_page_loading_logging and self.log_to_console:
-                    logger.info(
-                        f"[PAGE LOADING] Page stability for {action_type}: "
-                        f"{round(stability_time * 1000, 2)}ms"
-                    )
-
-            # Get after snapshot
-            logger.info("Capturing post-action snapshot...")
-            snapshot_start_after = time.time()
-            after_snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            after_snapshot_time = time.time() - snapshot_start_after
-            logger.info(
-                f"Post-action snapshot "
-                f"captured in {after_snapshot_time:.2f}s"
-            )
-
-            # Check for snapshot quality and log warnings
-            if before_snapshot == after_snapshot:
-                snapshot = "snapshot not changed"
-                logger.debug("Page snapshot unchanged after action")
-            else:
-                snapshot = after_snapshot
-                # Check if snapshot is empty or problematic
-                if "<empty>" in after_snapshot:
-                    logger.warning(
-                        f"Action {action_type} resulted "
-                        f"in empty snapshot - "
-                        f"page may still be loading"
-                    )
-                elif len(after_snapshot.strip()) < 50:
-                    logger.warning(
-                        f"Action {action_type} resulted "
-                        f"in very short snapshot:"
-                        f" {len(after_snapshot)} chars"
-                    )
-                else:
-                    logger.debug(
-                        f"Action {action_type} resulted "
-                        f"in updated snapshot: "
-                        f"{len(after_snapshot)} chars"
-                    )
-
-            # Get tab information for output
-            tab_info = await self._get_tab_info_for_output()
-
-            # Create comprehensive output for logging
-            execution_time = time.time() - action_start_time
-            total_snapshot_time = before_snapshot_time + after_snapshot_time
-            outputs = {
-                "result": result_message,
-                "snapshot": snapshot,
-                "success": success,
-                "action_details": action_details,
-                "execution_stats": {
-                    "exec_time_ms": round(exec_time * 1000, 2),
-                    "stability_time_ms": round(stability_time * 1000, 2)
-                    if stability_time > 0
-                    else None,
-                    "snapshot_time_ms": round(total_snapshot_time * 1000, 2),
-                    "total_time_ms": round(execution_time * 1000, 2),
-                },
-                **tab_info,  # Include tab information
-            }
-
-            # If snapshot is unchanged after click, add element details to log
-            if (
-                snapshot == "snapshot not changed"
-                and action_type == "click"
-                and element_details
-            ):
-                logger.debug(
-                    "Snapshot unchanged after click. "
-                    "Adding element details to log."
-                )
-                outputs["clicked_element_tag"] = element_details.get(
-                    "tagName", "N/A"
-                )
-                outputs["clicked_element_content"] = element_details.get(
-                    "name", ""
-                )
-                outputs["clicked_element_type"] = element_details.get(
-                    "role", "generic"
-                )
-
-            # Log the action with all details
-            await self._log_action(
-                action_name=f"_exec_with_snapshot_{action_type}",
-                inputs=inputs,
-                outputs=outputs,
-                execution_time=execution_time,
-                page_load_time=page_load_time,
-            )
-
-            return {"result": result_message, "snapshot": snapshot}
-
-        except Exception as e:
-            execution_time = time.time() - action_start_time
-            error_msg = f"{type(e).__name__}: {e!s}"
-
-            # Log error
-            await self._log_action(
-                action_name=f"_exec_with_snapshot_{action_type}",
-                inputs=inputs,
-                outputs=None,
-                execution_time=execution_time,
-                page_load_time=page_load_time,
-                error=error_msg,
-            )
-
-            raise
-
-    async def _extract_links_by_refs(
-        self, snapshot: str, page, refs: List[str]
-    ) -> List[Dict[str, str]]:
-        r"""Extract multiple links by their reference IDs."""
-        import re
-
-        found_links = []
-        ref_set = set(refs)
-        lines = snapshot.split('\n')
-
-        for line in lines:
-            link_match = re.search(
-                r'- link\s+"([^"]+)"\s+\[ref=([^\]]+)\]', line
-            )
-            if link_match and link_match.group(2) in ref_set:
-                text, found_ref = link_match.groups()
-                try:
-                    url = await self._get_link_url_by_ref(page, found_ref)
-                    found_links.append(
-                        {"text": text, "ref": found_ref, "url": url or ""}
-                    )
-                except Exception as e:
-                    logger.warning(
-                        f"Failed to get URL for ref {found_ref}: {e}"
-                    )
-                    found_links.append(
-                        {"text": text, "ref": found_ref, "url": ""}
-                    )
-
-        return found_links
-
-    async def _get_link_url_by_ref(self, page, ref: str) -> str:
-        r"""Get URL of a link element by reference ID."""
-        try:
-            element = await page.query_selector(f'[aria-ref="{ref}"]')
-            if element:
-                href = await element.get_attribute('href')
-                if href:
-                    from urllib.parse import urljoin
-
-                    return urljoin(page.url, href)
-            return ""
-        except Exception as e:
-            logger.warning(f"Failed to get URL for ref {ref}: {e}")
-            return ""
-
-    def _ensure_agent(self) -> PlaywrightLLMAgent:
-        r"""Create PlaywrightLLMAgent on first use."""
-        if self._web_agent_model is None:
-            raise RuntimeError(
-                "web_agent_model required for high-level task planning"
-            )
-
-        if self._agent is None:
-            self._agent = PlaywrightLLMAgent(
-                headless=self._headless,
-                user_data_dir=self._user_data_dir,
-                model_backend=self._web_agent_model,
-            )
-        return self._agent
-
-    # Public API Methods
-
-    async def open_browser(self) -> Dict[str, Any]:
-        r"""Starts a new browser session. This must be the first browser
-        action.
-
-        This method initializes the browser and navigates to a default start
-        page. To visit a specific URL, use `visit_page` after this.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of interactive elements.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        # Add logging if enabled
-        action_start = time.time()
-        inputs: Dict[str, Any] = {}  # No input parameters for agents
-
-        logger.info("Starting browser session...")
-
-        browser_start = time.time()
-        await self._session.ensure_browser()
-        browser_time = time.time() - browser_start
-        logger.info(f"Browser session started in {browser_time:.2f}s")
-
-        try:
-            # Always use the configured default start URL
-            start_url = self._default_start_url
-            logger.info(f"Navigating to configured default page: {start_url}")
-
-            # Use visit_page without creating a new tab
-            result = await self.visit_page(start_url)
-
-            # Log success
-            if self.enable_action_logging or self.enable_timing_logging:
-                execution_time = time.time() - action_start
-                await self._log_action(
-                    action_name="open_browser",
-                    inputs=inputs,
-                    outputs={
-                        "result": "Browser opened and navigated to "
-                        "default page."
-                    },
-                    execution_time=execution_time,
-                )
-
-            return result
-
-        except Exception as e:
-            # Log error
-            if self.enable_action_logging or self.enable_timing_logging:
-                execution_time = time.time() - action_start
-                await self._log_action(
-                    action_name="open_browser",
-                    inputs=inputs,
-                    outputs=None,
-                    execution_time=execution_time,
-                    error=f"{type(e).__name__}: {e!s}",
-                )
-            raise
-
-    @action_logger
-    async def close_browser(self) -> str:
-        r"""Closes the browser session, releasing all resources.
-
-        This should be called at the end of a task for cleanup.
-
-        Returns:
-            str: A confirmation message.
-        """
-        if self._agent is not None:
-            try:
-                await self._agent.close()
-            except Exception:
-                pass
-            self._agent = None
-
-        await self._session.close()
-        return "Browser session closed."
-
-    @action_logger
-    async def visit_page(self, url: str) -> Dict[str, Any]:
-        r"""Opens a URL in a new browser tab and switches to it.
-
-        Args:
-            url (str): The web address to load. This should be a valid and
-                existing URL.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of the new page.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the new active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        if not url or not isinstance(url, str):
-            return {
-                "result": "Error: 'url' must be a non-empty string",
-                "snapshot": "",
-                "tabs": [],
-                "current_tab": 0,
-                "total_tabs": 1,
-            }
-
-        if '://' not in url:
-            url = f'https://{url}'
-
-        await self._ensure_browser()
-        session = await self._get_session()
-        nav_result = ""
-
-        # By default, we want to create a new tab.
-        should_create_new_tab = True
-        try:
-            # If the browser has just started with a single "about:blank" tab,
-            # use that tab instead of creating a new one.
-            tab_info_data = await self._get_tab_info_for_output()
-            tabs = tab_info_data.get("tabs", [])
-            if len(tabs) == 1 and tabs[0].get("url") == "about:blank":
-                logger.info(
-                    "Found single blank tab, navigating in current tab "
-                    "instead of creating a new one."
-                )
-                should_create_new_tab = False
-        except Exception as e:
-            logger.warning(
-                "Could not get tab info to check for blank tab, "
-                f"proceeding with default behavior (new tab). Error: {e}"
+                    "CDP connection is only supported in TypeScript mode"
+                )
+
+            # Note: Python implementation doesn't support viewport_limit
+            if viewport_limit:
+                import warnings
+
+                warnings.warn(
+                    "viewport_limit is not supported "
+                    "in Python mode and will be ignored",
+                    UserWarning,
+                )
+
+            return PyToolkit(
+                headless=headless,
+                user_data_dir=user_data_dir,
+                stealth=stealth,
+                web_agent_model=web_agent_model,
+                cache_dir=cache_dir,
+                enabled_tools=enabled_tools,
+                browser_log_to_file=browser_log_to_file,
+                session_id=session_id,
+                default_start_url=default_start_url,
+                default_timeout=default_timeout,
+                short_timeout=short_timeout,
+                navigation_timeout=navigation_timeout,
+                network_idle_timeout=network_idle_timeout,
+                screenshot_timeout=screenshot_timeout,
+                page_stability_timeout=page_stability_timeout,
+                dom_content_loaded_timeout=dom_content_loaded_timeout,
+                **kwargs,
             )
-
-        if should_create_new_tab:
-            logger.info(f"Creating new tab and navigating to URL: {url}")
-            try:
-                new_tab_id = await session.create_new_tab(url)
-                await session.switch_to_tab(new_tab_id)
-                nav_result = f"Visited {url} in new tab {new_tab_id}"
-            except Exception as e:
-                logger.error(f"Failed to create new tab and navigate: {e}")
-                nav_result = f"Error creating new tab: {e}"
         else:
-            logger.info(f"Navigating to URL in current tab: {url}")
-            nav_result = await session.visit(url)
-
-        # Get snapshot
-        snapshot = ""
-        try:
-            snapshot = await session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-        except Exception as e:
-            logger.warning(f"Failed to capture snapshot: {e}")
-
-        # Get tab information
-        tab_info = await self._get_tab_info_for_output()
-
-        return {"result": nav_result, "snapshot": snapshot, **tab_info}
-
-    @action_logger
-    async def back(self) -> Dict[str, Any]:
-        r"""Goes back to the previous page in the browser history.
-
-        This action simulates using the browser's "back" button in the
-        currently active tab.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of the previous page.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        page = await self._require_page()
-
-        try:
-            logger.info("Navigating back in browser history...")
-            nav_start = time.time()
-            await page.go_back(
-                wait_until="domcontentloaded", timeout=self._navigation_timeout
-            )
-            nav_time = time.time() - nav_start
-            logger.info(f"Back navigation completed in {nav_time:.2f}s")
-
-            # Minimal wait for page stability (back navigation is usually fast)
-            import asyncio
-
-            await asyncio.sleep(0.2)
-
-            # Get snapshot
-            logger.info("Capturing page snapshot after back navigation...")
-            snapshot_start = time.time()
-            snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            snapshot_time = time.time() - snapshot_start
-            logger.info(
-                f"Back navigation snapshot captured in {snapshot_time:.2f}s"
-            )
-
-            # Get tab information
-            tab_info = await self._get_tab_info_for_output()
-
-            return {
-                "result": "Back navigation successful.",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
-        except Exception as e:
-            logger.warning(f"Back navigation failed: {e}")
-            # Get current snapshot even if navigation failed
-            snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            tab_info = await self._get_tab_info_for_output()
-            return {
-                "result": f"Back navigation failed: {e!s}",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
-    @action_logger
-    async def forward(self) -> Dict[str, Any]:
-        r"""Goes forward to the next page in the browser history.
-
-        This action simulates using the browser's "forward" button in the
-        currently active tab.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of the next page.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        page = await self._require_page()
-
-        try:
-            logger.info("Navigating forward in browser history...")
-            nav_start = time.time()
-            await page.go_forward(
-                wait_until="domcontentloaded", timeout=self._navigation_timeout
-            )
-            nav_time = time.time() - nav_start
-            logger.info(f"Forward navigation completed in {nav_time:.2f}s")
-
-            # Minimal wait for page stability (forward navigation is usually
-            # fast)
-            import asyncio
-
-            await asyncio.sleep(0.2)
-
-            # Get snapshot
-            logger.info("Capturing page snapshot after forward navigation...")
-            snapshot_start = time.time()
-            snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            snapshot_time = time.time() - snapshot_start
-            logger.info(
-                f"Forward navigation snapshot captured in {snapshot_time:.2f}s"
-            )
-
-            # Get tab information
-            tab_info = await self._get_tab_info_for_output()
-
-            return {
-                "result": "Forward navigation successful.",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
-        except Exception as e:
-            logger.warning(f"Forward navigation failed: {e}")
-            # Get current snapshot even if navigation failed
-            snapshot = await self._session.get_snapshot(
-                force_refresh=True, diff_only=False
-            )
-            tab_info = await self._get_tab_info_for_output()
-            return {
-                "result": f"Forward navigation failed: {e!s}",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
-    @action_logger
-    async def get_page_snapshot(self) -> str:
-        r"""Gets a textual snapshot of the page's interactive elements.
-
-        The snapshot lists elements like buttons, links, and inputs, each with
-        a unique `ref` ID. This ID is used by other tools (e.g., `click`,
-        `type`) to interact with a specific element. This tool provides no
-        visual information.
-
-        Returns:
-            str: A formatted string representing the interactive elements and
-                their `ref` IDs. For example:
-                '- link "Sign In" [ref=1]'
-                '- textbox "Username" [ref=2]'
-        """
-        logger.info("Capturing page snapshot")
-
-        analysis_start = time.time()
-        analysis_data = await self._get_unified_analysis()
-        analysis_time = time.time() - analysis_start
-        logger.info(
-            f"Page snapshot analysis " f"completed in {analysis_time:.2f}s"
-        )
-
-        snapshot_text = analysis_data.get("snapshotText", "")
-        return (
-            snapshot_text
-            if snapshot_text
-            else self._format_snapshot_from_analysis(analysis_data)
-        )
-
-    @dependencies_required('PIL')
-    @action_logger
-    async def get_som_screenshot(self):
-        r"""Captures a screenshot with interactive elements highlighted.
-
-        "SoM" stands for "Set of Marks". This tool takes a screenshot and draws
-        boxes around clickable elements, overlaying a `ref` ID on each. Use
-        this for a visual understanding of the page, especially when the
-        textual snapshot is not enough.
-
-        Returns:
-            ToolResult: An object containing:
-                - `text` (str): A summary, e.g., "Visual webpage screenshot
-                  captured with 42 interactive elements".
-                - `images` (List[str]): A list containing one base64-encoded
-                  PNG image data URL.
-        """
-        from PIL import Image
-
-        from camel.utils.tool_result import ToolResult
-
-        os.makedirs(self._cache_dir, exist_ok=True)
-        # Get screenshot and analysis
-        page = await self._require_page()
-
-        # Log screenshot timeout start
-        logger.info(
-            f"Starting screenshot capture"
-            f"with timeout: {self._screenshot_timeout}ms"
-        )
-
-        start_time = time.time()
-        image_data = await page.screenshot(timeout=self._screenshot_timeout)
-        screenshot_time = time.time() - start_time
-
-        logger.info(f"Screenshot capture completed in {screenshot_time:.2f}s")
-        image = Image.open(io.BytesIO(image_data))
-
-        # Log unified analysis start
-        logger.info("Starting unified page analysis...")
-        analysis_start_time = time.time()
-        analysis_data = await self._get_unified_analysis()
-        analysis_time = time.time() - analysis_start_time
-        logger.info(f"Unified page analysis completed in {analysis_time:.2f}s")
-
-        # Log image processing
-        logger.info("Processing visual marks on screenshot...")
-        mark_start_time = time.time()
-        rects = self._convert_analysis_to_rects(analysis_data)
-        marked_image = self._add_set_of_mark(image, rects)
-        mark_time = time.time() - mark_start_time
-        logger.info(f"Visual marks processing completed in {mark_time:.2f}s")
-
-        # Save screenshot to cache directory
-        parsed_url = urllib.parse.urlparse(page.url)
-        url_name = sanitize_filename(str(parsed_url.path), max_length=241)
-        timestamp = datetime.datetime.now().strftime("%m%d%H%M%S")
-        file_path = os.path.join(
-            self._cache_dir, f"{url_name}_{timestamp}_som.png"
-        )
-        marked_image.save(file_path, "PNG")
-
-        # Convert to base64
-        img_buffer = io.BytesIO()
-        marked_image.save(img_buffer, format="PNG")
-        img_buffer.seek(0)
-        img_base64 = base64.b64encode(img_buffer.getvalue()).decode('utf-8')
-        img_data_url = f"data:image/png;base64,{img_base64}"
-
-        text_result = (
-            f"Visual webpage screenshot "
-            f"captured with {len(rects)} interactive elements"
-        )
-
-        return ToolResult(text=text_result, images=[img_data_url])
-
-    async def click(self, *, ref: str) -> Dict[str, Any]:
-        r"""Performs a click on an element on the page.
-
-        Args:
-            ref (str): The `ref` ID of the element to click. This ID is
-                obtained from a page snapshot (`get_page_snapshot` or
-                `get_som_screenshot`).
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of the page after the
-                  click.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        self._validate_ref(ref, "click")
-
-        analysis = await self._get_unified_analysis()
-        elements = analysis.get("elements", {})
-        if ref not in elements:
-            logger.error(f"Error: Element reference '{ref}' not found. ")
-            # Added snapshot to give more context on failure
-            snapshot = self._format_snapshot_from_analysis(analysis)
-            tab_info = await self._get_tab_info_for_output()
-            return {
-                "result": f"Error: Element reference '{ref}' not found. ",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
-        element_details = elements.get(ref)
-        action = {"type": "click", "ref": ref}
-        result = await self._exec_with_snapshot(
-            action, element_details=element_details
-        )
-
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
-
-        return result
-
-    async def type(self, *, ref: str, text: str) -> Dict[str, Any]:
-        r"""Types text into an input element on the page.
-
-        Args:
-            ref (str): The `ref` ID of the input element, from a snapshot.
-            text (str): The text to type into the element.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A textual snapshot of the page after
-                  typing.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        self._validate_ref(ref, "type")
-        await self._get_unified_analysis()  # Ensure aria-ref attributes
-
-        action = {"type": "type", "ref": ref, "text": text}
-        result = await self._exec_with_snapshot(action)
-
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
-
-        return result
-
-    async def select(self, *, ref: str, value: str) -> Dict[str, Any]:
-        r"""Selects an option in a dropdown (`<select>`) element.
-
-        Args:
-            ref (str): The `ref` ID of the `<select>` element.
-            value (str): The `value` attribute of the `<option>` to select,
-                not its visible text.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A snapshot of the page after the
-                  selection.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        self._validate_ref(ref, "select")
-        await self._get_unified_analysis()
-
-        action = {"type": "select", "ref": ref, "value": value}
-        result = await self._exec_with_snapshot(action)
-
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
-
-        return result
-
-    async def scroll(self, *, direction: str, amount: int) -> Dict[str, Any]:
-        r"""Scrolls the current page window.
-
-        Args:
-            direction (str): The direction to scroll: 'up' or 'down'.
-            amount (int): The number of pixels to scroll.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A snapshot of the page after scrolling.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        if direction not in ("up", "down"):
-            tab_info = await self._get_tab_info_for_output()
-            return {
-                "result": "Error: direction must be 'up' or 'down'",
-                "snapshot": "",
-                **tab_info,
-            }
-
-        action = {"type": "scroll", "direction": direction, "amount": amount}
-        result = await self._exec_with_snapshot(action)
-
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
-
-        return result
-
-    async def enter(self) -> Dict[str, Any]:
-        r"""Simulates pressing the Enter key on the currently focused element.
-
-        This is useful for submitting forms or search queries after using the
-        `type` tool.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A new page snapshot, as this action often
-                  triggers navigation.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        # Always press Enter on the currently focused element
-        action = {"type": "enter"}
-
-        result = await self._exec_with_snapshot(action)
-
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
-
-        return result
-
-    @action_logger
-    async def wait_user(
-        self, timeout_sec: Optional[float] = None
-    ) -> Dict[str, Any]:
-        r"""Pauses execution and waits for human input from the console.
-
-        Use this for tasks requiring manual steps, like solving a CAPTCHA. The
-        agent will resume after the user presses Enter in the console.
-
-        Args:
-            timeout_sec (Optional[float]): Max time to wait in seconds. If
-                `None`, it will wait indefinitely.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): A message indicating how the wait ended.
-                - "snapshot" (str): The page snapshot after the wait.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        import asyncio
-
-        prompt = (
-            "🕑 Agent waiting for human input. "
-            "Complete action in browser, then press Enter..."
-        )
-        logger.info(f"\n{prompt}\n")
-
-        async def _await_enter():
-            await asyncio.to_thread(input, ">>> Press Enter to resume <<<\n")
-
-        try:
-            if timeout_sec is not None:
-                logger.info(
-                    f"Waiting for user input with timeout: {timeout_sec}s"
-                )
-                start_time = time.time()
-                await asyncio.wait_for(_await_enter(), timeout=timeout_sec)
-                wait_time = time.time() - start_time
-                logger.info(f"User input received after {wait_time:.2f}s")
-                result_msg = "User resumed."
-            else:
-                logger.info("Waiting for user " "input (no timeout)")
-                start_time = time.time()
-                await _await_enter()
-                wait_time = time.time() - start_time
-                logger.info(f"User input received " f"after {wait_time:.2f}s")
-                result_msg = "User resumed."
-        except asyncio.TimeoutError:
-            wait_time = timeout_sec or 0.0
-            logger.info(
-                f"User input timeout reached "
-                f"after {wait_time}s, auto-resuming"
-            )
-            result_msg = f"Timeout {timeout_sec}s reached, auto-resumed."
-
-        snapshot = await self._session.get_snapshot(
-            force_refresh=True, diff_only=False
-        )
-        tab_info = await self._get_tab_info_for_output()
-
-        return {"result": result_msg, "snapshot": snapshot, **tab_info}
-
-    @action_logger
-    async def get_page_links(self, *, ref: List[str]) -> Dict[str, Any]:
-        r"""Gets the destination URLs for a list of link elements.
-
-        This is useful to know where a link goes before clicking it.
-
-        Args:
-            ref (List[str]): A list of `ref` IDs for link elements, obtained
-                from a page snapshot.
-
-        Returns:
-            Dict[str, Any]: A dictionary containing:
-                - "links" (List[Dict]): A list of found links, where each
-                  link has "text", "ref", and "url" keys.
-        """
-        if not ref or not isinstance(ref, list):
-            return {"links": []}
-
-        for r in ref:
-            if not r or not isinstance(r, str):
-                return {"links": []}
-
-        page = await self._require_page()
-        snapshot = await self._session.get_snapshot(
-            force_refresh=True, diff_only=False
-        )
-        links = await self._extract_links_by_refs(snapshot, page, ref)
-
-        return {"links": links}
-
-    @action_logger
-    async def solve_task(
-        self, task_prompt: str, start_url: str, max_steps: int = 15
-    ) -> str:
-        r"""Delegates a complex, high-level task to a specialized web agent.
-
-        Use this for multi-step tasks that can be described in a single prompt
-        (e.g., "log into my account and check for new messages"). The agent
-        will autonomously perform the necessary browser actions.
-
-        NOTE: This is a high-level action; for simple interactions, use tools
-        like `click` and `type`. `web_agent_model` must be provided during
-        toolkit initialization.
-
-        Args:
-            task_prompt (str): A natural language description of the task.
-            start_url (str): The URL to start the task from. This should be a
-                valid and existing URL, as agents may generate non-existent
-                ones.
-            max_steps (int): The maximum number of steps the agent can take.
-
-        Returns:
-            str: A summary message indicating the task has finished.
-        """
-        agent = self._ensure_agent()
-        await agent.navigate(start_url)
-        await agent.process_command(task_prompt, max_steps=max_steps)
-        return "Task processing finished - see stdout for detailed trace."
-
-    def get_log_summary(self) -> Dict[str, Any]:
-        r"""Get a summary of logged actions."""
-        if not self.log_buffer:
-            return {"total_actions": 0, "summary": "No actions logged"}
-
-        total_actions = len(self.log_buffer)
-        total_execution_time = sum(
-            entry.get("execution_time_ms", 0) for entry in self.log_buffer
-        )
-        total_page_load_time = sum(
-            entry.get("page_load_time_ms", 0)
-            for entry in self.log_buffer
-            if "page_load_time_ms" in entry
-        )
-
-        action_counts: Dict[str, int] = {}
-        error_count = 0
-
-        for entry in self.log_buffer:
-            action = entry["action"]
-            action_counts[action] = action_counts.get(action, 0) + 1
-            if "error" in entry:
-                error_count += 1
-
-        return {
-            "total_actions": total_actions,
-            "total_execution_time_ms": round(total_execution_time, 2),
-            "total_page_load_time_ms": round(total_page_load_time, 2),
-            "action_counts": action_counts,
-            "error_count": error_count,
-            "success_rate": round(
-                (total_actions - error_count) / total_actions * 100, 2
-            )
-            if total_actions > 0
-            else 0,
-        }
-
-    def clear_logs(self) -> None:
-        r"""Clear the log buffer."""
-        self.log_buffer.clear()
-        logger.info("Log buffer cleared")
-
-    def get_tools(self) -> List[FunctionTool]:
-        r"""Get available function tools
-        based on enabled_tools configuration."""
-        # Map tool names to their corresponding methods
-        tool_map = {
-            "open_browser": self.open_browser,
-            "close_browser": self.close_browser,
-            "visit_page": self.visit_page,
-            "back": self.back,
-            "forward": self.forward,
-            "get_page_snapshot": self.get_page_snapshot,
-            "get_som_screenshot": self.get_som_screenshot,
-            "get_page_links": self.get_page_links,
-            "click": self.click,
-            "type": self.type,
-            "select": self.select,
-            "scroll": self.scroll,
-            "enter": self.enter,
-            "wait_user": self.wait_user,
-            "solve_task": self.solve_task,
-            "switch_tab": self.switch_tab,
-            "close_tab": self.close_tab,
-            "get_tab_info": self.get_tab_info,
-        }
-
-        enabled_tools = []
-
-        for tool_name in self.enabled_tools:
-            if tool_name == "solve_task" and self._web_agent_model is None:
-                logger.warning(
-                    f"Tool '{tool_name}' is enabled but web_agent_model "
-                    f"is not provided. Skipping this tool."
-                )
-                continue
-
-            if tool_name in tool_map:
-                tool = FunctionTool(
-                    cast(Callable[..., Any], tool_map[tool_name])
-                )
-                enabled_tools.append(tool)
-            else:
-                logger.warning(f"Unknown tool name: {tool_name}")
-
-        logger.info(f"Returning {len(enabled_tools)} enabled tools")
-        return enabled_tools
-
-    def clone_for_new_session(
-        self, new_session_id: Optional[str] = None
-    ) -> "HybridBrowserToolkit":
-        r"""Create a new instance of HybridBrowserToolkit with a unique
-        session.
-
-        Args:
-            new_session_id: Optional new session ID. If None, a UUID will be
-            generated.
-
-        Returns:
-            A new HybridBrowserToolkit instance with the same configuration
-            but a different session.
-        """
-        import uuid
-
-        if new_session_id is None:
-            new_session_id = str(uuid.uuid4())[:8]
-
-        return HybridBrowserToolkit(
-            headless=self._headless,
-            user_data_dir=self._user_data_dir,
-            stealth=self._stealth,
-            web_agent_model=self._web_agent_model,
-            cache_dir=f"{self._cache_dir.rstrip('/')}_clone_{new_session_id}/",
-            enabled_tools=self.enabled_tools.copy(),
-            browser_log_to_file=self._browser_log_to_file,
-            session_id=new_session_id,
-            default_start_url=self._default_start_url,
-            default_timeout=self._default_timeout,
-            short_timeout=self._short_timeout,
-            navigation_timeout=self._navigation_timeout,
-            network_idle_timeout=self._network_idle_timeout,
-            screenshot_timeout=self._screenshot_timeout,
-            page_stability_timeout=self._page_stability_timeout,
-            dom_content_loaded_timeout=self._dom_content_loaded_timeout,
-        )
-
-    @action_logger
-    async def switch_tab(self, *, tab_id: str) -> Dict[str, Any]:
-        r"""Switches to a different browser tab using its ID.
-
-        After switching, all actions will apply to the new tab. Use
-        `get_tab_info` to find the ID of the tab you want to switch to.
-
-        Args:
-            tab_id (str): The ID of the tab to activate.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A snapshot of the newly active tab.
-                - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the new active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        await self._ensure_browser()
-        session = await self._get_session()
-
-        success = await session.switch_to_tab(tab_id)
-
-        if success:
-            snapshot = await session.get_snapshot(
-                force_refresh=True, diff_only=False
+            raise ValueError(
+                f"Invalid mode: {mode}. Must be 'typescript' or 'python'."
             )
-            tab_info = await self._get_tab_info_for_output()
-
-            result = {
-                "result": f"Successfully switched to tab {tab_id}",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-        else:
-            tab_info = await self._get_tab_info_for_output()
-            result = {
-                "result": f"Failed to switch to tab {tab_id}. Tab may not "
-                f"exist.",
-                "snapshot": "",
-                **tab_info,
-            }
-
-        return result
-
-    @action_logger
-    async def close_tab(self, *, tab_id: str) -> Dict[str, Any]:
-        r"""Closes a browser tab using its ID.
-
-        Use `get_tab_info` to find the ID of the tab to close. After
-        closing, the browser will switch to another tab if available.
-
-        Args:
-            tab_id (str): The ID of the tab to close.
-
-        Returns:
-            Dict[str, Any]: A dictionary with the result of the action:
-                - "result" (str): Confirmation of the action.
-                - "snapshot" (str): A snapshot of the active tab after closure.
-                - "tabs" (List[Dict]): Information about remaining tabs.
-                - "current_tab" (int): Index of the new active tab.
-                - "total_tabs" (int): Total number of remaining tabs.
-        """
-        await self._ensure_browser()
-        session = await self._get_session()
-
-        success = await session.close_tab(tab_id)
-
-        if success:
-            # Get current state after closing the tab
-            try:
-                snapshot = await session.get_snapshot(
-                    force_refresh=True, diff_only=False
-                )
-            except Exception:
-                snapshot = ""  # No active tab
-
-            tab_info = await self._get_tab_info_for_output()
-
-            result = {
-                "result": f"Successfully closed tab {tab_id}",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-        else:
-            tab_info = await self._get_tab_info_for_output()
-            result = {
-                "result": f"Failed to close tab {tab_id}. Tab may not "
-                f"exist.",
-                "snapshot": "",
-                **tab_info,
-            }
-
-        return result
-
-    @action_logger
-    async def get_tab_info(self) -> Dict[str, Any]:
-        r"""Gets a list of all open browser tabs and their information.
-
-        This includes each tab's index, title, and URL, and indicates which
-        tab is currently active. Use this to manage multiple tabs.
-
-        Returns:
-            Dict[str, Any]: A dictionary with tab information:
-                - "tabs" (List[Dict]): A list of open tabs, each with:
-                  - "index" (int): The tab's zero-based index.
-                  - "title" (str): The page title.
-                  - "url" (str): The current URL.
-                  - "is_current" (bool): True if the tab is active.
-                - "current_tab" (int): Index of the active tab.
-                - "total_tabs" (int): Total number of open tabs.
-        """
-        await self._ensure_browser()
-        return await self._get_tab_info_for_output()