yjTdZddlmZddlZddlmZmZGddejZdS)u Browser Provider ABC ==================== Defines the pluggable-backend interface for cloud browser providers (Browserbase, Browser Use, Firecrawl, …). Providers register instances via :meth:`PluginContext.register_browser_provider`; the active one (selected via ``browser.cloud_provider`` in ``config.yaml``) services every cloud-mode ``browser_*`` tool call. Providers live in ``/plugins/browser//`` (built-in, auto-loaded as ``kind: backend``) or ``~/.hermes/plugins/browser//`` (user, opt-in via ``plugins.enabled``). This ABC mirrors :class:`agent.web_search_provider.WebSearchProvider` (PR #25182) — same shape, same registration flow, same picker integration. The legacy in-tree ``tools.browser_providers.base.CloudBrowserProvider`` ABC was deleted in PR #25214 (this work) along with the per-vendor inline modules in ``tools/browser_providers/``; the lifecycle contract documented below is preserved bit-for-bit so the tool wrapper (:mod:`tools.browser_tool`) does not have to translate. Session metadata contract (preserved from the legacy ``CloudBrowserProvider``):: { "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 "expires_at": str, # optional provider-authoritative ISO timestamp "features": dict, # feature flags that were enabled "external_call_id": str, # optional, managed-gateway billing key } ``bb_session_id`` is a legacy key name kept verbatim for backward compat with :mod:`tools.browser_tool` — it holds the provider's session ID regardless of which provider is in use. ) annotationsN)AnyDictceZdZdZeejddZeddZejddZ ejdd Z ejdd Z ejddZ ddZ ddZddZdS)BrowserProvideruAbstract base class for a cloud browser backend. Subclasses must implement :meth:`name`, :meth:`is_available`, and the three lifecycle methods: :meth:`create_session`, :meth:`close_session`, :meth:`emergency_cleanup`. The lifecycle shape preserves the legacy ``CloudBrowserProvider`` contract bit-for-bit so the dispatcher in :mod:`tools.browser_tool` is a pure registry lookup — no per-provider conditionals, no shape translation. returnstrcdS)zStable short identifier used in the ``browser.cloud_provider`` config key. Lowercase, hyphens permitted to preserve existing user-visible names. Examples: ``browserbase``, ``browser-use``, ``firecrawl``. Nselfs c|jS)zEHuman-readable label shown in ``hermes tools``. Defaults to ``name``.)rr s r display_namezBrowserProvider.display_nameHs yrboolcdS)uReturn True when this provider can service calls. Typically a cheap check (env var present, managed-gateway token readable, optional Python dep importable). Must NOT make network calls — this runs at tool-registration time and on every ``hermes tools`` paint. Mirrors the legacy ``CloudBrowserProvider.is_configured()`` method; renamed for parity with :class:`agent.web_search_provider.WebSearchProvider`. Nr r s r is_availablezBrowserProvider.is_availableMrrtask_idDict[str, object]cdS)uzCreate 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 "expires_at": str, # optional provider-authoritative ISO timestamp "features": dict, # feature flags that were enabled } ``bb_session_id`` is a legacy key name kept for backward compat with the rest of :mod:`tools.browser_tool` — it holds the provider's session ID regardless of which provider is in use. May raise ``ValueError`` (missing credentials) or ``RuntimeError`` (network / API failure); the dispatcher surfaces these to the user. Nr )r rs rcreate_sessionzBrowserProvider.create_sessionZrr session_idcdS)uRelease / terminate a cloud session by its provider session ID. Returns True on success, False on failure. Should not raise — log and return False on any exception so the dispatcher's cleanup loop keeps moving across sessions. Nr r rs r close_sessionzBrowserProvider.close_sessionprrNonecdS)uBest-effort session teardown during process exit. Called from atexit / signal handlers. Must tolerate missing credentials, network errors, etc. — log and move on. Must not raise. Nr rs remergency_cleanupz!BrowserProvider.emergency_cleanupyrrDict[str, Any]c|jddgdS)avReturn provider metadata for the ``hermes tools`` picker. Used by :mod:`hermes_cli.tools_config` to inject this provider as a row in the Browser Automation picker. Shape mirrors the existing hardcoded entries in ``TOOL_CATEGORIES["browser"]``:: { "name": "Browserbase", "badge": "paid", "tag": "Cloud browser with stealth and proxies", "env_vars": [ {"key": "BROWSERBASE_API_KEY", "prompt": "Browserbase API key", "url": "https://browserbase.com"}, ], "post_setup": "agent_browser", } Default: minimal entry derived from :attr:`display_name`. Override to expose API key prompts, badges, managed-Nous gating, and the ``post_setup`` install hook. )rbadgetagenv_varsrr s rget_setup_schemaz BrowserProvider.get_setup_schemas"0%    rc*|S)z/Backward-compat alias for :meth:`is_available`.)rr s r is_configuredzBrowserProvider.is_configureds  """rc|jS)z5Backward-compat alias returning :attr:`display_name`.r(r s r provider_namezBrowserProvider.provider_names   rN)rr )rr)rr rr)rr rr)rr rr)rr")__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrrrr!r)r+r-r rrrr2s9     X X            *              T####!!!!!!rr) r1 __future__rr3typingrrABCrr rrr8s$$L#""""" !!!!!cg!!!!!r