session_client_env.py 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. """A local session's client environment: the allowlisted values a shell-launched client (classic CLI,
  2. Ink TUI) sends as ``session.create``'s ``client_env``. Main's ``hermes`` process read them from its own
  3. shell; the one gateway now runs every session, so they are frozen with the session's policy and bound
  4. for its turns only, never written to the gateway's ``os.environ``. Desktop sends none: its sessions
  5. keep the gateway's environment, and so does a session created before ``client_env`` existed.
  6. Plain names and string values only. Behaviour names are read through :func:`session_env`; the
  7. toolchain names (``PATH``, an activated venv, nvm/pyenv/conda) reach that session's tool subprocesses
  8. through :func:`toolchain_environ`. Values naming this host (toolchain paths, the prefill file, the
  9. project-plugins check of the client's folder) apply only when the gateway proved the client is on its
  10. host (``local``); otherwise the session keeps the gateway's and is told so. Values are never logged.
  11. """
  12. from __future__ import annotations
  13. import json
  14. import os
  15. from contextlib import contextmanager
  16. from contextvars import ContextVar
  17. from tools.code_execution_env import is_secret_env_name
  18. # What main's CLI read per process and the gateway otherwise reads daemon-wide.
  19. BEHAVIOUR_ENV = ('HERMES_EPHEMERAL_SYSTEM_PROMPT', 'HERMES_PREFILL_MESSAGES_FILE', 'HERMES_INFERENCE_PROVIDER',
  20. 'HERMES_ENABLE_PROJECT_PLUGINS')
  21. # Behaviour values that name the client's host: a path, or the opt-in that inspects the client's folder.
  22. HOST_BEHAVIOUR = ('HERMES_PREFILL_MESSAGES_FILE', 'HERMES_ENABLE_PROJECT_PLUGINS')
  23. TOOL_ENV = ('PATH', 'VIRTUAL_ENV', 'GOPATH', 'GOROOT', 'CARGO_HOME', 'RUSTUP_HOME', 'JAVA_HOME')
  24. TOOL_ENV_PREFIXES = ('CONDA_', 'NODE_', 'NVM_', 'PYENV_')
  25. # ``terminal.client_env_passthrough`` names more non-secret toolchain variables for a profile.
  26. CONFIG_KEY = 'client_env_passthrough'
  27. # The session-start notice of a session whose client the gateway could not place on its own host.
  28. NOT_LOCAL_WARNING = ("this session uses the gateway's own PATH, toolchain and prefill file: the client's environment "
  29. 'was not applied because the client is not attached to this gateway locally.')
  30. _MAX_NAMES = 256
  31. _MAX_BYTES = 256 * 1024
  32. # (env, local) for the session executing here; None outside a shell client's session.
  33. _BOUND: ContextVar = ContextVar('session_client_env', default=None)
  34. def configured_names(config) -> frozenset:
  35. """The profile's extra tool names (``terminal.client_env_passthrough``)."""
  36. terminal = config.get('terminal') if isinstance(config, dict) else None
  37. raw = terminal.get(CONFIG_KEY) if isinstance(terminal, dict) else None
  38. return frozenset(name.strip() for name in raw if isinstance(name, str) and name.strip()) if isinstance(raw, list) else frozenset()
  39. def _travels(name: str, secret=None) -> bool:
  40. """A toolchain name may travel unless it is a credential by execute_code's secret policy (even when
  41. listed: ``NODE_AUTH_TOKEN`` matches ``NODE_``; secrets reach tools through ``terminal.env_passthrough``)
  42. or a Hermes control name (a delegated child's markers, Kanban pins). ``secret``: a session's frozen
  43. copy of that policy's substrings."""
  44. hidden = is_secret_env_name(name) if secret is None else any(s in name.upper() for s in secret)
  45. return not hidden and not name.startswith('HERMES_')
  46. def client_env_rules(config, *, local=True) -> dict:
  47. """The normalisation rules (plain data) a session's map is filtered by, frozen with it: an exact retry
  48. is judged by these, never by the profile's allowlist or the secret policy as they are later. A client
  49. not proven ``local`` keeps only the values that name nothing on this host (prompt, provider request)."""
  50. from tools.code_execution_env import _SECRET_SUBSTRINGS
  51. return {'behaviour': [n for n in BEHAVIOUR_ENV if local or n not in HOST_BEHAVIOUR],
  52. 'names': sorted(set(TOOL_ENV) | configured_names(config)) if local else [],
  53. 'prefixes': list(TOOL_ENV_PREFIXES) if local else [], 'secret': list(_SECRET_SUBSTRINGS)}
  54. def _kept(name: str, rules: dict) -> bool:
  55. return name in rules['behaviour'] or (_travels(name, rules['secret']) and (
  56. name in rules['names'] or name.startswith(tuple(rules['prefixes']))))
  57. def collect_client_env(environ=None, config=None) -> dict[str, str]:
  58. """Client side: this shell's allowlisted values (the profile's extra names included)."""
  59. environ = os.environ if environ is None else environ
  60. rules = client_env_rules(config)
  61. return {name: value for name, value in environ.items() if isinstance(value, str) and _kept(name, rules)}
  62. def normalise_client_env(value, rules) -> dict[str, str]:
  63. """The validated map filtered by ``rules`` (``None``: unfiltered, for a map frozen before rules were).
  64. Raises ``ValueError`` for anything but a bounded flat string-to-string map."""
  65. if (not isinstance(value, dict) or len(value) > _MAX_NAMES
  66. or any(not isinstance(k, str) or not isinstance(v, str) for k, v in value.items())
  67. or sum(len(k) + len(v) for k, v in value.items()) > _MAX_BYTES):
  68. raise ValueError('client_env must be a map of variable names to string values')
  69. return {name: value[name] for name in sorted(value) if rules is None or _kept(name, rules)}
  70. def accept_client_env(value, config, *, local=True) -> dict[str, str]:
  71. """Gateway side: the map filtered by the session profile's own current rules."""
  72. return normalise_client_env(value, client_env_rules(config, local=local))
  73. def retry_matches(committed: dict, request: dict) -> bool:
  74. """Whether a retried ``session.create`` (``request``: its params) carries the client environment the
  75. committed session (``committed``: its stored policy) froze. The complete retried map, normalised by
  76. the rules frozen with the session, must equal the stored one: an added name those rules keep, a
  77. missing stored name or a changed value is a different request; one they drop never counts. Staging
  78. and the transactional commit both judge by this. A session committed without a map (Desktop, one
  79. from before the field) still matches only a retry that sends none."""
  80. stored = committed.get('client_env_json')
  81. if stored is None or 'client_env' not in request:
  82. return stored is None and 'client_env' not in request
  83. rules = committed.get('client_env_rules_json')
  84. try:
  85. sent = normalise_client_env(request['client_env'], None if rules is None else json.loads(rules))
  86. except ValueError:
  87. return False
  88. return sent == json.loads(stored)
  89. @contextmanager
  90. def client_env_scope(env, *, local=True, rules=None):
  91. """Bind one session's client environment (``None``: the gateway's own) for this context; ``local``
  92. is the gateway's own proof, frozen in the session's policy, that the client runs on this host;
  93. ``rules`` the normalisation rules frozen with it (``client_env_rules``; ``None``: the built-ins)."""
  94. token = _BOUND.set(None if env is None else (env, bool(local), rules))
  95. try:
  96. yield
  97. finally:
  98. _BOUND.reset(token)
  99. def bound_client_env():
  100. bound = _BOUND.get()
  101. return None if bound is None else bound[0]
  102. def session_env(name: str, default: str = '') -> str:
  103. """A behaviour value for the session executing here: its client's (an unexported name is unset,
  104. as it was for main's process), else the gateway's own environment, which a client not attached
  105. locally also keeps for the values that name this host."""
  106. bound = _BOUND.get()
  107. if bound is None or (name in HOST_BEHAVIOUR and not bound[1]):
  108. return os.getenv(name, default)
  109. return bound[0].get(name, default)
  110. def tool_env() -> dict[str, str]:
  111. """The toolchain values this session's tool subprocesses start with (empty when unbound or remote)."""
  112. bound = _BOUND.get()
  113. if bound is None or not bound[1]:
  114. return {}
  115. return {name: value for name, value in bound[0].items() if name not in BEHAVIOUR_ENV and _travels(name)}
  116. def toolchain_environ(base=None) -> dict[str, str]:
  117. """The environment this session's tool subprocesses start from (``base``: the gateway's). Unbound
  118. (messaging, cron, Desktop): unchanged. Every client's session drops the gateway's own behaviour
  119. values it reads from its client (:func:`session_env`), so tools never see the daemon's ephemeral
  120. prompt or provider request in place of the session's. A client not attached locally keeps the
  121. host values (``HOST_BEHAVIOUR``) and the rest of the gateway's environment. A local shell client's
  122. session: its toolchain replaces the gateway's, and every toolchain name it did not export (built-in,
  123. or configured for its profile when the session was created) is unset, as in main's process: one
  124. client's venv or GEM_HOME never reaches another's session through the daemon it started. PATH is
  125. the exception: a client that sent none runs with the gateway's."""
  126. env = dict(os.environ if base is None else base)
  127. bound = _BOUND.get()
  128. if bound is None:
  129. return env
  130. for name in BEHAVIOUR_ENV:
  131. if bound[1] or name not in HOST_BEHAVIOUR:
  132. env.pop(name, None)
  133. if not bound[1]:
  134. return env
  135. rules = bound[2] or {'names': TOOL_ENV, 'prefixes': TOOL_ENV_PREFIXES, 'secret': None}
  136. names = {name for name in rules['names'] if _travels(name, rules['secret'])}
  137. prefixes = tuple(rules['prefixes'])
  138. kept = {k: v for k, v in env.items() if k == 'PATH' or not (k in names or k.startswith(prefixes))}
  139. return kept | tool_env()