| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657 |
- """Browser Provider ABC: pluggable cloud browser backends (Browserbase, Browser Use, Firecrawl, …).
- Providers register via :meth:`PluginContext.register_browser_provider`; the active one (selected by
- ``browser.cloud_provider``) supplies the CDP browser ``browser_exec`` drives in cloud mode. They live in
- ``<repo>/plugins/browser/<name>/`` (built-in) or ``~/.hermes/plugins/browser/<name>/`` (user).
- Session metadata contract (legacy ``CloudBrowserProvider`` shape; ``tools.browser_session`` caches it
- as-is). ``bb_session_id`` is a legacy key name kept verbatim — it holds the provider's session ID
- regardless of provider::
- {
- "session_name": str, # unique session label (logs only)
- "bb_session_id": str, # provider session ID (for close/cleanup)
- "cdp_url": str, # CDP websocket URL
- "expires_at": str, # optional provider-authoritative ISO timestamp
- "features": dict, # feature flags that were enabled
- "external_call_id": str, # optional, managed-gateway billing key
- }
- """
- from __future__ import annotations
- import abc
- from typing import Dict
- from agent.provider_base import ProviderBase
- class BrowserProvider(ProviderBase):
- """Abstract base class for a cloud browser backend.
- Subclasses implement :attr:`name` (the ``browser.cloud_provider`` value), :meth:`is_available`, and
- the lifecycle trio :meth:`create_session` / :meth:`close_session` / :meth:`emergency_cleanup`.
- ``get_setup_schema`` may add ``"post_setup"`` naming a ``hermes tools`` install hook.
- """
- @abc.abstractmethod
- def is_available(self) -> bool:
- """True when this provider can service calls. Cheap check only (env var, token readable, dep
- importable) — must NOT make network calls; runs at tool-registration time and on every
- ``hermes tools`` paint."""
- @abc.abstractmethod
- def create_session(self, task_id: str) -> dict[str, object]:
- """Create a cloud browser session and return the metadata dict from the module docstring.
- May raise ``ValueError`` (missing credentials) or ``RuntimeError`` (network / API failure);
- the dispatcher surfaces these to the user."""
- @abc.abstractmethod
- def close_session(self, session_id: str) -> bool:
- """Release a cloud session by provider session ID. Returns True on success, False on failure;
- should not raise (log and return False so the dispatcher's cleanup loop keeps moving)."""
- @abc.abstractmethod
- def emergency_cleanup(self, session_id: str) -> None:
- """Best-effort teardown from atexit / signal handlers. Must tolerate missing credentials and
- network errors; must not raise."""
|