browser_session_cloud.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  1. """``browser.*`` config knobs and cloud browser provider resolution (explicit ``browser.cloud_provider``,
  2. auto-detect, per-profile cache).
  3. Every config read is profile-scoped: under a routed profile (multiplexed gateway, HERMES_HOME override)
  4. the cached slots are bypassed or keyed by ``hermes_home_key()``, so one profile's engine / headed /
  5. private-URL policy never reaches another.
  6. """
  7. from __future__ import annotations
  8. import logging
  9. import threading
  10. from typing import Any, Callable, Optional
  11. from agent.browser_provider import BrowserProvider
  12. from hermes_constants import get_hermes_home_override, hermes_home_key
  13. from tools.tool_backend_helpers import normalize_browser_cloud_provider
  14. from utils import is_truthy_value
  15. logger = logging.getLogger(__name__)
  16. DEFAULT_COMMAND_TIMEOUT = 30
  17. _VALID_ENGINES = ("auto", "lightpanda")
  18. # Per-profile memo for config-derived values: {name: {home_key: value}}. ``reset_caches`` clears it.
  19. _memo_slots: dict[str, dict[str, Any]] = {}
  20. _memo_lock = threading.Lock()
  21. # Cloud provider cache keyed by (home_key, registry generation): a plugin (re)registering a provider
  22. # bumps the generation and the next lookup resolves again.
  23. _cached_providers: dict[tuple[str, Any], Optional[BrowserProvider]] = {}
  24. _provider_lock = threading.RLock()
  25. def browser_section() -> dict:
  26. """The active profile's ``browser:`` section as every runtime reader sees it: the user file, the managed
  27. overlay winning, ``${VAR}`` expanded, no defaults (``load_user_config_effective``); ``{}`` when absent."""
  28. from hermes_cli.config_effective import load_user_config_effective
  29. section = load_user_config_effective().get("browser")
  30. return section if isinstance(section, dict) else {}
  31. def browser_cfg(key: str, default, parse: Callable[[Any], Any] = lambda v: v):
  32. """``parse(browser.<key>)`` from :func:`browser_section`; ``default`` when absent or unparseable."""
  33. try:
  34. section = browser_section()
  35. if key in section:
  36. return parse(section[key])
  37. except (OSError, ValueError, TypeError) as exc:
  38. logger.debug("Could not read browser.%s: %s", key, exc)
  39. return default
  40. def _memo(name: str, compute: Callable[[], Any]):
  41. """Process cache, one slot per profile home; a routed profile always recomputes."""
  42. if get_hermes_home_override() is not None:
  43. return compute()
  44. home = hermes_home_key()
  45. with _memo_lock:
  46. slot = _memo_slots.setdefault(name, {})
  47. if home in slot:
  48. return slot[home]
  49. value = compute()
  50. with _memo_lock:
  51. _memo_slots.setdefault(name, {})[home] = value
  52. return value
  53. def reset_caches(home_key: Optional[str] = None) -> None:
  54. """Drop cached config reads (all homes, or only ``home_key``'s) and the provider cache."""
  55. with _memo_lock:
  56. if home_key is None:
  57. _memo_slots.clear()
  58. else:
  59. for slot in _memo_slots.values():
  60. slot.pop(home_key, None)
  61. with _provider_lock:
  62. for key in [k for k in _cached_providers if home_key in (None, k[0])]:
  63. _cached_providers.pop(key, None)
  64. def _truthy(value) -> bool:
  65. return is_truthy_value(value, default=False)
  66. def command_timeout() -> int:
  67. """``browser.command_timeout`` (floored at 5 s): the floor of the Chromium launch timeout."""
  68. return _memo("command_timeout", lambda: browser_cfg(
  69. "command_timeout", DEFAULT_COMMAND_TIMEOUT,
  70. lambda v: DEFAULT_COMMAND_TIMEOUT if v is None else max(int(v), 5)))
  71. def inactivity_timeout(default: int) -> int:
  72. """``browser.inactivity_timeout`` (30 s floor: no instant reaping)."""
  73. return browser_cfg("inactivity_timeout", default, lambda v: default if v is None else max(int(v), 30))
  74. def chromium_args() -> list[str]:
  75. """``browser.chromium_args``: extra flags appended to every packaged/shared Chromium launch."""
  76. def parse(value) -> list[str]:
  77. if isinstance(value, str):
  78. value = [part for part in value.replace("\n", ",").split(",")]
  79. return [str(v).strip() for v in (value or []) if str(v).strip()]
  80. return browser_cfg("chromium_args", [], parse)
  81. def executable_path() -> str:
  82. """``browser.executable_path`` ("" = the packaged Chromium)."""
  83. return browser_cfg("executable_path", "", lambda v: str(v or "").strip())
  84. def user_data_dir() -> str:
  85. """``browser.user_data_dir``: a persistent profile every session shares ("" = fresh per session).
  86. ``~`` expands; a relative path is anchored at this profile's HERMES_HOME."""
  87. import os
  88. raw = browser_cfg("user_data_dir", "", lambda v: str(v or "").strip())
  89. if not raw:
  90. return ""
  91. raw = os.path.expanduser(raw)
  92. if os.path.isabs(raw):
  93. return raw
  94. from hermes_constants import get_hermes_home
  95. return str(get_hermes_home() / raw)
  96. def get_browser_engine() -> str:
  97. """``auto`` (packaged Chromium) or ``lightpanda``; ``chrome`` is accepted as ``auto``."""
  98. def compute() -> str:
  99. engine = browser_cfg("engine", "auto", lambda v: str(v).strip().lower() if v and str(v).strip() else "auto")
  100. if engine == "chrome":
  101. return "auto"
  102. if engine not in _VALID_ENGINES:
  103. logger.warning("Unknown browser engine %r (valid: %s), using 'auto'", engine, ", ".join(_VALID_ENGINES))
  104. return "auto"
  105. return engine
  106. return _memo("engine", compute)
  107. def is_headed_mode() -> bool:
  108. """``browser.headed``: launch a visible window (Linux: only when a display exists)."""
  109. return _memo("headed", lambda: browser_cfg("headed", False, _truthy))
  110. def auto_local_for_private_urls() -> bool:
  111. """``browser.auto_local_for_private_urls`` (default True): route private/LAN URLs to a local sidecar
  112. browser even with a cloud provider configured."""
  113. return _memo("auto_local", lambda: browser_cfg("auto_local_for_private_urls", True, bool))
  114. def use_real_profile() -> bool:
  115. """Real-profile consent. Read on EVERY call: it is a consent switch (flipping it off must not need a
  116. restart) and each multiplexed profile decides for itself."""
  117. return browser_cfg("use_real_profile", False, bool)
  118. def allow_private_urls() -> bool:
  119. """Whether the browser may navigate to private/internal addresses (default False: SSRF guard on)."""
  120. return _memo("allow_private_urls", lambda: browser_cfg("allow_private_urls", False, _truthy))
  121. # ── Cloud provider ───────────────────────────────────────────────────────────────────────────────────
  122. def _registry_generation(scope: str):
  123. try:
  124. from agent.browser_registry import registry_generation
  125. except ImportError: # isolated compat stubs ship only get_provider
  126. return (0, 0)
  127. return registry_generation(scope=scope)
  128. def _ensure_browser_plugins_loaded() -> None:
  129. """Idempotent plugin discovery (standalone scripts/tests may never import ``model_tools``)."""
  130. try:
  131. from hermes_cli.plugins import _ensure_plugins_discovered
  132. _ensure_plugins_discovered()
  133. except Exception as exc: # health: allow BLE001 -- plugin discovery failure must never break browsing
  134. logger.debug("Browser plugin discovery failed (non-fatal): %s", exc)
  135. def _instantiate_explicit_provider(provider_key: str) -> Optional[BrowserProvider]:
  136. """The provider named by ``browser.cloud_provider``. An unregistered name raises ``ValueError`` (never a
  137. silent reroute to auto-detect); any other instantiation error yields None so the next call retries."""
  138. from agent.browser_registry import get_provider
  139. try:
  140. _ensure_browser_plugins_loaded()
  141. resolved = get_provider(provider_key)
  142. except Exception: # health: allow BLE001 -- a broken provider plugin must not take the browser down
  143. logger.warning("Failed to instantiate cloud_provider %r; will retry on next call", provider_key, exc_info=True)
  144. return None
  145. if resolved is None:
  146. from tools.tool_backend_helpers import selection_error
  147. raise ValueError(selection_error(
  148. "browser", f"'{provider_key}'",
  149. "no registered browser plugin has that name (install the corresponding plugin or fix the config key spelling)",
  150. ))
  151. return resolved
  152. def _autodetect_provider() -> Optional[BrowserProvider]:
  153. """Browser Use, then Browserbase, from credentials; never raises. Third-party plugins are only reachable
  154. through an explicit ``browser.cloud_provider``."""
  155. # Late import: a core tool must not execute bundled plugin code before a session is resolved.
  156. from plugins.browser.browser_use.provider import BrowserUseBrowserProvider
  157. from plugins.browser.browserbase.provider import BrowserbaseBrowserProvider
  158. try:
  159. for cls in (BrowserUseBrowserProvider, BrowserbaseBrowserProvider):
  160. provider = cls()
  161. if provider.is_available():
  162. return provider
  163. except Exception: # health: allow BLE001 -- auto-detect must never poison the cache
  164. logger.debug("Cloud provider auto-detect failed", exc_info=True)
  165. return None
  166. def _resolve_provider_uncached() -> tuple[Optional[BrowserProvider], bool]:
  167. """``(provider, definitive)``. Definitive answers (explicit ``local``/``camofox``, a resolved provider) are
  168. cached; a transient None (unreadable config, missing credentials) is not, so it self-heals."""
  169. provider_key = None
  170. try:
  171. section = browser_section()
  172. if "cloud_provider" in section:
  173. provider_key = normalize_browser_cloud_provider(section.get("cloud_provider"))
  174. except (OSError, ValueError, TypeError) as exc:
  175. logger.debug("Could not read cloud_provider from config: %s", exc)
  176. if provider_key in ("local", "camofox"):
  177. return None, True # camofox is a plugin with its own tool surface, not a CDP provider
  178. if provider_key == "nous":
  179. provider_key = "browser-use" # the managed Nous subscription is served by the Browser Use provider
  180. if provider_key:
  181. resolved = _instantiate_explicit_provider(provider_key)
  182. return resolved, resolved is not None
  183. if provider_key is not None: # an empty selection was written: no auto-detect
  184. return None, False
  185. resolved = _autodetect_provider()
  186. return resolved, resolved is not None
  187. def get_cloud_provider() -> Optional[BrowserProvider]:
  188. """The cloud provider for the active profile, or None for local browsing."""
  189. scope = hermes_home_key()
  190. with _provider_lock:
  191. while True:
  192. before = _registry_generation(scope)
  193. if (scope, before) in _cached_providers:
  194. return _cached_providers[(scope, before)]
  195. resolved, definitive = _resolve_provider_uncached()
  196. if _registry_generation(scope) != before: # a reload landed mid-resolution: resolve again
  197. continue
  198. if definitive:
  199. for stale in [k for k in _cached_providers if k[0] == scope]:
  200. _cached_providers.pop(stale, None)
  201. _cached_providers[(scope, before)] = resolved
  202. return resolved
  203. def is_local_backend() -> bool:
  204. """True when the browser runs locally AND the terminal is local too.
  205. SSRF protection matters only when the browser reaches networks the terminal cannot (cloud backends,
  206. containerized terminals). A CDP override is never trusted as local (that Chrome may live off-host).
  207. """
  208. from tools.browser_session_cdp import get_cdp_override_raw
  209. if get_cdp_override_raw() or get_cloud_provider() is not None:
  210. return False
  211. # Scope-aware: under multiplexing the routed profile's terminal backend lives in the per-turn scope (#68559).
  212. from tools.terminal_scope import terminal_env
  213. return terminal_env("TERMINAL_ENV", "local").strip().lower() in ("local", "")
  214. def browser_backend_name(local_engine: Optional[str] = None) -> str:
  215. """Shared-metrics label for the active profile's backend in session-creation precedence
  216. (CDP override > cloud provider > local engine). ``local_engine``: the call ran on a LOCAL browser (the
  217. hybrid ``::local`` sidecar, a cloud failure's local fallback, the real profile) of that engine (``local``
  218. or ``lightpanda``, as its session was created), so neither a configured provider nor ``browser.engine``
  219. names it. Config reads only, no network I/O."""
  220. from tools.browser_session_cdp import get_cdp_override_raw
  221. if get_cdp_override_raw():
  222. return "cdp"
  223. if local_engine:
  224. return local_engine
  225. provider = get_cloud_provider()
  226. if provider is not None:
  227. return str(getattr(provider, "name", "") or "other")
  228. return "lightpanda" if get_browser_engine() == "lightpanda" else "local"