base_session_env.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. """Bash session-snapshot scripting for ``tools.environments.base``.
  2. Pure string builders: the CWD marker, the ``export -p`` dump that strips
  3. per-session vars, the ``init_session`` bootstrap, and the per-command wrapper.
  4. No module state lives here; ``BaseEnvironment`` supplies quoting hooks.
  5. """
  6. import re
  7. import shlex
  8. from typing import Iterable
  9. # Bridged per-session vars (gateway.session_context._VAR_MAP) are injected fresh onto every
  10. # command's process env and must NEVER persist in the shared bash snapshot: one long-lived
  11. # backend serves many sessions, so a snapshot carrying the FIRST session's HERMES_SESSION_ID
  12. # would make every LATER session source a foreign identity. Every bridged name starts with
  13. # one of these prefixes (or is HERMES_UI_SESSION_ID); unit tests use this regex as the
  14. # Python-side contract for the exclusion set.
  15. # Per-session variables that the gateway bridges freshly onto every command's process environment (via
  16. # tools/environments/local._inject_session_context_env, reading gateway.session_context._VAR_MAP). They must
  17. # NEVER be persisted into the shared bash session snapshot: a single long-lived backend serves many
  18. # concurrent sessions (the messaging gateway, TUI, desktop/web dashboard all collapse the terminal to one
  19. # "default" environment), so ``export -p`` dumping the FIRST session's HERMES_SESSION_ID into the snapshot
  20. # makes every LATER session ``source`` that stale value and see a FOREIGN session's identity — overriding
  21. # the correct per-command Popen env (issue: cross-session HERMES_SESSION_ID leak via the shared snapshot).
  22. # Stripping them from the snapshot is safe because they are re-injected on every command; a snapshot should
  23. # only carry the user's own shell state (PATH, functions, exports they set), not Hermes' per-turn session
  24. # identity. Used by unit tests as the Python-side contract for the exclusion set; the dump path unsets by
  25. # name/prefix instead of grepping declare lines (see below / issue #71296).
  26. _SNAPSHOT_EXCLUDED_ENV_REGEX = (
  27. "^declare -x (HERMES_SESSION_|HERMES_UI_SESSION_ID|HERMES_CRON_AUTO_DELIVER_|"
  28. "HERMES_CRON_SESSION|HERMES_DELEGATED_CHILD_CONTEXT|"
  29. "HERMES_RPC_|HERMES_KERNEL_DIR)")
  30. _SHELL_ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
  31. # mktemp template suffix + the shell variable holding the allocated temp path.
  32. _SNAP_TMP_SUFFIX = ".tmp.XXXXXXXXXX"
  33. _SNAP_TMP = '"$__hermes_snap_tmp"'
  34. def _cwd_marker(session_id: str) -> str:
  35. return f"__HERMES_CWD_{session_id}__"
  36. def _pipe_marker(session_id: str) -> str:
  37. return f"__HERMES_PIPE_{session_id}__"
  38. def _pipe_marker_printf(marker: str) -> str:
  39. """Emit the pipeline's per-segment exit statuses (``PIPESTATUS``) on their own line.
  40. ``cmd | tail`` exits with tail's status, so the shell's code cannot prove ``cmd``
  41. passed. The array holds each segment's own status and is captured before anything
  42. else runs.
  43. """
  44. return f"printf '\\n{marker}%s{marker}\\n' \"${{__hermes_ps[*]-}}\""
  45. def _eval_capturing_pipestatus(escaped: str) -> str:
  46. """``eval`` the command and keep its last pipeline's ``PIPESTATUS`` as side data.
  47. The array must be read inside the same ``eval`` (afterwards it holds only ``eval``'s
  48. status), while ``$?`` stays the exit code: the two differ for ``!``, ``if``/``while``,
  49. ``pipefail`` and parse errors. The blank line stops the capture joining a command
  50. continued by a trailing backslash. The restore sits on the left of ``&&`` so its
  51. non-zero status fires neither a user's ``ERR`` trap a second time nor ``set -e``.
  52. """
  53. return f"eval '{escaped}\n\n__hermes_rc=$? __hermes_ps=(\"${{PIPESTATUS[@]}}\"); (exit $__hermes_rc) && :'"
  54. def _can_capture_pipestatus(command: str) -> bool:
  55. """An unterminated heredoc would read the capture line as its body (into the user's
  56. file), and a trailing ``\\`` would join onto it: such commands run unchanged."""
  57. return "<<" not in command and not command.endswith("\\")
  58. def _cwd_marker_printf(marker: str) -> str:
  59. """Emit the CWD marker on its own line (leading ``\\n`` guards against a
  60. command whose output lacks a trailing newline; ``_split_cwd_marker`` strips it)."""
  61. return f"printf '\\n{marker}%s{marker}\\n' \"$(pwd -P)\""
  62. def _export_dump_excluding_session_vars(tmp_path: str, excluded_names: Iterable[str] = ()) -> str:
  63. """Shell snippet dumping ``export -p`` to *tmp_path* minus the per-session bridged vars (see
  64. ``_SNAPSHOT_EXCLUDED_ENV_REGEX``) and *excluded_names*. The vars are ``unset`` in a subshell
  65. BEFORE ``export -p``: a line-based ``grep -vE`` is unsafe because bash 3.2 prints a value
  66. containing a newline as a multi-line ``declare -x`` block, so smuggled continuation lines would
  67. survive into the snapshot and execute on the next ``source``. ``|| true`` keeps the success
  68. contract. The dump is a brace group with the redirection on the group: *tmp_path* is usually a
  69. shell-variable expansion, and a redirect on a pipeline segment would expand it inside that
  70. segment's subshell, inconsistently with the parent that expands the follow-up ``mv``.
  71. ``curl … | bash #`` smuggled into a Matrix room/display name via ``HERMES_SESSION_CHAT_NAME``) land in
  72. the snapshot and execute on the next ``source`` (issue #71296). Unsetting first means ``export -p``
  73. never emits those vars — including any continuation lines.
  74. """
  75. # ${!PREFIX*} is bash 3.2+ name-prefix expansion; empty matches are ignored
  76. # under 2>/dev/null. Caller names are quoted so malformed config can never
  77. # become shell syntax (valid names stay unquoted by shlex.quote()).
  78. safe_names = {name for name in excluded_names if isinstance(name, str) and name}
  79. extra_unset = "".join(f" {shlex.quote(name)}" for name in sorted(safe_names))
  80. return (
  81. "{ ( unset ${!HERMES_SESSION_*} ${!HERMES_CRON_AUTO_DELIVER_*} "
  82. # AI_AGENT / HERMES_AGENT are per-command attribution markers re-exported
  83. # by every wrapper with ${VAR:-default} semantics; persisting them would
  84. # let the FIRST command's value override a later outer-harness value.
  85. "AI_AGENT HERMES_AGENT "
  86. # Scope markers stamped onto a delegate_task child's / cron run's subprocess
  87. # env; a snapshot taken inside that window would re-assert them on every
  88. # later ``source`` and fence the PARENT session's kanban CLI (#90782).
  89. "HERMES_DELEGATED_CHILD_CONTEXT HERMES_CRON_SESSION "
  90. # Remote code-execution channel vars (RPC token, kernel/rpc dirs): a
  91. # leaked token in the snapshot would re-export into every later command
  92. # on the backend and outlive the private dir it protects.
  93. "${!HERMES_RPC_*} HERMES_KERNEL_DIR "
  94. f"HERMES_UI_SESSION_ID{extra_unset} 2>/dev/null; "
  95. "export -p; ) || true; } "
  96. f"> {tmp_path}")
  97. def _snapshot_bootstrap_script(
  98. *, quoted_cwd: str, quoted_snap: str, snap_tmp_template: str, excluded_names: Iterable[str], cwd_marker: str,
  99. ) -> str:
  100. """Login-shell bootstrap that captures env/functions/aliases into the snapshot. Atomic publish:
  101. assemble in a ``mktemp`` file, then ``mv`` over the final path so a concurrent ``source`` never
  102. reads a half-written snapshot (``$$`` is the parent PID in ``&``-launched subshells and macOS
  103. bash 3.2 lacks ``$BASHPID``, so only ``mktemp`` is portable). Functions are filtered by NAME via
  104. ``declare -F`` (a line-based ``declare -f | grep -v`` strips the header and leaves an orphaned
  105. body that breaks every sourced command); the non-empty guard matters because bare ``declare -f``
  106. dumps ALL functions. The trailing ``cd`` restores the configured cwd after profile scripts (e.g.
  107. ``cd ~``) so ``pwd -P`` reports terminal.cwd, not the profile's directory."""
  108. return (
  109. "umask 077\n"
  110. f"__hermes_snap_tmp=$(mktemp {snap_tmp_template}) || exit 1\n"
  111. f"{_export_dump_excluding_session_vars(_SNAP_TMP, excluded_names)}\n"
  112. "__hermes_fns=$(declare -F | awk '{print $3}' | grep -vE '^_[^_]') || true\n"
  113. f"[ -n \"$__hermes_fns\" ] && declare -f $__hermes_fns >> {_SNAP_TMP} 2>/dev/null || true\n"
  114. f"alias -p >> {_SNAP_TMP}\n"
  115. f"echo 'shopt -s expand_aliases' >> {_SNAP_TMP}\n"
  116. f"echo 'set +e' >> {_SNAP_TMP}\n"
  117. f"echo 'set +u' >> {_SNAP_TMP}\n"
  118. # Publish only if assembly succeeded; otherwise drop the partial temp.
  119. f"mv -f {_SNAP_TMP} {quoted_snap} || rm -f {_SNAP_TMP}\n"
  120. f"builtin cd -- {quoted_cwd} 2>/dev/null || true\n"
  121. f"{_cwd_marker_printf(cwd_marker)}\n")
  122. def _passthrough_save_restore(names: Iterable[str]) -> tuple[list[str], list[str]]:
  123. """Shell lines that save profile-scoped passthrough vars before the snapshot is sourced
  124. and restore (or unset) them afterwards — a shared snapshot may hold the previous
  125. profile's value. Values stay in environment memory and never enter the command string."""
  126. save: list[str] = []
  127. restore: list[str] = []
  128. for name in names:
  129. marker = f"_HERMES_RUNTIME_PASSTHROUGH_{name}"
  130. present, value = f"{marker}_PRESENT", f"{marker}_VALUE"
  131. save += [f"{present}=${{{name}+x}}", f"{value}=${{{name}-}}"]
  132. restore += [
  133. f'if [ "${present}" = x ]; then export {name}="${value}"; else unset {name}; fi',
  134. f"unset {present} {value}"]
  135. return save, restore
  136. def _wrap_command_script(
  137. command: str, *, quoted_cwd: str, quoted_snap: str, snap_tmp_template: str,
  138. passthrough_names: Iterable[str], snapshot_ready: bool, cwd_marker: str,
  139. pipe_marker: str = "", persist_env: bool = True) -> str:
  140. """Per-command bash script: source snapshot, cd, run, re-dump env, emit CWD marker.
  141. ``persist_env=False`` skips the re-dump, so every command starts from the login-time
  142. snapshot and exports from one command never reach the next (the CWD marker still runs).
  143. ``source`` stdout goes to /dev/null because macOS bash 3.2 / some Homebrew builds echo
  144. ``declare -x`` lines when sourcing. AI_AGENT/HERMES_AGENT advertise the harness to remote
  145. backends (whose env is not inherited); ``${VAR:-default}`` never clobbers an outer harness.
  146. GIT_PAGER/PAGER=cat stop pager-happy tools hanging a PTY-backed command. The env re-dump
  147. uses the same mktemp+mv atomic publish as the bootstrap and chains ``mv`` on the dump
  148. succeeding so a failed dump never replaces a good snapshot. ``umask 077`` is applied after
  149. the user's command so snapshot files (which may carry secrets) are private without
  150. changing the command's umask.
  151. """
  152. escaped = command.replace("'", "'\\''")
  153. capture = bool(pipe_marker) and _can_capture_pipestatus(command)
  154. save, restore = _passthrough_save_restore(passthrough_names)
  155. parts = list(save)
  156. if snapshot_ready:
  157. parts.append(f"source {quoted_snap} >/dev/null 2>&1 || true")
  158. parts += restore
  159. parts += [
  160. 'export AI_AGENT="${AI_AGENT:-hermes-agent}" HERMES_AGENT="${HERMES_AGENT:-true}"',
  161. 'export GIT_PAGER="${GIT_PAGER:-cat}" PAGER="${PAGER:-cat}"',
  162. # ``--`` keeps hyphen-prefixed directory names from being parsed as options.
  163. f"builtin cd -- {quoted_cwd} || exit 126",
  164. _eval_capturing_pipestatus(escaped) if capture else f"eval '{escaped}'",
  165. "__hermes_ec=$?",
  166. "umask 077"]
  167. if snapshot_ready and persist_env:
  168. parts.append(
  169. f"__hermes_snap_tmp=$(mktemp {snap_tmp_template}) && "
  170. f"{{ {_export_dump_excluding_session_vars(_SNAP_TMP, passthrough_names)} "
  171. f"&& mv -f {_SNAP_TMP} {quoted_snap}; }} "
  172. f"2>/dev/null || rm -f {_SNAP_TMP} 2>/dev/null || true")
  173. if capture:
  174. parts.append(_pipe_marker_printf(pipe_marker))
  175. parts += [_cwd_marker_printf(cwd_marker), "exit $__hermes_ec"]
  176. return "\n".join(parts)
  177. def _split_cwd_marker(output: str, marker: str) -> tuple[str | None, str] | None:
  178. """Locate the last ``marker<path>marker`` pair in *output*. Returns
  179. ``(cwd_path_or_None, output_without_marker_line)``, or ``None`` when no complete pair
  180. exists. The stripped span runs from the ``\\n`` the wrapper injected before the marker
  181. through the end of the marker line."""
  182. last = output.rfind(marker)
  183. if last == -1:
  184. return None
  185. search_start = max(0, last - 4096) # CWD path won't be >4KB
  186. first = output.rfind(marker, search_start, last)
  187. if first == -1 or first == last:
  188. return None
  189. cwd_path = output[first + len(marker) : last].strip() or None
  190. line_start = output.rfind("\n", 0, first)
  191. if line_start == -1:
  192. line_start = first
  193. line_end = output.find("\n", last + len(marker))
  194. line_end = line_end + 1 if line_end != -1 else len(output)
  195. return cwd_path, output[:line_start] + output[line_end:]