PR #18159: fix(doctor,browser): centralize tool PATH fallbacks (mise/asdf/nvm/Homebrew)

• Repository: NousResearch/hermes-agent
• Author: y0shua1ee
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/18159

Description (problem / solution / changelog)

Fixes #18158

Summary

hermes doctor and tools/browser_tool independently need a sane PATH for finding Node, npm, agent-browser, and other CLI tools when Hermes is launched from a non-interactive process manager (launchd, systemd user services, dashboards, IDE integrations, cron). In those environments the user's shell init is not sourced, so version-manager shims (mise / asdf / nvm) and Homebrew locations are missing from PATH even when the tools are installed and work fine in an interactive shell.

This PR introduces hermes_cli/path_env.py and wires both call sites through it so they agree on the same fallback set.

What's in the patch

hermes_cli/path_env.py — three small helpers:

• common_tool_path_dirs(existing_only=True) — ordered fallback PATH directories: user-level shims first (~/.local/bin, ~/.local/share/mise/shims, ~/.asdf/shims, ~/.nvm/versions/node/*/bin, ~/.bun/bin), then platform locations (/opt/homebrew/{bin,sbin}, Termux dirs, /usr/local/{bin,sbin}, /usr/{bin,sbin}, /{bin,sbin}). Filters to existing dirs by default.
• merge_common_tool_path(existing_path=None, prepend=False) — merge fallbacks into a PATH string while preserving an explicitly configured PATH by default; opt-in to prepend.
• ensure_common_tool_paths(prepend=False) — update os.environ['PATH'] in place.

Wires it in:

• hermes_cli/doctor.py — call ensure_common_tool_paths() right before the External Tools check so version-manager shims become visible to shutil.which() lookups.
• tools/browser_tool.py — derive _SANE_PATH / _SANE_PATH_DIRS from common_tool_path_dirs(existing_only=False) so doctor and the browser tool agree on the same fallback set.

Behavior change

• Users with mise/asdf/nvm-managed Node now see ✓ Node.js and ✓ agent-browser from hermes doctor even when Hermes is launched from a non-interactive process manager — without needing an external wrapper script around the hermes entrypoint.
• tools/browser_tool picks up the same set, so the browser subprocess sees the same tool directories doctor verified.
• Existing PATH entries keep priority — fallbacks are appended by default, with an opt-in prepend=True for callers that need fallbacks to win (e.g. browser command execution).

Tests

New tests: tests/hermes_cli/test_path_env.py covers helper behaviour: version-manager dirs, Homebrew/Termux statics, dedupe, append vs prepend, and os.environ['PATH'] mutation.

Updated tests:

• tests/hermes_cli/test_doctor.py::test_run_doctor_sets_interactive_env_for_tool_checks — also asserts that doctor invokes the path helper.
• tests/tools/test_browser_homebrew_paths.py::TestSanePath — adds assertions that _SANE_PATH includes mise/asdf shims (still covers Homebrew and standard dirs).

$ python -m pytest tests/hermes_cli/test_path_env.py \
                   tests/hermes_cli/test_doctor.py::test_run_doctor_sets_interactive_env_for_tool_checks \
                   tests/tools/test_browser_homebrew_paths.py -o 'addopts=' -q
29 passed

Risk / scope

Small surface, no breaking changes:

• New helper module with three functions and unit tests
• One new call in hermes_cli/doctor.py (idempotent)
• tools/browser_tool switches from a hand-maintained tuple to the helper output, with the same Homebrew/Termux/FHS coverage plus the new shim dirs
• No new dependencies; everything is stdlib os / pathlib.

Changed files

• hermes_cli/doctor.py (modified, +7/-0)
• hermes_cli/path_env.py (added, +118/-0)
• tests/hermes_cli/test_doctor.py (modified, +6/-0)
• tests/hermes_cli/test_path_env.py (added, +79/-0)
• tests/tools/test_browser_homebrew_paths.py (modified, +6/-0)
• tools/browser_tool.py (modified, +4/-14)