| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284 |
- """``browser.*`` config knobs and cloud browser provider resolution (explicit ``browser.cloud_provider``,
- auto-detect, per-profile cache).
- Every config read is profile-scoped: under a routed profile (multiplexed gateway, HERMES_HOME override)
- the cached slots are bypassed or keyed by ``hermes_home_key()``, so one profile's engine / headed /
- private-URL policy never reaches another.
- """
- from __future__ import annotations
- import logging
- import threading
- from typing import Any, Callable, Optional
- from agent.browser_provider import BrowserProvider
- from hermes_constants import get_hermes_home_override, hermes_home_key
- from tools.tool_backend_helpers import normalize_browser_cloud_provider
- from utils import is_truthy_value
- logger = logging.getLogger(__name__)
- DEFAULT_COMMAND_TIMEOUT = 30
- _VALID_ENGINES = ("auto", "lightpanda")
- # Per-profile memo for config-derived values: {name: {home_key: value}}. ``reset_caches`` clears it.
- _memo_slots: dict[str, dict[str, Any]] = {}
- _memo_lock = threading.Lock()
- # Cloud provider cache keyed by (home_key, registry generation): a plugin (re)registering a provider
- # bumps the generation and the next lookup resolves again.
- _cached_providers: dict[tuple[str, Any], Optional[BrowserProvider]] = {}
- _provider_lock = threading.RLock()
- def browser_section() -> dict:
- """The active profile's ``browser:`` section as every runtime reader sees it: the user file, the managed
- overlay winning, ``${VAR}`` expanded, no defaults (``load_user_config_effective``); ``{}`` when absent."""
- from hermes_cli.config_effective import load_user_config_effective
- section = load_user_config_effective().get("browser")
- return section if isinstance(section, dict) else {}
- def browser_cfg(key: str, default, parse: Callable[[Any], Any] = lambda v: v):
- """``parse(browser.<key>)`` from :func:`browser_section`; ``default`` when absent or unparseable."""
- try:
- section = browser_section()
- if key in section:
- return parse(section[key])
- except (OSError, ValueError, TypeError) as exc:
- logger.debug("Could not read browser.%s: %s", key, exc)
- return default
- def _memo(name: str, compute: Callable[[], Any]):
- """Process cache, one slot per profile home; a routed profile always recomputes."""
- if get_hermes_home_override() is not None:
- return compute()
- home = hermes_home_key()
- with _memo_lock:
- slot = _memo_slots.setdefault(name, {})
- if home in slot:
- return slot[home]
- value = compute()
- with _memo_lock:
- _memo_slots.setdefault(name, {})[home] = value
- return value
- def reset_caches(home_key: Optional[str] = None) -> None:
- """Drop cached config reads (all homes, or only ``home_key``'s) and the provider cache."""
- with _memo_lock:
- if home_key is None:
- _memo_slots.clear()
- else:
- for slot in _memo_slots.values():
- slot.pop(home_key, None)
- with _provider_lock:
- for key in [k for k in _cached_providers if home_key in (None, k[0])]:
- _cached_providers.pop(key, None)
- def _truthy(value) -> bool:
- return is_truthy_value(value, default=False)
- def command_timeout() -> int:
- """``browser.command_timeout`` (floored at 5 s): the floor of the Chromium launch timeout."""
- return _memo("command_timeout", lambda: browser_cfg(
- "command_timeout", DEFAULT_COMMAND_TIMEOUT,
- lambda v: DEFAULT_COMMAND_TIMEOUT if v is None else max(int(v), 5)))
- def inactivity_timeout(default: int) -> int:
- """``browser.inactivity_timeout`` (30 s floor: no instant reaping)."""
- return browser_cfg("inactivity_timeout", default, lambda v: default if v is None else max(int(v), 30))
- def chromium_args() -> list[str]:
- """``browser.chromium_args``: extra flags appended to every packaged/shared Chromium launch."""
- def parse(value) -> list[str]:
- if isinstance(value, str):
- value = [part for part in value.replace("\n", ",").split(",")]
- return [str(v).strip() for v in (value or []) if str(v).strip()]
- return browser_cfg("chromium_args", [], parse)
- def executable_path() -> str:
- """``browser.executable_path`` ("" = the packaged Chromium)."""
- return browser_cfg("executable_path", "", lambda v: str(v or "").strip())
- def user_data_dir() -> str:
- """``browser.user_data_dir``: a persistent profile every session shares ("" = fresh per session).
- ``~`` expands; a relative path is anchored at this profile's HERMES_HOME."""
- import os
- raw = browser_cfg("user_data_dir", "", lambda v: str(v or "").strip())
- if not raw:
- return ""
- raw = os.path.expanduser(raw)
- if os.path.isabs(raw):
- return raw
- from hermes_constants import get_hermes_home
- return str(get_hermes_home() / raw)
- def get_browser_engine() -> str:
- """``auto`` (packaged Chromium) or ``lightpanda``; ``chrome`` is accepted as ``auto``."""
- def compute() -> str:
- engine = browser_cfg("engine", "auto", lambda v: str(v).strip().lower() if v and str(v).strip() else "auto")
- if engine == "chrome":
- return "auto"
- if engine not in _VALID_ENGINES:
- logger.warning("Unknown browser engine %r (valid: %s), using 'auto'", engine, ", ".join(_VALID_ENGINES))
- return "auto"
- return engine
- return _memo("engine", compute)
- def is_headed_mode() -> bool:
- """``browser.headed``: launch a visible window (Linux: only when a display exists)."""
- return _memo("headed", lambda: browser_cfg("headed", False, _truthy))
- def auto_local_for_private_urls() -> bool:
- """``browser.auto_local_for_private_urls`` (default True): route private/LAN URLs to a local sidecar
- browser even with a cloud provider configured."""
- return _memo("auto_local", lambda: browser_cfg("auto_local_for_private_urls", True, bool))
- def use_real_profile() -> bool:
- """Real-profile consent. Read on EVERY call: it is a consent switch (flipping it off must not need a
- restart) and each multiplexed profile decides for itself."""
- return browser_cfg("use_real_profile", False, bool)
- def allow_private_urls() -> bool:
- """Whether the browser may navigate to private/internal addresses (default False: SSRF guard on)."""
- return _memo("allow_private_urls", lambda: browser_cfg("allow_private_urls", False, _truthy))
- # ── Cloud provider ───────────────────────────────────────────────────────────────────────────────────
- def _registry_generation(scope: str):
- try:
- from agent.browser_registry import registry_generation
- except ImportError: # isolated compat stubs ship only get_provider
- return (0, 0)
- return registry_generation(scope=scope)
- def _ensure_browser_plugins_loaded() -> None:
- """Idempotent plugin discovery (standalone scripts/tests may never import ``model_tools``)."""
- try:
- from hermes_cli.plugins import _ensure_plugins_discovered
- _ensure_plugins_discovered()
- except Exception as exc: # health: allow BLE001 -- plugin discovery failure must never break browsing
- logger.debug("Browser plugin discovery failed (non-fatal): %s", exc)
- def _instantiate_explicit_provider(provider_key: str) -> Optional[BrowserProvider]:
- """The provider named by ``browser.cloud_provider``. An unregistered name raises ``ValueError`` (never a
- silent reroute to auto-detect); any other instantiation error yields None so the next call retries."""
- from agent.browser_registry import get_provider
- try:
- _ensure_browser_plugins_loaded()
- resolved = get_provider(provider_key)
- except Exception: # health: allow BLE001 -- a broken provider plugin must not take the browser down
- logger.warning("Failed to instantiate cloud_provider %r; will retry on next call", provider_key, exc_info=True)
- return None
- if resolved is None:
- from tools.tool_backend_helpers import selection_error
- raise ValueError(selection_error(
- "browser", f"'{provider_key}'",
- "no registered browser plugin has that name (install the corresponding plugin or fix the config key spelling)",
- ))
- return resolved
- def _autodetect_provider() -> Optional[BrowserProvider]:
- """Browser Use, then Browserbase, from credentials; never raises. Third-party plugins are only reachable
- through an explicit ``browser.cloud_provider``."""
- # Late import: a core tool must not execute bundled plugin code before a session is resolved.
- from plugins.browser.browser_use.provider import BrowserUseBrowserProvider
- from plugins.browser.browserbase.provider import BrowserbaseBrowserProvider
- try:
- for cls in (BrowserUseBrowserProvider, BrowserbaseBrowserProvider):
- provider = cls()
- if provider.is_available():
- return provider
- except Exception: # health: allow BLE001 -- auto-detect must never poison the cache
- logger.debug("Cloud provider auto-detect failed", exc_info=True)
- return None
- def _resolve_provider_uncached() -> tuple[Optional[BrowserProvider], bool]:
- """``(provider, definitive)``. Definitive answers (explicit ``local``/``camofox``, a resolved provider) are
- cached; a transient None (unreadable config, missing credentials) is not, so it self-heals."""
- provider_key = None
- try:
- section = browser_section()
- if "cloud_provider" in section:
- provider_key = normalize_browser_cloud_provider(section.get("cloud_provider"))
- except (OSError, ValueError, TypeError) as exc:
- logger.debug("Could not read cloud_provider from config: %s", exc)
- if provider_key in ("local", "camofox"):
- return None, True # camofox is a plugin with its own tool surface, not a CDP provider
- if provider_key == "nous":
- provider_key = "browser-use" # the managed Nous subscription is served by the Browser Use provider
- if provider_key:
- resolved = _instantiate_explicit_provider(provider_key)
- return resolved, resolved is not None
- if provider_key is not None: # an empty selection was written: no auto-detect
- return None, False
- resolved = _autodetect_provider()
- return resolved, resolved is not None
- def get_cloud_provider() -> Optional[BrowserProvider]:
- """The cloud provider for the active profile, or None for local browsing."""
- scope = hermes_home_key()
- with _provider_lock:
- while True:
- before = _registry_generation(scope)
- if (scope, before) in _cached_providers:
- return _cached_providers[(scope, before)]
- resolved, definitive = _resolve_provider_uncached()
- if _registry_generation(scope) != before: # a reload landed mid-resolution: resolve again
- continue
- if definitive:
- for stale in [k for k in _cached_providers if k[0] == scope]:
- _cached_providers.pop(stale, None)
- _cached_providers[(scope, before)] = resolved
- return resolved
- def is_local_backend() -> bool:
- """True when the browser runs locally AND the terminal is local too.
- SSRF protection matters only when the browser reaches networks the terminal cannot (cloud backends,
- containerized terminals). A CDP override is never trusted as local (that Chrome may live off-host).
- """
- from tools.browser_session_cdp import get_cdp_override_raw
- if get_cdp_override_raw() or get_cloud_provider() is not None:
- return False
- # Scope-aware: under multiplexing the routed profile's terminal backend lives in the per-turn scope (#68559).
- from tools.terminal_scope import terminal_env
- return terminal_env("TERMINAL_ENV", "local").strip().lower() in ("local", "")
- def browser_backend_name(local_engine: Optional[str] = None) -> str:
- """Shared-metrics label for the active profile's backend in session-creation precedence
- (CDP override > cloud provider > local engine). ``local_engine``: the call ran on a LOCAL browser (the
- hybrid ``::local`` sidecar, a cloud failure's local fallback, the real profile) of that engine (``local``
- or ``lightpanda``, as its session was created), so neither a configured provider nor ``browser.engine``
- names it. Config reads only, no network I/O."""
- from tools.browser_session_cdp import get_cdp_override_raw
- if get_cdp_override_raw():
- return "cdp"
- if local_engine:
- return local_engine
- provider = get_cloud_provider()
- if provider is not None:
- return str(getattr(provider, "name", "") or "other")
- return "lightpanda" if get_browser_engine() == "lightpanda" else "local"
|