Skip to content

The agent that grows with you

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.py
index 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 annotations
import os
import shutil
-import socket
from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional
from tools.bot_desktop import runtime
@@ -25,25 +23,25 @@ _SYSTEM_BROWSERS = ("google-chrome", "google-chrome-stable", "chromium", "chromi
def 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's
state 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, while
a distro chromium ships the helper. The bundle stays the answer when it is the only browser — a dock
icon 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 explicit
finders = [_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_userns
return 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-started
instance 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_bypass
return [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 None
else sandbox_bypass) else ())]
@@ -113,72 +110,3 @@ def dock_exec_line(exe: str, user_data_dir: str, *, sandbox_bypass: Optional[boo
quoted = "".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 env
diff --git a/tools/bot_desktop/launcher.sh b/tools/bot_desktop/launcher.sh
index 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" ]]; then
dock_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.py
index 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: str
install_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 browser
blocker: Optional[str] = None # why start() would refuse right now (memory); None = may start
memory_available_mb: Optional[int] = None
memory_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 screen
env.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 icon
return 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_line
exe = sandbox_host.chromium_executable(env)
diff --git a/tools/bot_desktop/sandbox_host.py b/tools/bot_desktop/sandbox_host.py
index 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 the
sandbox (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 run
the 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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):
+ pass
diff --git a/tools/browser_session_real_profile.py b/tools/browser_session_real_profile.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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)