local.py 62 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234
  1. """Local execution environment — spawn-per-call with session snapshot."""
  2. import contextlib
  3. import logging
  4. import ntpath
  5. import os
  6. import platform
  7. import re
  8. import shlex
  9. import shutil
  10. import signal
  11. import subprocess
  12. import sys
  13. import tempfile
  14. import threading
  15. import time
  16. from collections.abc import Mapping
  17. from pathlib import Path
  18. from hermes_constants import get_process_hermes_home
  19. from tools.environments.base import BaseEnvironment
  20. from tools.environments.base_output import _pipe_stdin
  21. from hermes_cli._subprocess_compat import windows_hide_flags
  22. from hermes_cli.process_identity import own_process_groups, release_process_groups
  23. from tools.environments.local_env_policy import (
  24. _ALWAYS_STRIP_FOLDED, _ALWAYS_STRIP_KEYS, _HERMES_PROVIDER_ENV_BLOCKLIST, _HERMES_PROVIDER_ENV_FORCE_PREFIX,
  25. _is_hermes_internal_secret, _is_provider_env_blocklisted, _is_terminal_first_party_env,
  26. _home_adapter_secret_env, _matches_terminal_first_party_prefix, _plugin_terminal_env_strip_keys,
  27. _registered_adapter_secret_env, _registry_adapter_secret_env,
  28. strip_profile_gate_env, strip_supervised_process_identity)
  29. from tools.environments.local_pythonpath import (
  30. _build_hermes_repo_root_aliases, _strip_hermes_owned_pythonpath_and_runtime_markers)
  31. _IS_WINDOWS = platform.system() == "Windows"
  32. logger = logging.getLogger(__name__)
  33. # --- Terminal temp-cache pruning ---
  34. # get_temp_dir() defaults to HERMES_HOME/cache/terminal (real storage, not tmpfs), so
  35. # stale artifacts don't vanish on reboot: the gateway housekeeping loop prunes hourly
  36. # and a once-per-process sweep covers CLI-only installs. Retention is idle-based like
  37. # the scratch dir: an entry goes 24h after the last write anywhere inside it.
  38. TERMINAL_TEMP_MAX_IDLE_HOURS = 24
  39. _terminal_temp_prune_lock = threading.Lock()
  40. _terminal_temp_pruned_once = False
  41. # Background artifacts come in triplets (hermes_bg_<id>.log/.pid/.exit). A live
  42. # server's .pid never changes mtime while its .log does, so age is judged per
  43. # GROUP (newest mtime sharing a stem) to keep pid/exit files of live sessions.
  44. _BG_GROUP_RE = re.compile(r"^(hermes_bg_[A-Za-z0-9_-]+)\.(log|pid|exit)$")
  45. def _default_terminal_temp_dir() -> Path | None:
  46. """Return HERMES_HOME/cache/terminal, or None if unresolvable."""
  47. try:
  48. from hermes_constants import get_hermes_home
  49. return get_hermes_home() / "cache" / "terminal"
  50. except Exception:
  51. return None
  52. def cleanup_terminal_temp_cache(max_age_hours: float = TERMINAL_TEMP_MAX_IDLE_HOURS) -> int:
  53. """Delete session temp artifacts idle for *max_age_hours* (no write anywhere in a
  54. directory's subtree; the kwarg name is the ``cleanup_*_cache`` signature the gateway
  55. housekeeping loop calls every entry with); return count.
  56. Only the managed default dir is pruned — never a user-pointed ``terminal.temp_dir``."""
  57. from hermes_constants_scratch import subtree_touched_since
  58. root = _default_terminal_temp_dir()
  59. if root is None:
  60. return 0
  61. cutoff = time.time() - (max_age_hours * 3600)
  62. try:
  63. entries = list(root.iterdir())
  64. except OSError:
  65. return 0
  66. mtimes: dict[Path, float] = {}
  67. group_newest: dict[str, float] = {}
  68. for f in entries:
  69. try:
  70. mtimes[f] = mt = f.stat().st_mtime
  71. except OSError:
  72. continue
  73. if m := _BG_GROUP_RE.match(f.name):
  74. group_newest[m.group(1)] = max(group_newest.get(m.group(1), 0.0), mt)
  75. def group_touched(stem: str) -> bool:
  76. # Re-stat every member right before each delete: the snapshot above is a candidate
  77. # list, and a session that writes its .log after it must keep the whole group.
  78. for sfx in ("log", "pid", "exit"):
  79. try:
  80. if (root / f"{stem}.{sfx}").stat().st_mtime >= cutoff:
  81. return True
  82. except FileNotFoundError:
  83. continue
  84. except OSError:
  85. return True
  86. return False
  87. removed = 0
  88. for f in mtimes:
  89. m = _BG_GROUP_RE.match(f.name)
  90. if m:
  91. if group_newest[m.group(1)] >= cutoff or group_touched(m.group(1)):
  92. continue
  93. elif subtree_touched_since(f, cutoff):
  94. continue
  95. try:
  96. shutil.rmtree(f, ignore_errors=True) if f.is_dir() else f.unlink()
  97. except OSError:
  98. continue
  99. # rmtree ignores errors: only a path that is really gone counts as removed, and only
  100. # an explicit lstat proves absence (lexists() swallows OSError from lstat).
  101. try:
  102. os.lstat(f)
  103. except FileNotFoundError:
  104. removed += 1
  105. except OSError:
  106. pass
  107. return removed
  108. def _prune_terminal_temp_once() -> None:
  109. """Best-effort prune, at most once per process (CLI-only installs)."""
  110. global _terminal_temp_pruned_once
  111. with _terminal_temp_prune_lock:
  112. if _terminal_temp_pruned_once:
  113. return
  114. _terminal_temp_pruned_once = True
  115. try:
  116. cleanup_terminal_temp_cache()
  117. except Exception as exc:
  118. logger.debug("Terminal temp prune failed: %s", exc)
  119. # --- Windows / MSYS path translation ---
  120. def _msys_to_windows_path(cwd: str) -> str:
  121. """``/c/Users/x`` / ``/cygdrive/c/..`` / ``/mnt/c/..`` -> native ``C:\\Users\\x`` so
  122. ``isdir``/``Popen(cwd=)`` find it. No-op off Windows, for empty input and for
  123. multi-segment POSIX paths like ``/home/x``; idempotent on native paths."""
  124. m = _IS_WINDOWS and cwd and re.match(r'^/(?:(?:cygdrive|mnt)/)?([a-zA-Z])(/.*)?$', cwd)
  125. if not m:
  126. return cwd
  127. tail = (m.group(2) or "").replace('/', '\\')
  128. return f"{m.group(1).upper()}:{tail or chr(92)}" # chr(92) = backslash
  129. def _resolve_local_initial_cwd(cwd: str) -> str:
  130. """Resolve the initial cwd to an absolute host path. A relative ``TERMINAL_CWD``
  131. naming the launch directory would otherwise make the wrapper ``cd`` *inside*
  132. the project; anchor it once so ``Popen(cwd=)`` and the in-shell ``cd`` agree."""
  133. expanded = os.path.expanduser(cwd) if cwd else os.getcwd()
  134. if _IS_WINDOWS:
  135. expanded = _msys_to_windows_path(expanded)
  136. # ntpath explicitly: with _IS_WINDOWS patched on a POSIX host,
  137. # os.path.isabs would reject ``C:\Users\x`` and mangle it below.
  138. if ntpath.isabs(expanded):
  139. return expanded
  140. if os.path.isabs(expanded):
  141. return expanded
  142. candidate = os.path.abspath(expanded)
  143. current = os.getcwd()
  144. # Relative name matching the tail of the current dir: use the current dir.
  145. if not os.path.isdir(candidate):
  146. wanted, have = Path(expanded).parts, Path(current).parts
  147. if wanted and len(wanted) <= len(have) and have[-len(wanted):] == wanted:
  148. return current
  149. return candidate
  150. def _windows_to_msys_path(cwd: str) -> str:
  151. """Native ``C:\\Users\\x`` -> Git Bash ``/c/Users/x`` so ``builtin cd`` resolves
  152. it. No-op off Windows / for non-drive paths."""
  153. m = _IS_WINDOWS and cwd and re.match(r'^([a-zA-Z]):[\\/]*(.*)$', cwd)
  154. if not m:
  155. return cwd
  156. tail = (m.group(2) or "").replace('\\', '/').lstrip('/')
  157. return f"/{m.group(1).lower()}/{tail}"
  158. def _bash_safe_path(path: str) -> str:
  159. """*path* safe to embed in a Git Bash script: ``C:\\Users\\x`` / ``C:/Users/x``
  160. become ``/c/Users/x`` (MSYS argument conversion mangles ``C:/`` forms) and
  161. leftover backslashes are normalized so bash does not eat ``\\U``. No-op off Windows."""
  162. return _windows_to_msys_path(path).replace("\\", "/") if _IS_WINDOWS and path else path
  163. def _quote_bash_path(path: str) -> str:
  164. """Quote *path* for safe interpolation into a Git Bash script on Windows."""
  165. import shlex
  166. return shlex.quote(_bash_safe_path(path))
  167. def _cwd_usable(path: str) -> bool:
  168. """True when *path* is a directory this process can actually chdir into
  169. (``isdir`` alone passes ``/root`` for a non-root user; ``Popen(cwd=)`` then dies)."""
  170. return os.path.isdir(path) and os.access(path, os.X_OK)
  171. def _resolve_safe_cwd(cwd: str) -> str:
  172. """``cwd`` if enterable, else the nearest usable ancestor, else
  173. ``tempfile.gettempdir()``. MSYS paths are normalized first on Windows so a valid
  174. ``pwd -P`` result is not rejected. Lets ``_run_bash`` recover from a deleted or
  175. inaccessible cwd instead of ``Popen`` raising and wedging every later call.
  176. Used by ``_run_bash`` to recover when the configured cwd is gone — most commonly because a previous tool
  177. call deleted its own working directory (issue #17558) — or inaccessible to this user, e.g. ``/root``
  178. leaking from a root-launched CLI session into a non-root gateway's cron jobs (issue #65583). Without
  179. this guard, ``subprocess.Popen(..., cwd=...)`` raises ``FileNotFoundError``/``PermissionError`` before
  180. bash starts, wedging every subsequent terminal call until the gateway restarts.
  181. """
  182. cwd = _msys_to_windows_path(cwd)
  183. if cwd and _cwd_usable(cwd):
  184. return cwd
  185. if cwd and os.path.isdir(cwd):
  186. logger.warning(
  187. "Configured terminal cwd %r exists but is not accessible to "
  188. "this user (uid=%s) — falling back to the nearest usable "
  189. "directory. If this is a gateway/cron process, check for "
  190. "root-owned paths leaking into terminal.cwd / TERMINAL_CWD "
  191. "(#65583).",
  192. cwd, getattr(os, "getuid", lambda: "?")())
  193. parent = os.path.dirname(cwd) if cwd else ""
  194. while parent and not _cwd_usable(parent):
  195. next_parent = os.path.dirname(parent)
  196. if next_parent == parent:
  197. return tempfile.gettempdir() # filesystem root itself is unusable
  198. parent = next_parent
  199. return parent or tempfile.gettempdir()
  200. # --- Child-process environment construction ---
  201. def _apply_profile_home(env: dict) -> None:
  202. """Bridge the context-local HERMES_HOME override, then the subprocess HOME contract."""
  203. from hermes_constants import apply_subprocess_home_env, get_hermes_home_override
  204. try:
  205. if value := get_hermes_home_override():
  206. env["HERMES_HOME"] = value
  207. except Exception:
  208. pass
  209. apply_subprocess_home_env(env)
  210. def _inject_session_context_env(env: dict) -> None:
  211. """Bridge gateway session ContextVars (HERMES_SESSION_*) into a child env.
  212. Cross-session leak guard: the vars' last-writer-wins ``os.environ`` mirror may
  213. belong to another turn on a concurrent multi-session host, so once the session
  214. context is engaged ContextVars are authoritative — a bound value (incl. "") wins
  215. and an _UNSET var is STRIPPED, not inherited. An unengaged CLI keeps the mirror."""
  216. try:
  217. from gateway.session_context import _UNSET, _VAR_MAP, session_context_engaged
  218. except Exception:
  219. return
  220. _engaged = session_context_engaged()
  221. for var_name, var in _VAR_MAP.items():
  222. value = var.get()
  223. if value is not _UNSET:
  224. env[var_name] = "" if value is None else str(value)
  225. elif _engaged:
  226. env.pop(var_name, None)
  227. def _filter_secret_env(
  228. items: Mapping[str, str], out: dict, *, unwrap_force: bool,
  229. plugin_strip: frozenset = frozenset()) -> None:
  230. """Copy *items* into *out*, dropping Hermes-managed secrets. ``_HERMES_FORCE_<NAME>``
  231. unwraps to ``NAME`` when ``unwrap_force`` (caller extras / terminal env), else is
  232. dropped. Blocklisted names survive only via env_passthrough registration or as
  233. context-entitled first-party ``BUZZ_*`` vars; the latter are used directly, never
  234. scope-resolved (UnscopedSecretError under multiplex)."""
  235. try:
  236. from tools.env_passthrough import is_env_passthrough, resolve_passthrough_value
  237. except Exception:
  238. is_env_passthrough, resolve_passthrough_value = (lambda _: False), (lambda _n, fb: fb)
  239. plugin_strip_folded = frozenset(k.upper() for k in plugin_strip)
  240. registered = _registered_adapter_secret_env()
  241. for key, value in items.items():
  242. if key.startswith(_HERMES_PROVIDER_ENV_FORCE_PREFIX):
  243. if not unwrap_force:
  244. continue
  245. key = key[len(_HERMES_PROVIDER_ENV_FORCE_PREFIX):]
  246. if not _is_hermes_internal_secret(key):
  247. out[key] = value
  248. continue
  249. if _is_hermes_internal_secret(key) or key.upper() in plugin_strip_folded:
  250. continue
  251. first_party = _is_terminal_first_party_env(key)
  252. passthrough = is_env_passthrough(key)
  253. if _is_provider_env_blocklisted(key, registered) and not (passthrough or first_party):
  254. continue
  255. if passthrough and not first_party:
  256. value = resolve_passthrough_value(key, value)
  257. if value is not None:
  258. out[key] = value
  259. def _finalize_child_env(env: dict) -> dict:
  260. """Guards shared by every spawn surface: profile-home propagation, session-context
  261. bridging, Hermes-owned PYTHONPATH + venv-marker strip, MSYS defaults, delegate_task
  262. Kanban scrub. Returns the (possibly new) dict."""
  263. _apply_profile_home(env)
  264. _inject_session_context_env(env)
  265. _strip_hermes_owned_pythonpath_and_runtime_markers(env)
  266. strip_supervised_process_identity(env)
  267. _apply_windows_msys_bash_env_defaults(env)
  268. from agent.delegation_context import delegated_child_subprocess_env
  269. return delegated_child_subprocess_env(env)
  270. def _scrubbed_env(parts, plugin_strip: frozenset, fix_path) -> dict:
  271. """Filter each ``(items, unwrap_force)`` in *parts* into one env, rewrite PATH via
  272. *fix_path* (always prepending the hermes install dir so bare ``hermes`` resolves
  273. for children of a systemd/cron-launched gateway), then apply the shared guards."""
  274. out: dict[str, str] = {}
  275. for items, unwrap_force in parts:
  276. _filter_secret_env(items, out, unwrap_force=unwrap_force, plugin_strip=plugin_strip)
  277. # Declared names the bound profile scope holds but the process env never did (a routed
  278. # profile's own .env / sources) — the filter above can only see names already present.
  279. # Unguarded on purpose: a scope/config failure here must be loud, not silently drop the
  280. # declared secret again (#114209); _scrub_child_env calls it the same way.
  281. from tools.env_passthrough import scoped_passthrough_additions
  282. out.update((k, v) for k, v in scoped_passthrough_additions(out).items() if k not in plugin_strip)
  283. path_key = _path_env_key(out)
  284. # Keep bare ``hermes`` invocations available to child jobs even when the gateway was launched by a
  285. # service manager or cron without the console script's directory on PATH. The terminal environment
  286. # already applies this invariant; Cron scripts use this sanitizer directly (#92998).
  287. if path_key is not None:
  288. out[path_key] = _prepend_hermes_bin_dir(fix_path(out.get(path_key, "")))
  289. return _finalize_child_env(out)
  290. def _sanitize_subprocess_env(base_env: dict | None, extra_env: dict | None = None) -> dict:
  291. """Filter Hermes-managed secrets from a subprocess environment (background/PTY
  292. spawn path, search workers, computer-use driver, user-script runners)."""
  293. return _scrubbed_env([(base_env or {}, False), (extra_env or {}, True)],
  294. _plugin_terminal_env_strip_keys(), lambda p: p)
  295. def _terminal_env(env: dict) -> dict:
  296. """*env* with the user's tools first on PATH (``_user_tools_first``), for background commands."""
  297. path_key = _path_env_key(env)
  298. if path_key is not None:
  299. env[path_key] = _user_tools_first(env[path_key])
  300. return env
  301. def hermes_subprocess_env(
  302. *, inherit_credentials: bool = False, base_env: dict[str, str] | None = None
  303. ) -> dict[str, str]:
  304. """Sanitize a non-terminal child's environment (no skill passthrough).
  305. Bot, GitHub and remote-compute secrets never pass through; provider/tool
  306. credentials pass only with ``inherit_credentials=True`` for children that
  307. need them. Callers needing one other secret should add only that key back.
  308. ``base_env`` lets an already curated environment use the same policy.
  309. Terminal and execute_code spawns use the skill-aware sanitizer instead.
  310. """
  311. env = dict(base_env) if base_env is not None else os.environ.copy()
  312. env = _scrub_credentials(env, inherit_credentials=inherit_credentials)
  313. env.setdefault("PYTHONUTF8", "1") # Windows UTF-8 safety for spawned processes
  314. return _finalize_child_env(env)
  315. def _scrub_credentials(env: dict, *, inherit_credentials: bool) -> dict:
  316. """Tier 1 (always) and, unless ``inherit_credentials``, Tier 2 provider/tool credentials, in place."""
  317. # Credential names fold to uppercase for membership: on Windows the env block
  318. # itself is case-insensitive, so a lowercase-stored ``gh_token`` IS GH_TOKEN.
  319. home_secrets = _home_adapter_secret_env() # one manifest stamp per scrub
  320. strip_folded = _ALWAYS_STRIP_FOLDED | {k.upper() for k in _plugin_terminal_env_strip_keys()} | home_secrets
  321. registered = _registry_adapter_secret_env() # home_secrets already strip above
  322. for key in list(env):
  323. if (key.upper() in strip_folded
  324. or (not inherit_credentials and _is_provider_env_blocklisted(key, registered))
  325. or key.startswith(_HERMES_PROVIDER_ENV_FORCE_PREFIX)
  326. or _is_hermes_internal_secret(key)):
  327. del env[key]
  328. return env
  329. def build_subprocess_env(
  330. base: Mapping[str, str] | None = None, *, inherit_profile_home: bool = True,
  331. scrub_secrets: bool = True, extra: Mapping[str, str] | None = None,
  332. strip_launch_profile: bool = False) -> dict[str, str]:
  333. """Single factory for child-process envs. ``base=None`` snapshots ``os.environ``.
  334. ``scrub_secrets=True`` -> :func:`_sanitize_subprocess_env` (profile home inherent,
  335. ``inherit_profile_home`` ignored). ``scrub_secrets=False`` keeps the base's secrets
  336. (git credential flows, ``bws``/``op``); ``inherit_profile_home``
  337. bridges HERMES_HOME + HOME and ``extra`` is applied last so caller overrides win. Both modes
  338. drop the supervised process's own identity (:func:`strip_supervised_process_identity`).
  339. ``strip_launch_profile`` drops the LAUNCH profile's ``.env`` residue from the base first
  340. (:func:`strip_launch_profile_env`; a no-op unless a routed home is active) so a child that
  341. acts for a routed profile sees only that profile's declared names, never the launch profile's.
  342. Under multiplex semantics it then overlays the bound secret scope (the routed profile's own
  343. ``.env`` + source values, which never enter ``os.environ``) and re-applies the managed keys,
  344. all BEFORE the scrub, so those values pass the same scrub / passthrough rules as any other."""
  345. env: dict[str, str] = dict(base) if base is not None else os.environ.copy()
  346. if strip_launch_profile:
  347. strip_launch_profile_env(env)
  348. from agent.secret_scope import current_secret_scope, is_multiplex_active
  349. if is_multiplex_active():
  350. # Single-profile: the scope IS os.environ, so overlaying it would only re-sanitize
  351. # values the child already inherits byte-identical.
  352. env.update(current_secret_scope() or {})
  353. # Administrator-managed values keep their precedence over the routed profile's own .env,
  354. # exactly as they do in the launch process (``_apply_managed_env`` applies them last).
  355. restore_managed_env(env)
  356. if scrub_secrets:
  357. return _sanitize_subprocess_env(env, dict(extra) if extra else None)
  358. if inherit_profile_home:
  359. _apply_profile_home(env)
  360. if extra:
  361. env.update(extra)
  362. strip_supervised_process_identity(env)
  363. from agent.delegation_context import delegated_child_subprocess_env
  364. return delegated_child_subprocess_env(env)
  365. def served_profile_child_env(
  366. base: Mapping[str, str] | None = None, *, target_home: str | Path | None = None,
  367. inherit_credentials: bool = False,
  368. ) -> dict[str, str]:
  369. """Child env for a process that acts FOR the active (possibly served) profile: ``hermes -p X``
  370. workers, ``key_cmd`` helpers, browser drivers. The process env is the LAUNCH profile's. When the
  371. target is a ROUTED home (not the launch profile's — under multiplex or a Desktop/dashboard backend
  372. serving ``?profile=`` with the flag off) the launch ``.env`` residue and bridged ``TERMINAL_*`` are
  373. dropped (``strip_launch_profile_env``) AND every provider/tool credential is scrubbed from the base
  374. regardless of provenance: a key systemd / Compose / the shell injected into the launch process was
  375. never recorded in ``.env`` or a source snapshot, so a name-based strip cannot see it and the target
  376. overlay cannot remove it. ``inherit_credentials=True`` is for children that legitimately run with
  377. the profile's credentials (they run the agent or mint its token): the target profile's own secrets
  378. (its ``.env`` + hydrated sources, what a standalone ``hermes -p X`` loads itself) are overlaid — never
  379. a sibling profile's. Under multiplex with neither a target nor a bound scope the call raises
  380. (``get_secret``'s fail-closed contract): minting with the launch environ would sign in as the wrong
  381. profile. ``False`` keeps the provider scrub; the caller re-adds the few keys the child needs via
  382. ``get_secret``. ``target_home`` defaults to the active override; ``base`` replaces the
  383. ``hermes_subprocess_env`` snapshot."""
  384. from agent.secret_scope import (
  385. UnscopedSecretError, build_profile_secret_scope, current_secret_scope, is_multiplex_active)
  386. from hermes_constants import apply_scratch_tmp_env, get_hermes_home_override
  387. env = dict(base) if base is not None else hermes_subprocess_env(inherit_credentials=inherit_credentials)
  388. target = str(target_home or get_hermes_home_override() or "")
  389. if target:
  390. env["HERMES_HOME"] = target
  391. apply_scratch_tmp_env(env) # TMPDIR follows the served home, like HOME does
  392. if _is_routed_home(target):
  393. strip_launch_profile_env(env, target)
  394. _scrub_credentials(env, inherit_credentials=False)
  395. if inherit_credentials:
  396. if target:
  397. secrets = build_profile_secret_scope(Path(target))
  398. else:
  399. secrets = current_secret_scope()
  400. if secrets is None and is_multiplex_active():
  401. raise UnscopedSecretError(
  402. "", "served_profile_child_env(inherit_credentials=True) called with no target home and "
  403. "no profile secret scope bound while multiplexing is on; the child would inherit the "
  404. "launch profile's credentials. Bind the profile scope (or pass target_home) at the spawn site.")
  405. env.update((k, v) for k, v in (secrets or {}).items() if v is not None)
  406. return env
  407. def host_gateway_child_env(
  408. base: Mapping[str, str] | None = None,
  409. ) -> dict[str, str]:
  410. """Child env for the host gateway: the default profile's secrets, never the launcher's.
  411. ``served_profile_child_env`` — not ``os.environ.copy()``. A profile-scoped parent
  412. (desktop, fleet restart, detached watcher) must not donate its dotenv to the
  413. multiplexer that owns the primary adapter map.
  414. """
  415. from hermes_constants import get_default_hermes_root
  416. return served_profile_child_env(
  417. base=base, target_home=get_default_hermes_root(), inherit_credentials=True,
  418. )
  419. def _is_routed_home(target_home: str | Path) -> bool:
  420. """True when ``target_home`` is not the process's own (launch) home.
  421. Same launch-home identity as ``agent.secret_scope.serves_routed_profile()``: under a host that
  422. mirrors the served profile into ``HERMES_HOME``, the live env var names the served home and the
  423. launch residue would never be stripped from that profile's child env."""
  424. from hermes_constants import get_routing_process_hermes_home
  425. try:
  426. return Path(target_home).resolve() != get_routing_process_hermes_home().resolve()
  427. except OSError:
  428. return True
  429. def strip_launch_profile_env(env: dict, target_home: str | Path | None = None) -> dict:
  430. """Drop the LAUNCH profile's residue from a child env built for another served profile.
  431. ``os.environ`` holds the default profile's ``.env`` and its bridged ``TERMINAL_*`` settings;
  432. the secret scrub removes credentials but not settings (``HERMES_MODEL``, ``TERMINAL_ENV``,
  433. ``HERMES_LANGUAGE``...), so a standalone ``hermes -p X`` worker and a served one saw different
  434. envs. The child re-loads X's own ``.env`` and bridges X's config itself. ``target_home``
  435. defaults to the active home override; no-op when there is no target or the target IS the
  436. launch profile. The authority test is "does this task serve a routed home", not "is the
  437. gateway-wide multiplex flag on": the Desktop/dashboard backend serves ``?profile=B`` by
  438. installing a HERMES_HOME override without that flag."""
  439. from agent.secret_scope import _is_global_env, load_env_file
  440. from hermes_constants import get_hermes_home_override, get_routing_process_hermes_home
  441. target = target_home or get_hermes_home_override()
  442. if not target or not _is_routed_home(target):
  443. return env
  444. launch_home = get_routing_process_hermes_home()
  445. from hermes_cli.config import TERMINAL_CONFIG_ENV_MAP
  446. # Folded strip: on Windows the env block is case-insensitive, so residue
  447. # stored under a variant casing is the same variable and must go too. The
  448. # selection folds the same way so a lowercase ``path`` in .env is still
  449. # recognized as a global name and left alone.
  450. # Current file AND every key any dotenv load put into os.environ this process lifetime: a key
  451. # removed or renamed in the launch .env after boot is still in os.environ with the old value, and
  452. # a re-parse of the file alone no longer names it (#107695 review). External secret sources
  453. # (vault, 1Password, ...) write their names into the same shared os.environ, and a name the
  454. # LAUNCH profile's source supplied is not the target profile's to see; the caller's scope
  455. # overlay puts back exactly the ones the target's own sources supply. The administrator-managed
  456. # .env is NOT residue: its values are policy for every profile (``_apply_managed_env`` applies
  457. # it last, with override, so it beats the user's own .env) — leave them in place. Neither is
  458. # the config backend's deployment (which backend, which plane, which instance): it is the
  459. # instance's, and a child without it reads the target profile's config from another backend.
  460. from hermes_cli.config_backend import deployment_env_names
  461. from hermes_cli.env_loader import launch_dotenv_keys, managed_dotenv_keys, source_supplied_names
  462. managed_names = {key.upper() for key in managed_dotenv_keys()} | set(deployment_env_names())
  463. residue_names = {
  464. key.upper() for key in
  465. set(load_env_file(launch_home / ".env")) | set(launch_dotenv_keys())
  466. | set(TERMINAL_CONFIG_ENV_MAP.values()) | set(source_supplied_names())
  467. if not _is_global_env(key.upper()) or key.upper().startswith("TERMINAL_")} - managed_names
  468. for key in [k for k in env if k.upper() in residue_names]:
  469. del env[key]
  470. # Authorization gates are the one residue a name list cannot see: a unit-file ``Environment=``
  471. # or an operator export never appears in the launch ``.env``, the secret scrub ignores
  472. # non-credentials, and the target's own ``.env`` rarely defines the key to overwrite it (#113270).
  473. return strip_profile_gate_env(env)
  474. def restore_managed_env(env: dict) -> dict:
  475. """Re-apply the administrator-managed ``.env`` values over *env* — call AFTER a routed profile's scope
  476. has been overlaid. ``_apply_managed_env`` gives those keys precedence over the user's own ``.env`` in
  477. the launch process; a routed child must see the same precedence, or the routed user's value for a
  478. managed key (``ORG_POLICY_FLAG=user-value``) silently wins over policy."""
  479. from hermes_cli.env_loader import managed_dotenv_keys
  480. for key in managed_dotenv_keys():
  481. if key in os.environ:
  482. env[key] = os.environ[key]
  483. return env
  484. # --- Shell discovery ---
  485. def _find_bash() -> str:
  486. """Resolve the shell Hermes runs commands with. Owned by pm (the store
  487. is the authority on bundled bash); this is a thin wrapper over
  488. pm.shell() for callers that need a bash binary."""
  489. import pm.shell
  490. bash = pm.shell.bash()
  491. if bash:
  492. return bash
  493. raise RuntimeError(
  494. "No shell found. Hermes needs bash (Git for Windows on Windows). "
  495. "Run `hermes pm install` or reinstall the bundle."
  496. )
  497. _git_bash_bin_dirs_cache: list[str] | None = None
  498. def _git_bash_bin_dirs() -> list[str]:
  499. """Git Bash's coreutils dirs in ``/etc/profile`` order (mingw first so coreutils
  500. beat System32 lookalikes); ``[]`` off Windows. A non-login ``bash -c`` (fallback
  501. when ``bash -l`` is broken) never sources ``/etc/profile``, so without these
  502. ``cat``/``mktemp``/``mv`` are missing and commands exit 127."""
  503. global _git_bash_bin_dirs_cache
  504. if _git_bash_bin_dirs_cache is None:
  505. _git_bash_bin_dirs_cache = _compute_git_bash_bin_dirs() if _IS_WINDOWS else []
  506. return _git_bash_bin_dirs_cache
  507. def _compute_git_bash_bin_dirs() -> list[str]:
  508. try:
  509. bash = _find_bash()
  510. except Exception:
  511. return []
  512. parent = os.path.dirname(os.path.dirname(bash)) # bash in <root>\bin or <root>\usr\bin (MinGit)
  513. root = os.path.dirname(parent) if os.path.basename(parent).lower() == "usr" else parent
  514. subs = ("mingw64/bin", "mingw32/bin", "usr/local/bin", "usr/bin", "bin")
  515. dirs = (os.path.join(root, *sub.split("/")) for sub in subs)
  516. return list(dict.fromkeys(d for d in dirs if os.path.isdir(d)))
  517. def _prepend_missing_path_entries(existing_path: str, dirs: list[str]) -> str:
  518. """Prepend *dirs* missing from *existing_path* (``os.pathsep``); an already-listed
  519. dir keeps its position; unchanged input when nothing is missing."""
  520. entries = [e for e in existing_path.split(os.pathsep) if e]
  521. missing = [d for d in dirs if d not in entries]
  522. return os.pathsep.join([*missing, *entries]) if missing else existing_path
  523. def _user_tools_first(existing_path: str) -> str:
  524. """*existing_path* with the user's tools before Hermes's (``pm.user_facing``) and, on
  525. Windows, Git Bash's dirs first. They go first even when already listed: they are store
  526. dirs that now sit behind the user's entries, and a non-login ``bash -c`` needs its
  527. coreutils ahead of System32's lookalikes."""
  528. from pm.user_facing import user_facing_path
  529. path = user_facing_path(existing_path)
  530. bash_dirs = _git_bash_bin_dirs()
  531. keys = {os.path.normcase(d) for d in bash_dirs}
  532. rest = [p for p in path.split(os.pathsep) if p and os.path.normcase(p) not in keys]
  533. return os.pathsep.join([*bash_dirs, *rest]) if bash_dirs else path
  534. # POSIX-sh-family shells that understand spawn_local's ``[shell, "-lic", "set +m; …"]``
  535. # invocation; fish, csh/tcsh, nushell, elvish, xonsh would error, so _find_shell
  536. # falls back to bash for them.
  537. # (#42203)
  538. _SPAWN_COMPATIBLE_SHELLS = frozenset({"bash", "zsh", "sh", "dash", "ksh", "mksh"})
  539. def _find_shell() -> str:
  540. """User's login shell for background spawning: ``$SHELL`` on POSIX when it is an
  541. executable sh-family shell, else ``_find_bash``. macOS's system bash 3.2 under
  542. ``-l`` with stdin ``/dev/null`` sources ``~/.bash_profile``, which often
  543. ``exec /bin/zsh -l`` and drops ``-c`` — the command silently never runs."""
  544. user_shell = "" if _IS_WINDOWS else os.environ.get("SHELL")
  545. if (user_shell and os.path.isfile(user_shell) and os.access(user_shell, os.X_OK)
  546. and Path(user_shell).name in _SPAWN_COMPATIBLE_SHELLS):
  547. return user_shell
  548. return _find_bash()
  549. # --- PATH completion for the terminal subshell ---
  550. # Standard PATH entries for environments with minimal PATH.
  551. _SANE_PATH = ("/opt/homebrew/bin:/opt/homebrew/sbin:"
  552. "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin")
  553. # Cached directory containing the ``hermes`` console-script.
  554. # ``_SENTINEL`` distinguishes "not resolved yet" from a resolved ``None``.
  555. _SENTINEL = object()
  556. _HERMES_BIN_DIR: str | None | object = _SENTINEL
  557. # True when the cached dir is a sealed payload's own launcher dir (see below).
  558. _HERMES_BIN_DIR_IS_PAYLOAD = False
  559. def _resolve_hermes_bin_dir() -> str | None:
  560. """Directory holding the ``hermes`` console-script, or None (cached). A gateway
  561. launched by systemd/cron/a desktop launcher lacks the install dir on PATH and bare
  562. ``hermes`` exits 127. Order: a sealed payload's own launcher dir; ``which``; absolute
  563. ``sys.argv[0]`` naming a real hermes executable; ``sys.executable``'s dir if it holds
  564. the shim."""
  565. global _HERMES_BIN_DIR, _HERMES_BIN_DIR_IS_PAYLOAD
  566. if _HERMES_BIN_DIR is not _SENTINEL:
  567. return _HERMES_BIN_DIR # type: ignore[return-value]
  568. from pm.environments import payload_command_dir
  569. # A payload's venv also holds a `hermes`, but on Windows its redirector names the
  570. # build machine's interpreter, so PATH order must not decide which copy children get.
  571. payload_dir = payload_command_dir(Path(__file__).resolve().parents[2])
  572. if payload_dir is not None and payload_dir.is_dir():
  573. _HERMES_BIN_DIR, _HERMES_BIN_DIR_IS_PAYLOAD = str(payload_dir), True
  574. return _HERMES_BIN_DIR
  575. which = shutil.which("hermes")
  576. argv0 = sys.argv[0] if sys.argv else ""
  577. base = os.path.basename(argv0).lower()
  578. exe_dir = os.path.dirname(sys.executable) if sys.executable else ""
  579. shim = "hermes.exe" if _IS_WINDOWS else "hermes"
  580. if which:
  581. candidate = os.path.dirname(which)
  582. elif (os.path.isabs(argv0) and (base == "hermes" or base.startswith("hermes."))
  583. and os.path.isfile(argv0)):
  584. candidate = os.path.dirname(argv0)
  585. else:
  586. candidate = exe_dir if exe_dir and os.path.isfile(os.path.join(exe_dir, shim)) else None
  587. _HERMES_BIN_DIR = candidate if candidate and os.path.isdir(candidate) else None
  588. _HERMES_BIN_DIR_IS_PAYLOAD = False
  589. return _HERMES_BIN_DIR
  590. def _prepend_hermes_bin_dir(existing_path: str) -> str:
  591. """Prepend the hermes install dir to ``existing_path`` if missing. A sealed payload's
  592. launcher dir moves to the front even when already listed: a login PATH can list
  593. another install's ``hermes`` ahead of it."""
  594. bin_dir = _resolve_hermes_bin_dir()
  595. if bin_dir and _HERMES_BIN_DIR_IS_PAYLOAD:
  596. rest = [entry for entry in existing_path.split(os.pathsep) if entry and entry != bin_dir]
  597. return os.pathsep.join([bin_dir, *rest])
  598. return _prepend_missing_path_entries(existing_path, [bin_dir] if bin_dir else [])
  599. def _managed_runtime_path_entries() -> list[str]:
  600. """Return existing Hermes-managed runtime dirs for the terminal subshell PATH.
  601. The terminal tool spawns a subshell whose PATH is the agent process's PATH
  602. plus ``_SANE_PATH``. Neither carries the runtimes Hermes installs for
  603. itself, so on a machine where Hermes provisioned its own toolchain a
  604. command the agent runs resolves a system copy instead — or nothing at all:
  605. - the pm store's node/npm entries — installed to satisfy the desktop
  606. toolchain; the agent's shell deserves the same.
  607. - ``$HERMES_HOME/bin`` — the managed ``uv``. ``install.sh`` writes it there
  608. and nothing has ever put that directory on PATH, so an install whose only
  609. uv is the managed one looks uv-less to both the agent and the model.
  610. Resolved per call rather than cached in a module constant because
  611. ``get_hermes_home()`` is profile-scoped and a managed runtime can appear
  612. mid-process (a lazy pm install, a first browser install).
  613. """
  614. try:
  615. import pm
  616. from hermes_constants import get_hermes_home
  617. env = pm.env_for("npm", base_env={"PATH": ""})
  618. managed = [Path(d) for d in env.get("PATH", "").split(os.pathsep) if d]
  619. candidates = [*managed, get_hermes_home() / "bin"]
  620. return [str(d) for d in candidates if d.is_dir()]
  621. except Exception:
  622. return []
  623. def _user_local_bin_entries() -> list[str]:
  624. """``~/.local/bin`` when it exists — the pip --user / pipx / uv-tool install
  625. target. A backend launched by a non-interactive SSH session, systemd or a GUI
  626. launcher inherits a PATH without it (only the login shell adds it), so CLIs
  627. installed there were ``command not found`` from the terminal tool (#111778)."""
  628. local_bin = Path.home() / ".local" / "bin"
  629. try:
  630. return [str(local_bin)] if local_bin.is_dir() else []
  631. except OSError:
  632. # HOME can point at a directory this process may not traverse (CI runs
  633. # with HOME=/root as an unprivileged user); such a home has no usable
  634. # ~/.local/bin either.
  635. return []
  636. def _append_missing_sane_path_entries(existing_path: str) -> str:
  637. """Normalised POSIX PATH with missing sane entries appended: empty entries
  638. dropped (shells read them as cwd), duplicates collapsed (first wins), then
  639. missing ``_SANE_PATH`` / managed-runtime / ``~/.local/bin`` dirs appended so
  640. user entries keep precedence. Windows is a no-op passthrough (native ``;``
  641. PATH untouched)."""
  642. if _IS_WINDOWS:
  643. return existing_path
  644. # dict preserves first-occurrence order; empty entries dropped.
  645. ordered = dict.fromkeys(entry for entry in existing_path.split(":") if entry)
  646. ordered.update(dict.fromkeys([*_SANE_PATH.split(":"), *_managed_runtime_path_entries(),
  647. *_user_local_bin_entries()]))
  648. return ":".join(ordered)
  649. def _apply_windows_msys_bash_env_defaults(env: dict) -> None:
  650. """Disable MSYS argument path conversion (``/FO`` -> ``C:/.../git/FO`` breaks
  651. tasklist/schtasks/wmic/``cmd /c``). Git for Windows honors ``MSYS_NO_PATHCONV``;
  652. MSYS2/Cygwin bash honor ``MSYS2_ARG_CONV_EXCL`` — set both; users can override.
  653. Git Bash rewrites arguments that look like Unix paths (``/FO``, ``/TN``, ``/Create``) into
  654. ``C:/.../git/FO``-style paths, which breaks native Windows commands such as ``tasklist``, ``schtasks``,
  655. and ``wmic``. Hermes runs terminal commands through bash on Windows, so set the standard MSYS opt-out by
  656. default. Refs #56700.
  657. MSYS2-proper and Cygwin bash (which ``_find_bash`` can still return via the final ``shutil.which``
  658. fallback) ignore it and honor ``MSYS2_ARG_CONV_EXCL`` instead, so set both. ``*`` disables all argv
  659. conversion — the semantic equivalent of ``MSYS_NO_PATHCONV=1``. Also fixes ``cmd /c`` mangling (#56147).
  660. """
  661. if _IS_WINDOWS:
  662. env.setdefault("MSYS_NO_PATHCONV", "1")
  663. env.setdefault("MSYS2_ARG_CONV_EXCL", "*")
  664. def _path_env_key(run_env: dict) -> str | None:
  665. """PATH env key to update without altering Windows casing (``Path`` vs ``PATH``);
  666. None when a Windows env has no PATH key at all."""
  667. return next((k for k in run_env if k.upper() == "PATH"), None) if _IS_WINDOWS else "PATH"
  668. def _make_run_env(env: dict) -> dict:
  669. """Build a run environment with a sane PATH and provider-var stripping. The process env is
  670. the LAUNCH profile's; under a routed home override its ``.env`` residue is dropped first
  671. (``strip_launch_profile_env``, a no-op for the launch profile) so the backend's own ``env``
  672. and the served profile's declared passthrough names are what the child sees. A local session's
  673. client toolchain (PATH, venv, nvm/pyenv/conda: ``agent.session_client_env``) replaces the daemon's
  674. beneath the backend's own ``env``."""
  675. from agent.session_client_env import toolchain_environ
  676. run_env = _scrubbed_env(
  677. [(dict(toolchain_environ(strip_launch_profile_env(os.environ.copy())) | env), True)],
  678. frozenset(),
  679. lambda p: _user_tools_first(_append_missing_sane_path_entries(p)),
  680. )
  681. # While this profile's Bot Desktop is running, its DISPLAY/XAUTHORITY/DBUS ride along so GUI
  682. # apps the agent launches from the terminal open on the Bot Screen the user is watching, not
  683. # on the user's own seat (#125830). published_env() is the pure read (no activity stamp — a
  684. # plain ``ls`` must not keep the screen alive past idle_stop_minutes), and it wins over the
  685. # login snapshot's seat DISPLAY; a user who wants their own seat uses an inline
  686. # ``DISPLAY=:0 cmd`` prefix, which bash applies after this env. Empty (or module missing) →
  687. # the seat env passes through untouched.
  688. try:
  689. from tools.bot_desktop.runtime import published_env
  690. published = published_env()
  691. except Exception:
  692. published = {}
  693. if published:
  694. run_env.update(published)
  695. run_env.pop("WAYLAND_DISPLAY", None) # X11 desktop; a leaked Wayland socket flips GTK/Chromium backends
  696. return run_env
  697. # --- Hermes venv / repo-root detection (module-level, computed once) ---
  698. # Owned here; read lazily by tools.environments.local_pythonpath (tests patch here).
  699. # The Electron app prepends the repo root to PYTHONPATH so the backend can ``import
  700. # tools``; other subprocesses must not inherit it. Aliases: launchers may emit other
  701. # spellings — the Windows gateway launcher renders Hermes-owned paths under the
  702. # configured HERMES_HOME spelling (possibly a junction to another drive).
  703. _hermes_repo_root: Path = Path(__file__).resolve().parents[2]
  704. _hermes_repo_root_aliases: tuple[Path, ...] = _build_hermes_repo_root_aliases(
  705. _hermes_repo_root, Path(__file__).absolute().parents[2], get_process_hermes_home())
  706. _in_venv: bool = (getattr(sys, "base_prefix", sys.prefix) != sys.prefix
  707. or hasattr(sys, "real_prefix")) # real_prefix: virtualenv<20
  708. _hermes_site_packages: list[Path] | None = None # lazily cached by local_pythonpath
  709. # --- Login-shell init files ---
  710. def _read_terminal_shell_init_config() -> tuple[list[str], bool]:
  711. """(shell_init_files, auto_source_bashrc) from config.yaml; defaults on any
  712. failure so terminal execution never breaks."""
  713. try:
  714. from hermes_cli.config import load_config
  715. terminal_cfg = (load_config() or {}).get("terminal") or {}
  716. files = terminal_cfg.get("shell_init_files") or []
  717. if not isinstance(files, list):
  718. files = []
  719. return [str(f) for f in files if f], bool(terminal_cfg.get("auto_source_bashrc", True))
  720. except Exception:
  721. return [], True
  722. def _resolve_shell_init_files() -> list[str]:
  723. """Files to source before the login-shell snapshot (``~``/``${VAR}`` expanded,
  724. missing dropped). ``auto_source_bashrc`` applies only without an explicit list:
  725. ~/.profile and ~/.bash_profile first (no interactivity guard; where
  726. n/nvm/asdf/pyenv add PATH), ~/.bashrc last (Debian's returns early when
  727. non-interactive, but guard-less bashrcs keep working)."""
  728. explicit, auto_bashrc = _read_terminal_shell_init_config()
  729. candidates = explicit or (["~/.profile", "~/.bash_profile", "~/.bashrc"]
  730. if auto_bashrc and not _IS_WINDOWS else [])
  731. resolved: list[str] = []
  732. for raw in candidates:
  733. try:
  734. path = os.path.expandvars(os.path.expanduser(raw))
  735. if path and os.path.isfile(path):
  736. resolved.append(path)
  737. except Exception:
  738. continue
  739. return resolved
  740. def _prepend_shell_init(cmd_string: str, files: list[str]) -> str:
  741. """Prepend guarded, silent ``source <file>`` lines: ``set +e`` keeps going on
  742. errors, ``2>/dev/null`` hides noisy prompts, ``|| true`` neutralises the status."""
  743. if not files:
  744. return cmd_string
  745. safe = [p.replace("'", "'\\''") for p in files]
  746. prelude = ["set +e", *(f"[ -r '{p}' ] && . '{p}' 2>/dev/null || true" for p in safe)]
  747. return "\n".join(prelude) + "\n" + cmd_string
  748. def _append_dropped_path_entries(cmd_string: str, parent_path: str) -> str:
  749. """Prepend a line that re-appends *parent_path* dirs the login profile dropped.
  750. A login profile can reset PATH outright (Debian's ``/etc/profile``, so every
  751. Debian/Ubuntu image and host), and the snapshot's ``export -p`` then pins the reset
  752. PATH over the spawn env for every later command: in the Docker image that loses
  753. ``/opt/hermes/bin`` and bare ``hermes`` exits 127 (#56634). Dropped dirs go AFTER
  754. the login PATH in parent order, so a command that resolved before still resolves
  755. to the same binary (the user's nvm/pyenv keep precedence); only commands that had
  756. no match gain one. Present entries are never duplicated; missing absolute dirs are skipped.
  757. Background commands (``ProcessRegistry.spawn_local``, ``bash -lic``, no snapshot) use
  758. this same prelude so the two paths cannot diverge."""
  759. if _IS_WINDOWS:
  760. return cmd_string # native PATH stays ``;``-joined; bash sees a converted copy
  761. # Relative entries resolve against the shell's cwd, not ours, so only absolute ones are checked.
  762. entries = [d for d in dict.fromkeys(parent_path.split(":"))
  763. if d and (not os.path.isabs(d) or os.path.isdir(d))]
  764. if not entries:
  765. return cmd_string
  766. restore = (f"for __hermes_p in {' '.join(shlex.quote(d) for d in entries)}; do "
  767. 'case ":$PATH:" in *":$__hermes_p:"*) ;; *) PATH="${PATH:+$PATH:}$__hermes_p" ;; esac; '
  768. "done; unset __hermes_p; export PATH")
  769. return restore + "\n" + cmd_string
  770. # --- Process-group teardown (POSIX) ---
  771. def _wait_for_group_exit(proc, pgid: int, timeout: float) -> bool:
  772. """Wait until the process group is gone, reaping the wrapper as we go (a dead
  773. but unreaped group leader still makes ``killpg(pgid, 0)`` succeed).
  774. POSIX-only; callers are behind the _IS_WINDOWS gate."""
  775. deadline = time.monotonic() + timeout
  776. while True:
  777. try:
  778. proc.poll()
  779. except Exception:
  780. pass
  781. try:
  782. os.killpg(pgid, 0) # windows-footgun: ok — POSIX process-group alive probe
  783. except ProcessLookupError:
  784. return True
  785. except PermissionError:
  786. pass # exists, even if we cannot signal it
  787. if time.monotonic() >= deadline:
  788. return False
  789. time.sleep(0.05)
  790. def _sweep_escaped_descendants(descendants: list, pgid: int) -> None:
  791. """SIGKILL snapshotted survivors that escaped the process group via ``setsid``
  792. — after TERM→KILL so in-group members keep their grace; psutil's identity-aware
  793. Process skips recycled PIDs. POSIX-only (see _IS_WINDOWS gate in caller)."""
  794. for child in descendants:
  795. try:
  796. if not child.is_running():
  797. continue
  798. try:
  799. if os.getpgid(child.pid) == pgid:
  800. continue # group-kill already covers it
  801. except OSError: # ProcessLookupError / PermissionError included
  802. pass
  803. child.kill()
  804. except Exception:
  805. continue
  806. def _leader_is_ours(pgid, expected_start) -> bool:
  807. """The setsid group leader's PID == its PGID. Confirm it is still the process we
  808. spawned before signalling the whole group, so a recycled PID/PGID can never take
  809. down an unrelated process group (#43044). The baseline and the current reading
  810. come from the same host at different times, so they go through the drift-tolerant
  811. fingerprint comparator — same-host readings drift ~1 s on macOS (#117505), and
  812. exact equality made the guard refuse to kill live, legitimately-owned groups.
  813. When no baseline was captured, or the current reading is unreadable, keep the
  814. legacy best-effort behaviour rather than refusing to kill: only a LIVE leader with
  815. a different start time proves recycling."""
  816. if pgid is None:
  817. return False
  818. if expected_start is None:
  819. return True
  820. from gateway.status import get_process_start_time, start_time_fingerprints_match
  821. try:
  822. current = get_process_start_time(pgid)
  823. except Exception:
  824. return True
  825. if current is None:
  826. # Unreadable while alive: best effort. Gone: POSIX never reuses a PGID while any
  827. # member of the group lives, so the group (if it still exists) is ours and its
  828. # reparented grandchildren still need the signal; an empty group is just ESRCH.
  829. return True
  830. try:
  831. return start_time_fingerprints_match(expected_start, current)
  832. except (TypeError, ValueError): # junk fingerprints: best-effort, never break signalling
  833. return True
  834. def _kill_process_group_posix(proc) -> None:
  835. """TERM the group, wait, KILL, then sweep setsid escapees. Descendants are
  836. snapshotted BEFORE the first signal — once the wrapper dies they reparent to
  837. init — and we wait on the group, not the wrapper, which can exit before
  838. grandchildren under load. POSIX-only (_IS_WINDOWS handled by the caller).
  839. PID-reuse guard (#43044): the group is only signalled while its leader's start
  840. time still matches the spawn-time baseline — a recycled PGID is never killed."""
  841. expected_start = getattr(proc, "_hermes_pgid_start", None)
  842. try:
  843. pgid = os.getpgid(proc.pid)
  844. except ProcessLookupError:
  845. if (pgid := getattr(proc, "_hermes_pgid", None)) is None:
  846. raise
  847. if not _leader_is_ours(pgid, expected_start):
  848. # Leader exited and its PID/PGID may have been recycled onto an unrelated
  849. # process group; signalling the stale number is unsafe. Bail out — a rare
  850. # orphaned grandchild may leak, which is strictly preferable to killing a
  851. # stranger. Sweep the snapshotted descendants by PID (identity-checked)
  852. # so we still reach escapees that are verifiably ours.
  853. descendants = []
  854. try:
  855. import psutil
  856. descendants = psutil.Process(proc.pid).children(recursive=True)
  857. except Exception:
  858. pass
  859. _sweep_escaped_descendants(descendants, pgid)
  860. return
  861. try: # psutil children snapshot; empty on any failure (must never break the kill)
  862. import psutil
  863. descendants = psutil.Process(proc.pid).children(recursive=True)
  864. except Exception:
  865. descendants = []
  866. if pgid == os.getpgrp():
  867. # The child shares OUR group (a spawner that skipped setsid — the Darwin gateway's
  868. # posix_spawn shim, #107029): killpg would signal the caller itself. Tear down by PID.
  869. _kill_known_pids(proc, descendants)
  870. else:
  871. try:
  872. os.killpg(pgid, signal.SIGTERM) # windows-footgun: ok — POSIX only (see _IS_WINDOWS gate in caller)
  873. if not _wait_for_group_exit(proc, pgid, 1.0):
  874. if not _leader_is_ours(pgid, expected_start):
  875. # Leader exited during the grace window; do not escalate to
  876. # SIGKILL on a possibly-recycled PGID.
  877. return
  878. os.killpg(pgid, signal.SIGKILL) # windows-footgun: ok — POSIX only (see _IS_WINDOWS gate in caller)
  879. _wait_for_group_exit(proc, pgid, 2.0)
  880. with contextlib.suppress(subprocess.TimeoutExpired, OSError):
  881. proc.wait(timeout=0.2)
  882. except ProcessLookupError:
  883. pass
  884. except PermissionError:
  885. # macOS answers killpg with EPERM (not ESRCH) once the group's only members are
  886. # unreaped zombies — rg exiting between the caller's poll() and the TERM after the
  887. # drain hit its limit (#116855). Nothing group-wide is signalable, and the error
  888. # must not escape: the caller still owns the output it drained. Signal the known
  889. # PIDs instead so a live child (a group we may not signal) cannot outlive us.
  890. _kill_known_pids(proc, descendants)
  891. _sweep_escaped_descendants(descendants, pgid)
  892. def _kill_known_pids(proc, descendants) -> None:
  893. """KILL the wrapper and its snapshotted descendants by PID (idempotent on zombies)."""
  894. for target in (proc, *descendants):
  895. with contextlib.suppress(Exception):
  896. target.kill()
  897. def _kill_process_windows(proc) -> None:
  898. """Identity-checked terminate (start time guards against PID reuse), else kill."""
  899. try:
  900. from gateway.status import get_process_start_time, terminate_pid
  901. terminate_pid(proc.pid, force=True, expected_start_time=get_process_start_time(proc.pid))
  902. except Exception:
  903. proc.kill()
  904. with contextlib.suppress(subprocess.TimeoutExpired, OSError):
  905. proc.wait(timeout=2.0)
  906. class LocalEnvironment(BaseEnvironment):
  907. """Run commands directly on the host: every execute() spawns a fresh bash;
  908. the session snapshot preserves exported env vars across calls (unless
  909. ``persistent=False``); CWD persists via the stdout marker."""
  910. _passwordless_sudo_probe_supported = True
  911. _profile_scoped_passthrough = True
  912. # Commands run on the Hermes host itself — controller-side platform behavior
  913. # (macOS TCC pruning, etc.) legitimately applies here.
  914. is_local = True
  915. # A subclass that confines its commands (a sandbox) sets this False: see BaseEnvironment.
  916. uses_host_filesystem = True
  917. def _additional_profile_scoped_passthrough_names(self) -> tuple[str, ...]:
  918. """First-party ``BUZZ_*`` names present in the env, excluded from the shared
  919. session snapshot. env_passthrough can never list them (it refuses blocklisted
  920. names), so under a multiplexed gateway profile A's BUZZ_PRIVATE_KEY would land
  921. in the snapshot and be sourced by profile B. Prefix-only and monotonic on
  922. purpose: conservative even when the context-gated carve-out is inactive."""
  923. merged = dict(os.environ | self.env)
  924. return tuple(sorted(
  925. name for name in merged
  926. if isinstance(name, str) and _matches_terminal_first_party_prefix(name)))
  927. def __init__(self, cwd: str = "", timeout: int = 60, env: dict | None = None, persistent: bool = True):
  928. super().__init__(cwd=_resolve_local_initial_cwd(cwd), timeout=timeout, env=env, persist_env=persistent)
  929. self.init_session()
  930. def get_temp_dir(self) -> str:
  931. """Shell-safe writable temp dir. Precedence: ``TERMINAL_TEMP_DIR``, TMPDIR/TMP/TEMP
  932. (Termux has no system temp dir), ``HERMES_HOME/cache/terminal`` (real storage: a
  933. tmpfs system temp dir fills under Hermes load; pruned by ``cleanup_terminal_temp_cache``),
  934. ``tempfile.gettempdir()``; backend env before process env so terminal.env
  935. overrides work. Windows: ``%TEMP%`` often has spaces that break unquoted bash,
  936. so always the HERMES_HOME cache dir with forward slashes (bash- and Python-valid)."""
  937. if _IS_WINDOWS:
  938. for key in ("TERMINAL_TEMP_DIR", "TMPDIR"):
  939. candidate = self.env.get(key) or os.environ.get(key)
  940. if candidate and os.path.isabs(candidate) and os.path.isdir(candidate):
  941. return Path(candidate).as_posix()
  942. cache_dir = (_default_terminal_temp_dir()
  943. or Path(tempfile.gettempdir()) / "hermes_terminal")
  944. cache_dir.mkdir(parents=True, exist_ok=True)
  945. _prune_terminal_temp_once()
  946. return str(cache_dir).replace("\\", "/")
  947. def _posix(p: str) -> str:
  948. return p.rstrip("/") or "/"
  949. for env_var in ("TERMINAL_TEMP_DIR", "TMPDIR", "TMP", "TEMP"):
  950. candidate = self.env.get(env_var) or os.environ.get(env_var)
  951. if candidate and candidate.startswith("/") and (
  952. env_var != "TERMINAL_TEMP_DIR" or os.path.isdir(candidate)):
  953. return _posix(candidate)
  954. try:
  955. cache_dir = _default_terminal_temp_dir()
  956. cache_dir.mkdir(parents=True, exist_ok=True)
  957. resolved = str(cache_dir)
  958. if resolved.startswith("/") and os.access(resolved, os.W_OK | os.X_OK):
  959. _prune_terminal_temp_once()
  960. return _posix(resolved)
  961. except Exception:
  962. pass
  963. # tempfile's own candidate walk already covers the system temp dir.
  964. fallback = tempfile.gettempdir()
  965. return _posix(fallback if fallback.startswith("/") else os.path.abspath(fallback))
  966. @staticmethod
  967. def _quote_cwd_for_cd(cwd: str) -> str:
  968. """Use native paths for Python, but Git Bash-friendly paths for cd."""
  969. return BaseEnvironment._quote_cwd_for_cd(_windows_to_msys_path(cwd))
  970. def _quote_shell_path(self, path: str) -> str:
  971. """Rewrite native/mixed Windows paths before quoting for Git Bash."""
  972. return _quote_bash_path(path)
  973. def _recover_cwd(self) -> None:
  974. """Swap ``self.cwd`` for a usable directory if it vanished or is inaccessible
  975. (e.g. a command ``rm -rf``'d its own cwd) — otherwise Popen raises before bash
  976. starts and every subsequent call fails. A benign MSYS→Windows normalization
  977. is not warned about."""
  978. # Recover when the cwd has been deleted out from under us — usually by a previous tool call that ran
  979. # ``rm -rf`` on its own working dir (issue #17558). On Windows, ``_resolve_safe_cwd`` also
  980. # normalises Git Bash-style POSIX paths (``/c/Users/...``) to native form so a perfectly valid ``pwd
  981. # -P`` result from bash isn't mistakenly treated as "missing" and spammed as a warning on every
  982. # command.
  983. safe_cwd = _resolve_safe_cwd(self.cwd)
  984. if safe_cwd == self.cwd:
  985. return
  986. if safe_cwd != _msys_to_windows_path(self.cwd):
  987. logger.warning(
  988. "LocalEnvironment cwd %r is missing on disk; "
  989. "falling back to %r so terminal commands keep working.",
  990. self.cwd, safe_cwd)
  991. self.cwd = safe_cwd
  992. def _run_bash(self, cmd_string: str, *, login: bool = False, timeout: int = 120,
  993. stdin_data: str | None = None) -> subprocess.Popen:
  994. bash = _find_bash()
  995. run_env = _make_run_env(self.env)
  996. # Login invocations (init_session's env snapshot) source the user's rc /
  997. # custom init files so nvm/asdf/pyenv land on PATH in the snapshot; then the
  998. # spawn env's dirs a resetting profile dropped are re-appended (#56634).
  999. if login:
  1000. cmd_string = _append_dropped_path_entries(cmd_string, run_env.get("PATH", ""))
  1001. cmd_string = _prepend_shell_init(cmd_string, _resolve_shell_init_files())
  1002. args = [bash, *(["-l"] if login else []), "-c", cmd_string]
  1003. self._recover_cwd()
  1004. # Not spawn_owned: an awaited command needs no spawn-ledger entry; own_process_groups below hands
  1005. # its group to the owner-death supervisor and _wait_for_process releases it.
  1006. proc = subprocess.Popen(
  1007. args, text=True, env=run_env, encoding="utf-8", errors="replace",
  1008. stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
  1009. stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
  1010. # detached-spawn: ok — owned via own_process_groups right below
  1011. start_new_session=True, cwd=self.cwd,
  1012. **({"creationflags": windows_hide_flags()} if _IS_WINDOWS else {}))
  1013. if not _IS_WINDOWS:
  1014. # The command dies with this process however it dies: a SIGKILLed / OOM-killed host left a
  1015. # running `npm run dev` or `sleep` on init. Released once the wait returns (see below).
  1016. own_process_groups([proc.pid])
  1017. proc._hermes_owned_pgid = proc.pid
  1018. with contextlib.suppress(ProcessLookupError):
  1019. proc._hermes_pgid = os.getpgid(proc.pid)
  1020. # Record the group leader's start-time fingerprint so _kill_process can
  1021. # detect PID/PGID recycling before signalling the group (#43044). The
  1022. # psutil fallback in get_process_start_time captures a baseline on every
  1023. # platform, macOS included.
  1024. from gateway.status import get_process_start_time
  1025. proc._hermes_pgid_start = get_process_start_time(proc.pid)
  1026. if stdin_data is not None:
  1027. _pipe_stdin(proc, stdin_data)
  1028. return proc
  1029. def _wait_for_process(self, proc, *args, **kwargs) -> dict:
  1030. """Base wait, then hand the command's group back from the owner-death supervisor: once the
  1031. command returned, what it left running in the background (`server &`) is not ours to kill,
  1032. exactly as on a graceful exit. A command that yielded to background took the group with it
  1033. (``ProcessRegistry.adopt_local`` clears ``_hermes_owned_pgid``)."""
  1034. try:
  1035. return super()._wait_for_process(proc, *args, **kwargs)
  1036. finally:
  1037. if (owned_pgid := getattr(proc, "_hermes_owned_pgid", None)) is not None:
  1038. proc._hermes_owned_pgid = None
  1039. release_process_groups([owned_pgid])
  1040. def _kill_process(self, proc):
  1041. """Kill the entire process group (all children)."""
  1042. try:
  1043. (_kill_process_windows if _IS_WINDOWS else _kill_process_group_posix)(proc)
  1044. except OSError: # ProcessLookupError / PermissionError included
  1045. with contextlib.suppress(Exception):
  1046. proc.kill()
  1047. def _force_kill_process(self, proc):
  1048. """SIGKILL the whole group with no TERM grace or wait: the caller os._exit()s next."""
  1049. if _IS_WINDOWS: # already a forced tree kill
  1050. return self._kill_process(proc)
  1051. with contextlib.suppress(OSError):
  1052. pgid = getattr(proc, "_hermes_pgid", None) or os.getpgid(proc.pid)
  1053. # PID-reuse guard (#43044): never SIGKILL a group whose leader's start time
  1054. # no longer matches the spawn-time baseline — the PGID may have been recycled
  1055. # onto an unrelated process group. Comparison is drift-tolerant (#117505);
  1056. # without a baseline keep the legacy best-effort behaviour.
  1057. if pgid != os.getpgrp() and _leader_is_ours(pgid, getattr(proc, "_hermes_pgid_start", None)):
  1058. os.killpg(pgid, signal.SIGKILL) # windows-footgun: ok — POSIX only (_IS_WINDOWS returned above)
  1059. with contextlib.suppress(OSError):
  1060. proc.kill()
  1061. def _extract_cwd_from_output(self, result: dict):
  1062. """Base semantics plus: Git Bash ``pwd -P`` emits MSYS form on Windows —
  1063. normalize to native and require the dir to exist, else ``_run_bash`` would
  1064. warn every command. A stale path rolls back to the previous cwd, which this
  1065. command did not observe, so ``cwd_observed`` is dropped."""
  1066. prev_cwd = self.cwd
  1067. super()._extract_cwd_from_output(result)
  1068. if self.cwd != prev_cwd:
  1069. normalized = _msys_to_windows_path(self.cwd)
  1070. if normalized and os.path.isdir(normalized):
  1071. self.cwd = normalized
  1072. result["cwd"] = normalized
  1073. else:
  1074. self.cwd = prev_cwd
  1075. result.pop("cwd_observed", None)
  1076. result.pop("cwd", None)
  1077. def cleanup(self):
  1078. """Clean up temp files, including orphaned atomic-write snapshots
  1079. (``snap.tmp.<bashpid>``) a failed/interrupted mv could leave behind."""
  1080. # See #38249.
  1081. import glob
  1082. try:
  1083. stale = glob.glob(f"{self._snapshot_path}.tmp.*")
  1084. except Exception:
  1085. stale = []
  1086. for f in (self._snapshot_path, self._cwd_file, *stale):
  1087. with contextlib.suppress(OSError):
  1088. os.unlink(f)