§ ÷‍yjîمَہ—UdZddlmZddlZddlZddlmZmZmZddl m Z eje¦«Z iZded<ej¦«Zdd„Zdd„Zdd„ZdZdd„Zdd„ZdS)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)عDictعListعOptional)عBrowserProviderzDict[str, BrowserProvider]ع _providersعproviderrعreturnعNonecَ<—t|t¦«s$tdt|¦«j›‌¦«‚|j}t|t¦«r| ¦«std¦«‚t5t |¦«}|t|<ddd¦«n#1swxYwY|پ0t d|t|¦«j¦«dSt d|t|¦«j¦«dS)uرRegister 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فگd‌Cر ش ًN¨¯ ھ ©¬ًNفذLرMشMذMف ً$ً$ف—>’> $ر'ش'ˆط#چ گ4رً$ً$ً$ٌ$ô$ً$ً$ً$ً$ً$ً$ًّّّ$ً$ً$ً$ًذفڈٹط:ط•$گx‘.”.ش)ٌ ô ً ً ً ُ ڈٹط3ط•$گx‘.”.ش)ٌ ô ً ً ً sآ%B1آ1B5آ8B5ْList[BrowserProvider]cَ°—t5tt ¦«¦«}ddd¦«n#1swxYwYt |d„¬¦«S)z0Return all registered providers, sorted by name.Ncَ—|jS)N©r)عps rْz list_providers..Vs€ q¤v€َ)عkey)rعlistrعvaluesعsorted)عitemss rعlist_providersr(Rsچ€ه ً*ً*ف•Z×&ز&ر(ش(ر)ش)ˆً*ً*ً*ٌ*ô*ً*ً*ً*ً*ً*ً*ًّّّ*ً*ً*ً*هگ%ذ-ذ-ذ.ر.ش.ذ.s ˆ';»?ء?rrْOptional[BrowserProvider]cَت—t|t¦«sdSt5t | ¦«¦«cddd¦«S#1swxYwYdS)z5Return the provider registered under *name*, or None.N)r rrrrrrs rعget_providerr+Ysڑ€هگd‌Cر ش ًطˆtف ً,ً,فڈ~ٹ~کdںjڑj™lœlر+ش+ً,ً,ً,ً,ٌ,ô,ً,ً,ً,ً,ً,ً,ًّّّ,ً,ً,ً,ً,ً,sں,AءAءA)zbrowser-useعbrowserbaseع configuredْ Optional[str]cَP—t5tt¦«}ddd¦«n#1swxYwYd d„}|dkrdS|r4| |¦«}|پ|St d|¦«tD](}| |¦«}|پ||¦«r|cSŒ)dS) uزResolve 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.}t d|j|d¬¦«Yd}~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ع Exceptionrعwarningr)r عexcs rع_is_available_safez$_resolve.._is_available_safe•st€ً فکںڑر(ش(ر)ش)ذ)ّفً ً ً فڈNٹNطZط”ک dً ٌ ô ً ًگ5گ5گ5گ5گ5ًّّّّ ّّّs‚ #£ A#AءAعlocalzVbrowser cloud_provider '%s' configured but not registered; falling back to auto-detect)r rr r0)rعdictrrrrع_LEGACY_PREFERENCE)r-عsnapshotr7r عlegacys rع_resolver=qs€ُB ً$ً$ف‌ ر#ش#ˆً$ً$ً$ٌ$ô$ً$ً$ً$ً$ً$ً$ًّّّ$ً$ً$ً$ً ً ً ً ًگWزذطˆtً ً ط—<’< ر+ش+ˆطذطˆOفڈٹً *àٌ ô ً ُ%ًًˆط—<’< ر'ش'ˆطذذ$6ذ$6°xر$@ش$@ذطˆOˆOˆOّàˆ4sˆ)©-°-cَx—t5t ¦«ddd¦«dS#1swxYwYdS)z"Clear the registry. **Test-only.**N)rrعclear©r"rع_reset_for_testsrA½s~€ه ًًف×زرشذًًًٌôًًًًًًًًًًًًًّّّsˆ/¯3¶3)r rr r)r r)rrr r))r-r.r r))r r)ع__doc__ع __future__rعloggingع threadingعtypingrrrعagent.browser_providerrع getLoggerrrrع__annotations__عLockrrr(r+r:r=rAr@r"rْrKsًً"ً"ً"ًH#ذ"ذ"ذ"ذ"ذ"à€€€طذذذط'ذ'ذ'ذ'ذ'ذ'ذ'ذ'ذ'ذ'à2ذ2ذ2ذ2ذ2ذ2à ˆش ک8ر $ش $€ً*,€ ذ+ذ+ذ+ر+طˆ Œرش€ً ً ً ً ً