diff --git a/tests/tools/test_managed_browserbase_and_modal.py b/tests/tools/test_managed_browserbase_and_modal.py index 2e1bec03b01..3d0d7b3419e 100644 --- a/tests/tools/test_managed_browserbase_and_modal.py +++ b/tests/tools/test_managed_browserbase_and_modal.py @@ -10,7 +10,9 @@ from unittest.mock import patch import pytest -TOOLS_DIR = Path(__file__).resolve().parents[2] / "tools" +REPO_ROOT = Path(__file__).resolve().parents[2] +TOOLS_DIR = REPO_ROOT / "tools" +PLUGINS_DIR = REPO_ROOT / "plugins" def _load_tool_module(module_name: str, filename: str): @@ -22,6 +24,21 @@ def _load_tool_module(module_name: str, filename: str): return module +def _load_plugin_module(module_name: str, relpath: str): + """Load a plugin module by file path from ``plugins/``. + + Mirror of :func:`_load_tool_module` for the plugin tree. Used by tests + that exercise the per-vendor browser plugins' session-lifecycle + behaviour after the PR #25214 migration. + """ + spec = spec_from_file_location(module_name, PLUGINS_DIR / relpath) + assert spec and spec.loader + module = module_from_spec(spec) + sys.modules[module_name] = module + spec.loader.exec_module(module) + return module + + def _reset_modules(prefixes: tuple[str, ...]): for name in list(sys.modules): if name.startswith(prefixes): @@ -200,13 +217,13 @@ def test_browserbase_does_not_use_gateway_only_configuration(): }) with patch.dict(os.environ, env, clear=True): - browserbase_module = _load_tool_module( - "tools.browser_providers.browserbase", - "browser_providers/browserbase.py", + browserbase_module = _load_plugin_module( + "plugins.browser.browserbase.provider", + "browser/browserbase/provider.py", ) - provider = browserbase_module.BrowserbaseProvider() + provider = browserbase_module.BrowserbaseBrowserProvider() - assert provider.is_configured() is False + assert provider.is_available() is False def test_browser_use_managed_gateway_adds_idempotency_key_and_persists_external_call_id(): @@ -231,13 +248,13 @@ def test_browser_use_managed_gateway_adds_idempotency_key_and_persists_external_ } with patch.dict(os.environ, env, clear=True): - browser_use_module = _load_tool_module( - "tools.browser_providers.browser_use", - "browser_providers/browser_use.py", + browser_use_module = _load_plugin_module( + "plugins.browser.browser_use.provider", + "browser/browser_use/provider.py", ) with patch.object(browser_use_module.requests, "post", return_value=_Response()) as post: - provider = browser_use_module.BrowserUseProvider() + provider = browser_use_module.BrowserUseBrowserProvider() session = provider.create_session("task-browser-use-managed") sent_headers = post.call_args.kwargs["headers"] @@ -271,11 +288,11 @@ def test_browser_use_managed_gateway_reuses_pending_idempotency_key_after_timeou } with patch.dict(os.environ, env, clear=True): - browser_use_module = _load_tool_module( - "tools.browser_providers.browser_use", - "browser_providers/browser_use.py", + browser_use_module = _load_plugin_module( + "plugins.browser.browser_use.provider", + "browser/browser_use/provider.py", ) - provider = browser_use_module.BrowserUseProvider() + provider = browser_use_module.BrowserUseBrowserProvider() timeout = browser_use_module.requests.Timeout("timed out") with patch.object( @@ -333,11 +350,11 @@ def test_browser_use_managed_gateway_preserves_pending_idempotency_key_for_in_pr } with patch.dict(os.environ, env, clear=True): - browser_use_module = _load_tool_module( - "tools.browser_providers.browser_use", - "browser_providers/browser_use.py", + browser_use_module = _load_plugin_module( + "plugins.browser.browser_use.provider", + "browser/browser_use/provider.py", ) - provider = browser_use_module.BrowserUseProvider() + provider = browser_use_module.BrowserUseBrowserProvider() with patch.object( browser_use_module.requests, @@ -380,11 +397,11 @@ def test_browser_use_managed_gateway_uses_new_idempotency_key_for_a_new_session_ } with patch.dict(os.environ, env, clear=True): - browser_use_module = _load_tool_module( - "tools.browser_providers.browser_use", - "browser_providers/browser_use.py", + browser_use_module = _load_plugin_module( + "plugins.browser.browser_use.provider", + "browser/browser_use/provider.py", ) - provider = browser_use_module.BrowserUseProvider() + provider = browser_use_module.BrowserUseBrowserProvider() with patch.object(browser_use_module.requests, "post", side_effect=[_Response(), _Response()]) as post: provider.create_session("task-browser-use-new") diff --git a/tools/browser_providers/__init__.py b/tools/browser_providers/__init__.py deleted file mode 100644 index 7fa59ef04ee..00000000000 --- a/tools/browser_providers/__init__.py +++ /dev/null @@ -1,10 +0,0 @@ -"""Cloud browser provider abstraction. - -Import the ABC so callers can do:: - - from tools.browser_providers import CloudBrowserProvider -""" - -from tools.browser_providers.base import CloudBrowserProvider - -__all__ = ["CloudBrowserProvider"] diff --git a/tools/browser_providers/base.py b/tools/browser_providers/base.py deleted file mode 100644 index 6b8e1ed4f6b..00000000000 --- a/tools/browser_providers/base.py +++ /dev/null @@ -1,59 +0,0 @@ -"""Abstract base class for cloud browser providers.""" - -from abc import ABC, abstractmethod -from typing import Dict - - -class CloudBrowserProvider(ABC): - """Interface for cloud browser backends (Browserbase, Steel, etc.). - - Implementations live in sibling modules and are registered in - ``browser_tool._PROVIDER_REGISTRY``. The user selects a provider via - ``hermes setup`` / ``hermes tools``; the choice is persisted as - ``config["browser"]["cloud_provider"]``. - """ - - @abstractmethod - def provider_name(self) -> str: - """Short, human-readable name shown in logs and diagnostics.""" - - @abstractmethod - def is_configured(self) -> bool: - """Return True when all required env vars / credentials are present. - - Called at tool-registration time (``check_browser_requirements``) to - gate availability. Must be cheap — no network calls. - """ - - @abstractmethod - def create_session(self, task_id: str) -> Dict[str, object]: - """Create a cloud browser session and return session metadata. - - Must return a dict with at least:: - - { - "session_name": str, # unique name for agent-browser --session - "bb_session_id": str, # provider session ID (for close/cleanup) - "cdp_url": str, # CDP websocket URL - "features": dict, # feature flags that were enabled - } - - ``bb_session_id`` is a legacy key name kept for backward compat with - the rest of browser_tool.py — it holds the provider's session ID - regardless of which provider is in use. - """ - - @abstractmethod - def close_session(self, session_id: str) -> bool: - """Release / terminate a cloud session by its provider session ID. - - Returns True on success, False on failure. Should not raise. - """ - - @abstractmethod - def emergency_cleanup(self, session_id: str) -> None: - """Best-effort session teardown during process exit. - - Called from atexit / signal handlers. Must tolerate missing - credentials, network errors, etc. — log and move on. - """ diff --git a/tools/browser_providers/browser_use.py b/tools/browser_providers/browser_use.py deleted file mode 100644 index a1f4f425ba0..00000000000 --- a/tools/browser_providers/browser_use.py +++ /dev/null @@ -1,225 +0,0 @@ -"""Browser Use cloud browser provider.""" - -import logging -import os -import threading -import uuid -from typing import Any, Dict, Optional - -import requests - -from tools.browser_providers.base import CloudBrowserProvider -from tools.managed_tool_gateway import resolve_managed_tool_gateway -from tools.tool_backend_helpers import managed_nous_tools_enabled, prefers_gateway - -logger = logging.getLogger(__name__) -_pending_create_keys: Dict[str, str] = {} -_pending_create_keys_lock = threading.Lock() - -_BASE_URL = "https://api.browser-use.com/api/v3" -_DEFAULT_MANAGED_TIMEOUT_MINUTES = 5 -_DEFAULT_MANAGED_PROXY_COUNTRY_CODE = "us" - - -def _get_or_create_pending_create_key(task_id: str) -> str: - with _pending_create_keys_lock: - existing = _pending_create_keys.get(task_id) - if existing: - return existing - - created = f"browser-use-session-create:{uuid.uuid4().hex}" - _pending_create_keys[task_id] = created - return created - - -def _clear_pending_create_key(task_id: str) -> None: - with _pending_create_keys_lock: - _pending_create_keys.pop(task_id, None) - - -def _should_preserve_pending_create_key(response: requests.Response) -> bool: - if response.status_code >= 500: - return True - - if response.status_code != 409: - return False - - try: - payload = response.json() - except Exception: - return False - - if not isinstance(payload, dict): - return False - - error = payload.get("error") - if not isinstance(error, dict): - return False - - message = str(error.get("message") or "").lower() - return "already in progress" in message - - -class BrowserUseProvider(CloudBrowserProvider): - """Browser Use (https://browser-use.com) cloud browser backend.""" - - def provider_name(self) -> str: - return "Browser Use" - - def is_configured(self) -> bool: - return self._get_config_or_none() is not None - - # ------------------------------------------------------------------ - # Config resolution (direct API key OR managed Nous gateway) - # ------------------------------------------------------------------ - - def _get_config_or_none(self) -> Optional[Dict[str, Any]]: - api_key = os.environ.get("BROWSER_USE_API_KEY") - if api_key and not prefers_gateway("browser"): - return { - "api_key": api_key, - "base_url": _BASE_URL, - "managed_mode": False, - } - - managed = resolve_managed_tool_gateway("browser-use") - if managed is None: - return None - - return { - "api_key": managed.nous_user_token, - "base_url": managed.gateway_origin.rstrip("/"), - "managed_mode": True, - } - - def _get_config(self) -> Dict[str, Any]: - config = self._get_config_or_none() - if config is None: - message = ( - "Browser Use requires a direct BROWSER_USE_API_KEY credential." - ) - if managed_nous_tools_enabled(): - message = ( - "Browser Use requires either a direct BROWSER_USE_API_KEY " - "credential or a managed Browser Use gateway configuration." - ) - raise ValueError(message) - return config - - # ------------------------------------------------------------------ - # Session lifecycle - # ------------------------------------------------------------------ - - def _headers(self, config: Dict[str, Any]) -> Dict[str, str]: - headers = { - "Content-Type": "application/json", - "X-Browser-Use-API-Key": config["api_key"], - } - return headers - - def create_session(self, task_id: str) -> Dict[str, object]: - config = self._get_config() - managed_mode = bool(config.get("managed_mode")) - - headers = self._headers(config) - if managed_mode: - headers["X-Idempotency-Key"] = _get_or_create_pending_create_key(task_id) - - # Keep gateway-backed sessions short so billing authorization does not - # default to a long Browser-Use timeout when Hermes only needs a task- - # scoped ephemeral browser. - payload = ( - { - "timeout": _DEFAULT_MANAGED_TIMEOUT_MINUTES, - "proxyCountryCode": _DEFAULT_MANAGED_PROXY_COUNTRY_CODE, - } - if managed_mode - else {} - ) - - try: - response = requests.post( - f"{config['base_url']}/browsers", - headers=headers, - json=payload, - timeout=30, - ) - except requests.RequestException as exc: - # Managed mode: propagate raw so callers can retry with the - # preserved idempotency key. Direct mode: wrap network failures - # into a clean RuntimeError for end users. - if managed_mode: - raise - raise RuntimeError( - f"Browser Use API connection failed: {exc}" - ) from exc - - if not response.ok: - if managed_mode and not _should_preserve_pending_create_key(response): - _clear_pending_create_key(task_id) - raise RuntimeError( - f"Failed to create Browser Use session: " - f"{response.status_code} {response.text}" - ) - - session_data = response.json() - if managed_mode: - _clear_pending_create_key(task_id) - session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" - external_call_id = response.headers.get("x-external-call-id") if managed_mode else None - - logger.info("Created Browser Use session %s", session_name) - - cdp_url = session_data.get("cdpUrl") or session_data.get("connectUrl") or "" - - return { - "session_name": session_name, - "bb_session_id": session_data["id"], - "cdp_url": cdp_url, - "features": {"browser_use": True}, - "external_call_id": external_call_id, - } - - def close_session(self, session_id: str) -> bool: - try: - config = self._get_config() - except ValueError: - logger.warning("Cannot close Browser Use session %s — missing credentials", session_id) - return False - - try: - response = requests.patch( - f"{config['base_url']}/browsers/{session_id}", - headers=self._headers(config), - json={"action": "stop"}, - timeout=10, - ) - if response.status_code in {200, 201, 204}: - logger.debug("Successfully closed Browser Use session %s", session_id) - return True - else: - logger.warning( - "Failed to close Browser Use session %s: HTTP %s - %s", - session_id, - response.status_code, - response.text[:200], - ) - return False - except Exception as e: - logger.error("Exception closing Browser Use session %s: %s", session_id, e) - return False - - def emergency_cleanup(self, session_id: str) -> None: - config = self._get_config_or_none() - if config is None: - logger.warning("Cannot emergency-cleanup Browser Use session %s — missing credentials", session_id) - return - try: - requests.patch( - f"{config['base_url']}/browsers/{session_id}", - headers=self._headers(config), - json={"action": "stop"}, - timeout=5, - ) - except Exception as e: - logger.debug("Emergency cleanup failed for Browser Use session %s: %s", session_id, e) diff --git a/tools/browser_providers/browserbase.py b/tools/browser_providers/browserbase.py deleted file mode 100644 index 4807345214b..00000000000 --- a/tools/browser_providers/browserbase.py +++ /dev/null @@ -1,222 +0,0 @@ -"""Browserbase cloud browser provider (direct credentials only).""" - -import logging -import os -import uuid -from typing import Any, Dict, Optional - -import requests - -from tools.browser_providers.base import CloudBrowserProvider - -logger = logging.getLogger(__name__) - - -class BrowserbaseProvider(CloudBrowserProvider): - """Browserbase (https://browserbase.com) cloud browser backend. - - This provider requires direct BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID - credentials. Managed Nous gateway support has been removed — the Nous - subscription now routes through Browser Use instead. - """ - - def provider_name(self) -> str: - return "Browserbase" - - def is_configured(self) -> bool: - return self._get_config_or_none() is not None - - # ------------------------------------------------------------------ - # Session lifecycle - # ------------------------------------------------------------------ - - def _get_config_or_none(self) -> Optional[Dict[str, Any]]: - api_key = os.environ.get("BROWSERBASE_API_KEY") - project_id = os.environ.get("BROWSERBASE_PROJECT_ID") - if api_key and project_id: - return { - "api_key": api_key, - "project_id": project_id, - "base_url": os.environ.get("BROWSERBASE_BASE_URL", "https://api.browserbase.com").rstrip("/"), - } - return None - - def _get_config(self) -> Dict[str, Any]: - config = self._get_config_or_none() - if config is None: - raise ValueError( - "Browserbase requires BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID " - "environment variables." - ) - return config - - def create_session(self, task_id: str) -> Dict[str, object]: - config = self._get_config() - - # Optional env-var knobs - enable_proxies = os.environ.get("BROWSERBASE_PROXIES", "true").lower() != "false" - enable_advanced_stealth = os.environ.get("BROWSERBASE_ADVANCED_STEALTH", "false").lower() == "true" - enable_keep_alive = os.environ.get("BROWSERBASE_KEEP_ALIVE", "true").lower() != "false" - custom_timeout_ms = os.environ.get("BROWSERBASE_SESSION_TIMEOUT") - - features_enabled = { - "basic_stealth": True, - "proxies": False, - "advanced_stealth": False, - "keep_alive": False, - "custom_timeout": False, - } - - session_config: Dict[str, object] = {"projectId": config["project_id"]} - - if enable_keep_alive: - session_config["keepAlive"] = True - - if custom_timeout_ms: - try: - timeout_val = int(custom_timeout_ms) - if timeout_val > 0: - session_config["timeout"] = timeout_val - except ValueError: - logger.warning("Invalid BROWSERBASE_SESSION_TIMEOUT value: %s", custom_timeout_ms) - - if enable_proxies: - session_config["proxies"] = True - - if enable_advanced_stealth: - session_config["browserSettings"] = {"advancedStealth": True} - - # --- Create session via API --- - headers = { - "Content-Type": "application/json", - "X-BB-API-Key": config["api_key"], - } - - try: - response = requests.post( - f"{config['base_url']}/v1/sessions", - headers=headers, - json=session_config, - timeout=30, - ) - - proxies_fallback = False - keepalive_fallback = False - - # Handle 402 — paid features unavailable - if response.status_code == 402: - if enable_keep_alive: - keepalive_fallback = True - logger.warning( - "keepAlive may require paid plan (402), retrying without it. " - "Sessions may timeout during long operations." - ) - session_config.pop("keepAlive", None) - response = requests.post( - f"{config['base_url']}/v1/sessions", - headers=headers, - json=session_config, - timeout=30, - ) - - if response.status_code == 402 and enable_proxies: - proxies_fallback = True - logger.warning( - "Proxies unavailable (402), retrying without proxies. " - "Bot detection may be less effective." - ) - session_config.pop("proxies", None) - response = requests.post( - f"{config['base_url']}/v1/sessions", - headers=headers, - json=session_config, - timeout=30, - ) - except requests.RequestException as exc: - raise RuntimeError( - f"Browserbase API connection failed: {exc}" - ) from exc - - if not response.ok: - raise RuntimeError( - f"Failed to create Browserbase session: " - f"{response.status_code} {response.text}" - ) - - session_data = response.json() - session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" - - if enable_proxies and not proxies_fallback: - features_enabled["proxies"] = True - if enable_advanced_stealth: - features_enabled["advanced_stealth"] = True - if enable_keep_alive and not keepalive_fallback: - features_enabled["keep_alive"] = True - if custom_timeout_ms and "timeout" in session_config: - features_enabled["custom_timeout"] = True - - feature_str = ", ".join(k for k, v in features_enabled.items() if v) - logger.info("Created Browserbase session %s with features: %s", session_name, feature_str) - - return { - "session_name": session_name, - "bb_session_id": session_data["id"], - "cdp_url": session_data["connectUrl"], - "features": features_enabled, - } - - def close_session(self, session_id: str) -> bool: - try: - config = self._get_config() - except ValueError: - logger.warning("Cannot close Browserbase session %s — missing credentials", session_id) - return False - - try: - response = requests.post( - f"{config['base_url']}/v1/sessions/{session_id}", - headers={ - "X-BB-API-Key": config["api_key"], - "Content-Type": "application/json", - }, - json={ - "projectId": config["project_id"], - "status": "REQUEST_RELEASE", - }, - timeout=10, - ) - if response.status_code in {200, 201, 204}: - logger.debug("Successfully closed Browserbase session %s", session_id) - return True - else: - logger.warning( - "Failed to close session %s: HTTP %s - %s", - session_id, - response.status_code, - response.text[:200], - ) - return False - except Exception as e: - logger.error("Exception closing Browserbase session %s: %s", session_id, e) - return False - - def emergency_cleanup(self, session_id: str) -> None: - config = self._get_config_or_none() - if config is None: - logger.warning("Cannot emergency-cleanup Browserbase session %s — missing credentials", session_id) - return - try: - requests.post( - f"{config['base_url']}/v1/sessions/{session_id}", - headers={ - "X-BB-API-Key": config["api_key"], - "Content-Type": "application/json", - }, - json={ - "projectId": config["project_id"], - "status": "REQUEST_RELEASE", - }, - timeout=5, - ) - except Exception as e: - logger.debug("Emergency cleanup failed for Browserbase session %s: %s", session_id, e) diff --git a/tools/browser_providers/firecrawl.py b/tools/browser_providers/firecrawl.py deleted file mode 100644 index 4a8ae82a2d2..00000000000 --- a/tools/browser_providers/firecrawl.py +++ /dev/null @@ -1,112 +0,0 @@ -"""Firecrawl cloud browser provider.""" - -import logging -import os -import uuid -from typing import Dict - -import requests - -from tools.browser_providers.base import CloudBrowserProvider - -logger = logging.getLogger(__name__) - -_BASE_URL = "https://api.firecrawl.dev" - - -class FirecrawlProvider(CloudBrowserProvider): - """Firecrawl (https://firecrawl.dev) cloud browser backend.""" - - def provider_name(self) -> str: - return "Firecrawl" - - def is_configured(self) -> bool: - return bool(os.environ.get("FIRECRAWL_API_KEY")) - - # ------------------------------------------------------------------ - # Session lifecycle - # ------------------------------------------------------------------ - - def _api_url(self) -> str: - return os.environ.get("FIRECRAWL_API_URL", _BASE_URL) - - def _headers(self) -> Dict[str, str]: - api_key = os.environ.get("FIRECRAWL_API_KEY") - if not api_key: - raise ValueError( - "FIRECRAWL_API_KEY environment variable is required. " - "Get your key at https://firecrawl.dev" - ) - return { - "Content-Type": "application/json", - "Authorization": f"Bearer {api_key}", - } - - def create_session(self, task_id: str) -> Dict[str, object]: - ttl = int(os.environ.get("FIRECRAWL_BROWSER_TTL", "300")) - - body: Dict[str, object] = {"ttl": ttl} - - try: - response = requests.post( - f"{self._api_url()}/v2/browser", - headers=self._headers(), - json=body, - timeout=30, - ) - except requests.RequestException as exc: - raise RuntimeError( - f"Firecrawl API connection failed: {exc}" - ) from exc - - if not response.ok: - raise RuntimeError( - f"Failed to create Firecrawl browser session: " - f"{response.status_code} {response.text}" - ) - - data = response.json() - session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" - - logger.info("Created Firecrawl browser session %s", session_name) - - return { - "session_name": session_name, - "bb_session_id": data["id"], - "cdp_url": data["cdpUrl"], - "features": {"firecrawl": True}, - } - - def close_session(self, session_id: str) -> bool: - try: - response = requests.delete( - f"{self._api_url()}/v2/browser/{session_id}", - headers=self._headers(), - timeout=10, - ) - if response.status_code in {200, 201, 204}: - logger.debug("Successfully closed Firecrawl session %s", session_id) - return True - else: - logger.warning( - "Failed to close Firecrawl session %s: HTTP %s - %s", - session_id, - response.status_code, - response.text[:200], - ) - return False - except Exception as e: - logger.error("Exception closing Firecrawl session %s: %s", session_id, e) - return False - - def emergency_cleanup(self, session_id: str) -> None: - try: - requests.delete( - f"{self._api_url()}/v2/browser/{session_id}", - headers=self._headers(), - timeout=5, - ) - except ValueError: - logger.warning("Cannot emergency-cleanup Firecrawl session %s — missing credentials", session_id) - except Exception as e: - logger.debug("Emergency cleanup failed for Firecrawl session %s: %s", session_id, e)