Skip to content

The agent that grows with you

feat(browser): chromium_executable reads browser.executable_path, pm, the Docker baked path, then a system Chromium where pm builds none

Tekniumd46703d87828
diff --git a/hermes_cli/browser_runtime.py b/hermes_cli/browser_runtime.py
index f18cfaa6108..08d0ab11229 100644
--- a/hermes_cli/browser_runtime.py
+++ b/hermes_cli/browser_runtime.py
@@ -1,16 +1,88 @@
-"""Read-only full-Chromium selection shared by browser launchers."""
+"""Read-only full-Chromium selection shared by browser launchers.
+
+Nothing here installs, downloads or starts anything: a caller that may provision (the launcher's
+one-shot ``pm.ensure("chromium")``) does so itself and then asks again.
+"""
from __future__ import annotations
import os
+from pathlib import Path
import pm
+# Written by the Docker image build with the pm Chromium binary it staged. The binary's path differs
+# per architecture (chrome-linux64/chrome vs chromium-linux-arm64/chromium), so the build resolves it
+# once; it also survives a volume over the runtime dir that hides pm's facts.
+BAKED_EXECUTABLE_FILE = Path("/etc/hermes/chromium-executable-path")
-def chromium_executable(*, allow_override: bool = True) -> str | None:
- """Prefer an explicit override unless the caller needs PM's own Chromium."""
- override = os.environ.get("AGENT_BROWSER_EXECUTABLE_PATH") if allow_override else None
- if override:
- return override
+# Distribution command names for a system Chromium, used only where pm builds none for this target
+# (Termux: `pkg install chromium` from x11-repo).
+_SYSTEM_CHROMIUM_COMMANDS = ("chromium", "chromium-browser")
+
+
+def _configured_executable() -> str | None:
+ """``browser.executable_path`` from the active profile's config (managed overlay applied)."""
+ from hermes_cli.config import cfg_get, load_config_readonly
+
+ value = cfg_get(load_config_readonly(), "browser", "executable_path", default="")
+ value = os.path.expanduser(value.strip()) if isinstance(value, str) else ""
+ return value or None
+
+
+def _pm_executable() -> str | None:
installed = pm.installed_package("chromium")
return str(installed.binary) if installed and installed.binary is not None else None
+
+
+def _baked_executable() -> str | None:
+ try:
+ value = BAKED_EXECUTABLE_FILE.read_text(encoding="utf-8").strip()
+ except OSError: # not a Hermes Docker image: nothing baked
+ return None
+ return value if value and os.path.isfile(value) else None
+
+
+def _pm_has_no_chromium() -> bool:
+ """pm publishes no Chromium for this target (Termux/Android, musl)."""
+ return pm.get_package("chromium").missing_reason(pm.current_target()) is not None
+
+
+def _system_executable() -> str | None:
+ from hermes_platform.resolver import locate_command
+
+ for name in _SYSTEM_CHROMIUM_COMMANDS:
+ found = locate_command(name).command
+ if found:
+ return found[0]
+ return None
+
+
+def chromium_executable(*, allow_override: bool = True) -> str | None:
+ """The full Chromium a browser launcher should run, or ``None`` when none is available.
+
+ Order: ``browser.executable_path`` (skipped with ``allow_override=False``, for callers that need
+ pm's own build) -> pm's installed ``chromium`` -> the Docker image's baked path -> a system
+ ``chromium`` / ``chromium-browser`` on PATH, only on targets pm builds no Chromium for (Termux).
+ """
+ if allow_override and (override := _configured_executable()):
+ return override
+ if found := _pm_executable() or _baked_executable():
+ return found
+ return _system_executable() if _pm_has_no_chromium() else None
+
+
+def chromium_missing_hint() -> str:
+ """One actionable line for "no Chromium" on this machine. Never suggests npm."""
+ from hermes_platform.host.runtime import is_termux
+
+ if is_termux():
+ return ("No Chromium found: pm builds none for Termux. Install one with "
+ "`pkg install x11-repo && pkg install chromium`, or set browser.executable_path.")
+ if BAKED_EXECUTABLE_FILE.exists():
+ return ("The image's Chromium is missing: pull the current Hermes image and recreate the "
+ "container (a volume mounted over the image's tool store hides it).")
+ if _pm_has_no_chromium():
+ return ("No Chromium found: pm builds none for this platform. Install your distribution's "
+ "chromium package, or set browser.executable_path.")
+ return "Chromium is not installed: run `hermes pm install chromium`."
diff --git a/tests/hermes_cli/test_browser_runtime.py b/tests/hermes_cli/test_browser_runtime.py
index 834a5dfcc60..d5a7557e177 100644
--- a/tests/hermes_cli/test_browser_runtime.py
+++ b/tests/hermes_cli/test_browser_runtime.py
@@ -1,22 +1,15 @@
-"""Browser resolution uses installed PM facts without provisioning a browser."""
+"""Browser resolution uses installed PM facts and config without provisioning a browser."""
import os
import pytest
import pm
+from hermes_cli import browser_runtime
from pm import paths
[email protected]("record_executable", [False, True])
-def test_chromium_resolves_installed_binary_without_mutation(tmp_path, monkeypatch, record_executable):
- from hermes_cli.browser_runtime import chromium_executable
-
- home = tmp_path / "home"
- store = home / "tools"
- monkeypatch.setenv("HERMES_HOME", str(home))
- monkeypatch.setenv("HERMES_RUNTIME_DIR", str(store))
- monkeypatch.delenv("AGENT_BROWSER_EXECUTABLE_PATH", raising=False)
+def _fake_pm_chromium(store):
lock = pm.Lockfile(paths.lockfile_path())
target = pm.current_target()
package = pm.get_package("chromium")
@@ -27,30 +20,41 @@ def test_chromium_resolves_installed_binary_without_mutation(tmp_path, monkeypat
binary.parent.mkdir(parents=True)
binary.write_bytes(b"browser-fixture")
binary.chmod(0o755)
- env = {"PLAYWRIGHT_BROWSERS_PATH": str(store)}
- if record_executable:
- env["AGENT_BROWSER_EXECUTABLE_PATH"] = str(binary)
facts = pm.Facts(store / "facts.json")
facts.record(
- "chromium", version, entry.name, env, store,
+ "chromium", version, entry.name, {"PLAYWRIGHT_BROWSERS_PATH": str(store)}, store,
target=target, artifacts=[a["sha256"] for a in lock.artifacts("chromium", target)],
)
+ return binary, facts
+
+
+def homes(tmp_path, monkeypatch):
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path / "home"))
+ monkeypatch.setenv("HERMES_RUNTIME_DIR", str(tmp_path / "tools"))
+ (tmp_path / "home").mkdir()
+ monkeypatch.setattr(browser_runtime, "BAKED_EXECUTABLE_FILE", tmp_path / "etc" / "chromium-executable-path")
+ return tmp_path
+
+
+def _write_config(home, text):
+ home.mkdir(parents=True, exist_ok=True)
+ (home / "config.yaml").write_text(text, encoding="utf-8")
+
+
+def test_chromium_resolves_installed_binary_without_mutation(homes):
+ binary, facts = _fake_pm_chromium(homes / "tools")
before = facts.path.read_bytes()
environment = dict(os.environ)
- assert chromium_executable() == str(binary)
+ assert browser_runtime.chromium_executable() == str(binary)
assert facts.path.read_bytes() == before
assert dict(os.environ) == environment
-def test_chromium_override_wins_without_installing(tmp_path, monkeypatch):
- from hermes_cli.browser_runtime import chromium_executable
-
- store = tmp_path / "missing-store"
- monkeypatch.setenv("HERMES_HOME", str(tmp_path / "home"))
- monkeypatch.setenv("HERMES_RUNTIME_DIR", str(store))
- override = str(tmp_path / "external browser")
- monkeypatch.setenv("AGENT_BROWSER_EXECUTABLE_PATH", override)
+def test_configured_executable_wins_without_installing(homes, monkeypatch):
+ override = homes / "external browser"
+ _write_config(homes / "home", f"browser:\n executable_path: '{override}'\n")
def forbidden(*args, **kwargs):
pytest.fail("browser resolution must not provision or activate packages")
@@ -59,8 +63,70 @@ def test_chromium_override_wins_without_installing(tmp_path, monkeypatch):
monkeypatch.setattr(pm, "activate", forbidden)
with monkeypatch.context() as scoped:
scoped.setattr(pm, "installed_package", forbidden)
- assert chromium_executable() == override
- monkeypatch.delenv("AGENT_BROWSER_EXECUTABLE_PATH")
- assert chromium_executable() is None
- assert not store.exists()
- assert "AGENT_BROWSER_EXECUTABLE_PATH" not in os.environ
+ assert browser_runtime.chromium_executable() == str(override)
+ # allow_override=False asks for pm's own build only.
+ assert browser_runtime.chromium_executable(allow_override=False) is None
+ assert not (homes / "tools").exists()
+
+
+def test_agent_browser_env_is_not_an_override(homes, monkeypatch):
+ monkeypatch.setenv("AGENT_BROWSER_EXECUTABLE_PATH", str(homes / "legacy"))
+ assert browser_runtime.chromium_executable() is None
+
+
+def test_override_is_read_from_the_active_profile(homes):
+ from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+
+ a, b = homes / "a", homes / "b"
+ _write_config(a, "browser:\n executable_path: /opt/a/chrome\n")
+ _write_config(b, "browser:\n executable_path: ''\n")
+ for home, expected in ((a, "/opt/a/chrome"), (b, None), (a, "/opt/a/chrome")):
+ token = set_hermes_home_override(home)
+ try:
+ assert browser_runtime.chromium_executable() == expected
+ finally:
+ reset_hermes_home_override(token)
+
+
+def test_baked_docker_path_after_pm(homes):
+ baked_binary = homes / "opt" / "chrome"
+ baked_binary.parent.mkdir()
+ baked_binary.write_bytes(b"x")
+ browser_runtime.BAKED_EXECUTABLE_FILE.parent.mkdir()
+ browser_runtime.BAKED_EXECUTABLE_FILE.write_text(f"{baked_binary}\n", encoding="utf-8")
+ assert browser_runtime.chromium_executable() == str(baked_binary)
+
+ binary, _ = _fake_pm_chromium(homes / "tools")
+ assert browser_runtime.chromium_executable() == str(binary)
+
+
+def test_baked_path_to_a_missing_binary_is_ignored_and_hinted(homes):
+ browser_runtime.BAKED_EXECUTABLE_FILE.parent.mkdir()
+ browser_runtime.BAKED_EXECUTABLE_FILE.write_text(str(homes / "gone"), encoding="utf-8")
+ assert browser_runtime.chromium_executable() is None
+ assert "pull the current Hermes image" in browser_runtime.chromium_missing_hint()
+
+
+def test_system_chromium_only_where_pm_builds_none(homes, monkeypatch):
+ bindir = homes / "bin"
+ bindir.mkdir()
+ exe = bindir / "chromium-browser"
+ exe.write_text("#!/bin/sh\n", encoding="utf-8")
+ exe.chmod(0o755)
+ monkeypatch.setenv("PATH", str(bindir))
+ # A target pm builds Chromium for: a system chromium on PATH is not picked up.
+ monkeypatch.setattr(pm, "current_target", lambda: "linux-x64")
+ assert browser_runtime.chromium_executable() is None
+ assert browser_runtime.chromium_missing_hint() == "Chromium is not installed: run `hermes pm install chromium`."
+ # Termux (linux-arm64-bionic): pm builds no Chromium, the system one is used.
+ monkeypatch.setattr(pm, "current_target", lambda: "linux-arm64-bionic")
+ assert browser_runtime.chromium_executable() == str(exe)
+
+
+def test_termux_hint_never_mentions_npm(homes, monkeypatch):
+ from hermes_platform.host import runtime
+
+ monkeypatch.setattr(runtime, "is_termux", lambda: True)
+ hint = browser_runtime.chromium_missing_hint()
+ assert "pkg install" in hint and "npm" not in hint and "npx" not in hint