PL j"UdZddlmZddlZddlZddlmZmZmZddl m Z ej e Z iZded<ejZdd ZddZddZdZddZddZddZdS)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] _providersproviderrreturnNonec<t|ts$tdt|j|j}t|t r|stdt5t |}|t|<dddn #1swxYwY|0t d|t|jdSt d|t|jdS)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 N NLMMM $$>>$''# 4$$$$$$$$$$$$$$$ : $x..)      3 $x..)     s%B11B58B5List[BrowserProvider]ct5tt}dddn #1swxYwYt |dS)z0Return all registered providers, sorted by name.Nc|jS)Nr)ps rz list_providers..Vsqv)key)rlistrvaluessorted)itemss rlist_providersr(Rs **Z&&(())*************** %-- . . ..s ';??rrOptional[BrowserProvider]ct|tsdSt5t|cdddS#1swxYwYdS)z5Return the provider registered under *name*, or None.N)r rrrrrrs r get_providerr+Ys dC t ,,~~djjll++,,,,,,,,,,,,,,,,,,s,AAA)z browser-use browserbase configured Optional[str]cPt5tt}dddn #1swxYwYd d}|dkrdS|r4||}||Std|t D](}||}|||r|cS)dS) 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. Nr rr boolc t|S#t$r.}td|j|dYd}~dSd}~wwxYw)zDWrap ``is_available()`` so a buggy provider doesn't kill resolution.uHBrowser provider %s.is_available() raised %s — treating as unavailableT)exc_infoNF)r0 is_available Exceptionrwarningr)r excs r_is_available_safez$_resolve.._is_available_safest (()) )    NNZd    55555  s # A#AAlocalzVbrowser cloud_provider '%s' configured but not registered; falling back to auto-detect)r rr r0)rdictrrrr_LEGACY_PREFERENCE)r-snapshotr7r legacys r_resolver=qsB $$ ##$$$$$$$$$$$$$$$    Wt  << ++  O  *    %<<''  $6$6x$@$@ OOO 4s )--c ddlm}|}|di}n4#t$r'}td|i}Yd}~nd}~wwxYwd}t |tr^d|vrZ ddlm }||d}n4#t$r'}td|d}Yd}~nd}~wwxYwt|S) zResolve the currently-active cloud browser provider. Reads ``browser.cloud_provider`` from config.yaml; falls back per the module docstring. Returns None for local mode or when no provider is available. r)read_raw_configbrowserz!Could not read browser config: %sNcloud_provider) normalize_browser_cloud_providerz+normalize_browser_cloud_provider failed: %s) hermes_cli.configr?rr4rrr r9tools.tool_backend_helpersrBr=)r?cfg browser_cfgr6r-rBs rget_active_browser_providerrGs2555555oggi,,  8#>>> !%J+t$$ )9[)H)H  S S S S S S99 011JJ    LLF L L LJJJJJJ  J  s,&) AAA9$B C(C  Ccxt5tddddS#1swxYwYdS)z"Clear the registry. **Test-only.**N)rrclearr"r_reset_for_testsrKs~ s /33)r rr r )r r)rrr r))r-r.r r))r r))r r )__doc__ __future__rlogging threadingtypingrrragent.browser_providerr getLoggerrrr__annotations__Lockrrr(r+r:r=rGrKrJr"rrUs1"""H#"""""''''''''''222222  8 $ $*, ++++     <////,,,,$ IIIIX    >r"