browser_provider.py 2.7 KB

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