The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(browser): Python Chromium launcher + browser_session layer (API for browser_exec-only)
Teknium855f03e3f720
diff --git a/tools/bot_desktop/browser.py b/tools/bot_desktop/browser.pyindex 7f801cbf327..239f2ec0f09 100644--- a/tools/bot_desktop/browser.py+++ b/tools/bot_desktop/browser.py@@ -1,21 +1,19 @@"""The bot's browser on its Bot Desktop: one executable, one persistent user-data-dir per profile.-The agent drives Chromium through agent-browser; a human who takes over clicks the dock's Browser-icon. Both must be THE SAME browser — same binary, same ``--user-data-dir`` — or the human logs in-to a jar the bot never sees. Chromium's singleton makes a second launch on the same user-data-dir-open a window in the running instance, which is exactly the hand-over we want — in ONE direction. When the-human's dock instance is already up, agent-browser's own launch is forwarded to it and dies without a-DevTools endpoint, so the dock exposes a debugging port and the agent ATTACHES to it (see-:func:`running_instance_cdp_port`) instead of launching.+The agent's Chromium (``tools.browser_session`` → ``tools.browser_launcher``) and the dock's Browser icon a+human clicks must be THE SAME browser — same binary, same ``--user-data-dir`` — or the human logs in to a+jar the bot never sees. Chromium's singleton makes a second launch on the same user-data-dir open a window+in the running instance, which is the hand-over we want in ONE direction. When the human's dock instance is+already up, a launch would be forwarded to it and exit without a DevTools endpoint, so the dock exposes a+debugging port and the launcher ATTACHES to it instead of launching."""from __future__ import annotationsimport osimport shutil-import socketfrom pathlib import Path-from typing import Optional, Tuple+from typing import Optionalfrom tools.bot_desktop import runtime@@ -25,25 +23,25 @@ _SYSTEM_BROWSERS = ("google-chrome", "google-chrome-stable", "chromium", "chromidef profile_dir() -> Path:- """User-data-dir the bot's browser uses on this profile's screen. ``AGENT_BROWSER_PROFILE`` pins your own:+ """User-data-dir the bot's browser uses on this profile's screen. ``browser.user_data_dir`` pins your own:``~`` expands, and a relative path is anchored at this profile's HERMES_HOME (where the rest of the screen'sstate lives), so ``pin`` means ``<HERMES_HOME>/pin`` and two profiles never share one jar by accident."""- override = os.path.expanduser(os.environ.get("AGENT_BROWSER_PROFILE", "").strip())- if override:- return Path(override) if os.path.isabs(override) else runtime.get_hermes_home() / override- return runtime.state_dir() / "browser-profile"+ from tools.browser_session_cloud import user_data_dir+ override = user_data_dir()+ return Path(override) if override else runtime.state_dir() / "browser-profile"def executable() -> Optional[str]:- """The Chromium agent-browser launches: an explicit ``AGENT_BROWSER_EXECUTABLE_PATH``, else the newest- Playwright Chromium it bundles, else a system Chrome/Chromium. ``None`` when there is none.+ """The Chromium the bot runs: an explicit ``browser.executable_path``, else the packaged Chromium, else a+ system Chrome/Chromium. ``None`` when there is none.Non-root under ``kernel.apparmor_restrict_unprivileged_userns=1`` (Ubuntu 23.10+) flips the order:Playwright's bundle has no setuid ``chrome_sandbox`` and dies 'FATAL: No usable sandbox!' there, whilea distro chromium ships the helper. The bundle stays the answer when it is the only browser — a dockicon that fails loudly beats a non-root ``--no-sandbox``."""- explicit = os.environ.get("AGENT_BROWSER_EXECUTABLE_PATH", "").strip()+ from tools.browser_session_cloud import executable_path+ explicit = executable_path()if explicit and os.access(explicit, os.X_OK) and not _is_headless_shell(explicit):return explicitfinders = [_managed_executable, _system_executable]@@ -60,10 +58,8 @@ def _managed_executable() -> Optional[str]:def _is_headless_shell(exe: str) -> bool:- """Playwright's ``chrome-headless-shell`` can drive pages but cannot open a window. The image's boot- hook exports it as ``AGENT_BROWSER_EXECUTABLE_PATH`` (it is the only build the unsuffixed tags carry,- and the lighter one everywhere), so trusting that override blindly would pin a windowless binary to- the dock's Browser icon."""+ """Playwright's ``chrome-headless-shell`` can drive pages but cannot open a window; trusting such an+ override blindly would pin a windowless binary to the dock's Browser icon."""return "headless" in os.path.basename(exe).lower() or "headless_shell" in exe@@ -76,7 +72,7 @@ def _is_root() -> bool:def _userns_restricted() -> bool:- from tools.browser_tool_session import apparmor_restricts_unprivileged_userns+ from tools.browser_launcher import apparmor_restricts_unprivileged_usernsreturn apparmor_restricts_unprivileged_userns()@@ -86,21 +82,22 @@ def dock_launch() -> Optional[tuple[str, str]]:return (exe, str(profile_dir())) if exe else None+# Flags the agent's launch and the dock's icon share on the persistent profile. --test-type hides the+# "Chrome for Testing is only for automated testing" and unsupported-flag (--no-sandbox as root) infobars+# that would sit over the human's takeover view; the persistent profile's HTTP cache is capped (uncapped it+# grows for months toward a hosted instance's 6 GB).+SHARED_PROFILE_ARGS = ("--test-type", f"--disk-cache-size={DISK_CACHE_BYTES}")++def dock_argv(exe: str, user_data_dir: str, *, sandbox_bypass: Optional[bool] = None) -> list[str]:"""Command the dock's Browser icon runs. ``--remote-debugging-port=0`` makes a human-startedinstance attachable (Chromium writes the chosen port to ``<user-data-dir>/DevToolsActivePort``);- first-run / default-browser dialogs would sit between the human and the bot's tabs."""- # --test-type hides the "Chrome for Testing is only for automated testing" and unsupported-flag- # (--no-sandbox as root) infobars, which otherwise sit at the top of the human's takeover view.- # The same sandbox policy agent-browser starts this binary with (root, Docker, AppArmor userns): the- # human's Browser is the bot's browser, in the same container; a stricter rule here just made the dock- # icon die with 'No usable sandbox!' in the official image while the agent's own Chromium ran fine.- from tools.browser_tool_session import CHROMIUM_SANDBOX_BYPASS_ARGS, _needs_chromium_sandbox_bypass- # The profile is persistent by design (logins survive handoffs); its HTTP cache is not worth a- # gateway's disk: uncapped it grows for months toward a hosted instance's 6 GB.+ first-run / default-browser dialogs would sit between the human and the bot's tabs. The sandbox policy+ is the launcher's (root, Docker, AppArmor userns): the human's Browser is the bot's browser."""+ from tools.browser_launcher import CHROMIUM_SANDBOX_BYPASS_ARGS, needs_chromium_sandbox_bypassreturn [exe, f"--user-data-dir={user_data_dir}", "--remote-debugging-port=0", "--no-first-run",- "--no-default-browser-check", "--test-type", f"--disk-cache-size={DISK_CACHE_BYTES}",- *(CHROMIUM_SANDBOX_BYPASS_ARGS if (_needs_chromium_sandbox_bypass() if sandbox_bypass is None+ "--no-default-browser-check", *SHARED_PROFILE_ARGS,+ *(CHROMIUM_SANDBOX_BYPASS_ARGS if (needs_chromium_sandbox_bypass() if sandbox_bypass is Noneelse sandbox_bypass) else ())]@@ -113,72 +110,3 @@ def dock_exec_line(exe: str, user_data_dir: str, *, sandbox_bypass: Optional[booquoted = "".join("\\" + ch if ch in '"`$\\' else ch for ch in arg)return '"' + quoted.replace("\\", "\\\\") + '"'return "Exec=" + " ".join(quote(arg) for arg in dock_argv(exe, user_data_dir, sandbox_bypass=sandbox_bypass))---def running_instance_cdp_port(user_data_dir: str, *, exclude_session: Optional[str] = None) -> Optional[int]:- """DevTools port of a Chromium currently running on ``user_data_dir``, or ``None``.-- Both files outlive a crashed or closed Chromium: ``SingletonLock`` is a symlink to ``host-pid`` and- ``DevToolsActivePort`` keeps the last port, so the pid must be alive AND the port must accept a- connection before it is trusted. An instance agent-browser launched for ``exclude_session`` itself is- reported as ``None``: its daemon already owns that browser, and handing it ``--cdp`` would make it- close the browser as a config change and then attach to the port that just died with it.- """- try:- with open(os.path.join(user_data_dir, "DevToolsActivePort"), encoding="utf-8-sig") as fh:- port_line = fh.readline().strip()- target = os.readlink(os.path.join(user_data_dir, "SingletonLock"))- except OSError:- return None- _host, _, pid_text = target.rpartition("-")- if not (port_line.isdigit() and pid_text.isdigit()) or not _pid_alive(int(pid_text)):- return None- if exclude_session and _launched_by_session(int(pid_text)) == exclude_session:- return None- port = int(port_line)- try:- with socket.create_connection(("127.0.0.1", port), timeout=0.5):- pass- except OSError:- return None- return port---def _launched_by_session(chromium_pid: int) -> Optional[str]:- """``AGENT_BROWSER_SESSION`` of the agent-browser daemon that spawned ``chromium_pid``, or ``None``- for a human-started (dock) instance. Chromium itself gets a scrubbed environment, so the daemon's- ``/proc/<ppid>/environ`` is the marker (Linux-only, same user)."""- try:- with open(f"/proc/{chromium_pid}/status", encoding="utf-8") as fh:- ppid = next((int(line.split()[1]) for line in fh if line.startswith("PPid:")), 0)- with open(f"/proc/{ppid}/environ", "rb") as fh:- raw = fh.read()- except (OSError, ValueError):- return None- for item in raw.split(b"\0"):- key, sep, value = item.partition(b"=")- if sep and key == b"AGENT_BROWSER_SESSION":- return value.decode("utf-8", "replace") or None- return None---def _pid_alive(pid: int) -> bool:- import psutil- return psutil.pid_exists(pid)---def env_for_agent(env: dict) -> dict:- """Pin agent-browser to the screen's browser identity unless the user pinned their own.-- A headless-shell pin is replaced, not kept: the image's boot hook exports one for ordinary browsing,- and leaving it would put the agent and the dock on different binaries over one ``--user-data-dir``,- where Chromium's singleton swallows the dock's launch into the windowless process. Only runs while a- screen is up (:func:`runtime.desktop_env`), so the heavier build is pinned just when it is the point.- """- env.setdefault("AGENT_BROWSER_PROFILE", str(profile_dir()))- exe = executable()- if exe:- pinned = env.get("AGENT_BROWSER_EXECUTABLE_PATH", "").strip()- if not pinned or _is_headless_shell(pinned):- env["AGENT_BROWSER_EXECUTABLE_PATH"] = exe- return envdiff --git a/tools/bot_desktop/launcher.sh b/tools/bot_desktop/launcher.shindex 93953fa39cd..67b8a039d69 100755--- a/tools/bot_desktop/launcher.sh+++ b/tools/bot_desktop/launcher.sh@@ -145,7 +145,7 @@ if [[ ! -e "$X/xfce4-panel.xml" ]]; thendock_ids+=("$n")}add_launcher "Terminal" utilities-terminal "xfce4-terminal"- # The bot's browser: runtime.py resolves the executable agent-browser drives plus the profile's+ # The bot's browser: runtime.py resolves the executable the agent's browser runs plus the profile's# persistent user-data-dir, so a human taking over lands in the bot's own cookie jar.[[ -n "${HERMES_BD_BROWSER_EXEC:-}" ]] && \add_launcher "Browser" internet-web-browser "$HERMES_BD_BROWSER_EXEC" "${HERMES_BD_BROWSER_EXEC_LINE:-}" && \diff --git a/tools/bot_desktop/runtime.py b/tools/bot_desktop/runtime.pyindex e2fb537caa1..954807af50b 100644--- a/tools/bot_desktop/runtime.py+++ b/tools/bot_desktop/runtime.py@@ -141,7 +141,7 @@ class DesktopStatus:socket: Optional[str]geometry: strinstall_command: Optional[str]- browser: Optional[str] # headed Chromium the dock's Browser icon and agent-browser share; None = no headed browser+ browser: Optional[str] # headed Chromium the dock's Browser icon and the agent's browser share; None = no headed browserblocker: Optional[str] = None # why start() would refuse right now (memory); None = may startmemory_available_mb: Optional[int] = Nonememory_limit_mb: Optional[int] = None@@ -351,8 +351,6 @@ def desktop_env(base_env: Optional[dict[str, str]] = None) -> dict[str, str]:touch_activity() # a browser / cua-driver spawn is the agent using its screenenv.update(published)env.pop("WAYLAND_DISPLAY", None) # X11 desktop; a leaked Wayland socket flips GTK/Chromium backends- from tools.bot_desktop.browser import env_for_agent- env_for_agent(env) # same binary + user-data-dir as the dock's Browser iconreturn env@@ -789,7 +787,7 @@ def _start_in_sandbox(wait_seconds: float) -> DesktopStatus:sd.mkdir(parents=True, exist_ok=True)os.chmod(sd, 0o700)with _flocked(sd / "start.lock"):- # The dock's Browser icon runs the sandbox's own Playwright Chromium on the profile agent-browser+ # The dock's Browser icon runs the sandbox's own Playwright Chromium on the profile the agent's browser# uses there: the human's browser is the bot's browser, as on the host.from tools.bot_desktop.browser import dock_exec_lineexe = sandbox_host.chromium_executable(env)diff --git a/tools/bot_desktop/sandbox_host.py b/tools/bot_desktop/sandbox_host.pyindex a8a1a0495a4..a827bc2be0a 100644--- a/tools/bot_desktop/sandbox_host.py+++ b/tools/bot_desktop/sandbox_host.py@@ -130,7 +130,7 @@ def desktop_home(env: Any) -> str:def browser_profile_dir(env: Any) -> str:- """The ONE ``--user-data-dir`` the agent's agent-browser and the dock's Browser icon share inside the+ """The ONE ``--user-data-dir`` the agent's browser and the dock's Browser icon share inside thesandbox (same rule as the host: two profiles would mean the human logs into a jar the bot never sees)."""return f"{desktop_home(env).rstrip('/')}/.hermes/bot-desktop/browser-profile"@@ -144,7 +144,7 @@ _CHROMIUM_PROBE = (def chromium_executable(env: Any) -> Optional[str]:- """Path of the Playwright Chromium agent-browser uses inside ``env`` (the dock's Browser icon must run+ """Path of the Playwright Chromium the agent's browser uses inside ``env`` (the dock's Browser icon must runthe same binary), or None when the image has none. Cached on the env."""cached = getattr(env, "_bd_chromium", "unset")if cached != "unset":diff --git a/tools/browser_launcher.py b/tools/browser_launcher.pynew file mode 100644index 00000000000..6b088aae6fd--- /dev/null+++ b/tools/browser_launcher.py@@ -0,0 +1,596 @@+"""Launch, track and stop the Chromium processes ``browser_exec`` drives.++One browser per launcher key (the session layer's cache key, or ``profile:<dir>`` for a persistent+profile shared by every key). Chromium picks its own DevTools port (``--remote-debugging-port=0``)+and writes it to ``<user-data-dir>/DevToolsActivePort``; the CDP URL comes from that file, so there+is no port race. Every owned launch leaves a host-wide record so a later Hermes process can reap+the Chromium of an owner that crashed, after proving the pid is still that browser.++Stop is always parent-first (``ProcessRegistry._terminate_host_pid``): Chromium reaps its own+zygotes and renderers on SIGTERM, and killing a zygote first turns a clean exit into a crash dump.+"""++from __future__ import annotations++import hashlib+import json+import logging+import os+import shutil+import subprocess+import sys+import threading+import time+from dataclasses import dataclass+from pathlib import Path+from typing import Any, Optional++logger = logging.getLogger(__name__)++# THE Chromium startup flags for a host where its sandbox cannot work. The Bot Desktop dock's Browser+# icon (same binary, same profile) uses the same list (``tools.bot_desktop.browser.dock_argv``), or the+# human's click dies while the agent's launch works.+CHROMIUM_SANDBOX_BYPASS_ARGS: tuple[str, ...] = ("--no-sandbox", "--disable-dev-shm-usage")++# Base flags, each kept for a reason (the minimum for an unattended, disposable automation browser):+# --no-first-run / --no-default-browser-check no welcome tab or default-browser bar on a fresh profile+# --disable-background-networking no field-trial / safe-browsing / update pings per launch+# --disable-component-update no component downloads into a throwaway profile+# --disable-default-apps / --disable-sync nothing installed or signed in behind the agent's back+# --disable-features=Translate no translate bubble covering the page+_BASE_FLAGS: tuple[str, ...] = (+ "--no-first-run", "--no-default-browser-check", "--disable-background-networking",+ "--disable-component-update", "--disable-default-apps", "--disable-sync", "--disable-features=Translate",+)+# Only for the launcher-resolved packaged Chromium: a keyring unlock prompt (Linux desktops) or the macOS+# keychain dialog would block an unattended launch. Never for a real or shared profile, whose cookies are+# encrypted with the OS store (``--password-store=basic`` would sign the copy out).+_PACKAGED_ONLY_FLAGS: tuple[str, ...] = ("--password-store=basic",)+_MACOS_PACKAGED_ONLY_FLAGS: tuple[str, ...] = ("--use-mock-keychain",)++_DEVTOOLS_FILE = "DevToolsActivePort"+_LAUNCH_LOG = "hermes-chromium.log"+_MIN_FIRST_LAUNCH_TIMEOUT_S = 120+_POLL_INTERVAL_S = 0.1+_STDERR_TAIL_CHARS = 1500+++@dataclass+class LaunchedBrowser:+ """A Chromium this process launched (``owned``) or attached to (a running instance on a shared+ profile, never killed by Hermes)."""++ key: str+ pid: Optional[int]+ start_time: Optional[int]+ cdp_url: str+ http_url: str+ user_data_dir: str+ owned: bool+ ephemeral: bool+ home_key: str+++_browsers: dict[str, LaunchedBrowser] = {}+_procs: dict[str, subprocess.Popen] = {}+_key_locks: dict[str, threading.Lock] = {}+_lock = threading.RLock()+_autoinstall_attempted = False+++# ── Host facts ───────────────────────────────────────────────────────────────────────────────────────++def apparmor_restricts_unprivileged_userns() -> bool:+ """Ubuntu 23.10+ default: unprivileged user namespaces are denied, so a Chromium whose+ ``chrome_sandbox`` helper is not setuid (Playwright's bundle) dies with 'No usable sandbox'."""+ try:+ with open("/proc/sys/kernel/apparmor_restrict_unprivileged_userns", encoding="utf-8") as f:+ return f.read().strip() == "1"+ except OSError:+ return False+++def running_in_docker() -> bool:+ """Best-effort detection of whether we're inside a Docker container."""+ if os.path.exists("/.dockerenv"):+ return True+ try:+ with open("/proc/1/cgroup", "rt", encoding="utf-8") as fp:+ return "docker" in fp.read()+ except OSError:+ return False+++def needs_chromium_sandbox_bypass() -> bool:+ """True when Chromium needs --no-sandbox to start reliably (root, Docker, AppArmor userns)."""+ if hasattr(os, "geteuid") and os.geteuid() == 0:+ return True+ if running_in_docker():+ return True+ return apparmor_restricts_unprivileged_userns()+++def _chromium_missing_hint() -> str:+ try:+ from hermes_cli.browser_runtime import chromium_missing_hint+ except ImportError: # LANE-PKG: remove this fallback once hermes_cli.browser_runtime.chromium_missing_hint lands+ if running_in_docker():+ return ("Chromium browser is missing. You're running in Docker — pull the latest image to get the "+ "bundled Chromium: docker pull ghcr.io/nousresearch/hermes-agent:latest")+ return "Chromium browser is missing. Install it with: hermes pm install chromium"+ return chromium_missing_hint()+++def _resolve_executable() -> Optional[str]:+ from hermes_cli.browser_runtime import chromium_executable+ exe = chromium_executable()+ if exe and (os.path.isfile(exe) or shutil.which(exe)):+ return exe+ return None+++def _maybe_autoinstall_chromium() -> bool:+ """One-shot ``pm.ensure("chromium")`` (a failed ~170 MB download must not retry per call). Docker+ supplies the binary, Termux has no PM Chromium, and an explicit executable is the user's choice."""+ global _autoinstall_attempted+ if _autoinstall_attempted:+ return False+ _autoinstall_attempted = True+ from hermes_constants import is_termux+ if running_in_docker() or is_termux():+ return False+ from pm import InstallError, ensure, lazy_installs_allowed+ if not lazy_installs_allowed():+ return False+ logger.info("browser: installing PM's pinned Chromium")+ try:+ ensure("chromium")+ except (InstallError, OSError) as exc:+ logger.warning("browser: Chromium auto-install failed: %s", exc)+ return False+ return True+++def chromium_ready() -> tuple[bool, str]:+ """``(True, "")`` when a Chromium is on disk (after at most one PM auto-install per process), else+ ``(False, actionable hint)``."""+ if _resolve_executable():+ return True, ""+ if _maybe_autoinstall_chromium() and _resolve_executable():+ return True, ""+ return False, _chromium_missing_hint()+++# ── Launch ───────────────────────────────────────────────────────────────────────────────────────────++def _default_user_data_dir(key: str, home_key: str) -> str:+ from hermes_constants import get_hermes_home+ digest = hashlib.sha256(f"{home_key}\0{key}".encode()).hexdigest()[:16]+ return str(Path(get_hermes_home()) / "cache" / "browser" / "chromium" / digest)+++def _launch_timeout(timeout: Optional[float]) -> float:+ if timeout is not None:+ return float(timeout)+ from tools.browser_session_cloud import command_timeout+ return float(max(command_timeout(), _MIN_FIRST_LAUNCH_TIMEOUT_S))+++def _has_display(env: dict) -> bool:+ return bool(env.get("DISPLAY") or env.get("WAYLAND_DISPLAY"))+++def _resolve_headed(headed: Optional[bool], env: dict) -> bool:+ """Headless unless ``browser.headed``; a display-less Linux host stays headless (a headed launch+ would die there). Windows obeys the same rule: headless unless the user opted in (#64867)."""+ if headed is None:+ from tools.browser_session_cloud import is_headed_mode+ headed = is_headed_mode()+ if not headed:+ return False+ return _has_display(env) or not sys.platform.startswith("linux")+++def _configured_chromium_args() -> list[str]:+ from tools.browser_session_cloud import chromium_args+ return chromium_args()+++def build_chromium_argv(executable: str, user_data_dir: str, *, packaged: bool, headed: bool,+ extra_args=()) -> list[str]:+ """The launch argv (pure in its inputs + host sandbox facts + ``browser.chromium_args``)."""+ argv = [executable, "--remote-debugging-port=0", f"--user-data-dir={user_data_dir}", *_BASE_FLAGS]+ if packaged:+ argv += _PACKAGED_ONLY_FLAGS+ if sys.platform == "darwin":+ argv += _MACOS_PACKAGED_ONLY_FLAGS+ if not headed:+ argv.append("--headless=new")+ configured = _configured_chromium_args()+ if needs_chromium_sandbox_bypass():+ argv += [flag for flag in CHROMIUM_SANDBOX_BYPASS_ARGS if flag not in configured]+ argv += [str(a) for a in extra_args]+ argv += configured+ argv.append("about:blank")+ return argv+++def _spawn_kwargs() -> dict[str, Any]:+ if os.name == "nt":+ from hermes_cli._subprocess_compat import windows_hide_flags+ return {"creationflags": windows_hide_flags() | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}+ return {"start_new_session": True}+++def _read_devtools_file(user_data_dir: str) -> Optional[tuple[int, str]]:+ """``(port, "/devtools/browser/<id>")`` once Chromium wrote both lines, else None."""+ try:+ with open(os.path.join(user_data_dir, _DEVTOOLS_FILE), encoding="utf-8-sig") as fh:+ port, path = fh.readline().strip(), fh.readline().strip()+ except OSError:+ return None+ if not port.isdigit() or not path.startswith("/devtools/browser/"):+ return None+ return int(port), path+++def _log_tail(user_data_dir: str) -> str:+ try:+ raw = Path(user_data_dir, _LAUNCH_LOG).read_bytes()[-_STDERR_TAIL_CHARS:]+ except OSError:+ return ""+ return raw.decode("utf-8", errors="replace").strip()+++def _wait_for_devtools(proc: subprocess.Popen, user_data_dir: str, deadline: float) -> tuple[Optional[tuple[int, str]], Optional[str]]:+ while True:+ found = _read_devtools_file(user_data_dir)+ if found:+ return found, None+ rc = proc.poll()+ if rc is not None:+ tail = _log_tail(user_data_dir)+ hint = (" Chromium's sandbox could not start; add --no-sandbox to browser.chromium_args."+ if "sandbox" in tail.lower() else "")+ return None, f"Chromium exited with code {rc} during startup.{hint}" + (f"\n{tail}" if tail else "")+ if time.monotonic() >= deadline:+ return None, "Chromium did not expose a DevTools endpoint in time."+ time.sleep(_POLL_INTERVAL_S)+++def _singleton_pid(user_data_dir: str) -> Optional[int]:+ try:+ target = os.readlink(os.path.join(user_data_dir, "SingletonLock"))+ except OSError:+ return None+ pid_text = target.rpartition("-")[2]+ return int(pid_text) if pid_text.isdigit() else None+++def _devtools_endpoint_live(port: int, path: str) -> bool:+ """The port answers ``/json/version`` with the browser id the DevToolsActivePort file names (the file+ outlives a crashed Chromium and its port can be recycled by another CDP server)."""+ try:+ import requests+ from agent.proxy_bypass import loopback_request_kwargs+ url = f"http://127.0.0.1:{port}/json/version"+ ws = str(requests.get(url, timeout=2, **loopback_request_kwargs(url)).json().get("webSocketDebuggerUrl") or "")+ except Exception: # health: allow BLE001 -- any probe failure means "not a live browser on this port"+ return False+ return ws.endswith(path)+++def running_instance(user_data_dir: str) -> Optional[tuple[int, str, int]]:+ """``(port, browser_path, pid)`` of a Chromium already running on ``user_data_dir`` (a human-started+ Bot Desktop dock instance, a surviving real-profile browser), else None. A second launch on that dir+ would be forwarded into it by Chromium's singleton and exit without a DevTools endpoint."""+ pid = _singleton_pid(user_data_dir)+ found = _read_devtools_file(user_data_dir)+ if pid is None or found is None or not _pid_alive(pid):+ return None+ port, path = found+ return (port, path, pid) if _devtools_endpoint_live(port, path) else None+++def _pid_alive(pid: int) -> bool:+ from gateway.status import _pid_exists+ return pid > 0 and _pid_exists(pid)+++def _start_time(pid: int) -> Optional[int]:+ from gateway.status import get_process_start_time+ return get_process_start_time(pid)+++def _make_browser(key: str, port: int, path: str, *, pid, start_time, user_data_dir: str, owned: bool,+ ephemeral: bool, home_key: str) -> LaunchedBrowser:+ return LaunchedBrowser(key=key, pid=pid, start_time=start_time, cdp_url=f"ws://127.0.0.1:{port}{path}",+ http_url=f"http://127.0.0.1:{port}", user_data_dir=user_data_dir, owned=owned,+ ephemeral=ephemeral, home_key=home_key)+++def _prepare_dir(user_data_dir: str, ephemeral: bool) -> None:+ if ephemeral:+ shutil.rmtree(user_data_dir, ignore_errors=True) # fresh profile per launch+ os.makedirs(user_data_dir, mode=0o700, exist_ok=True)+ try:+ os.unlink(os.path.join(user_data_dir, _DEVTOOLS_FILE)) # a stale port confuses the readiness poll+ except OSError:+ pass+++def _spawn(argv: list[str], env: dict, user_data_dir: str) -> subprocess.Popen:+ with open(os.path.join(user_data_dir, _LAUNCH_LOG), "wb") as log:+ return subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=log, stderr=log, env=env,+ **_spawn_kwargs())+++def _attach_running(key: str, user_data_dir: str, ephemeral: bool, home_key: str) -> Optional[LaunchedBrowser]:+ if ephemeral:+ return None+ running = running_instance(user_data_dir)+ if running is None:+ return None+ port, path, pid = running+ logger.info("browser: attaching to the Chromium already running on %s (pid %s)", user_data_dir, pid)+ return _make_browser(key, port, path, pid=pid, start_time=_start_time(pid), user_data_dir=user_data_dir,+ owned=False, ephemeral=False, home_key=home_key)+++def launch_chromium(key: str, *, executable: Optional[str] = None, user_data_dir: Optional[str] = None,+ ephemeral: bool = True, headed: Optional[bool] = None, extra_args=(),+ env: Optional[dict] = None, timeout: Optional[float] = None,+ ) -> tuple[Optional[LaunchedBrowser], Optional[str]]:+ """Start (or reuse) the Chromium for ``key``; ``(browser, None)`` or ``(None, error)``.++ ``executable=None`` resolves the packaged Chromium (``chromium_ready``); an explicit executable (the+ Bot Desktop's, the user's real browser) is used as given. ``user_data_dir=None`` is a fresh+ ephemeral profile under ``<HERMES_HOME>/cache/browser/chromium/``; a persistent dir that already has+ a live Chromium on it is ATTACHED (``owned=False``, never killed)."""+ from hermes_constants import hermes_home_key+ with _key_lock(key): # one launch per key; other keys launch concurrently+ existing = get_browser(key)+ if existing is not None:+ return existing, None+ home_key = hermes_home_key()+ packaged = executable is None+ if packaged:+ ok, hint = chromium_ready()+ if not ok:+ return None, hint+ executable = _resolve_executable()+ udd = user_data_dir or _default_user_data_dir(key, home_key)+ attached = _attach_running(key, udd, ephemeral, home_key)+ if attached is not None:+ with _lock:+ _browsers[key] = attached+ return attached, None+ return _launch_owned(key, executable, udd, ephemeral=ephemeral, packaged=packaged, headed=headed,+ extra_args=extra_args, env=env, timeout=timeout, home_key=home_key)+++def _key_lock(key: str) -> threading.Lock:+ with _lock:+ return _key_locks.setdefault(key, threading.Lock())+++def _launch_owned(key: str, executable: str, udd: str, *, ephemeral: bool, packaged: bool, headed,+ extra_args, env, timeout, home_key: str) -> tuple[Optional[LaunchedBrowser], Optional[str]]:+ if env is None:+ from tools.browser_session import build_browser_env+ env = build_browser_env()+ try:+ _prepare_dir(udd, ephemeral)+ except OSError as exc:+ return None, f"Could not create the browser profile directory {udd}: {exc}"+ argv = build_chromium_argv(executable, udd, packaged=packaged, headed=_resolve_headed(headed, env),+ extra_args=extra_args)+ try:+ proc = _spawn(argv, env, udd)+ except (OSError, subprocess.SubprocessError) as exc:+ return None, f"Failed to launch Chromium ({executable}): {exc}"+ start_time = _start_time(proc.pid)+ found, err = _wait_for_devtools(proc, udd, time.monotonic() + _launch_timeout(timeout))+ if found is None:+ _terminate(proc.pid, start_time, proc)+ if ephemeral:+ shutil.rmtree(udd, ignore_errors=True)+ return None, err+ browser = _make_browser(key, found[0], found[1], pid=proc.pid, start_time=start_time, user_data_dir=udd,+ owned=True, ephemeral=ephemeral, home_key=home_key)+ with _lock:+ _browsers[key] = browser+ _procs[key] = proc+ _write_record(browser)+ logger.info("browser: launched Chromium pid %s for %s (port %s)", proc.pid, key, found[0])+ return browser, None+++# ── Lookup / stop ────────────────────────────────────────────────────────────────────────────────────++def _alive(browser: LaunchedBrowser) -> bool:+ proc = _procs.get(browser.key)+ if proc is not None and browser.owned:+ return proc.poll() is None+ if browser.pid is None:+ return False+ if not _pid_alive(browser.pid):+ return False+ return browser.start_time is None or _start_time(browser.pid) == browser.start_time+++def get_browser(key: str) -> Optional[LaunchedBrowser]:+ """The live browser for ``key``, or None (a dead one is dropped and its leftovers removed)."""+ with _lock:+ browser = _browsers.get(key)+ if browser is None:+ return None+ if _alive(browser):+ return browser+ logger.info("browser: Chromium for %s (pid %s) is gone", key, browser.pid)+ _forget(key, browser)+ return None+++def _forget(key: str, browser: LaunchedBrowser) -> None:+ _browsers.pop(key, None)+ proc = _procs.pop(key, None)+ if proc is not None:+ try:+ proc.wait(timeout=0) # reap the zombie+ except subprocess.TimeoutExpired:+ pass+ if browser.owned:+ _remove_record(browser)+ if browser.ephemeral:+ shutil.rmtree(browser.user_data_dir, ignore_errors=True)+++def _terminate(pid: Optional[int], start_time: Optional[int], proc: Optional[subprocess.Popen]) -> None:+ """Parent-first teardown (tools/AGENTS.md): SIGTERM the browser alone, then its snapshot survivors."""+ if not pid:+ return+ from tools.process_registry import ProcessRegistry+ try:+ ProcessRegistry._terminate_host_pid(pid, start_time)+ except OSError as exc:+ logger.debug("browser: terminating Chromium pid %s failed: %s", pid, exc)+ if proc is not None:+ try:+ proc.wait(timeout=5)+ except subprocess.TimeoutExpired:+ proc.kill()+++def stop_browser(key: str) -> None:+ """Stop ``key``'s browser if this process launched it (an attached one is only forgotten)."""+ with _lock:+ browser = _browsers.get(key)+ proc = _procs.get(key)+ if browser is None:+ return+ if browser.owned:+ _terminate(browser.pid, browser.start_time, proc)+ with _lock:+ _forget(key, browser)+++def stop_all_browsers(home_key: Optional[str] = None) -> None:+ """Stop every browser this process launched (only ``home_key``'s when given). Idempotent."""+ with _lock:+ keys = [k for k, b in _browsers.items() if home_key in (None, b.home_key)]+ for key in keys:+ stop_browser(key)+++def browser_keys() -> list[str]:+ with _lock:+ return list(_browsers)+++# ── Host-wide records + orphan reap ──────────────────────────────────────────────────────────────────++def _records_dir() -> Path:+ """Host-wide (every profile, every Hermes process of this user): a crashed owner's Chromium is reaped+ by whichever Hermes runs next. Socket-safe tmp root, mode 0700."""+ from hermes_constants import socket_safe_tmpdir+ uid = os.getuid() if hasattr(os, "getuid") else 0+ path = Path(socket_safe_tmpdir()) / f"hermes-chromium-{uid}"+ path.mkdir(mode=0o700, parents=True, exist_ok=True)+ return path+++def _record_path(browser: LaunchedBrowser) -> Path:+ digest = hashlib.sha256(browser.user_data_dir.encode()).hexdigest()[:16]+ return _records_dir() / f"{digest}-{browser.pid}.json"+++def _write_record(browser: LaunchedBrowser) -> None:+ from utils import atomic_json_write+ record = {"owner_pid": os.getpid(), "owner_start_time": _start_time(os.getpid()), "pid": browser.pid,+ "start_time": browser.start_time, "user_data_dir": browser.user_data_dir,+ "home_key": browser.home_key, "ephemeral": browser.ephemeral}+ try:+ atomic_json_write(_record_path(browser), record, indent=None)+ except OSError as exc:+ logger.debug("browser: could not write launch record for pid %s: %s", browser.pid, exc)+++def _remove_record(browser: LaunchedBrowser) -> None:+ try:+ _record_path(browser).unlink(missing_ok=True)+ except OSError as exc:+ logger.debug("browser: could not remove launch record for pid %s: %s", browser.pid, exc)+++def _owner_alive(record: dict) -> bool:+ owner = record.get("owner_pid")+ if not isinstance(owner, int) or not _pid_alive(owner):+ return False+ expected = record.get("owner_start_time")+ return expected is None or _start_time(owner) == expected+++def _cmdline_names_dir(pid: int, user_data_dir: str) -> bool:+ """True only when ``pid``'s argv carries exactly ``--user-data-dir=<user_data_dir>``."""+ try:+ import psutil+ argv = psutil.Process(pid).cmdline()+ except Exception: # health: allow BLE001 -- unreadable identity fails closed (no kill)+ return False+ want = os.path.normpath(user_data_dir)+ return any(tok.startswith("--user-data-dir=") and os.path.normpath(tok.split("=", 1)[1]) == want+ for tok in argv)+++def _is_recorded_browser(record: dict) -> bool:+ pid, udd = record.get("pid"), record.get("user_data_dir")+ if not isinstance(pid, int) or not isinstance(udd, str) or not _pid_alive(pid):+ return False+ expected = record.get("start_time")+ if expected is not None and _start_time(pid) != expected:+ return False+ if not _cmdline_names_dir(pid, udd):+ logger.warning("browser: refusing to reap pid %s: its command line does not name %s", pid, udd)+ return False+ return True+++def _tracked_here(record: dict) -> bool:+ with _lock:+ return any(b.pid == record.get("pid") for b in _browsers.values())+++def _reap_record(path: Path) -> bool:+ try:+ record = json.loads(path.read_text(encoding="utf-8-sig"))+ if not isinstance(record, dict):+ raise ValueError("not a JSON object")+ except (OSError, ValueError):+ path.unlink(missing_ok=True)+ return False+ if record.get("owner_pid") == os.getpid():+ if _tracked_here(record):+ return False+ elif _owner_alive(record):+ return False+ reaped = False+ if _is_recorded_browser(record):+ _terminate(record["pid"], record.get("start_time"), None)+ logger.info("browser: reaped orphaned Chromium pid %s (%s)", record["pid"], record["user_data_dir"])+ reaped = True+ if reaped and record.get("ephemeral") and isinstance(record.get("user_data_dir"), str):+ shutil.rmtree(record["user_data_dir"], ignore_errors=True)+ path.unlink(missing_ok=True)+ return reaped+++def reap_orphaned_browsers() -> int:+ """Stop Chromium processes whose owning Hermes process is gone; returns the count. A pid is signalled+ only after its start time AND its ``--user-data-dir`` argv token match the record."""+ try:+ records = sorted(_records_dir().glob("*.json"))+ except OSError as exc:+ logger.debug("browser: launch records unavailable: %s", exc)+ return 0+ return sum(1 for path in records if _reap_record(path))diff --git a/tools/browser_lightpanda.py b/tools/browser_lightpanda.pyindex 2c4f8c6578a..8bc420c1aa5 100644--- a/tools/browser_lightpanda.py+++ b/tools/browser_lightpanda.py@@ -1,9 +1,8 @@-"""Lightpanda local engine for Browser Use mode.+"""Lightpanda local engine.-With ``browser.engine: lightpanda``, Browser Use mode spawns one ``lightpanda serve`` per-browser session and points ``browser_exec`` at its CDP endpoint (``BU_CDP_URL``); the-built-in ``browser_*`` tools keep going through ``agent-browser --engine lightpanda``.-``tools.browser_tool`` owns the session cache, inactivity reaper and atexit sweep.+With ``browser.engine: lightpanda``, each browser session spawns one ``lightpanda serve`` and+``browser_exec`` drives its CDP endpoint (``BU_CDP_URL``). ``tools.browser_session`` owns the+session cache, inactivity reaper and atexit sweep."""import functools@@ -61,19 +60,24 @@ def _home_candidates() -> list:return candidates+# System PATH fallbacks for a minimal service PATH (systemd units, launchd), Homebrew included.+_SANE_PATH_DIRS = ("/opt/homebrew/bin", "/opt/homebrew/sbin", "/usr/local/sbin", "/usr/local/bin",+ "/usr/sbin", "/usr/bin", "/sbin", "/bin")+++def merge_sane_path(existing_path: str = "") -> str:+ """``existing_path`` with the standard system dirs that exist appended (existing order kept)."""+ parts = [p for p in (existing_path or "").split(os.pathsep) if p]+ return os.pathsep.join(parts + [d for d in _SANE_PATH_DIRS if d not in parts and os.path.isdir(d)])++def find_lightpanda_binary() -> Optional[str]:- """Return the lightpanda executable, or None. Order: PATH (with agent-browser's Homebrew/managed-node- fallbacks), then installer/agent-browser locations, then ``$HERMES_HOME/bin``. No Windows build."""+ """Return the lightpanda executable, or None. Order: PATH (plus the standard system dirs), then the+ installer's locations, then ``$HERMES_HOME/bin``. No Windows build."""if os.name == "nt":logger.debug("Lightpanda has no Windows build")return None- path_env = os.environ.get("PATH", "")- try:- from tools.browser_tool_install import _merge_browser_path- path_env = _merge_browser_path(path_env)- except Exception as e:- logger.debug("browser PATH merge unavailable: %s", e)- return shutil.which("lightpanda", path=path_env) or next(+ return shutil.which("lightpanda", path=merge_sane_path(os.environ.get("PATH", ""))) or next((str(c) for c in _home_candidates() if c.is_file() and os.access(c, os.X_OK)), None)@@ -134,12 +138,8 @@ def _record_path(session_name: str) -> Path:def _browser_env() -> dict:- try:- from tools.browser_tool import _build_browser_env- return _build_browser_env()- except Exception as e:- logger.debug("credential-scrubbed browser env unavailable: %s", e)- return os.environ.copy()+ from tools.browser_session import build_browser_env+ return build_browser_env()def _cdp_ready(url: str, timeout: float = 0.2) -> bool:@@ -161,7 +161,7 @@ def _read_log_tail(path: str) -> str:def _terminate(proc: subprocess.Popen, what: str = "lightpanda") -> None:- """poll -> terminate -> wait(5) -> kill; shared with the real-profile Chrome cleanup."""+ """poll -> terminate -> wait(5) -> kill (fallback when the tree-kill failed)."""try:if proc.poll() is None:proc.terminate()@@ -343,3 +343,37 @@ def reap_orphaned_lightpanda() -> int:logger.debug("orphan lightpanda kill failed for pid %s: %s", pid, e)record_path.unlink(missing_ok=True)return reaped+++def using_lightpanda_engine() -> bool:+ """True when ``browser.engine`` is ``lightpanda``."""+ from tools.browser_session_cloud import get_browser_engine+ return get_browser_engine() == "lightpanda"+++def lightpanda_engine_status() -> tuple[bool, str]:+ """Whether ``browser.engine: lightpanda`` is actually in effect, and why.++ ``(False, "")`` when the engine isn't lightpanda; else the reason names the setting shadowing it, in+ session-creation precedence, with config-only gates (no network I/O) for ``/browser status`` and+ ``hermes doctor``."""+ if not using_lightpanda_engine():+ return False, ""+ from tools.browser_session_cdp import get_cdp_override_raw+ from tools.browser_session_cloud import get_cloud_provider, use_real_profile+ if get_cdp_override_raw():+ return False, "a CDP override is active (/browser connect or browser.cdp_url)"+ # Real profile before the cloud provider: browser_exec resolves it first, so it claims the session.+ if use_real_profile():+ return False, "browser.use_real_profile is on (Lightpanda cannot load a Chromium profile)"+ try:+ provider = get_cloud_provider()+ except ValueError: # an unknown explicit provider name: browser_exec reports it on use+ provider = None+ if provider is not None:+ name = getattr(provider, "display_name", "") or type(provider).__name__+ return False, f"cloud provider {name} is selected (browser.cloud_provider, or auto-detected from credentials)"+ from tools.browser_use_cli import _read_browser_cfg, is_legacy_browser_use_cloud_config+ if is_legacy_browser_use_cloud_config(_read_browser_cfg()):+ return False, "Browser Use cloud (BROWSER_USE_API_KEY) is selected"+ return True, "Hermes spawns `lightpanda serve` per browser session"diff --git a/tools/browser_session.py b/tools/browser_session.pynew file mode 100644index 00000000000..ce1974cacf4--- /dev/null+++ b/tools/browser_session.py@@ -0,0 +1,382 @@+"""Browser sessions for ``browser_exec``: one session per cache key, created in a fixed precedence and+always carrying a ``cdp_url``.++Precedence (``BU_CDP_*`` operator env is honoured earlier, by ``browser_exec``):+CDP override (live ``/browser connect`` > ``BROWSER_CDP_URL`` > ``browser.cdp_url``) > hybrid ``::local``+sidecar (private URL, never the real profile) > cloud provider (``create_session``; on failure a LOCAL+session marked ``fallback_from_cloud``) > local: real profile (consented) > Lightpanda+(``browser.engine: lightpanda``) > the packaged Chromium via ``tools.browser_launcher``.++State lives here; sibling modules (``browser_session_*``) late-import this module inside functions.+"""++from __future__ import annotations++import atexit+import logging+import threading+import uuid+from typing import Any, Callable, Optional++from hermes_cli.config import DEFAULT_CONFIG+from hermes_constants import hermes_home_key+from utils import env_int++logger = logging.getLogger(__name__)++LOCAL_SUFFIX = "::local"+_LOCAL_SUFFIX = LOCAL_SUFFIX++# Inactivity timeout: config.yaml is authoritative; BROWSER_INACTIVITY_TIMEOUT stays a legacy env fallback.+DEFAULT_SESSION_INACTIVITY_TIMEOUT = int(DEFAULT_CONFIG.get("browser", {}).get("inactivity_timeout", 120))+++def _get_session_inactivity_timeout() -> int:+ from tools.browser_session_cloud import inactivity_timeout+ return inactivity_timeout(env_int("BROWSER_INACTIVITY_TIMEOUT", DEFAULT_SESSION_INACTIVITY_TIMEOUT))+++BROWSER_SESSION_INACTIVITY_TIMEOUT = _get_session_inactivity_timeout()+# Orphan reap cadence: a startup-only reap never recovers a leak that appears in a long-lived process.+BROWSER_ORPHAN_REAP_INTERVAL = 300+MAX_INACTIVITY_CLEANUP_FAILURES = 3++_active_sessions: dict[str, dict[str, Any]] = {}+_session_last_activity: dict[str, float] = {}+# Owner Hermes home per session: the janitor is one process-global thread, so each teardown re-enters the+# OWNING profile's scope (#86402).+_session_owner_homes: dict[str, str] = {}+_cleanup_failures: dict[str, int] = {} # consecutive janitor failures (#100738)+_cleanup_lock = threading.Lock() # protects every dict above+_cleanup_thread: Optional[threading.Thread] = None+_cleanup_running = False+_cleanup_done = False++# A session built while its profile published a new live endpoint is closed and rebuilt; bounded so a+# flapping connect/disconnect loop cannot keep a call building browsers forever.+_STALE_ENDPOINT_RETRIES = 2+++# ── Env ──────────────────────────────────────────────────────────────────────────────────────────────++def build_browser_env() -> dict:+ """Env for every browser child (Chromium, ``lightpanda serve``, the harness CLI base): the served+ profile's child env WITHOUT credentials, the Bot Desktop DISPLAY when its screen is up, a loopback+ NO_PROXY (a macOS system proxy would capture the local CDP dial, #110565), and a short TMPDIR+ (Chrome's SingletonSocket overflows the AF_UNIX path cap under a deep scratch dir)."""+ from agent.proxy_bypass import add_loopback_no_proxy+ from hermes_constants import socket_safe_tmpdir+ from tools.bot_desktop.runtime import desktop_env+ from tools.environments.local import served_profile_child_env+ env = add_loopback_no_proxy(desktop_env(served_profile_child_env(inherit_credentials=False)))+ env["TMPDIR"] = socket_safe_tmpdir()+ return env+++# ── Bot Desktop fence ────────────────────────────────────────────────────────────────────────────────++def shares_bot_desktop_browser(session_info: dict[str, Any]) -> bool:+ """Every LOCAL session is a browser Hermes launched with this profile's Bot Desktop DISPLAY, so it is the+ screen a human who took over is typing into. Cloud / user-supplied CDP sessions are another browser. A+ human lease with the screen already gone still fences (computer_use does the same)."""+ if not (session_info.get("features") or {}).get("local"):+ return False+ from tools.bot_desktop import lease as _bd_lease, runtime as _bd_runtime+ return bool(_bd_runtime.published_env().get("DISPLAY")) or _bd_lease.human_holds()+++def human_holds_shared_browser(session_info: dict[str, Any]) -> bool:+ """True while a human holds the Bot Desktop lease over the browser ``session_info`` shares with them; the+ janitor treats that as activity (reaping it mid-login kills the human's session, #110064)."""+ if not shares_bot_desktop_browser(session_info):+ return False+ from tools.bot_desktop import lease as _bd_lease+ return _bd_lease.human_holds()+++def run_fenced(session_info: dict[str, Any], fn: Callable[[], dict[str, Any]]) -> dict[str, Any]:+ """Run ``fn`` under the Bot Desktop lease fence when ``session_info`` is the bot's LOCAL browser.++ While a human holds the lease every action AND read against it is refused (the page may show their+ credential); the fence brackets the whole run so a takeover mid-command also voids the result.+ """+ if not shares_bot_desktop_browser(session_info):+ return fn()+ from tools.bot_desktop import lease as _bd_lease+ try:+ admitted = _bd_lease.assert_agent_may_act()+ except _bd_lease.HumanHasControl as e:+ return {"success": False, "error": str(e), "code": "human_has_control"}+ result = fn()+ if _bd_lease.get().epoch != admitted.epoch:+ return {"success": False, "code": "human_has_control",+ "error": "A human took over the bot's screen while this browser command ran; its result was "+ "discarded. Tell the user what you need; retry once they hand back."}+ return result+++def ensure_screen_for_headed_chromium() -> None:+ """Tool-call boundary for ``bot_desktop.auto_start``: a headed Chromium is about to start, so a headless+ profile gets its screen first. Headless browsing and Lightpanda never bring one up."""+ from tools.browser_session_cloud import is_headed_mode+ if is_headed_mode():+ from tools.bot_desktop.runtime import ensure_started_for_tool+ ensure_started_for_tool()+++def browser_in_sandbox() -> bool:+ """The bot's browser runs INSIDE the terminal backend when its screen is PLACED there (policy, not+ liveness: the host is never touched by a page the model chose, whether or not the screen is up)."""+ from tools.bot_desktop import placement+ return placement.resolve().where == placement.TERMINAL+++# ── Session records ──────────────────────────────────────────────────────────────────────────────────++def _session_record(prefix: str, cdp_url: Optional[str], features: dict[str, Any]) -> dict[str, Any]:+ """Fresh session dict with a random ``<prefix>_<hex10>`` session name (log / Lightpanda identity)."""+ return {"session_name": f"{prefix}_{uuid.uuid4().hex[:10]}", "bb_session_id": None,+ "cdp_url": cdp_url, "features": features}+++def is_local_sidecar_key(session_key: str) -> bool:+ return session_key.endswith(LOCAL_SUFFIX)+++def owner_task_id(session_key: str) -> str:+ """The task a session key belongs to: strips the ``::local`` sidecar suffix and the ``@<home>`` served+ profile tag browser_exec adds (per-turn cleanup is called with the bare task id)."""+ key = session_key[: -len(LOCAL_SUFFIX)] if is_local_sidecar_key(session_key) else session_key+ return key.rsplit("@", 1)[0] if "@" in key else key+++def real_profile_note(cache_key: Optional[str]) -> Optional[str]:+ """The real-profile fallback note on ``cache_key``'s existing session; never creates or touches one."""+ with _cleanup_lock:+ return (_active_sessions.get(cache_key or "default") or {}).get("real_profile_unavailable")+++def session_for_task(task_id: Optional[str]) -> dict[str, Any]:+ """The active session serving ``task_id`` (its exact key, else one whose owner is that task), or {}."""+ task = task_id or "default"+ with _cleanup_lock:+ if task in _active_sessions:+ return _active_sessions[task]+ return next((info for key, info in _active_sessions.items()+ if owner_task_id(key) == task and not is_local_sidecar_key(key)), {})+++# ── Session creation ─────────────────────────────────────────────────────────────────────────────────++def _bot_desktop_target() -> Optional[tuple[str, dict[str, Any]]]:+ """``(launcher key, launch kwargs)`` for the shared Bot Desktop profile while its host screen is up: the+ agent's Chromium and the dock's Browser icon are THE SAME browser (binary + user-data-dir), and a dock+ instance a human already started is attached, never relaunched."""+ from tools.bot_desktop import runtime as _bd_runtime+ if not _bd_runtime.published_env().get("DISPLAY"):+ return None+ from tools.bot_desktop import browser as _bd_browser+ udd = str(_bd_browser.profile_dir())+ return f"profile:{udd}", {"executable": _bd_browser.executable(), "user_data_dir": udd, "ephemeral": False,+ "extra_args": _bd_browser.SHARED_PROFILE_ARGS}+++def _launch_target(cache_key: str) -> tuple[str, dict[str, Any], bool]:+ """``(launcher key, launch kwargs, shared)``. A persistent profile (Bot Desktop, ``browser.user_data_dir``)+ is keyed by its dir so every cache key shares the one Chromium Chromium's singleton allows on it."""+ bot_desktop = _bot_desktop_target()+ if bot_desktop is not None:+ return bot_desktop[0], bot_desktop[1], True+ from tools.browser_session_cloud import user_data_dir+ udd = user_data_dir()+ if udd:+ return f"profile:{udd}", {"user_data_dir": udd, "ephemeral": False}, True+ return cache_key, {}, False+++def _create_chromium_session(cache_key: str) -> dict[str, Any]:+ if browser_in_sandbox():+ from tools.browser_session_sandbox import create_sandbox_session+ return create_sandbox_session(cache_key)+ from tools.browser_launcher import launch_chromium+ launcher_key, kwargs, shared = _launch_target(cache_key)+ ensure_screen_for_headed_chromium()+ browser, err = launch_chromium(launcher_key, **kwargs)+ if browser is None:+ raise RuntimeError(err or "the local browser could not be started")+ info = _session_record("h", browser.cdp_url, {"local": True})+ info.update(launcher_key=launcher_key, shared_profile=shared)+ logger.info("Created local browser session %s for %s (Chromium pid %s)", info["session_name"], cache_key, browser.pid)+ return info+++def _create_lightpanda_session(cache_key: str) -> dict[str, Any]:+ from tools.browser_lightpanda import launch_lightpanda+ from tools.browser_session_cloud import is_local_backend+ info = _session_record("lp", None, {"local": True, "lightpanda": True})+ server, err = launch_lightpanda(info["session_name"], block_private_networks=not is_local_backend())+ if err:+ raise RuntimeError(err)+ info["cdp_url"] = server.cdp_url+ logger.info("Created Lightpanda session %s (port %s) for %s", info["session_name"], server.port, cache_key)+ return info+++def _create_local_session(cache_key: str, allow_real_profile: bool = True) -> dict[str, Any]:+ """Local session. The ONE place real profile vs fresh browser is decided: when the consented profile+ can't load, the fresh browser carries ``real_profile_unavailable`` so the first result tells the model it+ is signed out. The hybrid sidecar passes ``allow_real_profile=False``: the user's cookie jar must not+ reach an arbitrary internal host the model chose."""+ fallback_note = None+ if allow_real_profile:+ from tools.browser_session_real_profile import real_profile_cdp, real_profile_fallback_note+ cdp_url, err = real_profile_cdp()+ if err:+ logger.warning("real-profile unavailable for %s, using a fresh browser: %s", cache_key, err)+ fallback_note = real_profile_fallback_note(err)+ elif cdp_url:+ info = _session_record("rp", cdp_url, {"local": True, "real_profile": True})+ logger.info("Created real-profile local session %s for %s", info["session_name"], cache_key)+ return info+ from tools.browser_lightpanda import using_lightpanda_engine+ info = _create_lightpanda_session(cache_key) if using_lightpanda_engine() else _create_chromium_session(cache_key)+ if fallback_note:+ info["real_profile_unavailable"] = fallback_note+ return info+++def _create_cloud_session_or_fallback(cache_key: str, provider) -> dict[str, Any]:+ """Cloud session; on failure (429, quota, outage) a LOCAL launcher session marked ``fallback_from_cloud``.+ ``cdp_url`` is resolved here because some providers return an HTTP discovery URL."""+ from tools.browser_session_cdp import resolve_cdp_override+ try:+ session_info = provider.create_session(cache_key)+ if not session_info or not isinstance(session_info, dict):+ raise ValueError(f"Cloud provider returned invalid session: {session_info!r}")+ except Exception as e: # health: allow BLE001 -- any provider failure falls back to a local browser+ provider_name = type(provider).__name__+ logger.warning("Cloud provider %s failed (%s); falling back to local Chromium for %s",+ provider_name, e, cache_key, exc_info=True)+ try:+ local = _create_local_session(cache_key)+ except Exception as local_error: # health: allow BLE001 -- report both failures together+ raise RuntimeError(f"Cloud provider {provider_name} failed ({e}) and local "+ f"fallback also failed ({local_error})") from e+ return {**local, "fallback_from_cloud": True, "fallback_reason": str(e), "fallback_provider": provider_name}+ session_info = dict(session_info)+ if session_info.get("cdp_url"):+ session_info["cdp_url"] = resolve_cdp_override(str(session_info["cdp_url"]))+ return session_info+++def _create_session_for_key(cache_key: str, force_local: bool) -> dict[str, Any]:+ """Fresh session (runs OUTSIDE the lock: cloud mode makes a network call, a launch takes seconds)."""+ from tools.browser_session_cdp import get_cdp_override+ from tools.browser_session_cloud import get_cloud_provider+ override = get_cdp_override()+ if override and not force_local:+ logger.info("Created CDP browser session for %s", cache_key)+ return _session_record("cdp", override, {"cdp_override": True})+ if force_local:+ return _create_local_session(cache_key, allow_real_profile=False)+ provider = get_cloud_provider()+ if provider is None:+ return _create_local_session(cache_key)+ return _create_cloud_session_or_fallback(cache_key, provider)+++def _backend_dead(session_info: dict[str, Any]) -> bool:+ """True when a local session's process is gone (Chromium crashed or was killed, ``lightpanda serve``+ exited): the next call builds a fresh one instead of handing out a dead endpoint."""+ features = session_info.get("features") or {}+ if features.get("lightpanda"):+ from tools.browser_lightpanda import get_server+ server = get_server(session_info.get("session_name", ""))+ return server is None or not server.is_alive()+ launcher_key = session_info.get("launcher_key") or (+ "hermes-real-profile" if features.get("real_profile") else None)+ if launcher_key:+ from tools.browser_launcher import get_browser+ return get_browser(launcher_key) is None+ return False+++def _reuse_or_evict(cache_key: str) -> Optional[dict[str, Any]]:+ from tools import browser_session_lifecycle as _lifecycle+ with _cleanup_lock:+ existing = _active_sessions.get(cache_key)+ if existing is None:+ return None+ if not _lifecycle.session_has_expired(existing) and not _backend_dead(existing):+ return existing+ logger.info("Replacing expired or dead browser session for %s", cache_key)+ _lifecycle.cleanup_single_session(cache_key)+ _lifecycle.update_session_activity(cache_key) # teardown dropped the entry; track the replacement+ with _cleanup_lock:+ replacement = _active_sessions.get(cache_key) # another thread may already have rebuilt it+ return replacement if replacement is not None and replacement is not existing else None+++def _publish(cache_key: str, session_info: dict[str, Any], home_key: str) -> dict[str, Any]:+ session_info = dict(session_info)+ session_info.setdefault("session_key", cache_key)+ session_info.setdefault("owner_task_id", owner_task_id(cache_key))+ session_info.setdefault("home_key", home_key) # the profile reaped on /browser connect+ _active_sessions[cache_key] = session_info+ return session_info+++def get_session_info(cache_key: Optional[str] = None) -> dict[str, Any]:+ """Get or create the session for ``cache_key`` (thread-safe); starts the inactivity janitor and touches+ activity. A ``::local`` key forces a local browser even with a cloud provider configured."""+ from tools import browser_session_lifecycle as _lifecycle+ from tools.browser_session_cdp import ensure_cdp_supervisor, live_cdp_generation+ key = cache_key or "default"+ _lifecycle.start_cleanup_thread()+ _lifecycle.update_session_activity(key)+ reused = _reuse_or_evict(key)+ if reused is not None:+ return reused++ force_local = is_local_sidecar_key(key)+ home_key = hermes_home_key()+ for attempt in range(_STALE_ENDPOINT_RETRIES + 1):+ generation = live_cdp_generation(home_key)+ session_info = _create_session_for_key(key, force_local)+ with _cleanup_lock:+ if key in _active_sessions: # created concurrently during the launch: don't leak ours+ winner = _active_sessions[key]+ stale_ours = session_info+ session_info = None+ else:+ winner = stale_ours = None+ # A /browser connect publish while ours was built may mean it resolved the old endpoint:+ # never publish it (a concurrent caller would get a browser being closed); rebuild.+ if live_cdp_generation(home_key) == generation or attempt == _STALE_ENDPOINT_RETRIES:+ session_info = _publish(key, session_info, home_key)+ break+ if winner is not None:+ _lifecycle.release_session_backend(key, stale_ours)+ return winner+ logger.info("Browser endpoint changed during session creation for %s; recreating", key)+ _lifecycle.release_session_backend(key, session_info)++ # Cloud / CDP-override sessions get the supervisor here (dialogs, frame tree, vault fill). Local+ # browsers are attached by browser_exec per call under the task id.+ if not (session_info.get("features") or {}).get("local"):+ ensure_cdp_supervisor(key)+ return session_info+++def _atexit_cleanup() -> None:+ """atexit only — NO SIGINT/SIGTERM handlers calling sys.exit(): a SystemExit raised inside a+ prompt_toolkit key-binding callback corrupts the coroutine state and makes the process unkillable."""+ try:+ from tools.browser_session_lifecycle import emergency_cleanup_all_sessions, stop_cleanup_thread+ except ImportError: # half-updated tree mid-`hermes update` (#112437): nothing resolvable to clean+ return+ emergency_cleanup_all_sessions()+ stop_cleanup_thread()+++atexit.register(_atexit_cleanup)diff --git a/tools/browser_session_cdp.py b/tools/browser_session_cdp.pynew file mode 100644index 00000000000..442f2ad89c3--- /dev/null+++ b/tools/browser_session_cdp.py@@ -0,0 +1,159 @@+"""User-supplied CDP endpoints (live ``/browser connect``, ``BROWSER_CDP_URL``, ``browser.cdp_url``),+dialog-policy config and the per-task CDP supervisor lifecycle."""++from __future__ import annotations++import logging+import threading+from typing import Optional++from agent.proxy_bypass import loopback_request_kwargs+from agent.redact import redact_cdp_url++logger = logging.getLogger(__name__)++# Live ``/browser connect`` endpoints, one per profile home (``hermes_home_key()``): a multiplexed+# gateway serves every profile from this process, so a process-wide value would reach them all.+_live_overrides: dict[str, str] = {}+_live_overrides_lock = threading.Lock()+# Per-profile count of live-endpoint publishes. A session records the value it saw before resolving its+# endpoint; ``get_session_info`` closes one whose profile published in between.+_live_generations: dict[str, int] = {}+++def resolve_cdp_override(cdp_url: str) -> str:+ """Normalize a CDP endpoint into a concrete websocket URL.++ Full ``ws://.../devtools/browser/...`` endpoints pass through; HTTP discovery roots and bare+ ``ws://host:port`` resolve via ``/json/version`` → ``webSocketDebuggerUrl`` (falls back to the raw value).+ """+ raw = (cdp_url or "").strip()+ if not raw:+ return ""+ lowered = raw.lower()+ if "/devtools/browser/" in lowered:+ return raw+ discovery_url = raw+ if lowered.startswith(("ws://", "wss://")):+ if not (raw.count(":") == 2 and raw.rstrip("/").rsplit(":", 1)[-1].isdigit() and "/" not in raw.split(":", 2)[-1]):+ return raw+ discovery_url = ("http://" if lowered.startswith("ws://") else "https://") + raw.split("://", 1)[1]+ version_url = discovery_url if discovery_url.lower().endswith("/json/version") else discovery_url.rstrip("/") + "/json/version"+ try:+ import requests # lazy: shared module object, so test patches still apply+ response = requests.get(version_url, timeout=10, **loopback_request_kwargs(version_url))+ response.raise_for_status()+ payload = response.json()+ except Exception as exc: # health: allow BLE001 -- any discovery failure falls back to the raw endpoint+ logger.warning("Failed to resolve CDP endpoint %s via %s: %s", redact_cdp_url(raw),+ redact_cdp_url(version_url), redact_cdp_url(str(exc)))+ return raw+ ws_url = str(payload.get("webSocketDebuggerUrl") or "").strip()+ if ws_url:+ logger.info("Resolved CDP endpoint %s -> %s", redact_cdp_url(raw), redact_cdp_url(ws_url))+ return ws_url+ logger.warning("CDP discovery at %s did not return webSocketDebuggerUrl; using raw endpoint",+ redact_cdp_url(version_url))+ return raw+++def live_cdp_override() -> str:+ """The current profile's live ``/browser connect`` endpoint, or "".++ On a multiplexed gateway a context with no profile bound answers "" rather than the launch+ profile's endpoint, the way ``get_secret`` fails closed."""+ from agent.secret_scope import is_multiplex_active+ from hermes_constants import get_hermes_home_override, hermes_home_key+ if get_hermes_home_override() is None and is_multiplex_active():+ return ""+ with _live_overrides_lock:+ return _live_overrides.get(hermes_home_key(), "")+++def set_live_cdp_override(url: Optional[str]) -> None:+ """Set (or with a falsy ``url`` clear) the current profile's live endpoint and bump its generation."""+ from hermes_constants import hermes_home_key+ key = hermes_home_key()+ with _live_overrides_lock:+ if url:+ _live_overrides[key] = url+ else:+ _live_overrides.pop(key, None)+ _live_generations[key] = _live_generations.get(key, 0) + 1+++def live_cdp_generation(home_key: Optional[str] = None) -> int:+ """The current (or ``home_key``'s) profile's live-endpoint generation."""+ from hermes_constants import hermes_home_key+ with _live_overrides_lock:+ return _live_generations.get(home_key or hermes_home_key(), 0)+++def env_cdp_url() -> str:+ """``BROWSER_CDP_URL`` from this profile's secret scope. A routed profile reads only its own ``.env``+ (``os.environ`` holds the launch profile's value)."""+ from agent.secret_scope import current_secret_scope, get_secret, serves_routed_profile+ if serves_routed_profile():+ value = (current_secret_scope() or {}).get("BROWSER_CDP_URL")+ else:+ value = get_secret("BROWSER_CDP_URL")+ return (value or "").strip()+++def get_cdp_override_raw() -> str:+ """The *configured* CDP override, no network I/O: live ``/browser connect`` > ``BROWSER_CDP_URL`` >+ ``browser.cdp_url``. Is-it-configured gates (check_fns, local-mode checks, doctor) MUST use this:+ a 10 s discovery probe against a stale URL would stall every schema build."""+ from tools.browser_session_cloud import browser_cfg+ return live_cdp_override() or env_cdp_url() or browser_cfg("cdp_url", "", lambda v: str(v or "").strip())+++def get_cdp_override() -> str:+ """Resolved CDP override URL, or "". May do HTTP discovery: call only on paths about to connect."""+ raw = get_cdp_override_raw()+ return resolve_cdp_override(raw) if raw else ""+++def get_dialog_policy_config() -> tuple[str, float]:+ """``browser.dialog_policy`` + ``browser.dialog_timeout_s``; supervisor defaults when absent/invalid."""+ from tools.browser_session_cloud import browser_cfg+ from tools.browser_supervisor_dialogs import DEFAULT_DIALOG_POLICY, DEFAULT_DIALOG_TIMEOUT_S, _VALID_POLICIES+ policy = str(browser_cfg("dialog_policy", DEFAULT_DIALOG_POLICY) or DEFAULT_DIALOG_POLICY)+ if policy not in _VALID_POLICIES:+ logger.debug("Invalid browser.dialog_policy=%r; using default", policy)+ policy = DEFAULT_DIALOG_POLICY+ try:+ timeout_s = float(browser_cfg("dialog_timeout_s", DEFAULT_DIALOG_TIMEOUT_S) or DEFAULT_DIALOG_TIMEOUT_S)+ except (TypeError, ValueError):+ timeout_s = DEFAULT_DIALOG_TIMEOUT_S+ return policy, (timeout_s if timeout_s > 0 else DEFAULT_DIALOG_TIMEOUT_S)+++def ensure_cdp_supervisor(task_id: str) -> None:+ """Start the CDP supervisor for ``task_id`` when an endpoint is reachable (idempotent; restarts on a+ URL change). URL precedence: the CDP override, then the session's own ``cdp_url``. A failed attach+ never breaks the session."""+ cdp_url = get_cdp_override()+ if not cdp_url:+ from tools import browser_session as _bs+ with _bs._cleanup_lock:+ session_cdp = str((_bs._active_sessions.get(task_id) or {}).get("cdp_url") or "")+ cdp_url = resolve_cdp_override(session_cdp) if session_cdp else ""+ if not cdp_url:+ return+ try:+ from tools.browser_supervisor import SUPERVISOR_REGISTRY+ policy, timeout_s = get_dialog_policy_config()+ SUPERVISOR_REGISTRY.get_or_start(task_id=task_id, cdp_url=cdp_url, dialog_policy=policy,+ dialog_timeout_s=timeout_s)+ except Exception as exc: # health: allow BLE001 -- a failed supervisor attach must not break the session+ logger.debug("CDP supervisor attach for task=%s failed (non-fatal): %s", task_id, exc)+++def stop_cdp_supervisor(task_id: str) -> None:+ """Stop ``task_id``'s CDP supervisor if one exists."""+ try:+ from tools.browser_supervisor import SUPERVISOR_REGISTRY+ SUPERVISOR_REGISTRY.stop(task_id)+ except Exception as exc: # health: allow BLE001 -- teardown must never abort on a supervisor error+ logger.debug("CDP supervisor stop for task=%s failed (non-fatal): %s", task_id, exc)diff --git a/tools/browser_session_cloud.py b/tools/browser_session_cloud.pynew file mode 100644index 00000000000..38dd44368e7--- /dev/null+++ b/tools/browser_session_cloud.py@@ -0,0 +1,280 @@+"""``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_cfg(key: str, default, parse: Callable[[Any], Any] = lambda v: v):+ """``parse(browser.<key>)`` from the RAW profile config (loader warnings must not leak into tool JSON);+ ``default`` when absent, not a mapping, or unparseable."""+ try:+ from hermes_cli.config import read_raw_config+ section = read_raw_config().get("browser", {})+ if isinstance(section, dict) and 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:+ from hermes_cli.config import read_raw_config+ section = read_raw_config().get("browser", {})+ if isinstance(section, dict) and "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_mode() -> bool:+ """True when sessions run on a local browser (no CDP override, no cloud provider)."""+ from tools.browser_session_cdp import get_cdp_override_raw+ return not get_cdp_override_raw() and get_cloud_provider() is None+++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() -> str:+ """Shared-metrics label for the active profile's backend in session-creation precedence+ (CDP override > cloud provider > local engine). Config reads only, no network I/O."""+ from tools.browser_session_cdp import get_cdp_override_raw+ if get_cdp_override_raw():+ return "cdp"+ 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"diff --git a/tools/browser_session_lifecycle.py b/tools/browser_session_lifecycle.pynew file mode 100644index 00000000000..82d5b3a434f--- /dev/null+++ b/tools/browser_session_lifecycle.py@@ -0,0 +1,353 @@+"""Browser session lifecycle: inactivity janitor, orphan reap, per-session teardown, ``cleanup_*`` entry+points and the atexit sweep.++Teardown per session kind (CDP supervisor stopped first, so our WebSocket closes before the endpoint):+cloud → ``provider.close_session``; Lightpanda → ``stop_lightpanda``; launcher Chromium → ``stop_browser``+(a shared persistent profile only once no other session uses it); sandbox → SIGTERM inside the sandbox;+real profile → shared, terminated at exit / consent-off; CDP override → nothing (the user's browser).+"""++from __future__ import annotations++import contextlib+import logging+import threading+import time+from datetime import UTC, datetime+from pathlib import Path+from typing import Any, Optional++from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override++logger = logging.getLogger(__name__)+++def _bs():+ from tools import browser_session+ return browser_session+++def _session_expiry_timestamp(session_info: dict[str, Any]) -> Optional[float]:+ """Provider-authoritative expiry as epoch seconds; None when absent or malformed."""+ value = session_info.get("expires_at")+ if isinstance(value, (int, float)) and not isinstance(value, bool):+ return float(value)+ if not isinstance(value, str) or not value.strip():+ return None+ normalized = value.strip()+ if normalized.endswith(("Z", "z")):+ normalized = f"{normalized[:-1]}+00:00"+ try:+ parsed = datetime.fromisoformat(normalized)+ except ValueError:+ logger.warning("Ignoring invalid cloud browser session expiry timestamp")+ return None+ if parsed.tzinfo is None:+ parsed = parsed.replace(tzinfo=UTC)+ return parsed.timestamp()+++def session_has_expired(session_info: dict[str, Any], *, now: Optional[float] = None) -> bool:+ """Whether a cached session crossed its provider deadline."""+ expires_at = _session_expiry_timestamp(session_info)+ return expires_at is not None and (time.time() if now is None else now) >= expires_at+++def _best_effort(label: str, fn) -> None:+ """Run ``fn()``; log and swallow any exception — teardown must never abort."""+ try:+ fn()+ except Exception as e: # health: allow BLE001 -- teardown boundary: one failure must not stop the rest+ logger.debug("%s failed: %s", label, e)+++def update_session_activity(cache_key: str) -> None:+ """Touch the activity timestamp and record the owning Hermes home on first sight (#86402)."""+ bs = _bs()+ with bs._cleanup_lock:+ bs._session_last_activity[cache_key] = time.time()+ bs._session_owner_homes.setdefault(cache_key, str(get_hermes_home()))+++def _session_owner_scope(cache_key: str):+ """Run under the Hermes home + secret scope owning ``cache_key``'s session (no-op when unrecorded); the+ janitor is process-global, so each teardown re-enters ITS profile, never ``os.environ``."""+ owner_home = _bs()._session_owner_homes.get(cache_key)+ if owner_home is None:+ yield+ return+ from agent.secret_scope import build_profile_secret_scope, reset_secret_scope, set_secret_scope+ from hermes_cli.env_loader import hydrate_profile_secret_sources+ home_token = set_hermes_home_override(owner_home)+ try:+ hydrate_profile_secret_sources(Path(owner_home))+ secret_token = set_secret_scope(build_profile_secret_scope(Path(owner_home)), profile_home=owner_home)+ try:+ yield+ finally:+ reset_secret_scope(secret_token)+ finally:+ reset_hermes_home_override(home_token)+++def _forget_session_tracking(cache_key: str, *, activity: bool = True, session: bool = False) -> None:+ bs = _bs()+ with bs._cleanup_lock:+ if session:+ bs._active_sessions.pop(cache_key, None)+ if activity:+ bs._session_last_activity.pop(cache_key, None)+ bs._session_owner_homes.pop(cache_key, None)+ bs._cleanup_failures.pop(cache_key, None)+++# ── Teardown ─────────────────────────────────────────────────────────────────────────────────────────++def _launcher_key_in_use(launcher_key: str, session_info: dict[str, Any]) -> bool:+ bs = _bs()+ with bs._cleanup_lock:+ return any(info is not session_info and info.get("launcher_key") == launcher_key+ for info in bs._active_sessions.values())+++def _close_cloud_session(session_info: dict[str, Any]) -> None:+ bb_session_id = session_info.get("bb_session_id")+ if not bb_session_id:+ return+ from tools.browser_session_cloud import get_cloud_provider+ provider = get_cloud_provider()+ if provider is None:+ return+ try:+ provider.close_session(bb_session_id)+ except Exception as e: # health: allow BLE001 -- a provider error must never abort the rest of the teardown+ logger.warning("Could not close cloud browser session: %s", e)+++def release_session_backend(cache_key: str, session_info: dict[str, Any]) -> None:+ """Release ``session_info``'s browser BY OBJECT (an unpublished session releases through this alone)."""+ _close_cloud_session(session_info)+ features = session_info.get("features") or {}+ if features.get("lightpanda"):+ from tools.browser_lightpanda import stop_lightpanda+ stop_lightpanda(session_info.get("session_name", ""))+ if features.get("sandbox"):+ from tools.browser_session_sandbox import stop_sandbox_browser+ stop_sandbox_browser(session_info)+ launcher_key = session_info.get("launcher_key")+ if launcher_key and not _launcher_key_in_use(launcher_key, session_info):+ from tools.browser_launcher import stop_browser+ stop_browser(launcher_key)+++def cleanup_single_session(cache_key: str) -> None:+ """Tear down one session by its exact key."""+ from tools.browser_session_cdp import stop_cdp_supervisor+ stop_cdp_supervisor(cache_key) # close our WebSocket BEFORE the backend tears the endpoint down+ bs = _bs()+ with bs._cleanup_lock:+ session_info = bs._active_sessions.pop(cache_key, None)+ _forget_session_tracking(cache_key)+ if session_info:+ release_session_backend(cache_key, session_info)+ logger.debug("Closed browser session %s", cache_key)+++def cleanup_browser(task_id: Optional[str] = None) -> None:+ """Close the sessions serving ``task_id``: its exact key, its hybrid ``::local`` sidecar, and the+ served-profile-tagged keys browser_exec builds for it (``<task>@<home>``). Per-turn cleanup calls this+ with the bare task id."""+ task = task_id or "default"+ bs = _bs()+ with bs._cleanup_lock:+ if bs.is_local_sidecar_key(task):+ keys = [task] if task in bs._active_sessions else []+ else:+ keys = [key for key in bs._active_sessions if key == task or bs.owner_task_id(key) == task]+ for key in keys:+ cleanup_single_session(key)+ if not keys:+ _forget_session_tracking(task)+++def cleanup_profile_browsers(home_key: str) -> None:+ """Close one profile home's sessions, CDP supervisors and harness daemons, and drop its cached config+ (``/browser connect`` on a multiplexed gateway). Other profiles' browsers stay."""+ bs = _bs()+ with bs._cleanup_lock:+ keys = [key for key, info in bs._active_sessions.items() if info.get("home_key") == home_key]+ for key in keys:+ cleanup_single_session(key)++ def _stop_supervisors():+ from tools.browser_supervisor import SUPERVISOR_REGISTRY+ SUPERVISOR_REGISTRY.stop_home(home_key)+ _best_effort("CDP supervisor stop", _stop_supervisors)++ def _stop_harness():+ from tools.browser_use_cli import stop_harness_daemons+ stop_harness_daemons(home_key)+ _best_effort("Browser Use harness daemon stop", _stop_harness)+ from tools.browser_session_cloud import reset_caches+ reset_caches(home_key)+++def cleanup_all_browsers() -> None:+ """Close every session (gateway shutdown), stop every browser this process launched, reset caches."""+ bs = _bs()+ with bs._cleanup_lock:+ keys = list(bs._active_sessions)+ for key in keys:+ _best_effort(f"browser cleanup for {key}", lambda key=key: cleanup_single_session(key))++ def _stop_supervisors():+ from tools.browser_supervisor import SUPERVISOR_REGISTRY+ SUPERVISOR_REGISTRY.stop_all()+ _best_effort("CDP supervisor stop", _stop_supervisors)++ def _stop_harness():+ from tools.browser_use_cli import stop_harness_daemons+ stop_harness_daemons()+ _best_effort("Browser Use harness daemon stop", _stop_harness)++ def _stop_launched():+ from tools.browser_launcher import stop_all_browsers+ stop_all_browsers() # incl. the shared real-profile / persistent-profile browsers+ _best_effort("Chromium stop", _stop_launched)++ def _stop_lightpanda():+ from tools.browser_lightpanda import stop_all_lightpanda+ stop_all_lightpanda()+ _best_effort("Lightpanda stop", _stop_lightpanda)+ from tools.browser_session_cloud import reset_caches+ reset_caches()+++def emergency_cleanup_all_sessions() -> None:+ """atexit: close this process's browsers, then reap orphans left by crashed Hermes processes (every+ clean exit sweeps accumulated orphans). Idempotent."""+ bs = _bs()+ if bs._cleanup_done:+ return+ bs._cleanup_done = True+ if bs._active_sessions:+ logger.info("Emergency cleanup: closing %s active session(s)...", len(bs._active_sessions))+ _best_effort("Browser cleanup on exit", cleanup_all_browsers)+ with bs._cleanup_lock:+ bs._active_sessions.clear()+ bs._session_last_activity.clear()+ bs._session_owner_homes.clear()+ bs._cleanup_failures.clear()+ _best_effort("Orphan reap on exit", reap_orphaned_browser_sessions)+++def reap_orphaned_browser_sessions() -> int:+ """Stop Chromium / ``lightpanda serve`` processes whose owning Hermes process is gone."""+ from tools.browser_launcher import reap_orphaned_browsers+ from tools.browser_lightpanda import reap_orphaned_lightpanda+ reaped = 0+ for reap in (reap_orphaned_lightpanda, reap_orphaned_browsers):+ try:+ reaped += reap()+ except OSError as exc:+ logger.debug("orphan reap (%s) failed: %s", reap.__name__, exc)+ if reaped:+ logger.info("Reaped %d orphaned browser process(es) from previous run(s)", reaped)+ return reaped+++# ── Inactivity janitor ───────────────────────────────────────────────────────────────────────────────++def _human_holds_shared_browser(cache_key: str) -> bool:+ bs = _bs()+ with bs._cleanup_lock:+ session_info = bs._active_sessions.get(cache_key)+ return bool(session_info) and bs.human_holds_shared_browser(session_info)+++def _force_reap(cache_key: str) -> None:+ """Janitor last resort after repeated failures (#100738): drop the record, release the backend."""+ from tools.browser_session_cdp import stop_cdp_supervisor+ stop_cdp_supervisor(cache_key)+ bs = _bs()+ with bs._cleanup_lock:+ session_info = bs._active_sessions.pop(cache_key, None)+ if session_info:+ release_session_backend(cache_key, session_info)+++def _cleanup_one_inactive(cache_key: str, elapsed: int) -> None:+ bs = _bs()+ logger.info("Cleaning up inactive session %s (inactive for %ss)", cache_key, elapsed)+ try:+ with _session_owner_scope(cache_key):+ cleanup_single_session(cache_key)+ _forget_session_tracking(cache_key)+ except Exception as e: # health: allow BLE001 -- counted; force-reaped after MAX_INACTIVITY_CLEANUP_FAILURES+ with bs._cleanup_lock:+ failures = bs._cleanup_failures[cache_key] = bs._cleanup_failures.get(cache_key, 0) + 1+ if failures < bs.MAX_INACTIVITY_CLEANUP_FAILURES:+ logger.warning("Error cleaning up inactive session %s (attempt %d/%d): %s",+ cache_key, failures, bs.MAX_INACTIVITY_CLEANUP_FAILURES, e)+ return+ logger.error("Browser cleanup failed %d times for %s; force-reaping: %s", failures, cache_key, e)+ try:+ with _session_owner_scope(cache_key):+ _force_reap(cache_key)+ finally:+ _forget_session_tracking(cache_key, activity=False)+++def cleanup_inactive_sessions() -> None:+ """Close sessions idle past ``BROWSER_SESSION_INACTIVITY_TIMEOUT`` (janitor thread), each under its owner+ profile's scope. A human holding the Bot Desktop lease counts as activity."""+ bs = _bs()+ now = time.time()+ with bs._cleanup_lock:+ idle = [(key, int(now - last)) for key, last in bs._session_last_activity.items()+ if now - last > bs.BROWSER_SESSION_INACTIVITY_TIMEOUT]+ for key, elapsed in idle:+ with _session_owner_scope(key):+ if _human_holds_shared_browser(key):+ update_session_activity(key)+ continue+ _cleanup_one_inactive(key, elapsed)+++def _janitor() -> None:+ """Every 30 s: close idle sessions; reap orphans at startup AND every BROWSER_ORPHAN_REAP_INTERVAL."""+ bs = _bs()+ reap_every = max(1, round(bs.BROWSER_ORPHAN_REAP_INTERVAL / 30))+ cycle = 0+ while bs._cleanup_running:+ if cycle % reap_every == 0:+ _best_effort("Orphan reap", reap_orphaned_browser_sessions)+ cycle += 1+ _best_effort("Inactive browser cleanup", cleanup_inactive_sessions)+ for _ in range(30): # 1 s granularity so stop is quick+ if not bs._cleanup_running:+ break+ time.sleep(1)+++def start_cleanup_thread() -> None:+ bs = _bs()+ with bs._cleanup_lock:+ if bs._cleanup_thread is None or not bs._cleanup_thread.is_alive():+ bs._cleanup_running = True+ bs._cleanup_thread = threading.Thread(target=_janitor, daemon=True, name="browser-cleanup")+ bs._cleanup_thread.start()+ logger.info("Started browser inactivity janitor (timeout: %ss)", bs.BROWSER_SESSION_INACTIVITY_TIMEOUT)+++def stop_cleanup_thread() -> None:+ bs = _bs()+ bs._cleanup_running = False+ thread = bs._cleanup_thread+ if thread is not None:+ # A second Ctrl+C during the timed join lands here; the janitor is a daemon thread.+ try:+ thread.join(timeout=5)+ except (SystemExit, KeyboardInterrupt):+ passdiff --git a/tools/browser_session_real_profile.py b/tools/browser_session_real_profile.pynew file mode 100644index 00000000000..420c33088fe--- /dev/null+++ b/tools/browser_session_real_profile.py@@ -0,0 +1,131 @@+"""Real-profile local browsing: snapshot the user's default Chromium profile into a Hermes-owned copy and+launch the user's REAL browser binary on it through the launcher.++The real binary (not the packaged Chromium, and never ``--password-store=basic``/``--use-mock-keychain``)+keeps the OS keychain path intact, so macOS cookies decrypt and the copy stays signed in. One shared+browser serves every session (concurrent tasks must not launch rival Chromiums on one copy dir); it is+terminated at exit or when consent is turned off.+"""++from __future__ import annotations++import logging+import threading+from typing import Optional++logger = logging.getLogger(__name__)++REAL_PROFILE_KEY = "hermes-real-profile"+_RP = "browser.use_real_profile is on, but "+# Keep lock contention well inside the agent's 420-second outer tool deadline (an abandoned holder+# may be a daemon worker Python cannot terminate).+_LOCK_TIMEOUT_S = 30.0+_lock = threading.Lock()+# Extra flags on top of the launcher's base set: no hang monitor / popup blocking / repost prompts on an+# unattended browser driving the user's own sessions.+_REAL_PROFILE_EXTRA_FLAGS = ("--disable-hang-monitor", "--disable-popup-blocking", "--disable-prompt-on-repost")+++def real_profile_fallback_note(err: str) -> str:+ """Tool-result note when the real profile can't load and a fresh browser serves instead: the browser keeps+ working (a consented user is never left with no browser), and the model is told it is signed out."""+ return (f"{err} Using a fresh browser without the user's logins for this session instead; "+ "tell the user if the task needs their accounts.")+++def _unsupported_reason(browser) -> Optional[str]:+ """Why the default browser's profile can't be used, else None. A pre-release channel lives in a profile+ dir we don't resolve; normalizing it to the stable family would drive a DIFFERENT account."""+ from hermes_cli.browser_connect import UNSUPPORTED_CHANNEL+ if browser is None:+ return (_RP + "your default browser is not a supported Chromium browser (Chrome, Edge, Brave, "+ "Brave Origin, Chromium). Real-profile browsing requires a Chromium default; set one or turn the toggle off.")+ if browser == UNSUPPORTED_CHANNEL:+ return (_RP + "your default browser is a pre-release Chromium channel (Beta / Dev / Canary), which "+ "real-profile browsing does not support. Set your default to a "+ "stable Chrome / Edge / Brave / Brave Origin / Chromium, or turn the toggle off.")+ return None+++def _snapshot_error(err: str) -> str:+ """A locked profile adds the approved-close command, which the agent must ASK the user about first."""+ from hermes_cli.browser_connect import _PROFILE_LOCKED_PREFIX+ if err and err.startswith(_PROFILE_LOCKED_PREFIX):+ return (err[len(_PROFILE_LOCKED_PREFIX):] + " To close it (only after the user approves — it "+ "quits their browser and loses unsaved tabs), run: `hermes browser close-profile`; the next "+ "browser session then uses the profile.")+ return f"{_RP}{err}"+++def terminate_real_profile_browser() -> None:+ """Stop the shared real-profile browser if this process launched it (idempotent, atexit-safe)."""+ from tools.browser_launcher import stop_browser+ stop_browser(REAL_PROFILE_KEY)+++def _consent_revoked() -> tuple[None, None]:+ """Consent off: stop the copy-browser and delete the snapshot store (copies of cookies/logins), so+ revoking consent actually removes the credential copies."""+ terminate_real_profile_browser()+ try:+ from hermes_cli.browser_connect import cleanup_real_profile_snapshots+ cleanup_real_profile_snapshots()+ except OSError as exc:+ logger.debug("real-profile cleanup-on-consent-off failed: %s", exc)+ return None, None+++def _launch(browser_name: str) -> tuple[Optional[str], Optional[str]]:+ from hermes_cli.browser_connect import chromium_executable, real_profile_copy_dir, snapshot_real_profile+ from tools.browser_launcher import launch_chromium, running_instance+ from tools.browser_session import ensure_screen_for_headed_chromium+ copy_dir = real_profile_copy_dir(browser_name)+ # The snapshot overlay rewrites Cookies / Login Data: it must never run while a live copy-browser+ # (maybe from an earlier Hermes process) holds the dir open. The launcher ATTACHES to such a browser.+ if running_instance(copy_dir) is None:+ copy_dir, err = snapshot_real_profile(browser_name)+ if err or not copy_dir:+ return None, _snapshot_error(err)+ real_binary = chromium_executable(browser_name)+ if real_binary is None:+ return None, f"{_RP}the real browser binary for '{browser_name}' could not be found. Reinstall it or turn the toggle off."+ ensure_screen_for_headed_chromium()+ launched, err = launch_chromium(REAL_PROFILE_KEY, executable=real_binary, user_data_dir=copy_dir,+ ephemeral=False, extra_args=_REAL_PROFILE_EXTRA_FLAGS, timeout=30.0)+ if launched is None:+ return None, f"{_RP}the real-profile browser failed to start: {err}"+ logger.info("real-profile browser ready for %s at %s (%s)", browser_name, launched.http_url, copy_dir)+ return launched.cdp_url, None+++def real_profile_cdp() -> tuple[Optional[str], Optional[str]]:+ """``(cdp_url, error)`` for consented real-profile browsing.++ Snapshot → launch the real binary on the copy (or attach to the one already running) → its CDP URL.+ ``(None, message)`` when it can't (callers fall back to a fresh browser and report the message);+ ``(None, None)`` when consent is off."""+ from tools.browser_session_cloud import use_real_profile+ if not use_real_profile():+ return _consent_revoked()+ # Lightpanda cannot load a Chromium profile; checked before default-browser detection so a host with no+ # Chromium default still reports the actionable engine conflict.+ from tools.browser_lightpanda import using_lightpanda_engine+ if using_lightpanda_engine():+ return None, (_RP + "browser.engine is set to 'lightpanda', which cannot load a real Chromium profile. "+ "Set browser.engine to 'auto' to use real-profile browsing, or turn the toggle off.")+ if not _lock.acquire(timeout=_LOCK_TIMEOUT_S):+ return None, (_RP + "the real-profile browser is already being prepared by another call that has not "+ "finished. Retry after that call completes, or restart Hermes if it was abandoned.")+ try:+ from tools.browser_launcher import get_browser+ running = get_browser(REAL_PROFILE_KEY)+ if running is not None:+ return running.cdp_url, None+ from hermes_cli.browser_connect import detect_default_chromium+ browser_name = detect_default_chromium()+ unsupported = _unsupported_reason(browser_name)+ if unsupported:+ return None, unsupported+ return _launch(browser_name)+ finally:+ _lock.release()diff --git a/tools/browser_session_sandbox.py b/tools/browser_session_sandbox.pynew file mode 100644index 00000000000..a69141704f1--- /dev/null+++ b/tools/browser_session_sandbox.py@@ -0,0 +1,117 @@+"""The bot's Chromium INSIDE the terminal backend's sandbox (Bot Desktop placed there).++Same browser a human takes over in the pane: the sandbox image's Playwright Chromium on the profile the+dock's Browser icon uses, on the sandbox screen's DISPLAY. Its DevTools port is the sandbox's loopback,+unreachable from this host (Docker bridge / ssh remote), so it is forwarded over the sandbox's exec+stream; Chromium's DevTools accepts any loopback ``Host`` header, port included.+"""++from __future__ import annotations++import logging+import shlex+import time+from typing import Any, Optional++logger = logging.getLogger(__name__)++_LAUNCH_TIMEOUT_S = 60.0+++def _sandbox():+ from tools.bot_desktop import runtime as _bd_runtime+ env = _bd_runtime._sandbox_env(create=True)+ if env is None:+ raise RuntimeError("the terminal backend's sandbox is not running, so there is nowhere to run the browser")+ published = _bd_runtime.published_env()+ if not published.get("DISPLAY"):+ # The sandbox died under a live screen: fail here rather than run headless in a dead sandbox or,+ # worse, fall back to the host.+ raise RuntimeError("the screen inside the terminal backend's sandbox is gone; start it again")+ return env, published+++def _read_devtools(env, user, udd: str) -> Optional[tuple[int, str]]:+ from tools.environments import streams+ proc = streams.run_in(env, ["cat", f"{udd}/DevToolsActivePort"], user=user, timeout=10)+ lines = proc.stdout.decode("utf-8", "replace").splitlines() if proc.returncode == 0 else []+ if len(lines) >= 2 and lines[0].strip().isdigit() and lines[1].startswith("/devtools/browser/"):+ return int(lines[0].strip()), lines[1].strip()+ return None+++def _start_chromium(env, user, exe: str, udd: str, child_env: dict) -> int:+ """Launch detached in the sandbox; returns the sandbox pid."""+ from tools.bot_desktop.browser import SHARED_PROFILE_ARGS+ from tools.browser_launcher import CHROMIUM_SANDBOX_BYPASS_ARGS, build_chromium_argv+ from tools.environments import streams+ # Container: no user namespaces for Chromium's own sandbox, so the bypass flags always apply; the+ # shared-profile flags match the dock's icon on this same profile.+ argv = build_chromium_argv(exe, udd, packaged=False, headed=True,+ extra_args=(*SHARED_PROFILE_ARGS, *CHROMIUM_SANDBOX_BYPASS_ARGS))+ argv = list(dict.fromkeys(argv))+ script = (f"mkdir -p {shlex.quote(udd)} && rm -f {shlex.quote(udd)}/DevToolsActivePort && "+ f"(setsid {shlex.join(argv)} >/dev/null 2>&1 & echo $!)")+ proc = streams.run_in(env, ["bash", "-c", script], child_env=child_env, user=user, timeout=30)+ pid_text = proc.stdout.decode("utf-8", "replace").strip().splitlines()[-1:] if proc.returncode == 0 else []+ if not pid_text or not pid_text[0].isdigit():+ raise RuntimeError(f"Chromium could not be started in the sandbox: {proc.stderr.decode('utf-8', 'replace')[-500:]}")+ return int(pid_text[0])+++def _wait_for_port(env, user, udd: str) -> tuple[int, str]:+ deadline = time.monotonic() + _LAUNCH_TIMEOUT_S+ while time.monotonic() < deadline:+ found = _read_devtools(env, user, udd)+ if found:+ return found+ time.sleep(0.5)+ raise RuntimeError("Chromium in the sandbox did not expose a DevTools endpoint in time")+++def create_sandbox_session(cache_key: str) -> dict[str, Any]:+ """Session on the sandbox Chromium (attach to the running one, else launch it)."""+ from tools.bot_desktop import sandbox_host+ from tools.browser_session import _session_record+ from tools.environments import streams+ env, published = _sandbox()+ user = sandbox_host._user_for(env)+ udd = sandbox_host.browser_profile_dir(env)+ owned_pid = None+ found = _read_devtools(env, user, udd)+ if found is not None and not _port_answers(env, user, found[0]):+ found = None+ if found is None:+ exe = sandbox_host.chromium_executable(env)+ if not exe:+ raise RuntimeError("the sandbox image has no Chromium to run the browser")+ child_env = {**published, "TMPDIR": streams.sandbox_temp_dir(env)}+ owned_pid = _start_chromium(env, user, exe, udd, child_env)+ found = _wait_for_port(env, user, udd)+ local_port = streams.forward_port(env, found[0], user=user)+ info = _session_record("sb", f"ws://127.0.0.1:{local_port}{found[1]}", {"local": True, "sandbox": True})+ info.update(sandbox_pid=owned_pid, shared_profile=True, launcher_key=None)+ logger.info("Created sandbox browser session %s for %s", info["session_name"], cache_key)+ return info+++def _port_answers(env, user, port: int) -> bool:+ from tools.environments import streams+ probe = f"exec 3<>/dev/tcp/127.0.0.1/{int(port)}"+ return streams.run_in(env, ["bash", "-c", probe], user=user, timeout=10).returncode == 0+++def stop_sandbox_browser(session_info: dict[str, Any]) -> None:+ """SIGTERM the sandbox Chromium this process launched (best effort; the sandbox's lifetime bounds it)."""+ pid = session_info.get("sandbox_pid")+ if not pid:+ return+ from tools.bot_desktop import runtime as _bd_runtime, sandbox_host+ from tools.environments import streams+ env = _bd_runtime._sandbox_env(create=False)+ if env is None:+ return+ try:+ streams.run_in(env, ["kill", "-TERM", str(int(pid))], user=sandbox_host._user_for(env), timeout=15)+ except (OSError, RuntimeError) as exc:+ logger.debug("sandbox browser stop for pid %s failed: %s", pid, exc)diff --git a/tools/browser_url_policy.py b/tools/browser_url_policy.pynew file mode 100644index 00000000000..5a1df5f1abd--- /dev/null+++ b/tools/browser_url_policy.py@@ -0,0 +1,142 @@+"""URL safety for ``browser_exec`` (pre-scan of URL literals, hybrid local routing) and the SSRF helpers+``browser_cdp`` uses on raw CDP calls.++Ordered floors: cloud metadata / IMDS refused unconditionally (a local Chromium on a cloud VM still+reaches the host IMDS); private addresses refused unless the backend is local, the URL is served by the+hybrid local sidecar, or ``browser.allow_private_urls``; then the website allow/deny policy.+"""++from __future__ import annotations++import ipaddress+import logging+import re+import socket+import urllib.parse+from typing import Optional++from tools.url_safety import (+ _is_declared_fake_ip,+ is_always_blocked_url,+ is_safe_url,+ normalize_url_for_request,+)+from tools.website_policy import check_website_access++logger = logging.getLogger(__name__)++_PRIVATE_HOST_SUFFIXES = (".localhost", ".local", ".lan", ".internal")+_CGNAT = ipaddress.ip_network("100.64.0.0/10")+# URL-shaped literals in a JS expression (http/https only). fetch/XHR to a private host never updates+# ``location.href``, so the literals are pre-screened instead.+_JS_URL_LITERAL_RE = re.compile(r"""https?://[^\s'"`)\]<>]+""", re.IGNORECASE)+++def _err(error: str, **extra) -> dict:+ return {"success": False, "error": error, **extra}+++def _private_ip(host: str) -> Optional[bool]:+ """None when ``host`` is not an IP literal."""+ try:+ ip = ipaddress.ip_address(host)+ except ValueError:+ return None+ if _is_declared_fake_ip(ip):+ return False+ return ip.is_private or ip.is_loopback or ip.is_link_local or ip in _CGNAT+++def url_is_private(url: str) -> bool:+ """True when the URL's host is (or resolves to) a private/LAN/loopback/CGNAT address.++ Routing oracle only: DNS failures are NOT private (the configured backend surfaces the error). A local+ proxy's declared fake-ip sentinel (``security.fake_ip_ranges``) is not private: the name is public and+ the cloud browser resolves it itself."""+ try:+ hostname = (urllib.parse.urlparse(url).hostname or "").strip().lower().rstrip(".")+ if not hostname:+ return False+ literal = _private_ip(hostname)+ if literal is not None:+ return literal+ if hostname == "localhost" or hostname.endswith(_PRIVATE_HOST_SUFFIXES):+ return True+ try:+ addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)+ except socket.gaierror:+ return False+ return any(_private_ip(sockaddr[0]) for *_, sockaddr in addr_info)+ except (ValueError, OSError, UnicodeError) as exc:+ logger.debug("URL-privacy check failed for %s: %s", url, exc)+ return False+++def hybrid_routes_locally(url: str) -> bool:+ """True when ``url`` belongs on the hybrid LOCAL sidecar instead of the cloud provider: a provider+ configured, ``browser.auto_local_for_private_urls`` on, a private URL, and no CDP override (it owns+ the whole session)."""+ from tools.browser_session_cdp import get_cdp_override_raw+ from tools.browser_session_cloud import auto_local_for_private_urls, get_cloud_provider+ return (+ not get_cdp_override_raw()+ and get_cloud_provider() is not None+ and auto_local_for_private_urls()+ and url_is_private(url)+ )+++def _secret_url_error(url: str) -> Optional[dict]:+ """Refuse URLs embedding an API key/token (raw and URL-decoded, catching ``%2D`` tricks): a prompt+ injection could otherwise exfiltrate secrets through the URL."""+ from agent.redact import _PREFIX_RE+ if _PREFIX_RE.search(url) or _PREFIX_RE.search(urllib.parse.unquote(url)):+ return _err("Blocked: URL contains what appears to be an API key or token. Secrets must not be sent in URLs.")+ return None+++def _url_policy_error(url: str, *, auto_local: bool = False) -> Optional[dict]:+ """Backend-aware checks on a normalized URL; None if allowed.++ Credential-NAMED query params (``?token=``, ``?signature=``) are deliberately not a floor: magic links,+ OAuth callbacks and signed CDN assets are how the agent signs in, and a cloud browser already sees every+ cookie of the session. Hermes' own secrets in a URL are caught by ``_secret_url_error``."""+ from tools.browser_session_cloud import allow_private_urls, is_local_backend+ if is_always_blocked_url(url): # unconditional: IMDS via any browser exfiltrates host credentials (#16234)+ return _err("Blocked: URL targets a cloud metadata endpoint")+ if not is_local_backend() and not auto_local and not allow_private_urls() and not is_safe_url(url):+ return _err("Blocked: URL targets a private or internal address")+ blocked = check_website_access(url)+ if blocked:+ return _err(blocked["message"],+ blocked_by_policy={"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]})+ return None+++def evaluate_url_safety(url: str, *, auto_local: bool = False) -> Optional[dict]:+ """None if ``url`` is safe to open, else an error dict. ``auto_local`` (served by the hybrid local+ sidecar) relaxes only the private-address floor, never the cloud-metadata one."""+ err = _secret_url_error(url)+ if err is None:+ url = normalize_url_for_request(url)+ err = _secret_url_error(url)+ return err or _url_policy_error(url, auto_local=auto_local)+++def eval_ssrf_guard_active() -> bool:+ """True when page-driven private-network access must be guarded: a non-local backend (cloud browser,+ off-host CDP, or a containerized terminal whose host browser reaches networks it can't) without+ ``browser.allow_private_urls``."""+ from tools.browser_session_cloud import allow_private_urls, is_local_backend+ return not is_local_backend() and not allow_private_urls()+++def url_blocked(url: str) -> bool:+ """True when ``url`` hits the always-blocked cloud-metadata floor or fails the SSRF guard."""+ return is_always_blocked_url(url) or not is_safe_url(url)+++def expression_targets_private_url(expression: str) -> Optional[str]:+ """The first private/always-blocked ``http(s)://`` literal in a JS expression (best-effort), else None."""+ literals = _JS_URL_LITERAL_RE.findall(expression) if isinstance(expression, str) else []+ return next((c for c in (m.rstrip(".,;") for m in literals) if url_blocked(c)), None)