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

camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit.py

@@ -11,75 +11,64 @@
 # See the License for the specific language governing permissions and
 # 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 camel.logger import get_logger
+from camel.messages import BaseMessage
 from camel.models import BaseModelBackend
-from camel.toolkits.base import BaseToolkit
+from camel.toolkits.base import BaseToolkit, RegisteredAgentToolkit
 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
+from .ws_wrapper import WebSocketBrowserWrapper
 
 logger = get_logger(__name__)
 
 
-class HybridBrowserToolkit(BaseToolkit):
+class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
     r"""A hybrid browser toolkit that combines non-visual, DOM-based browser
     automation with visual, screenshot-based capabilities.
 
-    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 toolkit now uses TypeScript implementation with Playwright's
+    _snapshotForAI functionality for enhanced AI integration.
     """
 
     # Default tool list - core browser functionality
     DEFAULT_TOOLS: ClassVar[List[str]] = [
-        "open_browser",
-        "close_browser",
-        "visit_page",
-        "back",
-        "forward",
-        "click",
-        "type",
-        "switch_tab",
+        "browser_open",
+        "browser_close",
+        "browser_visit_page",
+        "browser_back",
+        "browser_forward",
+        "browser_click",
+        "browser_type",
+        "browser_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",
+        "browser_open",
+        "browser_close",
+        "browser_visit_page",
+        "browser_back",
+        "browser_forward",
+        "browser_get_page_snapshot",
+        "browser_get_som_screenshot",
+        "browser_get_page_links",
+        "browser_click",
+        "browser_type",
+        "browser_select",
+        "browser_scroll",
+        "browser_enter",
+        "browser_wait_user",
+        "browser_solve_task",
+        "browser_switch_tab",
+        "browser_close_tab",
+        "browser_get_tab_info",
     ]
 
     def __init__(
@@ -101,137 +90,104 @@ class HybridBrowserToolkit(BaseToolkit):
         screenshot_timeout: Optional[int] = None,
         page_stability_timeout: Optional[int] = None,
         dom_content_loaded_timeout: Optional[int] = None,
+        viewport_limit: bool = False,
+        connect_over_cdp: bool = False,
+        cdp_url: Optional[str] = None,
     ) -> None:
         r"""Initialize the HybridBrowserToolkit.
 
         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`.
+            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.
+                When True, only elements within the current viewport
+                bounds will be included in snapshots.
+                When False (default), all elements on the page are
+                included. Defaults to False.
+            connect_over_cdp (bool): Whether to connect to an existing
+            browser via Chrome DevTools Protocol. Defaults to False.
+            cdp_url (Optional[str]): WebSocket endpoint URL for CDP
+            connection (e.g., 'ws://localhost:9222/devtools/browser/...').
+            Required when connect_over_cdp is True. 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
-            )
+        RegisteredAgentToolkit.__init__(self)
+
+        # Initialize configuration loader
+        self.config_loader = ConfigLoader.from_kwargs(
+            headless=headless,
+            user_data_dir=user_data_dir,
+            stealth=stealth,
+            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,
+            cache_dir=cache_dir,
+            browser_log_to_file=browser_log_to_file,
+            session_id=session_id,
+            enabled_tools=enabled_tools,
+            connect_over_cdp=connect_over_cdp,
+            cdp_url=cdp_url,
         )
 
-        # 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
+        # Legacy attribute access for backward compatibility
+        browser_config = self.config_loader.get_browser_config()
+        toolkit_config = self.config_loader.get_toolkit_config()
 
-        # Initialize log buffer for in-memory storage
-        self.log_buffer: List[Dict[str, Any]] = []
+        self._headless = browser_config.headless
+        self._user_data_dir = browser_config.user_data_dir
+        self._stealth = browser_config.stealth
+        self._web_agent_model = web_agent_model
+        self._cache_dir = toolkit_config.cache_dir
+        self._browser_log_to_file = toolkit_config.browser_log_to_file
+        self._default_start_url = browser_config.default_start_url
+        self._session_id = toolkit_config.session_id or "default"
+        self._viewport_limit = browser_config.viewport_limit
+
+        # Store timeout configuration for backward compatibility
+        self._default_timeout = browser_config.default_timeout
+        self._short_timeout = browser_config.short_timeout
+        self._navigation_timeout = browser_config.navigation_timeout
+        self._network_idle_timeout = browser_config.network_idle_timeout
+        self._screenshot_timeout = browser_config.screenshot_timeout
+        self._page_stability_timeout = browser_config.page_stability_timeout
+        self._dom_content_loaded_timeout = (
+            browser_config.dom_content_loaded_timeout
+        )
 
         # Configure enabled tools
         if enabled_tools is None:
@@ -250,42 +206,22 @@ class HybridBrowserToolkit(BaseToolkit):
 
         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
+        # Initialize WebSocket wrapper
+        self._ws_wrapper: Optional[WebSocketBrowserWrapper] = None
+        self._ws_config = self.config_loader.to_ws_config()
 
-    @web_agent_model.setter
-    def web_agent_model(self, value: Optional[BaseModelBackend]) -> None:
-        """Set the web agent model."""
-        self._web_agent_model = value
+    async def _ensure_ws_wrapper(self):
+        """Ensure WebSocket wrapper is initialized."""
+        if self._ws_wrapper is None:
+            self._ws_wrapper = WebSocketBrowserWrapper(self._ws_config)
+            await self._ws_wrapper.start()
 
-    @property
-    def cache_dir(self) -> str:
-        """Get the cache directory."""
-        return self._cache_dir
+    async def _get_ws_wrapper(self) -> WebSocketBrowserWrapper:
+        """Get the WebSocket wrapper, initializing if needed."""
+        await self._ensure_ws_wrapper()
+        if self._ws_wrapper is None:
+            raise RuntimeError("Failed to initialize WebSocket wrapper")
+        return self._ws_wrapper
 
     def __del__(self):
         r"""Cleanup browser resources on garbage collection."""
@@ -300,800 +236,35 @@ class HybridBrowserToolkit(BaseToolkit):
             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)
+                            asyncio.wait_for(self.browser_close(), timeout=2.0)
                         )
                     except asyncio.TimeoutError:
-                        pass  # Skip cleanup if it takes too long
+                        pass
             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
+                pass
         except Exception:
-            # This can happen if browser is not open.
-            return None
+            pass
 
-    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
+    @property
+    def web_agent_model(self) -> Optional[BaseModelBackend]:
+        """Get the web agent model."""
+        return self._web_agent_model
 
-    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"
-            )
+    @web_agent_model.setter
+    def web_agent_model(self, value: Optional[BaseModelBackend]) -> None:
+        """Set the web agent model."""
+        self._web_agent_model = value
 
-        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
+    @property
+    def cache_dir(self) -> str:
+        """Get the cache directory."""
+        return self._cache_dir
 
     # Public API Methods
 
-    async def open_browser(self) -> Dict[str, Any]:
+    async def browser_open(self) -> Dict[str, Any]:
         r"""Starts a new browser session. This must be the first browser
         action.
 
@@ -1103,60 +274,45 @@ class HybridBrowserToolkit(BaseToolkit):
         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.
+                - "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,
-                )
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.open_browser(self._default_start_url)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
 
             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
+            logger.error(f"Failed to open browser: {e}")
+            return {
+                "result": f"Error opening browser: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
-    @action_logger
-    async def close_browser(self) -> str:
+    async def browser_close(self) -> str:
         r"""Closes the browser session, releasing all resources.
 
         This should be called at the end of a task for cleanup.
@@ -1164,18 +320,16 @@ class HybridBrowserToolkit(BaseToolkit):
         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."
+        try:
+            if self._ws_wrapper:
+                await self._ws_wrapper.stop()
+                self._ws_wrapper = None
+            return "Browser session closed."
+        except Exception as e:
+            logger.error(f"Failed to close browser: {e}")
+            return f"Error closing browser: {e}"
 
-    @action_logger
-    async def visit_page(self, url: str) -> Dict[str, Any]:
+    async def browser_visit_page(self, url: str) -> Dict[str, Any]:
         r"""Opens a URL in a new browser tab and switches to it.
 
         Args:
@@ -1190,70 +344,39 @@ class HybridBrowserToolkit(BaseToolkit):
                 - "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):
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.visit_page(url)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to visit page: {e}")
             return {
-                "result": "Error: 'url' must be a non-empty string",
+                "result": f"Error visiting page: {e}",
                 "snapshot": "",
                 "tabs": [],
                 "current_tab": 0,
-                "total_tabs": 1,
+                "total_tabs": 0,
             }
 
-        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}"
-            )
-
-        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]:
+    async def browser_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
@@ -1267,57 +390,39 @@ class HybridBrowserToolkit(BaseToolkit):
                 - "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"
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.back()
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
             )
 
-            # Get tab information
-            tab_info = await self._get_tab_info_for_output()
-
-            return {
-                "result": "Back navigation successful.",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
+            return result
         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()
+            logger.error(f"Failed to navigate back: {e}")
             return {
-                "result": f"Back navigation failed: {e!s}",
-                "snapshot": snapshot,
-                **tab_info,
+                "result": f"Error navigating back: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
             }
 
-    @action_logger
-    async def forward(self) -> Dict[str, Any]:
+    async def browser_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
@@ -1331,164 +436,191 @@ class HybridBrowserToolkit(BaseToolkit):
                 - "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"
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.forward()
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
             )
 
-            # Get tab information
-            tab_info = await self._get_tab_info_for_output()
-
-            return {
-                "result": "Forward navigation successful.",
-                "snapshot": snapshot,
-                **tab_info,
-            }
-
+            return result
         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()
+            logger.error(f"Failed to navigate forward: {e}")
             return {
-                "result": f"Forward navigation failed: {e!s}",
-                "snapshot": snapshot,
-                **tab_info,
+                "result": f"Error navigating forward: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
             }
 
-    @action_logger
-    async def get_page_snapshot(self) -> str:
+    async def browser_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
+        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.
 
+        If viewport_limit is enabled, only elements within the current
+        viewport
+        will be included in the snapshot.
+
         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)
-        )
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            return await ws_wrapper.get_page_snapshot(self._viewport_limit)
+        except Exception as e:
+            logger.error(f"Failed to get page snapshot: {e}")
+            return f"Error capturing snapshot: {e}"
 
     @dependencies_required('PIL')
-    @action_logger
-    async def get_som_screenshot(self):
+    async def browser_get_som_screenshot(
+        self,
+        read_image: bool = True,
+        instruction: Optional[str] = None,
+    ) -> str:
         r"""Captures a screenshot with interactive elements highlighted.
 
-        "SoM" stands for "Set of Marks". This tool takes a screenshot and draws
+        "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.
 
+        Args:
+            read_image (bool, optional): If `True`, the agent will analyze
+                the screenshot. Requires agent to be registered.
+                (default: :obj:`True`)
+            instruction (Optional[str], optional): A specific question or
+                command for the agent regarding the screenshot, used only if
+                `read_image` is `True`. For example: "Find the login button."
+
         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.
+            str: A confirmation message indicating the screenshot was
+                captured, the file path where it was saved, and optionally the
+                agent's analysis if `read_image` is `True`.
         """
-        from PIL import Image
+        import base64
+        import datetime
+        import os
+        import urllib.parse
 
-        from camel.utils.tool_result import ToolResult
+        from camel.utils import sanitize_filename
 
-        os.makedirs(self._cache_dir, exist_ok=True)
-        # Get screenshot and analysis
-        page = await self._require_page()
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.get_som_screenshot()
 
-        # Log screenshot timeout start
-        logger.info(
-            f"Starting screenshot capture"
-            f"with timeout: {self._screenshot_timeout}ms"
-        )
+            # Initialize result text
+            result_text = result.text
+            file_path = None
 
-        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"
-        )
+            # Save screenshot to cache directory if images are available
+            if result.images:
+                # Ensure cache directory exists (use absolute path)
+                cache_dir = os.path.abspath(self._cache_dir)
+                os.makedirs(cache_dir, exist_ok=True)
+
+                # Get current page URL for filename
+                try:
+                    # Try to get the current page URL from the wrapper
+                    page_info = await ws_wrapper.get_tab_info()
+                    current_tab = next(
+                        (tab for tab in page_info if tab.get('is_current')),
+                        None,
+                    )
+                    url = current_tab['url'] if current_tab else 'unknown'
+                except Exception:
+                    url = 'unknown'
+
+                # Generate filename
+                parsed_url = urllib.parse.urlparse(url)
+                url_name = sanitize_filename(
+                    str(parsed_url.path) or 'homepage', max_length=241
+                )
+                timestamp = datetime.datetime.now().strftime("%m%d%H%M%S")
+                file_path = os.path.join(
+                    cache_dir, f"{url_name}_{timestamp}_som.png"
+                )
+
+                # Extract base64 data and save to file
+                for _, image_data in enumerate(result.images):
+                    if image_data.startswith('data:image/png;base64,'):
+                        # Remove data URL prefix
+                        base64_data = image_data.split(',', 1)[1]
+
+                        # Decode and save
+                        image_bytes = base64.b64decode(base64_data)
+                        with open(file_path, 'wb') as f:
+                            f.write(image_bytes)
+
+                        logger.info(f"Screenshot saved to: {file_path}")
+
+                        # Update result text to include file path
+                        result_text += f" (saved to: {file_path})"
+                        break
+
+            # Analyze image if requested and agent is registered
+            if read_image and file_path:
+                if self.agent is None:
+                    logger.error(
+                        "Cannot analyze screenshot: No agent registered. "
+                        "Please pass this toolkit to ChatAgent via "
+                        "toolkits_to_register_agent parameter."
+                    )
+                    result_text += (
+                        " Error: No agent registered for image analysis. "
+                        "Please pass this toolkit to ChatAgent via "
+                        "toolkits_to_register_agent parameter."
+                    )
+                else:
+                    try:
+                        # Load the image and create a message
+                        from PIL import Image
+
+                        img = Image.open(file_path)
+                        inst = instruction if instruction is not None else ""
+                        message = BaseMessage.make_user_message(
+                            role_name="User",
+                            content=inst,
+                            image_list=[img],
+                        )
 
-        return ToolResult(text=text_result, images=[img_data_url])
+                        # Get agent's analysis
+                        response = await self.agent.astep(message)
+                        agent_response = response.msgs[0].content
+                        result_text += f". Agent analysis: {agent_response}"
+                    except Exception as e:
+                        logger.error(f"Error analyzing screenshot: {e}")
+                        result_text += f". Error analyzing screenshot: {e}"
 
-    async def click(self, *, ref: str) -> Dict[str, Any]:
+            return result_text
+        except Exception as e:
+            logger.error(f"Failed to get screenshot: {e}")
+            return f"Error capturing screenshot: {e}"
+
+    async def browser_click(self, *, ref: str) -> Dict[str, Any]:
         r"""Performs a click on an element on the page.
 
         Args:
@@ -1505,155 +637,379 @@ class HybridBrowserToolkit(BaseToolkit):
                 - "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()
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.click(ref)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to click element: {e}")
             return {
-                "result": f"Error: Element reference '{ref}' not found. ",
-                "snapshot": snapshot,
-                **tab_info,
+                "result": f"Error clicking element: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
             }
 
-        element_details = elements.get(ref)
-        action = {"type": "click", "ref": ref}
-        result = await self._exec_with_snapshot(
-            action, element_details=element_details
-        )
+    async def browser_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.
+        """
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.type(ref, text)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to type text: {e}")
+            return {
+                "result": f"Error typing text: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
+
+    async def browser_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.
 
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
+        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.
+        """
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.select(ref, value)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
 
-        return result
+            return result
+        except Exception as e:
+            logger.error(f"Failed to select option: {e}")
+            return {
+                "result": f"Error selecting option: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
+
+    async def browser_scroll(
+        self, *, direction: str, amount: int = 500
+    ) -> 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, default is 500.
+
+        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.
+        """
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.scroll(direction, amount)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to scroll: {e}")
+            return {
+                "result": f"Error scrolling: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
-    async def type(self, *, ref: str, text: str) -> Dict[str, Any]:
-        r"""Types text into an input element on the page.
+    async def browser_enter(self) -> Dict[str, Any]:
+        r"""Simulates pressing the Enter key on the currently focused
+        element.
 
-        Args:
-            ref (str): The `ref` ID of the input element, from a snapshot.
-            text (str): The text to type into the 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 textual snapshot of the page after
-                  typing.
+                - "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.
         """
-        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)
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.enter()
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
 
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
+            return result
+        except Exception as e:
+            logger.error(f"Failed to press enter: {e}")
+            return {
+                "result": f"Error pressing enter: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
-        return result
+    async def browser_switch_tab(self, *, tab_id: str) -> Dict[str, Any]:
+        r"""Switches to a different browser tab using its ID.
 
-    async def select(self, *, ref: str, value: str) -> Dict[str, Any]:
-        r"""Selects an option in a dropdown (`<select>`) element.
+        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:
-            ref (str): The `ref` ID of the `<select>` element.
-            value (str): The `value` attribute of the `<option>` to select,
-                not its visible text.
+            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 page after the
-                  selection.
+                - "snapshot" (str): A snapshot of the newly active tab.
                 - "tabs" (List[Dict]): Information about all open tabs.
-                - "current_tab" (int): Index of the active tab.
+                - "current_tab" (int): Index of the new 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)
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.switch_tab(tab_id)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
 
-        # Add tab information to the result
-        tab_info = await self._get_tab_info_for_output()
-        result.update(tab_info)
+            return result
+        except Exception as e:
+            logger.error(f"Failed to switch tab: {e}")
+            return {
+                "result": f"Error switching tab: {e}",
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
-        return result
+    async def browser_close_tab(self, *, tab_id: str) -> Dict[str, Any]:
+        r"""Closes a browser tab using its ID.
 
-    async def scroll(self, *, direction: str, amount: int) -> Dict[str, Any]:
-        r"""Scrolls the current page window.
+        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:
-            direction (str): The direction to scroll: 'up' or 'down'.
-            amount (int): The number of pixels to scroll.
+            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 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.
+                - "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.
         """
-        if direction not in ("up", "down"):
-            tab_info = await self._get_tab_info_for_output()
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            result = await ws_wrapper.close_tab(tab_id)
+
+            # Add tab information
+            tab_info = await ws_wrapper.get_tab_info()
+            result.update(
+                {
+                    "tabs": tab_info,
+                    "current_tab": next(
+                        (
+                            i
+                            for i, tab in enumerate(tab_info)
+                            if tab.get("is_current")
+                        ),
+                        0,
+                    ),
+                    "total_tabs": len(tab_info),
+                }
+            )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to close tab: {e}")
             return {
-                "result": "Error: direction must be 'up' or 'down'",
+                "result": f"Error closing tab: {e}",
                 "snapshot": "",
-                **tab_info,
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
             }
 
-        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.
+    async def browser_get_tab_info(self) -> Dict[str, Any]:
+        r"""Gets a list of all open browser tabs and their information.
 
-        This is useful for submitting forms or search queries after using the
-        `type` tool.
+        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 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.
+            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.
         """
-        # 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)
+        try:
+            ws_wrapper = await self._get_ws_wrapper()
+            tab_info = await ws_wrapper.get_tab_info()
 
-        return result
+            return {
+                "tabs": tab_info,
+                "current_tab": next(
+                    (
+                        i
+                        for i, tab in enumerate(tab_info)
+                        if tab.get("is_current")
+                    ),
+                    0,
+                ),
+                "total_tabs": len(tab_info),
+            }
+        except Exception as e:
+            logger.error(f"Failed to get tab info: {e}")
+            return {
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
-    @action_logger
-    async def wait_user(
+    # Additional methods for backward compatibility
+    async def browser_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
+        Use this for tasks requiring manual steps, like solving a CAPTCHA.
+        The
         agent will resume after the user presses Enter in the console.
 
         Args:
@@ -1677,7 +1033,13 @@ class HybridBrowserToolkit(BaseToolkit):
         logger.info(f"\n{prompt}\n")
 
         async def _await_enter():
-            await asyncio.to_thread(input, ">>> Press Enter to resume <<<\n")
+            try:
+                await asyncio.to_thread(
+                    input, ">>> Press Enter to resume <<<\n"
+                )
+            except (asyncio.CancelledError, Exception):
+                # Handle cancellation gracefully
+                pass
 
         try:
             if timeout_sec is not None:
@@ -1685,178 +1047,48 @@ class HybridBrowserToolkit(BaseToolkit):
                     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."
+                task = asyncio.create_task(_await_enter())
+                try:
+                    await asyncio.wait_for(task, timeout=timeout_sec)
+                    wait_time = time.time() - start_time
+                    logger.info(f"User input received after {wait_time:.2f}s")
+                    result_msg = "User resumed."
+                except asyncio.TimeoutError:
+                    task.cancel()
+                    # Wait for task to be cancelled properly
+                    try:
+                        await task
+                    except asyncio.CancelledError:
+                        pass
+                    raise
             else:
-                logger.info("Waiting for user " "input (no timeout)")
+                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")
+                logger.info(f"User input received 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"
+                f"User input timeout reached after {wait_time}s, "
+                f"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
+        try:
+            snapshot = await self.browser_get_page_snapshot()
+            tab_info = await self.browser_get_tab_info()
+            return {"result": result_msg, "snapshot": snapshot, **tab_info}
+        except Exception as e:
+            logger.warning(f"Failed to get snapshot after wait: {e}")
+            return {
+                "result": result_msg,
+                "snapshot": "",
+                "tabs": [],
+                "current_tab": 0,
+                "total_tabs": 0,
+            }
 
     def clone_for_new_session(
         self, new_session_id: Optional[str] = None
@@ -1882,7 +1114,8 @@ class HybridBrowserToolkit(BaseToolkit):
             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}/",
+            cache_dir=f"{self._cache_dir.rstrip('/')}_clone_"
+            f"{new_session_id}/",
             enabled_tools=self.enabled_tools.copy(),
             browser_log_to_file=self._browser_log_to_file,
             session_id=new_session_id,
@@ -1896,117 +1129,49 @@ class HybridBrowserToolkit(BaseToolkit):
             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
-            )
-            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()
+    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 = {
+            "browser_open": self.browser_open,
+            "browser_close": self.browser_close,
+            "browser_visit_page": self.browser_visit_page,
+            "browser_back": self.browser_back,
+            "browser_forward": self.browser_forward,
+            "browser_get_page_snapshot": self.browser_get_page_snapshot,
+            "browser_get_som_screenshot": self.browser_get_som_screenshot,
+            "browser_click": self.browser_click,
+            "browser_type": self.browser_type,
+            "browser_select": self.browser_select,
+            "browser_scroll": self.browser_scroll,
+            "browser_enter": self.browser_enter,
+            "browser_wait_user": self.browser_wait_user,
+            "browser_switch_tab": self.browser_switch_tab,
+            "browser_close_tab": self.browser_close_tab,
+            "browser_get_tab_info": self.browser_get_tab_info,
+        }
 
-        success = await session.close_tab(tab_id)
+        enabled_tools = []
 
-        if success:
-            # Get current state after closing the tab
-            try:
-                snapshot = await session.get_snapshot(
-                    force_refresh=True, diff_only=False
+        for tool_name in self.enabled_tools:
+            if (
+                tool_name == "browser_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."
                 )
-            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.
+                continue
 
-        This includes each tab's index, title, and URL, and indicates which
-        tab is currently active. Use this to manage multiple tabs.
+            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}")
 
-        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()
+        logger.info(f"Returning {len(enabled_tools)} enabled tools")
+        return enabled_tools