`gjUdZddlmZddlZddlZddlmZmZmZddl m Z eje Z iZded<ej ZddZdd Zdd Zd Zdd Zdd Zy)u Browser Provider Registry ========================= Central map of registered cloud browser providers. Populated by plugins at import-time via :meth:`PluginContext.register_browser_provider`; consumed by :func:`tools.browser_tool._get_cloud_provider` to route each cloud-mode ``browser_*`` tool call to the active backend. Active selection ---------------- The active provider is chosen by configuration with this precedence: 1. ``browser.cloud_provider`` in ``config.yaml`` (explicit override). 2. Legacy preference order — ``browser-use`` → ``browserbase`` — filtered by availability. Matches the historic auto-detect order in :func:`tools.browser_tool._get_cloud_provider` (Browser Use checked first because it covers both the managed Nous gateway and direct API key path; Browserbase as the older direct-credentials fallback). ``firecrawl`` is intentionally NOT in the legacy walk — users only get Firecrawl as a cloud browser when they explicitly set ``browser.cloud_provider: firecrawl``, matching pre-migration behaviour where Firecrawl was never auto-selected. 3. Otherwise ``None`` — the dispatcher falls back to local browser mode. The explicit-config branch (rule 1) intentionally ignores ``is_available()`` so the dispatcher surfaces a typed "X_API_KEY is not set" error to the user instead of silently switching backends. Matches the legacy :func:`tools.browser_tool._get_cloud_provider` behaviour for configured names. Note: there is no "capability" split here (unlike the web subsystem, which has search/extract/crawl). Every browser provider implements the full :class:`agent.browser_provider.BrowserProvider` lifecycle; the registry's job is purely selection, not capability routing. ) annotationsN)DictListOptional)BrowserProviderzDict[str, BrowserProvider] _providersct|ts!tdt|j|j }t|t r|js tdt5tj|}|t|<ddd+tjd|t|jytjd|t|jy#1swYaxYw)uRegister a cloud browser provider. Re-registration (same ``name``) overwrites the previous entry and logs a debug message — makes hot-reload scenarios (tests, dev loops) behave predictably. z**+ -   ==D dC  LMM $>>$'# 4$ : $x.))  3 $x.)) $$s /C..C7ct5ttj}dddt dS#1swYxYw)z0Return all registered providers, sorted by name.Nc|jS)Nr)ps rz list_providers..Vs qvv)key)rlistrvaluessorted)itemss rlist_providersr%Rs; *Z&&()* %- ..**s ;Act|tsyt5tj |j cdddS#1swYyxYw)z5Return the provider registered under *name*, or None.N)r rrrrrrs r get_providerr'Ys9 dC  ,~~djjl+,,,s #AA)z browser-use browserbasect5tt}ddddd}|dk(ry|r+j|}||Stj d|t D]"}j|}|||s |cSy#1swYlxYw)uResolve the active browser provider. Resolution rules (in order): 1. **Explicit "local".** Returns None — the dispatcher disables cloud mode entirely. Mirrors legacy short-circuit in :func:`tools.browser_tool._get_cloud_provider`. 2. **Explicit config wins, ignoring availability.** If ``configured`` names a registered provider, return it even if its :meth:`is_available` returns False — the dispatcher will surface a precise "X_API_KEY is not set" error instead of silently routing somewhere else. 3. **Legacy preference walk, filtered by availability.** Walk :data:`_LEGACY_PREFERENCE` (``browser-use`` → ``browserbase``) looking for a provider whose ``is_available()`` is True. There is intentionally NO "single-eligible shortcut" rule here (unlike :func:`agent.web_search_registry._resolve`). Pre-migration, the auto-detect branch in ``tools.browser_tool._get_cloud_provider`` only considered Browser Use and Browserbase; Firecrawl was reachable only via an explicit ``browser.cloud_provider: firecrawl`` config key. Preserving that gate matters because Firecrawl shares its API key with the *web* extract plugin (``plugins/web/firecrawl/``), so users who set ``FIRECRAWL_API_KEY`` for web extract must NOT get silently routed to a paid cloud browser on a fresh install. Third-party browser-provider plugins added under ``~/.hermes/plugins/browser//`` are subject to the same gate — they must be explicitly configured to take effect. Returns None when no provider is configured AND no available provider matches the legacy preference; the dispatcher then falls back to local browser mode. Nc t|jS#t$r-}tj d|j |dYd}~yd}~wwxYw)zDWrap ``is_available()`` so a buggy provider doesn't kill resolution.uHBrowser provider %s.is_available() raised %s — treating as unavailableT)exc_infoNF)bool is_available Exceptionrwarningr)rexcs r_is_available_safez$_resolve.._is_available_safesM () )  NNZd    s A#A  AlocalzVbrowser cloud_provider '%s' configured but not registered; falling back to auto-detect)rrreturnr,)rdictrrrr_LEGACY_PREFERENCE) configuredsnapshotr1rlegacys r_resolver9qsB $ #$ W << +  O  *  %<<'  $6x$@O Q$$s BB cbt5tjdddy#1swYyxYw)z"Clear the registry. **Test-only.**N)rrclearrr_reset_for_testsr=s& s%.)rrr3None)r3zList[BrowserProvider])rrr3Optional[BrowserProvider])r6z Optional[str]r3r?)r3r>)__doc__ __future__rlogging threadingtypingrrragent.browser_providerr getLoggerr rr__annotations__Lockrrr%r'r5r9r=r<rrrIso"H#''2   8 $*, &+  </,$ IXr