"""The bot's browser on its Bot Desktop: one executable, one persistent user-data-dir per profile. 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 from pathlib import Path from typing import Optional from tools.bot_desktop import runtime DISK_CACHE_BYTES = 256 * 1024 * 1024 _SYSTEM_BROWSERS = ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser") def profile_dir() -> Path: """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 ``/pin`` and two profiles never share one jar by accident.""" 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 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``. """ 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] if not _is_root() and _userns_restricted(): finders.reverse() return next((exe for find in finders if (exe := find())), None) def _managed_executable() -> Optional[str]: from hermes_cli.browser_runtime import chromium_executable exe = chromium_executable(allow_override=False) return exe if exe and os.access(exe, os.X_OK) and not _is_headless_shell(exe) else None def _is_headless_shell(exe: str) -> bool: """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 def _system_executable() -> Optional[str]: return next((shutil.which(name) for name in _SYSTEM_BROWSERS if shutil.which(name)), None) def _is_root() -> bool: return hasattr(os, "geteuid") and os.geteuid() == 0 def _userns_restricted() -> bool: from tools.browser_launcher import apparmor_restricts_unprivileged_userns return apparmor_restricts_unprivileged_userns() def dock_launch() -> Optional[tuple[str, str]]: """``(executable, user_data_dir)`` for the dock's Browser icon, or ``None`` when no Chromium exists.""" exe = executable() 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 ``/DevToolsActivePort``); 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", *SHARED_PROFILE_ARGS, *(CHROMIUM_SANDBOX_BYPASS_ARGS if (needs_chromium_sandbox_bypass() if sandbox_bypass is None else sandbox_bypass) else ())] def dock_exec_line(exe: str, user_data_dir: str, *, sandbox_bypass: Optional[bool] = None) -> str: """The ``Exec=`` line of the dock's ``.desktop`` entry. Every argument is double-quoted per the Desktop Entry spec (a browser under ``/opt/Google Chrome/`` or a profile under a spaced HERMES_HOME otherwise splits into garbage): inside the quotes ``" ` $ \\`` are backslash-escaped, and because the value is itself a string field, each of those backslashes is escaped once more.""" def quote(arg: str) -> str: 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))