feat: add ensure_dependency() wrapper + ship install.sh in wheel

Includes paired change: browser tool now searches ~/.hermes/node_modules/.bin/
for agent-browser installed via install.sh --ensure browser.

.github/workflows/upload_to_pypi.yml

@@ -71,6 +71,11 @@ jobs:
           test -f hermes_cli/web_dist/index.html || { echo "ERROR: web_dist not built"; exit 1; }
           test -f hermes_cli/tui_dist/entry.js || { echo "ERROR: tui_dist not built"; exit 1; }
 
+      - name: Bundle install.sh into wheel
+        run: |
+          mkdir -p hermes_cli/scripts
+          cp scripts/install.sh hermes_cli/scripts/install.sh
+
       - name: Build wheel and sdist
         run: uv build --sdist --wheel
 

hermes_cli/dep_ensure.py

@@ -0,0 +1,96 @@
+"""Lazy dependency bootstrapper for non-Python runtime deps.
+
+Wraps install.sh --ensure to install node, browser, ripgrep, ffmpeg
+on first use. Prompts interactively unless told not to.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+_DEP_CHECKS = {
+    "node": lambda: shutil.which("node") is not None,
+    "browser": lambda: (
+        shutil.which("agent-browser") is not None
+        or _has_system_browser()
+        or _has_hermes_agent_browser()
+    ),
+    "ripgrep": lambda: shutil.which("rg") is not None,
+    "ffmpeg": lambda: shutil.which("ffmpeg") is not None,
+}
+
+_DEP_DESCRIPTIONS = {
+    "node": "Node.js (required for browser tools and TUI)",
+    "browser": "Browser engine (Chromium, for web browsing tools)",
+    "ripgrep": "ripgrep (fast file search)",
+    "ffmpeg": "ffmpeg (TTS voice messages)",
+}
+
+
+def _has_system_browser() -> bool:
+    for name in ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser"):
+        if shutil.which(name):
+            return True
+    return False
+
+
+def _has_hermes_agent_browser() -> bool:
+    hermes_home = os.environ.get("HERMES_HOME", str(Path.home() / ".hermes"))
+    return (Path(hermes_home) / "node_modules" / ".bin" / "agent-browser").is_file()
+
+
+def _find_install_script(
+    package_dir: Path | None = None,
+    repo_root: Path | None = None,
+) -> Path | None:
+    """Locate install.sh — bundled in wheel or in git checkout."""
+    if package_dir is None:
+        package_dir = Path(__file__).parent
+    if repo_root is None:
+        repo_root = package_dir.parent
+
+    bundled = package_dir / "scripts" / "install.sh"
+    if bundled.is_file():
+        return bundled
+    repo = repo_root / "scripts" / "install.sh"
+    if repo.is_file():
+        return repo
+    return None
+
+
+def ensure_dependency(dep: str, interactive: bool = True) -> bool:
+    """Ensure a non-Python dependency is available. Returns True if available."""
+    check = _DEP_CHECKS.get(dep)
+    if check and check():
+        return True
+
+    script = _find_install_script()
+    if script is None:
+        if interactive:
+            desc = _DEP_DESCRIPTIONS.get(dep, dep)
+            print(f"  {desc} is not installed and install.sh was not found.")
+            print(f"  Install {dep} manually and try again.")
+        return False
+
+    if interactive and sys.stdin.isatty():
+        desc = _DEP_DESCRIPTIONS.get(dep, dep)
+        try:
+            reply = input(f"{desc} is not installed. Install now? [Y/n] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        if reply not in ("", "y", "yes"):
+            return False
+
+    result = subprocess.run(
+        ["bash", str(script), "--ensure", dep],
+        env={**os.environ, "IS_INTERACTIVE": "false"},
+    )
+    if result.returncode != 0:
+        return False
+
+    if check:
+        return check()
+    return True

pyproject.toml

@@ -210,7 +210,7 @@ hermes-acp = "acp_adapter.entry:main"
 py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_bootstrap", "hermes_constants", "hermes_state", "hermes_time", "hermes_logging", "utils"]
 
 [tool.setuptools.package-data]
-hermes_cli = ["web_dist/**/*", "tui_dist/**/*"]
+hermes_cli = ["web_dist/**/*", "tui_dist/**/*", "scripts/install.sh"]
 gateway = ["assets/**/*"]
 acp_adapter = ["bootstrap/*.sh", "bootstrap/*.ps1"]
 

tests/hermes_cli/test_dep_ensure.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+from unittest.mock import patch
+
+
+def test_ensure_dependency_skips_when_present():
+    """ensure_dependency is a no-op when the dep is already available."""
+    from hermes_cli.dep_ensure import ensure_dependency
+    with patch("hermes_cli.dep_ensure.shutil") as mock_shutil:
+        mock_shutil.which.return_value = "/usr/bin/node"
+        result = ensure_dependency("node", interactive=False)
+        assert result is True
+
+
+def test_ensure_dependency_returns_false_when_missing_noninteractive():
+    """ensure_dependency returns False for missing dep in non-interactive mode."""
+    from hermes_cli.dep_ensure import ensure_dependency
+    with patch("hermes_cli.dep_ensure.shutil") as mock_shutil:
+        mock_shutil.which.return_value = None
+        with patch("hermes_cli.dep_ensure._find_install_script", return_value=None):
+            result = ensure_dependency("node", interactive=False)
+            assert result is False
+
+
+def test_find_install_script_from_checkout(tmp_path):
+    """_find_install_script finds scripts/install.sh in a git checkout."""
+    from hermes_cli.dep_ensure import _find_install_script
+    scripts_dir = tmp_path / "scripts"
+    scripts_dir.mkdir()
+    (scripts_dir / "install.sh").write_text("#!/bin/bash", encoding="utf-8")
+    result = _find_install_script(package_dir=tmp_path / "hermes_cli", repo_root=tmp_path)
+    assert result is not None
+    assert result.name == "install.sh"
+
+
+def test_find_install_script_from_wheel(tmp_path):
+    """_find_install_script finds bundled install.sh in a wheel."""
+    from hermes_cli.dep_ensure import _find_install_script
+    bundled = tmp_path / "hermes_cli" / "scripts"
+    bundled.mkdir(parents=True)
+    (bundled / "install.sh").write_text("#!/bin/bash", encoding="utf-8")
+    result = _find_install_script(package_dir=tmp_path / "hermes_cli", repo_root=tmp_path)
+    assert result is not None
+    assert result.name == "install.sh"

tools/browser_tool.py

@@ -144,7 +144,8 @@ def _browser_candidate_path_dirs() -> list[str]:
     """Return ordered browser CLI PATH candidates shared by discovery and execution."""
     hermes_home = get_hermes_home()
     hermes_node_bin = str(hermes_home / "node" / "bin")
-    return [hermes_node_bin, *list(_discover_homebrew_node_dirs()), *_SANE_PATH_DIRS]
+    hermes_nm_bin = str(hermes_home / "node_modules" / ".bin")
+    return [hermes_node_bin, hermes_nm_bin, *list(_discover_homebrew_node_dirs()), *_SANE_PATH_DIRS]
 
 
 def _merge_browser_path(existing_path: str = "") -> str: