{"repo":"NousResearch/hermes-agent","public_id":"25214","display_label":"Refactor cloud browser providers as plugin architecture","summary":"These items concern migrating cloud browser providers to follow an image_gen-style plugin pattern. The work involves restructuring browser provider integrations similarly to how image generation providers are organized.","subsystem":null,"counts":{"members":3,"open_issues":0,"open_issues_distinct":0,"open_prs":0,"closed_issues":1,"merged_prs":1,"attempt_prs":1},"landed_fix":{"status":"merged_to_main","basis":"structural","pr":27403,"merged_at":"2026-05-17T11:04:16+00:00"},"resolution":{"state":"resolved","by":"pr-27403"},"freshness":{"state":"verified","last_verified_at":"2026-05-17T11:04:16+00:00","is_stale":false},"grouping":{"backbone":"STRUCTURAL_SPANNING","link_density":1.0},"fix_edges":[{"issue_number":25214,"pr_number":27403,"tier":"verified","basis":"closing_ref","confidence":0.95,"recoverable_from_timeline":true,"pr_merged_at":"2026-05-17T11:04:16+00:00"}],"members":[{"kind":"issue","number":25214,"title":"Mirror web-provider plugin migration for browser providers","url":null,"state":"closed"},{"kind":"pr","number":25580,"title":"refactor(browser): all cloud browser providers as image_gen-style plugins (closes #25214)","url":null,"state":"closed","close_reason":{"refs":[{"kind":"commit","value":"c6e6909e5","number":0},{"kind":"commit","value":"c74ff2c8e","number":0},{"kind":"commit","value":"f36c89cd5","number":0},{"kind":"pr","value":"#27403","number":27403},{"kind":"pr","value":"#2746","number":2746},{"kind":"pr","value":"#25214","number":25214}],"category":"merged_via","implication":"superseded"},"merged":false},{"kind":"pr","number":27403,"title":"refactor(browser): all cloud browser providers as image_gen-style plugins (#25214, salvages #25580)","url":null,"state":"merged","close_reason":{"category":"merged"},"merged":true,"is_fix_pr":true,"fix_tier":"verified","files_changed":["agent/browser_provider.py","agent/browser_registry.py","hermes_cli/plugins.py","hermes_cli/tools_config.py","plugins/browser/browser_use/__init__.py","plugins/browser/browser_use/plugin.yaml","plugins/browser/browser_use/provider.py","plugins/browser/browserbase/__init__.py","plugins/browser/browserbase/plugin.yaml","plugins/browser/browserbase/provider.py","plugins/browser/firecrawl/__init__.py","plugins/browser/firecrawl/plugin.yaml","plugins/browser/firecrawl/provider.py","tests/plugins/browser/__init__.py","tests/plugins/browser/check_parity_vs_main.py","tests/plugins/browser/test_browser_provider_plugins.py","tests/tools/test_managed_browserbase_and_modal.py","tools/browser_providers/__init__.py","tools/browser_providers/base.py","tools/browser_tool.py"],"fix_hunks":[{"file":"agent/browser_provider.py","hunks":["@@ -0,0 +1,175 @@\n+\"\"\"\n+Browser Provider ABC\n+====================\n+\n+Defines the pluggable-backend interface for cloud browser providers\n+(Browserbase, Browser Use, Firecrawl, …). Providers register instances via\n+:meth:`PluginContext.register_browser_provider`; the active one (selected via\n+``browser.cloud_provider`` in ``config.yaml``) services every cloud-mode\n+``browser_*`` tool call.\n+\n+Providers live in ``/plugins/browser//`` (built-in, auto-loaded as\n+``kind: backend``) or ``~/.hermes/plugins/browser//`` (user, opt-in via\n+``plugins.enabled``).\n+\n+This ABC mirrors :class:`agent.web_search_provider.WebSearchProvider` (PR\n+#25182) — same shape, same registration flow, same picker integration. The\n+legacy in-tree ``tools.browser_providers.base.CloudBrowserProvider`` ABC was\n+deleted in PR #25214 (this work) along with the per-vendor inline modules in\n+``tools/browser_providers/``; the lifecycle contract documented below is\n+preserved bit-for-bit so the tool wrapper (:mod:`tools.browser_tool`) does\n+not have to translate.\n+\n+Session metadata contract (preserved from the legacy ``CloudBrowserProvider``)::\n+\n+ {\n+ \"session_name\": str, # unique name for agent-browser --session\n+ \"bb_session_id\": str, # provider session ID (for close/cleanup)\n+ \"cdp_url\": str, # CDP websocket URL\n+ \"features\": dict, # feature flags that were enabled\n+ \"external_call_id\": str, # optional, managed-gateway billing key\n+ }\n+\n+``bb_session_id`` is a legacy key name kept verbatim for backward compat with\n+:mod:`tools.browser_tool` — it holds the provider's session ID regardless of\n+which provider is in use.\n+\"\"\"\n+\n+from __future__ import annotations\n+\n+import abc\n+from typing import Any, Dict\n+\n+\n+# ---------------------------------------------------------------------------\n+# ABC\n+# ---------------------------------------------------------------------------\n+\n+\n+class BrowserProvider(abc.ABC):\n+ \"\"\"Abstract base class for a cloud browser backend.\n+\n+ Subclasses must implement :meth:`name`, :meth:`is_available`, and the\n+ three lifecycle methods: :meth:`create_session`, :meth:`close_session`,\n+ :meth:`emergency_cleanup`.\n+\n+ The lifecycle shape preserves the legacy ``CloudBrowserProvider`` contract\n+ bit-for-bit so the dispatcher in :mod:`tools.browser_tool` is a pure\n+ registry lookup — no per-provider conditionals, no shape translation.\n+ \"\"\"\n+\n+ @property\n+ @abc.abstractmethod\n+ def name(self) -> str:\n+ \"\"\"Stable short identifier used in the ``browser.cloud_provider``\n+ config key.\n+\n+ Lowercase, hyphens permitted to preserve existing user-visible names.\n+ Examples: ``browserbase``, ``browser-use``, ``firecrawl``.\n+ \"\"\"\n+\n+ @property\n+ def display_name(self) -> str:\n+ \"\"\"Human-readable label shown in ``hermes tools``. Defaults to ``name``.\"\"\"\n+ return self.name\n+\n+ @abc.abstractmethod\n+ def is_available(self) -> bool:\n+ \"\"\"Return True when this provider can service calls.\n+\n+ Typically a cheap check (env var present, managed-gateway token\n+ readable, optional Python dep importable). Must NOT make network\n+ calls — this runs at tool-registration time and on every\n+ ``hermes tools`` paint.\n+\n+ Mirrors the legacy ``CloudBrowserProvider.is_configured()`` method;\n+ renamed for parity with :class:`agent.web_search_provider.WebSearchProvider`.\n+ \"\"\"\n+\n+ @abc.abstractmethod\n+ def create_session(self, task_id: str) -> Dict[str, object]:\n+ \"\"\"Create a cloud browser session and return session metadata.\n+\n+ Must return a dict with at least::\n+\n+ {\n+ \"session_name\": str, # unique name for agent-browser --session\n+ \"bb_session_id\": str, # provider session ID (for close/cleanup)\n+ \"cdp_url\": str, # CDP websocket URL\n+ \"features\": dict, # feature flags that were enabled\n+ }\n+\n+ ``bb_session_id`` is a legacy key name kept for backward compat with\n+ the rest of :mod:`tools.browser_tool` — it holds the provider's\n+ session ID regardless of which provider is in use.\n+\n+ May raise ``ValueError`` (missing credentials) or ``RuntimeError``\n+ (network / API failure); the dispatcher surfaces these to the user.\n+ \"\"\"\n+\n+ @abc.abstractmethod\n+ def close_session(self, session_id: str) -> bool:\n+ \"\"\"Release / terminate a cloud session by its provider session ID.\n+\n+ Returns True on success, False on failure. Should not raise — log and\n+ return False on any exception so the dispatcher's cleanup loop keeps\n+ moving across sessions.\n+ \"\"\"\n+\n+ @abc.abstractmethod\n+ def emergency_cleanup(self, session_id: str) -> None:\n+ \"\"\"Best-effort session teardown during process exit.\n+\n+ Called from atexit / signal handlers. Must tolerate missing\n+ credentials, network errors, etc. — log and move on. Must not raise.\n+ \"\"\"\n+\n+ def get_setup_schema(self) -> Dict[str, Any]:\n+ \"\"\"Return provider metadata for the ``hermes tools`` picker.\n+\n+ Used by :mod:`hermes_cli.tools_config` to inject this provider as a\n+ row in the Browser Automation picker. Shape mirrors the existing\n+ hardcoded entries in ``TOOL_CATEGORIES[\"browser\"]``::\n+\n+ {\n+ \"name\": \"Browserbase\",\n+ \"badge\": \"paid\",\n+ \"tag\": \"Cloud browser with stealth and proxies\",\n+ \"env_vars\": [\n+ {\"key\": \"BROWSERBASE_API_KEY\",\n+ \"prompt\": \"Browserbase API key\",\n+ \"url\": \"https://browserbase.com\"},\n+ ],\n+ \"post_setup\": \"agent_browser\",\n+ }\n+\n+ Default: minimal entry derived from :attr:`display_name`. Override to\n+ expose API key prompts, badges, managed-Nous gating, and the\n+ ``post_setup`` install hook.\n+ \"\"\"\n+ return {\n+ \"name\": self.display_name,\n+ \"badge\": \"\",\n+ \"tag\": \"\",\n+ \"env_vars\": [],\n+ }\n+\n+ # ------------------------------------------------------------------\n+ # Backward-compat shims for the legacy CloudBrowserProvider API\n+ # ------------------------------------------------------------------\n+ #\n+ # The pre-PR-#25214 ABC exposed ``is_configured()`` and ``provider_name()``;\n+ # ``tools.browser_tool`` has ~6 callers that still use those names. Rather\n+ # than churn every callsite (and break out-of-tree downstream code that\n+ # subclassed CloudBrowserProvider), we expose the old names as thin\n+ # delegations to the new API. Subclasses MUST implement :meth:`is_available`\n+ # and :attr:`name`; they may override ``is_configured`` / ``provider_name``\n+ # for compatibility with the legacy ABC but it is not required.\n+\n+ def is_configured(self) -> bool:\n+ \"\"\"Backward-compat alias for :meth:`is_available`.\"\"\"\n+ return self.is_available()\n+\n+ def provider_name(self) -> str:\n+ \"\"\"Backward-compat alias returning :attr:`display_name`.\"\"\"\n+ return self.display_name"]},{"file":"agent/browser_registry.py","hunks":["@@ -0,0 +1,223 @@\n+\"\"\"\n+Browser Provider Registry\n+=========================\n+\n+Central map of registered cloud browser providers. Populated by plugins at\n+import-time via :meth:`PluginContext.register_browser_provider`; consumed by\n+:func:`tools.browser_tool._get_cloud_provider` to route each cloud-mode\n+``browser_*`` tool call to the active backend.\n+\n+Active selection\n+----------------\n+The active provider is chosen by configuration with this precedence:\n+\n+1. ``browser.cloud_provider`` in ``config.yaml`` (explicit override).\n+2. Legacy preference order — ``browser-use`` → ``browserbase`` — filtered by\n+ availability. Matches the historic auto-detect order in\n+ :func:`tools.browser_tool._get_cloud_provider` (Browser Use checked first\n+ because it covers both the managed Nous gateway and direct API key path;\n+ Browserbase as the older direct-credentials fallback). ``firecrawl`` is\n+ intentionally NOT in the legacy walk — users only get Firecrawl as a\n+ cloud browser when they explicitly set ``browser.cloud_provider:\n+ firecrawl``, matching pre-migration behaviour where Firecrawl was never\n+ auto-selected.\n+3. Otherwise ``None`` — the dispatcher falls back to local browser mode.\n+\n+The explicit-config branch (rule 1) intentionally ignores ``is_available()``\n+so the dispatcher surfaces a typed \"X_API_KEY is not set\" error to the user\n+instead of silently switching backends. Matches the legacy\n+:func:`tools.browser_tool._get_cloud_provider` behaviour for configured names.\n+\n+Note: there is no \"capability\" split here (unlike the web subsystem, which\n+has search/extract/crawl). Every browser provider implements the full\n+:class:`agent.browser_provider.BrowserProvider` lifecycle; the registry's\n+job is purely selection, not capability routing.\n+\"\"\"\n+\n+from __future__ import annotations\n+\n+import logging\n+import threading\n+from typing import Dict, List, Optional\n+\n+from agent.browser_provider import BrowserProvider\n+\n+logger = logging.getLogger(__name__)\n+\n+\n+_providers: Dict[str, BrowserProvider] = {}\n+_lock = threading.Lock()\n+\n+\n+def register_provider(provider: BrowserProvider) -> None:\n+ \"\"\"Register a cloud browser provider.\n+\n+ Re-registration (same ``name``) overwrites the previous entry and logs\n+ a debug message — makes hot-reload scenarios (tests, dev loops) behave\n+ predictably.\n+ \"\"\"\n+ if not isinstance(provider, BrowserProvider):\n+ raise TypeError(\n+ f\"register_provider() expects a BrowserProvider instance, \"\n+ f\"got {type(provider).__name__}\"\n+ )\n+ name = provider.name\n+ if not isinstance(name, str) or not name.strip():\n+ raise ValueError(\"Browser provider .name must be a non-empty string\")\n+ with _lock:\n+ existing = _providers.get(name)\n+ _providers[name] = provider\n+ if existing is not None:\n+ logger.debug(\n+ \"Browser provider '%s' re-registered (was %r)\",\n+ name, type(existing).__name__,\n+ )\n+ else:\n+ logger.debug(\n+ \"Registered browser provider '%s' (%s)\",\n+ name, type(provider).__name__,\n+ )\n+\n+\n+def list_providers() -> List[BrowserProvider]:\n+ \"\"\"Return all registered providers, sorted by name.\"\"\"\n+ with _lock:\n+ items = list(_providers.values())\n+ return sorted(items, key=lambda p: p.name)\n+\n+\n+def get_provider(name: str) -> Optional[BrowserProvider]:\n+ \"\"\"Return the provider registered under *name*, or None.\"\"\"\n+ if not isinstance(name, str):\n+ return None\n+ with _lock:\n+ return _providers.get(name.strip())\n+\n+\n+# ---------------------------------------------------------------------------\n+# Active-provider resolution\n+# ---------------------------------------------------------------------------\n+\n+\n+# Legacy auto-detect order — used when no ``browser.cloud_provider`` is set.\n+# Matches the pre-migration walk in :func:`tools.browser_tool._get_cloud_provider`.\n+# Firecrawl is intentionally absent so users with ``FIRECRAWL_API_KEY`` set\n+# for web-extract don't get silently routed to a paid cloud browser. See\n+# :func:`_resolve` for the full rationale.\n+_LEGACY_PREFERENCE = (\n+ \"browser-use\",\n+ \"browserbase\",\n+)\n+\n+\n+def _resolve(configured: Optional[str]) -> Optional[BrowserProvider]:\n+ \"\"\"Resolve the active browser provider.\n+\n+ Resolution rules (in order):\n+\n+ 1. **Explicit \"local\".** Returns None — the dispatcher disables cloud\n+ mode entirely. Mirrors legacy short-circuit in\n+ :func:`tools.browser_tool._get_cloud_provider`.\n+ 2. **Explicit config wins, ignoring availability.** If ``configured``\n+ names a registered provider, return it even if its\n+ :meth:`is_available` returns False — the dispatcher will surface a\n+ precise \"X_API_KEY is not set\" error instead of silently routing\n+ somewhere else.\n+ 3. **Legacy preference walk, filtered by availability.** Walk\n+ :data:`_LEGACY_PREFERENCE` (``browser-use`` → ``browserbase``) looking\n+ for a provider whose ``is_available()`` is True.\n+\n+ There is intentionally NO \"single-eligible shortcut\" rule here (unlike\n+ :func:`agent.web_search_registry._resolve`). Pre-migration, the\n+ auto-detect branch in ``tools.browser_tool._get_cloud_provider`` only\n+ considered Browser Use and Browserbase; Firecrawl was reachable only\n+ via an explicit ``browser.cloud_provider: firecrawl`` config key.\n+ Preserving that gate matters because Firecrawl shares its API key with\n+ the *web* extract plugin (``plugins/web/firecrawl/``), so users who set\n+ ``FIRECRAWL_API_KEY`` for web extract must NOT get silently routed to a\n+ paid cloud browser on a fresh install. Third-party browser-provider\n+ plugins added under ``~/.hermes/plugins/browser//`` are subject\n+ to the same gate — they must be explicitly configured to take effect.\n+\n+ Returns None when no provider is configured AND no available provider\n+ matches the legacy preference; the dispatcher then falls back to local\n+ browser mode.\n+ \"\"\"\n+ with _lock:\n+ snapshot = dict(_providers)\n+\n+ def _is_available_safe(p: BrowserProvider) -> bool:\n+ \"\"\"Wrap ``is_available()`` so a buggy provider doesn't kill resolution.\"\"\"\n+ try:\n+ return bool(p.is_available())\n+ except Exception as exc: # noqa: BLE001\n+ logger.warning(\n+ \"Browser provider %s.is_available() raised %s — treating as unavailable\",\n+ p.name, exc, exc_info=True,\n+ )\n+ return False\n+\n+ # 1. Explicit \"local\" short-circuit.\n+ if configured == \"local\":\n+ return None\n+\n+ # 2. Explicit config wins — return regardless of is_available() so the\n+ # user gets a precise downstream error message rather than a silent\n+ # backend switch. Matches _get_cloud_provider() in browser_tool.py.\n+ if configured:\n+ provider = snapshot.get(configured)\n+ if provider is not None:\n+ return provider\n+ logger.debug(\n+ \"browser cloud_provider '%s' configured but not registered; \"\n+ \"falling back to auto-detect\",\n+ configured,\n+ )\n+\n+ # 3. Legacy preference walk — only providers in _LEGACY_PREFERENCE are\n+ # auto-eligible. Filtered by availability so we don't surface a\n+ # provider the user has no credentials for. See docstring for why\n+ # we do NOT fall back to \"any single-eligible registered provider\".\n+ for legacy in _LEGACY_PREFERENCE:\n+ provider = snapshot.get(legacy)\n+ if provider is not None and _is_available_safe(provider):\n+ return provider\n+\n+ return None\n+\n+\n+def get_active_browser_provider() -> Optional[BrowserProvider]:\n+ \"\"\"Resolve the currently-active cloud browser provider.\n+\n+ Reads ``browser.cloud_provider`` from config.yaml; falls back per the\n+ module docstring. Returns None for local mode or when no provider is\n+ available.\n+ \"\"\"\n+ try:\n+ from hermes_cli.config import read_raw_config\n+\n+ cfg = read_raw_config()\n+ browser_cfg = cfg.get(\"browser\", {})\n+ except Exception as exc:\n+ logger.debug(\"Could not read browser config: %s\", exc)\n+ browser_cfg = {}\n+\n+ configured: Optional[str] = None\n+ if isinstance(browser_cfg, dict) and \"cloud_provider\" in browser_cfg:\n+ try:\n+ from tools.tool_backend_helpers import normalize_browser_cloud_provider\n+\n+ configured = normalize_browser_cloud_provider(\n+ browser_cfg.get(\"cloud_provider\")\n+ )\n+ except Exception as exc:\n+ logger.debug(\"normalize_browser_cloud_provider failed: %s\", exc)\n+ configured = None\n+\n+ return _resolve(configured)\n+\n+\n+def _reset_for_tests() -> None:\n+ \"\"\"Clear the registry. **Test-only.**\"\"\"\n+ with _lock:\n+ _providers.clear()"]},{"file":"hermes_cli/plugins.py","hunks":["@@ -608,6 +608,38 @@ def register_web_search_provider(self, provider) -> None:\n self.manifest.name, provider.name,\n )\n \n+ # -- browser provider registration ---------------------------------------\n+\n+ def register_browser_provider(self, provider) -> None:\n+ \"\"\"Register a cloud browser backend.\n+\n+ ``provider`` must be an instance of\n+ :class:`agent.browser_provider.BrowserProvider`. The\n+ ``provider.name`` attribute is what ``browser.cloud_provider`` in\n+ ``config.yaml`` matches against when routing cloud-mode\n+ ``browser_*`` tool calls.\n+\n+ Mirrors :meth:`register_web_search_provider` exactly — same\n+ registration shape, same gating, same logging. The browser\n+ subsystem's dispatcher (:func:`tools.browser_tool._get_cloud_provider`)\n+ consults the registry built up by these calls.\n+ \"\"\"\n+ from agent.browser_provider import BrowserProvider\n+ from agent.browser_registry import register_provider as _register_browser_provider\n+\n+ if not isinstance(provider, BrowserProvider):\n+ logger.warning(\n+ \"Plugin '%s' tried to register a browser provider that does \"\n+ \"not inherit from BrowserProvider. Ignoring.\",\n+ self.manifest.name,\n+ )\n+ return\n+ _register_browser_provider(provider)\n+ logger.info(\n+ \"Plugin '%s' registered browser provider: %s\",\n+ self.manifest.name, provider.name,\n+ )\n+\n # -- platform adapter registration ---------------------------------------\n \n def register_platform("]},{"file":"hermes_cli/tools_config.py","hunks":["@@ -378,6 +378,17 @@ def _get_plugin_toolset_keys() -> set:\n \"browser\": {\n \"name\": \"Browser Automation\",\n \"icon\": \"🌐\",\n+ # Per-provider rows for Browserbase, Browser Use, and Firecrawl are\n+ # injected at runtime from plugins.browser..provider via\n+ # _plugin_browser_providers() in _visible_providers(). Only\n+ # non-provider UX setup-flow rows remain here:\n+ # - \"Nous Subscription (Browser Use cloud)\" — managed Browser Use\n+ # billed via Nous subscription (requires_nous_auth +\n+ # override_env_vars). Uses the browser-use plugin as the\n+ # underlying backend but has a distinct setup UX.\n+ # - \"Local Browser\" — non-cloud option, no CloudBrowserProvider.\n+ # - \"Camofox\" — anti-detection local Firefox; short-circuits the\n+ # cloud-provider dispatch path via _is_camofox_mode().\n \"providers\": [\n {\n \"name\": \"Nous Subscription (Browser Use cloud)\",","@@ -398,37 +409,6 @@ def _get_plugin_toolset_keys() -> set:\n \"browser_provider\": \"local\",\n \"post_setup\": \"agent_browser\",\n },\n- {\n- \"name\": \"Browserbase\",\n- \"badge\": \"paid\",\n- \"tag\": \"Cloud browser with stealth and proxies\",\n- \"env_vars\": [\n- {\"key\": \"BROWSERBASE_API_KEY\", \"prompt\": \"Browserbase API key\", \"url\": \"https://browserbase.com\"},\n- {\"key\": \"BROWSERBASE_PROJECT_ID\", \"prompt\": \"Browserbase project ID\"},\n- ],\n- \"browser_provider\": \"browserbase\",\n- \"post_setup\": \"agent_browser\",\n- },\n- {\n- \"name\": \"Browser Use\",\n- \"badge\": \"paid\",\n- \"tag\": \"Cloud browser with remote execution\",\n- \"env_vars\": [\n- {\"key\": \"BROWSER_USE_API_KEY\", \"prompt\": \"Browser Use API key\", \"url\": \"https://browser-use.com\"},\n- ],\n- \"browser_provider\": \"browser-use\",\n- \"post_setup\": \"agent_browser\",\n- },\n- {\n- \"name\": \"Firecrawl\",\n- \"badge\": \"paid\",\n- \"tag\": \"Cloud browser with remote execution\",\n- \"env_vars\": [\n- {\"key\": \"FIRECRAWL_API_KEY\", \"prompt\": \"Firecrawl API key\", \"url\": \"https://firecrawl.dev\"},\n- ],\n- \"browser_provider\": \"firecrawl\",\n- \"post_setup\": \"agent_browser\",\n- },\n {\n \"name\": \"Camofox\",\n \"badge\": \"free · local\",","@@ -1662,6 +1642,61 @@ def _plugin_web_search_providers() -> list[dict]:\n return rows\n \n \n+# Mirror of _plugin_web_search_providers for cloud browser backends. After\n+# PR #25214, Browserbase / Browser Use / Firecrawl live as plugins under\n+# plugins/browser//; this helper is the sole source of provider rows\n+# for those three in the \"Browser Automation\" picker. The hardcoded\n+# ``TOOL_CATEGORIES[\"browser\"]`` entries that drove the category before\n+# were deleted in the same PR; only non-provider UX setup-flow rows remain\n+# (\"Nous Subscription\", \"Local Browser\", \"Camofox\") — see the comment block\n+# in ``TOOL_CATEGORIES[\"browser\"]`` for why each one stays hardcoded.\n+def _plugin_browser_providers() -> list[dict]:\n+ \"\"\"Build picker-row dicts from plugin-registered cloud browser providers.\n+\n+ Each returned dict mirrors the legacy ``TOOL_CATEGORIES[\"browser\"]``\n+ schema (``name`` / ``badge`` / ``tag`` / ``env_vars`` /\n+ ``browser_provider`` / ``post_setup``) so the picker behaves identically\n+ whether a provider was hardcoded or plugin-registered.\n+\n+ Populates ``browser_provider`` (the legacy config key written to\n+ ``browser.cloud_provider``) and a ``browser_plugin_name`` marker so\n+ setup / write paths can route through the registry when they want to.\n+ \"\"\"\n+ try:\n+ from agent.browser_registry import list_providers as _list_browser_providers\n+ from hermes_cli.plugins import _ensure_plugins_discovered\n+\n+ _ensure_plugins_discovered()\n+ providers = _list_browser_providers()\n+ except Exception:\n+ return []\n+\n+ rows: list[dict] = []\n+ for provider in providers:\n+ name = getattr(provider, \"name\", None)\n+ if not name:\n+ continue\n+ try:\n+ schema = provider.get_setup_schema()\n+ except Exception:\n+ continue\n+ if not isinstance(schema, dict):\n+ continue\n+ row = {\n+ \"name\": schema.get(\"name\", provider.display_name),\n+ \"badge\": schema.get(\"badge\", \"\"),\n+ \"tag\": schema.get(\"tag\", \"\"),\n+ \"env_vars\": schema.get(\"env_vars\", []),\n+ \"browser_provider\": name,\n+ \"browser_plugin_name\": name,\n+ }\n+ # Pass-through optional fields the schema can opt into.\n+ if schema.get(\"post_setup\"):\n+ row[\"post_setup\"] = schema[\"post_setup\"]\n+ rows.append(row)\n+ return rows\n+\n+\n def _visible_providers(cat: dict, config: dict) -> list[dict]:\n \"\"\"Return provider entries visible for the current auth/config state.\"\"\"\n features = get_nous_subscription_features(config)","@@ -1691,6 +1726,14 @@ def _visible_providers(cat: dict, config: dict) -> list[dict]:\n if cat.get(\"name\") == \"Web Search & Extract\":\n visible.extend(_plugin_web_search_providers())\n \n+ # Inject plugin-registered cloud browser backends. After PR #25214,\n+ # Browserbase / Browser Use / Firecrawl are the plugin-supplied rows;\n+ # the hardcoded \"Nous Subscription\" / \"Local Browser\" / \"Camofox\" rows\n+ # stay because they're non-provider UX setup flows (subscription auth,\n+ # local fallback, and the REST-API anti-detection backend respectively).\n+ if cat.get(\"name\") == \"Browser Automation\":\n+ visible.extend(_plugin_browser_providers())\n+\n return visible\n \n "]},{"file":"plugins/browser/browser_use/__init__.py","hunks":["@@ -0,0 +1,14 @@\n+\"\"\"Browser Use cloud browser plugin — bundled, auto-loaded.\n+\n+Mirrors the ``plugins/web//`` layout: ``provider.py`` holds the\n+provider class; ``__init__.py::register`` instantiates and registers it.\n+\"\"\"\n+\n+from __future__ import annotations\n+\n+from plugins.browser.browser_use.provider import BrowserUseBrowserProvider\n+\n+\n+def register(ctx) -> None:\n+ \"\"\"Register the Browser Use provider with the plugin context.\"\"\"\n+ ctx.register_browser_provider(BrowserUseBrowserProvider())"]},{"file":"plugins/browser/browser_use/plugin.yaml","hunks":["@@ -0,0 +1,7 @@\n+name: browser-browser-use\n+version: 1.0.0\n+description: \"Browser Use (https://browser-use.com) cloud browser backend. Supports both direct BROWSER_USE_API_KEY and the managed Nous tool gateway. Also powers the 'Nous Subscription' UX flow that bills usage to a Nous subscription.\"\n+author: NousResearch\n+kind: backend\n+provides_browser_providers:\n+ - browser-use"]},{"file":"plugins/browser/browser_use/provider.py","hunks":["@@ -1,4 +1,32 @@\n-\"\"\"Browser Use cloud browser provider.\"\"\"\n+\"\"\"Browser Use cloud browser provider — plugin form.\n+\n+Subclasses :class:`agent.browser_provider.BrowserProvider` (the plugin-facing\n+ABC introduced in PR #25214). The legacy in-tree module\n+``tools.browser_providers.browser_use`` was removed in the same PR; this file\n+is now the canonical implementation.\n+\n+Browser Use is the only browser backend with dual auth: a direct\n+``BROWSER_USE_API_KEY`` for self-billed users, or the managed Nous tool\n+gateway (which Hermes uses to bill Browser Use sessions to a Nous\n+subscription). The dispatch order — direct API key first, managed gateway\n+second — preserves the pre-migration behaviour in\n+``tools.browser_providers.browser_use.BrowserUseProvider._get_config_or_none``.\n+\n+Config keys this provider responds to::\n+\n+ browser:\n+ cloud_provider: \"browser-use\" # explicit selection\n+ tool_gateway:\n+ browser: \"gateway\" # optional: prefer managed gateway\n+ # even when BROWSER_USE_API_KEY is set\n+\n+Auth env vars (one of)::\n+\n+ BROWSER_USE_API_KEY=... # https://browser-use.com\n+ # OR a managed Nous gateway entry (configured via 'hermes setup')\n+\"\"\"\n+\n+from __future__ import annotations\n \n import logging\n import os","@@ -8,11 +36,14 @@\n \n import requests\n \n-from tools.browser_providers.base import CloudBrowserProvider\n-from tools.managed_tool_gateway import resolve_managed_tool_gateway\n-from tools.tool_backend_helpers import managed_nous_tools_enabled, prefers_gateway\n+from agent.browser_provider import BrowserProvider\n \n logger = logging.getLogger(__name__)\n+\n+# Idempotency tracking for managed-mode session creation. The managed Nous\n+# gateway returns 409 \"already in progress\" on retried POSTs; we forward the\n+# original idempotency key so the gateway can deduplicate. Cleared on\n+# success or terminal failure.\n _pending_create_keys: Dict[str, str] = {}\n _pending_create_keys_lock = threading.Lock()\n ","@@ -38,6 +69,16 @@ def _clear_pending_create_key(task_id: str) -> None:\n \n \n def _should_preserve_pending_create_key(response: requests.Response) -> bool:\n+ \"\"\"Decide whether to keep the idempotency key after a failed create.\n+\n+ Preserve the key when the failure looks retryable (5xx) OR when the\n+ gateway reports the original request is still in flight (409 \"already\n+ in progress\") — in either case, retrying with the same key lets the\n+ gateway deduplicate.\n+\n+ Drop the key on any other 4xx (auth failure, bad request, etc.) — those\n+ won't succeed by being retried.\n+ \"\"\"\n if response.status_code >= 500:\n return True\n ","@@ -60,13 +101,24 @@ def _should_preserve_pending_create_key(response: requests.Response) -> bool:\n return \"already in progress\" in message\n \n \n-class BrowserUseProvider(CloudBrowserProvider):\n- \"\"\"Browser Use (https://browser-use.com) cloud browser backend.\"\"\"\n+class BrowserUseBrowserProvider(BrowserProvider):\n+ \"\"\"Browser Use (https://browser-use.com) cloud browser backend.\n+\n+ Dual auth: prefers a direct BROWSER_USE_API_KEY when set, falling back\n+ to the managed Nous tool gateway when ``tool_gateway.browser`` config\n+ routes through it. Setting ``tool_gateway.browser: gateway`` flips the\n+ order so managed billing wins even when BROWSER_USE_API_KEY is present.\n+ \"\"\"\n \n- def provider_name(self) -> str:\n+ @property\n+ def name(self) -> str:\n+ return \"browser-use\"\n+\n+ @property\n+ def display_name(self) -> str:\n return \"Browser Use\"\n \n- def is_configured(self) -> bool:\n+ def is_available(self) -> bool:\n return self._get_config_or_none() is not None\n \n # ------------------------------------------------------------------","@@ -74,6 +126,14 @@ def is_configured(self) -> bool:\n # ------------------------------------------------------------------\n \n def _get_config_or_none(self) -> Optional[Dict[str, Any]]:\n+ # Import here to avoid a hard dependency at module-import time —\n+ # managed_tool_gateway pulls in the Nous auth stack which can be\n+ # heavy and is not needed for direct-API-key users.\n+ from tools.managed_tool_gateway import resolve_managed_tool_gateway\n+ from tools.tool_backend_helpers import prefers_gateway\n+\n+ # Direct API key wins unless the user has explicitly opted into the\n+ # managed Nous gateway via ``tool_gateway.browser: gateway``.\n api_key = os.environ.get(\"BROWSER_USE_API_KEY\")\n if api_key and not prefers_gateway(\"browser\"):\n return {","@@ -93,6 +153,8 @@ def _get_config_or_none(self) -> Optional[Dict[str, Any]]:\n }\n \n def _get_config(self) -> Dict[str, Any]:\n+ from tools.tool_backend_helpers import managed_nous_tools_enabled\n+\n config = self._get_config_or_none()\n if config is None:\n message = (","@@ -111,11 +173,10 @@ def _get_config(self) -> Dict[str, Any]:\n # ------------------------------------------------------------------\n \n def _headers(self, config: Dict[str, Any]) -> Dict[str, str]:\n- headers = {\n+ return {\n \"Content-Type\": \"application/json\",\n \"X-Browser-Use-API-Key\": [redacted:secret-assignment]\"api_key\"],\n }\n- return headers\n \n def create_session(self, task_id: str) -> Dict[str, object]:\n config = self._get_config()","@@ -166,7 +227,9 @@ def create_session(self, task_id: str) -> Dict[str, object]:\n if managed_mode:\n _clear_pending_create_key(task_id)\n session_name = f\"hermes_{task_id}_{uuid.uuid4().hex[:8]}\"\n- external_call_id = response.headers.get(\"x-external-call-id\") if managed_mode else None\n+ external_call_id = (\n+ response.headers.get(\"x-external-call-id\") if managed_mode else None\n+ )\n \n logger.info(\"Created Browser Use session %s\", session_name)\n ","@@ -184,7 +247,9 @@ def close_session(self, session_id: str) -> bool:\n try:\n config = self._get_config()\n except ValueError:\n- logger.warning(\"Cannot close Browser Use session %s — missing credentials\", session_id)\n+ logger.warning(\n+ \"Cannot close Browser Use session %s — missing credentials\", session_id\n+ )\n return False\n \n try:","@@ -212,7 +277,10 @@ def close_session(self, session_id: str) -> bool:\n def emergency_cleanup(self, session_id: str) -> None:\n config = self._get_config_or_none()\n if config is None:\n- logger.warning(\"Cannot emergency-cleanup Browser Use session %s — missing credentials\", session_id)\n+ logger.warning(\n+ \"Cannot emergency-cleanup Browser Use session %s — missing credentials\",\n+ session_id,\n+ )\n return\n try:\n requests.patch(","@@ -222,4 +290,21 @@ def emergency_cleanup(self, session_id: str) -> None:\n timeout=5,\n )\n except Exception as e:\n- logger.debug(\"Emergency cleanup failed for Browser Use session %s: %s\", session_id, e)\n+ logger.debug(\n+ \"Emergency cleanup failed for Browser Use session %s: %s\", session_id, e\n+ )\n+\n+ def get_setup_schema(self) -> Dict[str, Any]:\n+ return {\n+ \"name\": \"Browser Use\",\n+ \"badge\": \"paid\",\n+ \"tag\": \"Cloud browser with remote execution\",\n+ \"env_vars\": [\n+ {\n+ \"key\": \"BROWSER_USE_API_KEY\",\n+ \"prompt\": \"Browser Use API key\",\n+ \"url\": \"https://browser-use.com\",\n+ },\n+ ],\n+ \"post_setup\": \"agent_browser\",\n+ }"]},{"file":"plugins/browser/browserbase/__init__.py","hunks":["@@ -0,0 +1,15 @@\n+\"\"\"Browserbase cloud browser plugin — bundled, auto-loaded.\n+\n+Mirrors the ``plugins/web//`` and ``plugins/image_gen/openai/``\n+layout: ``provider.py`` holds the provider class; ``__init__.py::register``\n+instantiates and registers it via the plugin context.\n+\"\"\"\n+\n+from __future__ import annotations\n+\n+from plugins.browser.browserbase.provider import BrowserbaseBrowserProvider\n+\n+\n+def register(ctx) -> None:\n+ \"\"\"Register the Browserbase provider with the plugin context.\"\"\"\n+ ctx.register_browser_provider(BrowserbaseBrowserProvider())"]},{"file":"plugins/browser/browserbase/plugin.yaml","hunks":["@@ -0,0 +1,7 @@\n+name: browser-browserbase\n+version: 1.0.0\n+description: \"Browserbase (https://browserbase.com) cloud browser backend. Requires BROWSERBASE_API_KEY + BROWSERBASE_PROJECT_ID. Supports stealth, proxies, and keep-alive sessions; auto-falls-back when paid features are unavailable.\"\n+author: NousResearch\n+kind: backend\n+provides_browser_providers:\n+ - browserbase"]},{"file":"plugins/browser/browserbase/provider.py","hunks":["@@ -1,4 +1,35 @@\n-\"\"\"Browserbase cloud browser provider (direct credentials only).\"\"\"\n+\"\"\"Browserbase cloud browser provider — plugin form.\n+\n+Subclasses :class:`agent.browser_provider.BrowserProvider` (the plugin-facing\n+ABC introduced in PR #25214). The legacy in-tree module\n+``tools.browser_providers.browserbase`` was removed in the same PR; this file\n+is now the canonical implementation.\n+\n+Browserbase requires direct ``BROWSERBASE_API_KEY`` and ``BROWSERBASE_PROJECT_ID``\n+credentials. Managed Nous gateway support has been removed — the Nous\n+subscription now routes through Browser Use instead (see\n+``plugins/browser/browser_use/``).\n+\n+Config keys this provider responds to::\n+\n+ browser:\n+ cloud_provider: \"browserbase\"\n+\n+Auth env vars::\n+\n+ BROWSERBASE_API_KEY=... # https://browserbase.com\n+ BROWSERBASE_PROJECT_ID=...\n+\n+Optional feature knobs::\n+\n+ BROWSERBASE_BASE_URL=... # default https://api.browserbase.com\n+ BROWSERBASE_PROXIES=true # default true\n+ BROWSERBASE_ADVANCED_STEALTH=false\n+ BROWSERBASE_KEEP_ALIVE=true # default true\n+ BROWSERBASE_SESSION_TIMEOUT=... (ms, integer)\n+\"\"\"\n+\n+from __future__ import annotations\n \n import logging\n import os","@@ -7,27 +38,31 @@\n \n import requests\n \n-from tools.browser_providers.base import CloudBrowserProvider\n+from agent.browser_provider import BrowserProvider\n \n logger = logging.getLogger(__name__)\n \n \n-class BrowserbaseProvider(CloudBrowserProvider):\n+class BrowserbaseBrowserProvider(BrowserProvider):\n \"\"\"Browserbase (https://browserbase.com) cloud browser backend.\n \n- This provider requires direct BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID\n- credentials. Managed Nous gateway support has been removed — the Nous\n- subscription now routes through Browser Use instead.\n+ Direct credentials only — managed-Nous-gateway support lives on the\n+ Browser Use provider now.\n \"\"\"\n \n- def provider_name(self) -> str:\n+ @property\n+ def name(self) -> str:\n+ return \"browserbase\"\n+\n+ @property\n+ def display_name(self) -> str:\n return \"Browserbase\"\n \n- def is_configured(self) -> bool:\n+ def is_available(self) -> bool:\n return self._get_config_or_none() is not None\n \n # ------------------------------------------------------------------\n- # Session lifecycle\n+ # Config resolution\n # ------------------------------------------------------------------\n \n def _get_config_or_none(self) -> Optional[Dict[str, Any]]:","@@ -37,7 +72,9 @@ def _get_config_or_none(self) -> Optional[Dict[str, Any]]:\n return {\n \"api_key\": [redacted:secret-assignment]\n \"project_id\": project_id,\n- \"base_url\": os.environ.get(\"BROWSERBASE_BASE_URL\", \"https://api.browserbase.com\").rstrip(\"/\"),\n+ \"base_url\": os.environ.get(\n+ \"BROWSERBASE_BASE_URL\", \"https://api.browserbase.com\"\n+ ).rstrip(\"/\"),\n }\n return None\n ","@@ -50,13 +87,21 @@ def _get_config(self) -> Dict[str, Any]:\n )\n return config\n \n+ # ------------------------------------------------------------------\n+ # Session lifecycle\n+ # ------------------------------------------------------------------\n+\n def create_session(self, task_id: str) -> Dict[str, object]:\n config = self._get_config()\n \n # Optional env-var knobs\n enable_proxies = os.environ.get(\"BROWSERBASE_PROXIES\", \"true\").lower() != \"false\"\n- enable_advanced_stealth = os.environ.get(\"BROWSERBASE_ADVANCED_STEALTH\", \"false\").lower() == \"true\"\n- enable_keep_alive = os.environ.get(\"BROWSERBASE_KEEP_ALIVE\", \"true\").lower() != \"false\"\n+ enable_advanced_stealth = (\n+ os.environ.get(\"BROWSERBASE_ADVANCED_STEALTH\", \"false\").lower() == \"true\"\n+ )\n+ enable_keep_alive = (\n+ os.environ.get(\"BROWSERBASE_KEEP_ALIVE\", \"true\").lower() != \"false\"\n+ )\n custom_timeout_ms = os.environ.get(\"BROWSERBASE_SESSION_TIMEOUT\")\n \n features_enabled = {","@@ -78,7 +123,9 @@ def create_session(self, task_id: str) -> Dict[str, object]:\n if timeout_val > 0:\n session_config[\"timeout\"] = timeout_val\n except ValueError:\n- logger.warning(\"Invalid BROWSERBASE_SESSION_TIMEOUT value: %s\", custom_timeout_ms)\n+ logger.warning(\n+ \"Invalid BROWSERBASE_SESSION_TIMEOUT value: %s\", custom_timeout_ms\n+ )\n \n if enable_proxies:\n session_config[\"proxies\"] = True","@@ -156,7 +203,9 @@ def create_session(self, task_id: str) -> Dict[str, object]:\n features_enabled[\"custom_timeout\"] = True\n \n feature_str = \", \".join(k for k, v in features_enabled.items() if v)\n- logger.info(\"Created Browserbase session %s with features: %s\", session_name, feature_str)\n+ logger.info(\n+ \"Created Browserbase session %s with features: %s\", session_name, feature_str\n+ )\n \n return {\n \"session_name\": session_name,","@@ -169,7 +218,9 @@ def close_session(self, session_id: str) -> bool:\n try:\n config = self._get_config()\n except ValueError:\n- logger.warning(\"Cannot close Browserbase session %s — missing credentials\", session_id)\n+ logger.warning(\n+ \"Cannot close Browserbase session %s — missing credentials\", session_id\n+ )\n return False\n \n try:","@@ -203,7 +254,10 @@ def close_session(self, session_id: str) -> bool:\n def emergency_cleanup(self, session_id: str) -> None:\n config = self._get_config_or_none()\n if config is None:\n- logger.warning(\"Cannot emergency-cleanup Browserbase session %s — missing credentials\", session_id)\n+ logger.warning(\n+ \"Cannot emergency-cleanup Browserbase session %s — missing credentials\",\n+ session_id,\n+ )\n return\n try:\n requests.post(","@@ -219,4 +273,25 @@ def emergency_cleanup(self, session_id: str) -> None:\n timeout=5,\n )\n except Exception as e:\n- logger.debug(\"Emergency cleanup failed for Browserbase session %s: %s\", session_id, e)\n+ logger.debug(\n+ \"Emergency cleanup failed for Browserbase session %s: %s\", session_id, e\n+ )\n+\n+ def get_setup_schema(self) -> Dict[str, Any]:\n+ return {\n+ \"name\": \"Browserbase\",\n+ \"badge\": \"paid\",\n+ \"tag\": \"Cloud browser with stealth and proxies\",\n+ \"env_vars\": [\n+ {\n+ \"key\": \"BROWSERBASE_API_KEY\",\n+ \"prompt\": \"Browserbase API key\",\n+ \"url\": \"https://browserbase.com\",\n+ },\n+ {\n+ \"key\": \"BROWSERBASE_PROJECT_ID\",\n+ \"prompt\": \"Browserbase project ID\",\n+ },\n+ ],\n+ \"post_setup\": \"agent_browser\",\n+ }"]},{"file":"plugins/browser/firecrawl/__init__.py","hunks":["@@ -0,0 +1,16 @@\n+\"\"\"Firecrawl cloud browser plugin — bundled, auto-loaded.\n+\n+Distinct from ``plugins/web/firecrawl/`` (the web search/extract/crawl\n+plugin); both share the FIRECRAWL_API_KEY but speak to different endpoints\n+(``/v2/browser`` here vs ``/v2/search`` / ``/v2/scrape`` / ``/v2/crawl``\n+over there).\n+\"\"\"\n+\n+from __future__ import annotations\n+\n+from plugins.browser.firecrawl.provider import FirecrawlBrowserProvider\n+\n+\n+def register(ctx) -> None:\n+ \"\"\"Register the Firecrawl cloud-browser provider with the plugin context.\"\"\"\n+ ctx.register_browser_provider(FirecrawlBrowserProvider())"]},{"file":"plugins/browser/firecrawl/plugin.yaml","hunks":["@@ -0,0 +1,7 @@\n+name: browser-firecrawl\n+version: 1.0.0\n+description: \"Firecrawl (https://firecrawl.dev) cloud browser backend. Requires FIRECRAWL_API_KEY. Distinct from the firecrawl WEB search/extract plugin — the two share an API key but operate on different endpoints.\"\n+author: NousResearch\n+kind: backend\n+provides_browser_providers:\n+ - firecrawl"]},{"file":"plugins/browser/firecrawl/provider.py","hunks":["@@ -1,26 +1,61 @@\n-\"\"\"Firecrawl cloud browser provider.\"\"\"\n+\"\"\"Firecrawl cloud browser provider — plugin form.\n+\n+Subclasses :class:`agent.browser_provider.BrowserProvider` (the plugin-facing\n+ABC introduced in PR #25214). The legacy in-tree module\n+``tools.browser_providers.firecrawl`` was removed in the same PR; this file\n+is now the canonical implementation.\n+\n+This is the cloud-browser path — distinct from the firecrawl WEB plugin at\n+``plugins/web/firecrawl/`` which handles search/extract/crawl on\n+``/v2/search`` / ``/v2/scrape`` / ``/v2/crawl``. The two plugins share the\n+``FIRECRAWL_API_KEY`` env var but talk to different endpoints (this one\n+hits ``/v2/browser``).\n+\n+Config keys this provider responds to::\n+\n+ browser:\n+ cloud_provider: \"firecrawl\" # explicit selection only — not in the\n+ # legacy auto-detect walk\n+\n+Auth env vars::\n+\n+ FIRECRAWL_API_KEY=... # https://firecrawl.dev\n+ FIRECRAWL_API_URL=... # optional override (default https://api.firecrawl.dev)\n+ FIRECRAWL_BROWSER_TTL=... # optional, default 300 seconds\n+\"\"\"\n+\n+from __future__ import annotations\n \n import logging\n import os\n import uuid\n-from typing import Dict\n+from typing import Any, Dict\n \n import requests\n \n-from tools.browser_providers.base import CloudBrowserProvider\n+from agent.browser_provider import BrowserProvider\n \n logger = logging.getLogger(__name__)\n \n _BASE_URL = \"https://api.firecrawl.dev\"\n \n \n-class FirecrawlProvider(CloudBrowserProvider):\n- \"\"\"Firecrawl (https://firecrawl.dev) cloud browser backend.\"\"\"\n+class FirecrawlBrowserProvider(BrowserProvider):\n+ \"\"\"Firecrawl (https://firecrawl.dev) cloud browser backend.\n \n- def provider_name(self) -> str:\n+ Cloud-browser path only — search/extract/crawl live in the separate\n+ ``plugins/web/firecrawl/`` plugin.\n+ \"\"\"\n+\n+ @property\n+ def name(self) -> str:\n+ return \"firecrawl\"\n+\n+ @property\n+ def display_name(self) -> str:\n return \"Firecrawl\"\n \n- def is_configured(self) -> bool:\n+ def is_available(self) -> bool:\n return bool(os.environ.get(\"FIRECRAWL_API_KEY\"))\n \n # ------------------------------------------------------------------","@@ -100,13 +135,34 @@ def close_session(self, session_id: str) -> bool:\n return False\n \n def emergency_cleanup(self, session_id: str) -> None:\n+ if not self.is_available():\n+ logger.warning(\n+ \"Cannot emergency-cleanup Firecrawl session %s — missing credentials\",\n+ session_id,\n+ )\n+ return\n try:\n requests.delete(\n f\"{self._api_url()}/v2/browser/{session_id}\",\n headers=self._headers(),\n timeout=5,\n )\n- except ValueError:\n- logger.warning(\"Cannot emergency-cleanup Firecrawl session %s — missing credentials\", session_id)\n except Exception as e:\n- logger.debug(\"Emergency cleanup failed for Firecrawl session %s: %s\", session_id, e)\n+ logger.debug(\n+ \"Emergency cleanup failed for Firecrawl session %s: %s\", session_id, e\n+ )\n+\n+ def get_setup_schema(self) -> Dict[str, Any]:\n+ return {\n+ \"name\": \"Firecrawl\",\n+ \"badge\": \"paid\",\n+ \"tag\": \"Cloud browser with remote execution\",\n+ \"env_vars\": [\n+ {\n+ \"key\": \"FIRECRAWL_API_KEY\",\n+ \"prompt\": \"Firecrawl API key\",\n+ \"url\": \"https://firecrawl.dev\",\n+ },\n+ ],\n+ \"post_setup\": \"agent_browser\",\n+ }"]},{"file":"tests/plugins/browser/check_parity_vs_main.py","hunks":["@@ -0,0 +1,273 @@\n+\"\"\"Behavior-parity check for the browser-provider plugin migration (#25214).\n+\n+Spawns one subprocess per (version, scenario) cell — pinned to either\n+origin/main (legacy in-tree providers + class-instantiation lookup) or\n+this PR's worktree (plugin-based registry) via `sys.path[0]`. Each\n+subprocess clears all browser-related env vars + writes a config.yaml,\n+loads `tools.browser_tool._get_cloud_provider()`, and emits a reduced\n+\"shape tuple\" {is_local, provider_name, is_available} as JSON.\n+\n+The parent process diffs the shapes per scenario. A diff means the\n+migration introduced an observable behaviour change vs origin/main —\n+which would be a real regression for users on the existing config keys.\n+\n+Run from the PR worktree:\n+\n+ cd ~/.hermes/hermes-agent/.worktrees/browser-providers-plugin\n+ python tests/plugins/browser/check_parity_vs_main.py\n+\"\"\"\n+from __future__ import annotations\n+\n+import json\n+import subprocess\n+import sys\n+from pathlib import Path\n+\n+\n+REPO_ROOT = Path(__file__).resolve().parents[3]\n+\n+\n+# Pin one path to current main, one to the PR worktree.\n+# ``REPO_ROOT`` is ``.../.worktrees/browser-providers-plugin``; the main\n+# checkout lives two levels up at ``~/.hermes/hermes-agent``.\n+MAIN_DIR = REPO_ROOT.parent.parent # ~/.hermes/hermes-agent\n+PR_DIR = REPO_ROOT # the worktree we're in\n+assert (MAIN_DIR / \"tools\" / \"browser_tool.py\").exists(), (\n+ f\"MAIN_DIR={MAIN_DIR} doesn't look like a hermes-agent checkout\"\n+)\n+assert (PR_DIR / \"tools\" / \"browser_tool.py\").exists(), (\n+ f\"PR_DIR={PR_DIR} doesn't look like a hermes-agent checkout\"\n+)\n+\n+\n+# Reduced shape comparison — exact instance addresses obviously differ\n+# between subprocesses, so we compare the parts that matter for users.\n+SUBPROCESS_SCRIPT = r\"\"\"\n+import json, os, sys, tempfile\n+sys.path.insert(0, sys.argv[1])\n+\n+# Isolated HERMES_HOME for the config write.\n+home = tempfile.mkdtemp()\n+os.environ[\"HERMES_HOME\"] = home\n+\n+# Clear every browser-related env var so is_available() is deterministic.\n+for k in (\n+ \"BROWSERBASE_API_KEY\", \"BROWSERBASE_PROJECT_ID\", \"BROWSERBASE_BASE_URL\",\n+ \"BROWSER_USE_API_KEY\", \"BROWSER_USE_GATEWAY_URL\",\n+ \"FIRECRAWL_API_KEY\", \"FIRECRAWL_API_URL\", \"FIRECRAWL_BROWSER_TTL\",\n+ \"TOOL_GATEWAY_DOMAIN\", \"TOOL_GATEWAY_USER_TOKEN\",\n+):\n+ os.environ.pop(k, None)\n+\n+# Apply per-scenario env (passed as JSON via argv[2]).\n+scenario_env = json.loads(sys.argv[2])\n+os.environ.update(scenario_env)\n+\n+# Apply per-scenario config (passed as YAML body via argv[3]).\n+config_yaml = sys.argv[3]\n+config_path = os.path.join(home, \"config.yaml\")\n+with open(config_path, \"w\") as f:\n+ f.write(config_yaml)\n+\n+# Fresh import — must not have any browser modules cached.\n+for name in list(sys.modules):\n+ if name.startswith(\"tools.\") or name.startswith(\"agent.\") or name.startswith(\"plugins.\"):\n+ sys.modules.pop(name, None)\n+\n+from tools.browser_tool import _get_cloud_provider, _is_local_mode\n+\n+provider = _get_cloud_provider()\n+\n+# Pull the human-readable backend name via the API that exists on BOTH\n+# legacy (origin/main: CloudBrowserProvider.provider_name()) and the new\n+# ABC (BrowserProvider exposes provider_name() as a backward-compat alias\n+# returning display_name). Both shapes resolve to the same string —\n+# 'Browserbase' / 'Browser Use' / 'Firecrawl' — so we can compare safely.\n+provider_name = None\n+is_available = None\n+if provider is not None:\n+ pn = getattr(provider, \"provider_name\", None)\n+ if callable(pn):\n+ provider_name = pn()\n+ elif isinstance(pn, str):\n+ provider_name = pn\n+ is_conf = getattr(provider, \"is_configured\", None)\n+ if callable(is_conf):\n+ is_available = bool(is_conf())\n+\n+shape = {\n+ \"is_local\": _is_local_mode(),\n+ \"provider_name\": provider_name,\n+ \"is_available\": is_available,\n+}\n+print(json.dumps(shape))\n+\"\"\"\n+\n+\n+SCENARIOS: list[tuple[str, str, dict[str, str]]] = [\n+ # (label, config.yaml body, extra env vars)\n+ (\"no-config-no-env\", \"\", {}),\n+ (\"explicit-local-no-env\", \"browser:\\n cloud_provider: local\\n\", {}),\n+ (\n+ \"explicit-browserbase-no-creds\",\n+ \"browser:\\n cloud_provider: browserbase\\n\",\n+ {},\n+ ),\n+ (\n+ \"explicit-browserbase-with-creds\",\n+ \"browser:\\n cloud_provider: browserbase\\n\",\n+ {\"BROWSERBASE_API_KEY\": \"x\", \"BROWSERBASE_PROJECT_ID\": \"y\"},\n+ ),\n+ (\n+ \"explicit-browser-use-no-creds\",\n+ \"browser:\\n cloud_provider: browser-use\\n\",\n+ {},\n+ ),\n+ (\n+ \"explicit-browser-use-with-creds\",\n+ \"browser:\\n cloud_provider: browser-use\\n\",\n+ {\"BROWSER_USE_API_KEY\": \"k\"},\n+ ),\n+ (\n+ \"explicit-firecrawl-no-creds\",\n+ \"browser:\\n cloud_provider: firecrawl\\n\",\n+ {},\n+ ),\n+ (\n+ \"explicit-firecrawl-with-creds\",\n+ \"browser:\\n cloud_provider: firecrawl\\n\",\n+ {\"FIRECRAWL_API_KEY\": \"k\"},\n+ ),\n+ (\n+ \"no-config-bu-creds\",\n+ \"\",\n+ {\"BROWSER_USE_API_KEY\": \"k\"},\n+ ),\n+ (\n+ \"no-config-bb-creds\",\n+ \"\",\n+ {\"BROWSERBASE_API_KEY\": \"x\", \"BROWSERBASE_PROJECT_ID\": \"y\"},\n+ ),\n+ (\n+ \"no-config-both-creds\",\n+ \"\",\n+ {\n+ \"BROWSER_USE_API_KEY\": \"k\",\n+ \"BROWSERBASE_API_KEY\": \"x\",\n+ \"BROWSERBASE_PROJECT_ID\": \"y\",\n+ },\n+ ),\n+ (\n+ \"no-config-firecrawl-only\",\n+ \"\",\n+ {\"FIRECRAWL_API_KEY\": \"k\"},\n+ ),\n+ (\n+ \"no-config-firecrawl-and-bb\",\n+ \"\",\n+ {\n+ \"FIRECRAWL_API_KEY\": \"k\",\n+ \"BROWSERBASE_API_KEY\": \"x\",\n+ \"BROWSERBASE_PROJECT_ID\": \"y\",\n+ },\n+ ),\n+]\n+\n+\n+def _run_scenario(repo_path: Path, label: str, config_yaml: str, env: dict) -> dict:\n+ \"\"\"Run one (version, scenario) cell. Returns the shape dict.\"\"\"\n+ venv_python = repo_path / \".venv\" / \"bin\" / \"python\"\n+ if not venv_python.exists():\n+ # Worktrees share the main repo's venv.\n+ venv_python = MAIN_DIR / \".venv\" / \"bin\" / \"python\"\n+ if not venv_python.exists():\n+ venv_python = Path(\"python3\")\n+\n+ out = subprocess.run(\n+ [\n+ str(venv_python),\n+ \"-c\",\n+ SUBPROCESS_SCRIPT,\n+ str(repo_path),\n+ json.dumps(env),\n+ config_yaml,\n+ ],\n+ capture_output=True,\n+ text=True,\n+ timeout=30,\n+ )\n+ if out.returncode != 0:\n+ return {\n+ \"error\": \"subprocess failed\",\n+ \"stdout\": out.stdout,\n+ \"stderr\": out.stderr[-500:],\n+ }\n+ try:\n+ return json.loads(out.stdout.strip().splitlines()[-1])\n+ except Exception as exc:\n+ return {\"error\": f\"could not parse output: {exc}\", \"stdout\": out.stdout}\n+\n+\n+def _reduce_for_comparison(shape: dict) -> dict:\n+ \"\"\"Reduce a shape dict to the parts that matter for user-visible parity.\n+\n+ We compare ``(is_local, provider_name, is_available)`` — the trio that\n+ decides what the dispatcher does with each tool call. ``provider_name``\n+ is the legacy ``provider_name()`` return value ('Browserbase' / 'Browser\n+ Use' / 'Firecrawl'), which is identical between legacy and plugin\n+ classes (the plugin's ``display_name`` matches the legacy\n+ ``provider_name()`` return).\n+ \"\"\"\n+ return {\n+ \"is_local\": shape.get(\"is_local\"),\n+ \"provider_name\": shape.get(\"provider_name\"),\n+ \"is_available\": shape.get(\"is_available\"),\n+ }\n+\n+\n+def main() -> int:\n+ print(f\"main: {MAIN_DIR}\")\n+ print(f\"pr: {PR_DIR}\")\n+ print()\n+\n+ failures: list[str] = []\n+ errors: list[str] = []\n+ for label, config_yaml, env in SCENARIOS:\n+ main_shape = _run_scenario(MAIN_DIR, label, config_yaml, env)\n+ pr_shape = _run_scenario(PR_DIR, label, config_yaml, env)\n+\n+ if \"error\" in main_shape or \"error\" in pr_shape:\n+ print(f\" [ERR ] {label}: subprocess failed\")\n+ print(f\" main: {main_shape}\")\n+ print(f\" pr: {pr_shape}\")\n+ errors.append(label)\n+ continue\n+\n+ main_reduced = _reduce_for_comparison(main_shape)\n+ pr_reduced = _reduce_for_comparison(pr_shape)\n+\n+ if main_reduced == pr_reduced:\n+ print(f\" [OK] {label}: {main_reduced}\")\n+ else:\n+ print(f\" [FAIL] {label}\")\n+ print(f\" main: {main_reduced}\")\n+ print(f\" pr: {pr_reduced}\")\n+ failures.append(label)\n+\n+ print()\n+ if errors:\n+ print(f\"SUBPROCESS ERRORS in {len(errors)} scenario(s):\")\n+ for e in errors:\n+ print(f\" - {e}\")\n+ if failures:\n+ print(f\"BEHAVIOUR REGRESSION in {len(failures)} scenario(s):\")\n+ for f in failures:\n+ print(f\" - {f}\")\n+ if failures or errors:\n+ return 1\n+ print(f\"PARITY OK across {len(SCENARIOS)} scenarios.\")\n+ return 0\n+\n+\n+if __name__ == \"__main__\":\n+ sys.exit(main())"]},{"file":"tests/plugins/browser/test_browser_provider_plugins.py","hunks":["@@ -0,0 +1,379 @@\n+\"\"\"Plugin-side tests for the browser provider migration (PR #25214).\n+\n+Covers:\n+\n+- All three bundled plugins (browserbase, browser-use, firecrawl)\n+ instantiate and self-report the expected ABC defaults.\n+- Each plugin's ``is_available()`` correctly reflects env-var presence.\n+- The browser_registry resolves an active provider in the documented\n+ scenarios:\n+ * explicit config wins ignoring availability (so dispatcher surfaces\n+ a typed credentials error)\n+ * legacy preference walk: browser-use → browserbase (filtered by\n+ availability)\n+ * firecrawl is NOT in the legacy walk — explicit-only\n+ * unknown name falls through to auto-detect\n+ * ``local`` short-circuits to None\n+\n+These tests use *real* imports from the plugin modules — no mocking of\n+provider classes themselves — so the test catches drift in the ABC\n+interface, the registry, and the plugin glue layer simultaneously.\n+Mirrors ``tests/plugins/web/test_web_search_provider_plugins.py`` from\n+PR #25182.\n+\"\"\"\n+from __future__ import annotations\n+\n+import pytest\n+\n+\n+# ---------------------------------------------------------------------------\n+# Helpers\n+# ---------------------------------------------------------------------------\n+\n+\n+def _clear_browser_env(monkeypatch: pytest.MonkeyPatch) -> None:\n+ \"\"\"Strip every browser-provider env var so is_available() returns False.\"\"\"\n+ for k in (\n+ \"BROWSERBASE_API_KEY\",\n+ \"BROWSERBASE_PROJECT_ID\",\n+ \"BROWSERBASE_BASE_URL\",\n+ \"BROWSER_USE_API_KEY\",\n+ \"BROWSER_USE_GATEWAY_URL\",\n+ \"FIRECRAWL_API_KEY\",\n+ \"FIRECRAWL_API_URL\",\n+ \"FIRECRAWL_BROWSER_TTL\",\n+ \"TOOL_GATEWAY_DOMAIN\",\n+ \"TOOL_GATEWAY_USER_TOKEN\",\n+ ):\n+ monkeypatch.delenv(k, raising=False)\n+\n+\n+def _ensure_plugins_loaded() -> None:\n+ \"\"\"Idempotently load plugins so the registry is populated.\"\"\"\n+ from hermes_cli.plugins import _ensure_plugins_discovered\n+\n+ _ensure_plugins_discovered()\n+\n+\n+# ---------------------------------------------------------------------------\n+# Per-test isolation\n+# ---------------------------------------------------------------------------\n+\n+\n[redacted:email](autouse=True)\n+def _isolate_env(monkeypatch: pytest.MonkeyPatch) -> None:\n+ \"\"\"Each test starts with a clean browser-provider env.\"\"\"\n+ _clear_browser_env(monkeypatch)\n+\n+\n+# ---------------------------------------------------------------------------\n+# Bundled plugins register\n+# ---------------------------------------------------------------------------\n+\n+\n+class TestBundledPluginsRegister:\n+ \"\"\"All three bundled browser plugins discover and register correctly.\"\"\"\n+\n+ def test_all_three_plugins_present_in_registry(self) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import list_providers\n+\n+ names = sorted(p.name for p in list_providers())\n+ assert names == [\"browser-use\", \"browserbase\", \"firecrawl\"]\n+\n+ @pytest.mark.parametrize(\n+ \"plugin_name,expected_display\",\n+ [\n+ (\"browserbase\", \"Browserbase\"),\n+ (\"browser-use\", \"Browser Use\"),\n+ (\"firecrawl\", \"Firecrawl\"),\n+ ],\n+ )\n+ def test_each_plugin_has_name_and_display_name(\n+ self, plugin_name: str, expected_display: str\n+ ) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ provider = get_provider(plugin_name)\n+ assert provider is not None, f\"plugin {plugin_name!r} not registered\"\n+ assert provider.name == plugin_name\n+ assert provider.display_name == expected_display\n+\n+ @pytest.mark.parametrize(\n+ \"plugin_name\",\n+ [\"browserbase\", \"browser-use\", \"firecrawl\"],\n+ )\n+ def test_each_plugin_has_setup_schema(self, plugin_name: str) -> None:\n+ \"\"\"``get_setup_schema()`` returns a dict the picker can consume.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ provider = get_provider(plugin_name)\n+ assert provider is not None\n+ schema = provider.get_setup_schema()\n+ assert isinstance(schema, dict)\n+ assert \"name\" in schema\n+ assert \"env_vars\" in schema\n+ # Every cloud-browser plugin needs the agent-browser post-setup hook\n+ # so the picker auto-installs the CLI on selection.\n+ assert schema.get(\"post_setup\") == \"agent_browser\"\n+\n+ @pytest.mark.parametrize(\n+ \"plugin_name\",\n+ [\"browserbase\", \"browser-use\", \"firecrawl\"],\n+ )\n+ def test_each_plugin_implements_full_lifecycle(self, plugin_name: str) -> None:\n+ \"\"\"The ABC's three lifecycle methods are all overridden.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_provider import BrowserProvider\n+ from agent.browser_registry import get_provider\n+\n+ provider = get_provider(plugin_name)\n+ assert provider is not None\n+ # Each method must be a real override, not the ABC's NotImplementedError\n+ # default — we check by comparing the function reference.\n+ assert type(provider).create_session is not BrowserProvider.create_session\n+ assert type(provider).close_session is not BrowserProvider.close_session\n+ assert (\n+ type(provider).emergency_cleanup is not BrowserProvider.emergency_cleanup\n+ )\n+\n+\n+# ---------------------------------------------------------------------------\n+# is_available() behavior\n+# ---------------------------------------------------------------------------\n+\n+\n+class TestIsAvailable:\n+ \"\"\"Each plugin's ``is_available()`` reflects env-var presence accurately.\"\"\"\n+\n+ def test_browserbase_requires_both_api_key_and_project_id(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(\"browserbase\")\n+ assert p is not None\n+ assert p.is_available() is False\n+\n+ # API key alone is insufficient.\n+ monkeypatch.setenv(\"BROWSERBASE_API_KEY\", \"key\")\n+ assert p.is_available() is False\n+\n+ # Both env vars set → available.\n+ monkeypatch.setenv(\"BROWSERBASE_PROJECT_ID\", \"proj\")\n+ assert p.is_available() is True\n+\n+ def test_browserbase_project_id_alone_insufficient(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(\"browserbase\")\n+ assert p is not None\n+ monkeypatch.setenv(\"BROWSERBASE_PROJECT_ID\", \"proj\")\n+ assert p.is_available() is False\n+\n+ def test_browser_use_satisfied_by_api_key(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(\"browser-use\")\n+ assert p is not None\n+ assert p.is_available() is False\n+ monkeypatch.setenv(\"BROWSER_USE_API_KEY\", \"key\")\n+ assert p.is_available() is True\n+\n+ def test_firecrawl_requires_api_key(self, monkeypatch: pytest.MonkeyPatch) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(\"firecrawl\")\n+ assert p is not None\n+ assert p.is_available() is False\n+ monkeypatch.setenv(\"FIRECRAWL_API_KEY\", \"key\")\n+ assert p.is_available() is True\n+\n+\n+# ---------------------------------------------------------------------------\n+# Registry resolution semantics\n+# ---------------------------------------------------------------------------\n+\n+\n+class TestRegistryResolution:\n+ \"\"\"``_resolve()`` implements the documented three-rule precedence.\"\"\"\n+\n+ def test_resolve_none_with_no_creds_returns_none(self) -> None:\n+ \"\"\"No config, no env → local mode (None).\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ assert _resolve(None) is None\n+\n+ def test_explicit_local_returns_none(self) -> None:\n+ \"\"\"``cloud_provider: local`` is a positive choice; short-circuits to None.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ assert _resolve(\"local\") is None\n+\n+ def test_explicit_browserbase_returns_provider_even_when_unavailable(self) -> None:\n+ \"\"\"Rule 1: explicit-config wins even when credentials are missing.\n+\n+ This is critical — the dispatcher needs to surface a typed\n+ credentials error rather than silently switching backends.\n+ \"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ provider = _resolve(\"browserbase\")\n+ assert provider is not None\n+ assert provider.name == \"browserbase\"\n+ assert provider.is_available() is False # confirms \"ignoring availability\"\n+\n+ def test_explicit_firecrawl_returns_provider_even_when_unavailable(self) -> None:\n+ \"\"\"Firecrawl behaves the same as browserbase under explicit config.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ provider = _resolve(\"firecrawl\")\n+ assert provider is not None\n+ assert provider.name == \"firecrawl\"\n+\n+ def test_explicit_unknown_falls_back_to_auto_detect(self) -> None:\n+ \"\"\"Rule 1 miss: unknown name → fall through to legacy walk.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ # With no credentials anywhere, auto-detect should also fail.\n+ assert _resolve(\"not-a-real-provider\") is None\n+\n+ def test_legacy_walk_prefers_browser_use_over_browserbase(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ \"\"\"Rule 3: walk order is browser-use → browserbase.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ # Both available — browser-use should win.\n+ monkeypatch.setenv(\"BROWSER_USE_API_KEY\", \"k1\")\n+ monkeypatch.setenv(\"BROWSERBASE_API_KEY\", \"k2\")\n+ monkeypatch.setenv(\"BROWSERBASE_PROJECT_ID\", \"p\")\n+\n+ provider = _resolve(None)\n+ assert provider is not None\n+ assert provider.name == \"browser-use\"\n+\n+ def test_legacy_walk_falls_through_to_browserbase(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ \"\"\"Rule 3: browser-use unavailable → browserbase picked.\"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ monkeypatch.setenv(\"BROWSERBASE_API_KEY\", \"k\")\n+ monkeypatch.setenv(\"BROWSERBASE_PROJECT_ID\", \"p\")\n+\n+ provider = _resolve(None)\n+ assert provider is not None\n+ assert provider.name == \"browserbase\"\n+\n+ def test_firecrawl_not_in_legacy_walk_even_when_only_one_available(\n+ self, monkeypatch: pytest.MonkeyPatch\n+ ) -> None:\n+ \"\"\"Regression: firecrawl is NEVER auto-selected even when single-eligible.\n+\n+ Pre-PR-#25214, the dispatcher only auto-detected between Browser Use\n+ and Browserbase; firecrawl was reachable solely via explicit\n+ config. We preserve that gate because FIRECRAWL_API_KEY is shared\n+ with the *web* firecrawl plugin — auto-routing a web-extract user\n+ to a paid cloud browser would be a real behaviour regression.\n+ \"\"\"\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import _resolve\n+\n+ monkeypatch.setenv(\"FIRECRAWL_API_KEY\", \"k\")\n+\n+ # Only firecrawl is_available() — but it's not in the legacy walk.\n+ assert _resolve(None) is None\n+\n+\n+# ---------------------------------------------------------------------------\n+# Legacy ABC backward-compat aliases (is_configured / provider_name)\n+# ---------------------------------------------------------------------------\n+\n+\n+class TestLegacyAbcAliases:\n+ \"\"\"is_configured() and provider_name() delegate to the new API.\"\"\"\n+\n+ @pytest.mark.parametrize(\n+ \"plugin_name\",\n+ [\"browserbase\", \"browser-use\", \"firecrawl\"],\n+ )\n+ def test_is_configured_delegates_to_is_available(self, plugin_name: str) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(plugin_name)\n+ assert p is not None\n+ assert p.is_configured() is p.is_available()\n+\n+ @pytest.mark.parametrize(\n+ \"plugin_name,expected_label\",\n+ [\n+ (\"browserbase\", \"Browserbase\"),\n+ (\"browser-use\", \"Browser Use\"),\n+ (\"firecrawl\", \"Firecrawl\"),\n+ ],\n+ )\n+ def test_provider_name_returns_display_name(\n+ self, plugin_name: str, expected_label: str\n+ ) -> None:\n+ _ensure_plugins_loaded()\n+ from agent.browser_registry import get_provider\n+\n+ p = get_provider(plugin_name)\n+ assert p is not None\n+ assert p.provider_name() == expected_label\n+\n+\n+# ---------------------------------------------------------------------------\n+# Picker integration\n+# ---------------------------------------------------------------------------\n+\n+\n+class TestPickerIntegration:\n+ \"\"\"`_plugin_browser_providers()` exposes all three plugins as picker rows.\"\"\"\n+\n+ def test_picker_rows_match_registered_plugins(self) -> None:\n+ _ensure_plugins_loaded()\n+ from hermes_cli.tools_config import _plugin_browser_providers\n+\n+ rows = _plugin_browser_providers()\n+ names = sorted(r.get(\"browser_provider\") for r in rows)\n+ assert names == [\"browser-use\", \"browserbase\", \"firecrawl\"]\n+\n+ def test_picker_rows_carry_post_setup_hook(self) -> None:\n+ \"\"\"Every browser plugin row has post_setup='agent_browser' so\n+ selecting it triggers the agent-browser CLI install.\"\"\"\n+ _ensure_plugins_loaded()\n+ from hermes_cli.tools_config import _plugin_browser_providers\n+\n+ for row in _plugin_browser_providers():\n+ assert row.get(\"post_setup\") == \"agent_browser\", (\n+ f\"plugin row {row['browser_provider']!r} missing post_setup hook\"\n+ )\n+\n+ def test_picker_rows_carry_browser_plugin_name_marker(self) -> None:\n+ \"\"\"`browser_plugin_name` matches `browser_provider` so downstream\n+ code can route through the registry when it wants to.\"\"\"\n+ _ensure_plugins_loaded()\n+ from hermes_cli.tools_config import _plugin_browser_providers\n+\n+ for row in _plugin_browser_providers():\n+ assert row.get(\"browser_plugin_name\") == row.get(\"browser_provider\")"]},{"file":"tests/tools/test_managed_browserbase_and_modal.py","hunks":["@@ -10,7 +10,9 @@\n import pytest\n \n \n-TOOLS_DIR = Path(__file__).resolve().parents[2] / \"tools\"\n+REPO_ROOT = Path(__file__).resolve().parents[2]\n+TOOLS_DIR = REPO_ROOT / \"tools\"\n+PLUGINS_DIR = REPO_ROOT / \"plugins\"\n \n \n def _load_tool_module(module_name: str, filename: str):","@@ -22,6 +24,21 @@ def _load_tool_module(module_name: str, filename: str):\n return module\n \n \n+def _load_plugin_module(module_name: str, relpath: str):\n+ \"\"\"Load a plugin module by file path from ``plugins/``.\n+\n+ Mirror of :func:`_load_tool_module` for the plugin tree. Used by tests\n+ that exercise the per-vendor browser plugins' session-lifecycle\n+ behaviour after the PR #25214 migration.\n+ \"\"\"\n+ spec = spec_from_file_location(module_name, PLUGINS_DIR / relpath)\n+ assert spec and spec.loader\n+ module = module_from_spec(spec)\n+ sys.modules[module_name] = module\n+ spec.loader.exec_module(module)\n+ return module\n+\n+\n def _reset_modules(prefixes: tuple[str, ...]):\n for name in list(sys.modules):\n if name.startswith(prefixes):","@@ -76,6 +93,48 @@ def _install_fake_tools_package():\n call_llm=lambda *args, **kwargs: \"\",\n )\n \n+ # Stubs for the browser-provider plugin layer introduced in PR #25214.\n+ # The fake `agent` package has an empty __path__ so real submodules\n+ # aren't reachable; we install just enough stand-ins to satisfy\n+ # ``tools.browser_tool``'s top-level imports. The actual lifecycle\n+ # tests instantiate the real plugin classes via _load_tool_module\n+ # below, so the stubs only need to satisfy import + isinstance.\n+ class _StubBrowserProvider:\n+ \"\"\"Minimal BrowserProvider stub for ``from agent.browser_provider import BrowserProvider``.\"\"\"\n+\n+ sys.modules[\"agent.browser_provider\"] = types.SimpleNamespace(\n+ BrowserProvider=_StubBrowserProvider,\n+ )\n+ sys.modules[\"agent.browser_registry\"] = types.SimpleNamespace(\n+ get_provider=lambda name: None,\n+ list_providers=lambda: [],\n+ register_provider=lambda provider: None,\n+ _resolve=lambda configured: None,\n+ )\n+\n+ # Plugin module stubs — the real plugin classes are loaded from disk by\n+ # the lifecycle tests below via _load_tool_module(). For the import\n+ # phase, we just need the class names to exist on the right module path.\n+ plugins_package = types.ModuleType(\"plugins\")\n+ plugins_package.__path__ = [] # type: ignore[attr-defined]\n+ sys.modules[\"plugins\"] = plugins_package\n+ plugins_browser_package = types.ModuleType(\"plugins.browser\")\n+ plugins_browser_package.__path__ = [] # type: ignore[attr-defined]\n+ sys.modules[\"plugins.browser\"] = plugins_browser_package\n+\n+ for _name, _classname in (\n+ (\"browserbase\", \"BrowserbaseBrowserProvider\"),\n+ (\"browser_use\", \"BrowserUseBrowserProvider\"),\n+ (\"firecrawl\", \"FirecrawlBrowserProvider\"),\n+ ):\n+ _vendor_pkg = types.ModuleType(f\"plugins.browser.{_name}\")\n+ _vendor_pkg.__path__ = [] # type: ignore[attr-defined]\n+ sys.modules[f\"plugins.browser.{_name}\"] = _vendor_pkg\n+ _provider_stub_cls = type(_classname, (_StubBrowserProvider,), {})\n+ sys.modules[f\"plugins.browser.{_name}.provider\"] = types.SimpleNamespace(\n+ **{_classname: _provider_stub_cls},\n+ )\n+\n sys.modules[\"tools.managed_tool_gateway\"] = _load_tool_module(\n \"tools.managed_tool_gateway\",\n \"managed_tool_gateway.py\",","@@ -157,13 +216,13 @@ def test_browserbase_does_not_use_gateway_only_configuration():\n })\n \n with patch.dict(os.environ, env, clear=True):\n- browserbase_module = _load_tool_module(\n- \"tools.browser_providers.browserbase\",\n- \"browser_providers/browserbase.py\",\n+ browserbase_module = _load_plugin_module(\n+ \"plugins.browser.browserbase.provider\",\n+ \"browser/browserbase/provider.py\",\n )\n- provider = browserbase_module.BrowserbaseProvider()\n+ provider = browserbase_module.BrowserbaseBrowserProvider()\n \n- assert provider.is_configured() is False\n+ assert provider.is_available() is False\n \n \n def test_browser_use_managed_gateway_adds_idempotency_key_and_persists_external_call_id():","@@ -188,13 +247,13 @@ def json(self):\n }\n \n with patch.dict(os.environ, env, clear=True):\n- browser_use_module = _load_tool_module(\n- \"tools.browser_providers.browser_use\",\n- \"browser_providers/browser_use.py\",\n+ browser_use_module = _load_plugin_module(\n+ \"plugins.browser.browser_use.provider\",\n+ \"browser/browser_use/provider.py\",\n )\n \n with patch.object(browser_use_module.requests, \"post\", return_value=_Response()) as post:\n- provider = browser_use_module.BrowserUseProvider()\n+ provider = browser_use_module.BrowserUseBrowserProvider()\n session = provider.create_session(\"task-browser-use-managed\")\n \n sent_headers = post.call_args.kwargs[\"headers\"]","@@ -228,11 +287,11 @@ def json(self):\n }\n \n with patch.dict(os.environ, env, clear=True):\n- browser_use_module = _load_tool_module(\n- \"tools.browser_providers.browser_use\",\n- \"browser_providers/browser_use.py\",\n+ browser_use_module = _load_plugin_module(\n+ \"plugins.browser.browser_use.provider\",\n+ \"browser/browser_use/provider.py\",\n )\n- provider = browser_use_module.BrowserUseProvider()\n+ provider = browser_use_module.BrowserUseBrowserProvider()\n timeout = browser_use_module.requests.Timeout(\"timed out\")\n \n with patch.object(","@@ -290,11 +349,11 @@ def json(self):\n }\n \n with patch.dict(os.environ, env, clear=True):\n- browser_use_module = _load_tool_module(\n- \"tools.browser_providers.browser_use\",\n- \"browser_providers/browser_use.py\",\n+ browser_use_module = _load_plugin_module(\n+ \"plugins.browser.browser_use.provider\",\n+ \"browser/browser_use/provider.py\",\n )\n- provider = browser_use_module.BrowserUseProvider()\n+ provider = browser_use_module.BrowserUseBrowserProvider()\n \n with patch.object(\n browser_use_module.requests,","@@ -337,11 +396,11 @@ def json(self):\n }\n \n with patch.dict(os.environ, env, clear=True):\n- browser_use_module = _load_tool_module(\n- \"tools.browser_providers.browser_use\",\n- \"browser_providers/browser_use.py\",\n+ browser_use_module = _load_plugin_module(\n+ \"plugins.browser.browser_use.provider\",\n+ \"browser/browser_use/provider.py\",\n )\n- provider = browser_use_module.BrowserUseProvider()\n+ provider = browser_use_module.BrowserUseBrowserProvider()\n \n with patch.object(browser_use_module.requests, \"post\", side_effect=[_Response(), _Response()]) as post:\n provider.create_session(\"task-browser-use-new\")"]},{"file":"/dev/null","hunks":["@@ -1,10 +0,0 @@\n-\"\"\"Cloud browser provider abstraction.\n-\n-Import the ABC so callers can do::\n-\n- from tools.browser_providers import CloudBrowserProvider\n-\"\"\"\n-\n-from tools.browser_providers.base import CloudBrowserProvider\n-\n-__all__ = [\"CloudBrowserProvider\"]"]},{"file":"/dev/null","hunks":["@@ -1,59 +0,0 @@\n-\"\"\"Abstract base class for cloud browser providers.\"\"\"\n-\n-from abc import ABC, abstractmethod\n-from typing import Dict\n-\n-\n-class CloudBrowserProvider(ABC):\n- \"\"\"Interface for cloud browser backends (Browserbase, Steel, etc.).\n-\n- Implementations live in sibling modules and are registered in\n- ``browser_tool._PROVIDER_REGISTRY``. The user selects a provider via\n- ``hermes setup`` / ``hermes tools``; the choice is persisted as\n- ``config[\"browser\"][\"cloud_provider\"]``.\n- \"\"\"\n-\n- @abstractmethod\n- def provider_name(self) -> str:\n- \"\"\"Short, human-readable name shown in logs and diagnostics.\"\"\"\n-\n- @abstractmethod\n- def is_configured(self) -> bool:\n- \"\"\"Return True when all required env vars / credentials are present.\n-\n- Called at tool-registration time (``check_browser_requirements``) to\n- gate availability. Must be cheap — no network calls.\n- \"\"\"\n-\n- @abstractmethod\n- def create_session(self, task_id: str) -> Dict[str, object]:\n- \"\"\"Create a cloud browser session and return session metadata.\n-\n- Must return a dict with at least::\n-\n- {\n- \"session_name\": str, # unique name for agent-browser --session\n- \"bb_session_id\": str, # provider session ID (for close/cleanup)\n- \"cdp_url\": str, # CDP websocket URL\n- \"features\": dict, # feature flags that were enabled\n- }\n-\n- ``bb_session_id`` is a legacy key name kept for backward compat with\n- the rest of browser_tool.py — it holds the provider's session ID\n- regardless of which provider is in use.\n- \"\"\"\n-\n- @abstractmethod\n- def close_session(self, session_id: str) -> bool:\n- \"\"\"Release / terminate a cloud session by its provider session ID.\n-\n- Returns True on success, False on failure. Should not raise.\n- \"\"\"\n-\n- @abstractmethod\n- def emergency_cleanup(self, session_id: str) -> None:\n- \"\"\"Best-effort session teardown during process exit.\n-\n- Called from atexit / signal handlers. Must tolerate missing\n- credentials, network errors, etc. — log and move on.\n- \"\"\""]},{"file":"tools/browser_tool.py","hunks":["@@ -83,10 +83,24 @@\n except Exception:\n _is_safe_url = lambda url: False # noqa: E731 — fail-closed: block all if safety module unavailable\n _is_always_blocked_url = lambda url: True # noqa: E731 — fail-closed on the floor too\n-from tools.browser_providers.base import CloudBrowserProvider\n-from tools.browser_providers.browserbase import BrowserbaseProvider\n-from tools.browser_providers.browser_use import BrowserUseProvider\n-from tools.browser_providers.firecrawl import FirecrawlProvider\n+# Browser-provider ABC + registry — PR #25214 moved the per-vendor providers\n+# (Browserbase / Browser Use / Firecrawl) out of ``tools/browser_providers/``\n+# and into ``plugins/browser//``. The dispatcher consults the\n+# registry; the legacy class names are re-exported below as backward-compat\n+# shims for callers that import them from this module.\n+from agent.browser_provider import BrowserProvider as CloudBrowserProvider # noqa: F401 (legacy alias)\n+from agent.browser_registry import ( # noqa: F401 (test-patchable surface)\n+ get_provider as _registry_get_browser_provider,\n+)\n+from plugins.browser.browserbase.provider import ( # noqa: F401 (legacy import surface)\n+ BrowserbaseBrowserProvider as BrowserbaseProvider,\n+)\n+from plugins.browser.browser_use.provider import ( # noqa: F401\n+ BrowserUseBrowserProvider as BrowserUseProvider,\n+)\n+from plugins.browser.firecrawl.provider import ( # noqa: F401\n+ FirecrawlBrowserProvider as FirecrawlProvider,\n+)\n from tools.tool_backend_helpers import normalize_browser_cloud_provider\n \n # Camofox local anti-detection browser backend (optional).","@@ -391,12 +405,29 @@ def _stop_cdp_supervisor(task_id: str) -> None:\n # ============================================================================\n # Cloud Provider Registry\n # ============================================================================\n+#\n+# Per-vendor browser providers (Browserbase / Browser Use / Firecrawl) live as\n+# plugins under ``plugins/browser//`` and self-register through\n+# :mod:`agent.browser_registry` at plugin-discovery time. The legacy\n+# class-name registry below is preserved as a backward-compat shim so test\n+# fixtures that ``monkeypatch.setattr(browser_tool, \"_PROVIDER_REGISTRY\", ...)``\n+# keep working — but ``_get_cloud_provider()`` now consults\n+# :mod:`agent.browser_registry` for the actual lookup.\n+#\n+# When the test patches ``_PROVIDER_REGISTRY``, we honour it (so the cache\n+# unit tests still drive the function); otherwise the registry-backed path\n+# wins. This keeps the test surface stable while letting third-party\n+# plugins drop in under ``~/.hermes/plugins/browser//``.\n \n _PROVIDER_REGISTRY: Dict[str, type] = {\n \"browserbase\": BrowserbaseProvider,\n \"browser-use\": BrowserUseProvider,\n \"firecrawl\": FirecrawlProvider,\n }\n+# Frozen copy of the import-time _PROVIDER_REGISTRY, used by\n+# ``_is_legacy_provider_registry_overridden`` to detect test-time\n+# monkeypatching. NEVER mutate this dict.\n+_DEFAULT_PROVIDER_REGISTRY: Dict[str, type] = dict(_PROVIDER_REGISTRY)\n \n _cached_cloud_provider: Optional[CloudBrowserProvider] = None\n _cloud_provider_resolved = False","@@ -411,13 +442,65 @@ def _stop_cdp_supervisor(task_id: str) -> None:\n _browser_engine_resolved = False\n \n \n+def _is_legacy_provider_registry_overridden() -> bool:\n+ \"\"\"Return True when a test has patched ``_PROVIDER_REGISTRY`` to a custom value.\n+\n+ Detected by spotting any registered class that *isn't* the canonical\n+ plugin-backed class for that name. Tests that\n+ ``monkeypatch.setattr(browser_tool, \"_PROVIDER_REGISTRY\", ...)`` install\n+ custom factories (`exploding_factory`, `lambda: fake_provider`, etc.);\n+ those entries fail the canonical-class identity check below.\n+\n+ Note: a future maintainer adding a 4th built-in provider only needs to\n+ extend ``_DEFAULT_PROVIDER_REGISTRY`` below — they do NOT need to update\n+ a hardcoded set of keys here. The detection just compares each registered\n+ value against the corresponding canonical class.\n+ \"\"\"\n+ try:\n+ for key, default_cls in _DEFAULT_PROVIDER_REGISTRY.items():\n+ if _PROVIDER_REGISTRY.get(key) is not default_cls:\n+ return True\n+ # Extra keys not in the default registry → also an override.\n+ return len(_PROVIDER_REGISTRY) != len(_DEFAULT_PROVIDER_REGISTRY)\n+ except Exception:\n+ return False\n+\n+\n+def _ensure_browser_plugins_loaded() -> None:\n+ \"\"\"Idempotently trigger plugin discovery so the browser registry is populated.\n+\n+ Normally `model_tools` is imported early in any session and that\n+ triggers `discover_plugins()` as a side effect. But `_get_cloud_provider`\n+ can be called from contexts that haven't gone through `model_tools` —\n+ standalone scripts, certain unit-test paths, the parity-sweep harness.\n+ Make discovery idempotent and side-effect-only here so users always\n+ see registered plugins regardless of import order. Cheap: subsequent\n+ calls early-return inside `_ensure_plugins_discovered`.\n+ \"\"\"\n+ try:\n+ from hermes_cli.plugins import _ensure_plugins_discovered\n+\n+ _ensure_plugins_discovered()\n+ except Exception as exc:\n+ logger.debug(\"Browser plugin discovery failed (non-fatal): %s\", exc)\n+\n+\n def _get_cloud_provider() -> Optional[CloudBrowserProvider]:\n \"\"\"Return the configured cloud browser provider, or None for local mode.\n \n Reads ``config[\"browser\"][\"cloud_provider\"]`` once and caches the result\n for the process lifetime. An explicit ``local`` provider disables cloud\n- fallback. If unset, fall back to Browserbase when direct or managed\n- Browserbase credentials are available.\n+ fallback. If unset, fall back to Browser Use (managed Nous gateway or\n+ direct API key) and then Browserbase (direct credentials only) — the\n+ historic auto-detect order, now expressed as the\n+ :data:`agent.browser_registry._LEGACY_PREFERENCE` walk.\n+\n+ Selection routes through :mod:`agent.browser_registry` so third-party\n+ browser plugins (``~/.hermes/plugins/browser//``) participate\n+ in explicit-config resolution. Test fixtures that override\n+ ``_PROVIDER_REGISTRY`` or ``BrowserUseProvider`` / ``BrowserbaseProvider``\n+ on this module still drive the function — see\n+ ``_is_legacy_provider_registry_overridden``.\n \"\"\"\n global _cached_cloud_provider, _cloud_provider_resolved\n if _cloud_provider_resolved:","@@ -437,9 +520,33 @@ def _get_cloud_provider() -> Optional[CloudBrowserProvider]:\n _cached_cloud_provider = None\n _cloud_provider_resolved = True\n return None\n- if provider_key and provider_key in _PROVIDER_REGISTRY:\n+ if provider_key:\n try:\n- resolved = _PROVIDER_REGISTRY[provider_key]()\n+ if _is_legacy_provider_registry_overridden():\n+ # Test fixture path: honour the patched dict so the\n+ # cache-policy unit tests keep working.\n+ factory = _PROVIDER_REGISTRY.get(provider_key)\n+ if factory is not None:\n+ resolved = factory()\n+ else:\n+ # Ensure plugins are discovered so the registry is\n+ # populated. Idempotent — cheap on subsequent calls.\n+ _ensure_browser_plugins_loaded()\n+ resolved = _registry_get_browser_provider(provider_key)\n+ if resolved is None:\n+ # Explicit config name unknown to the registry —\n+ # might be a typo, an uninstalled plugin, or a\n+ # registry-population failure. Warn the user\n+ # (legacy code would have surfaced a typed\n+ # credentials error via direct class instantiation;\n+ # post-migration we surface this WARNING instead).\n+ logger.warning(\n+ \"browser.cloud_provider=%r is not a registered \"\n+ \"browser plugin; falling back to auto-detect \"\n+ \"(install the corresponding plugin or fix the \"\n+ \"config key spelling).\",\n+ provider_key,\n+ )\n except Exception:\n logger.warning(\n \"Failed to instantiate explicit cloud_provider %r; will retry on next call\",","@@ -453,8 +560,15 @@ def _get_cloud_provider() -> Optional[CloudBrowserProvider]:\n logger.debug(\"Could not read cloud_provider from config: %s\", e)\n \n if resolved is None:\n- # Prefer Browser Use (managed Nous gateway or direct API key),\n- # fall back to Browserbase (direct credentials only).\n+ # Auto-detect path: Browser Use first (managed Nous gateway or\n+ # direct API key), then Browserbase (direct credentials). Uses\n+ # the legacy class names imported at the top of this module so\n+ # tests that ``monkeypatch.setattr(browser_tool, \"BrowserUseProvider\", ...)``\n+ # keep driving this branch deterministically. Third-party browser\n+ # plugins are intentionally NOT reachable from auto-detect — they\n+ # participate only via explicit ``browser.cloud_provider: ``,\n+ # mirroring the firecrawl gate documented on\n+ # :data:`agent.browser_registry._LEGACY_PREFERENCE`.\n try:\n fallback_provider = BrowserUseProvider()\n if fallback_provider.is_configured():\n"]}]}],"trust":{"default_tier":"verified","includes_suggested":false}}