| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170 |
- """A local session's client environment: the allowlisted values a shell-launched client (classic CLI,
- Ink TUI) sends as ``session.create``'s ``client_env``. Main's ``hermes`` process read them from its own
- shell; the one gateway now runs every session, so they are frozen with the session's policy and bound
- for its turns only, never written to the gateway's ``os.environ``. Desktop sends none: its sessions
- keep the gateway's environment, and so does a session created before ``client_env`` existed.
- Plain names and string values only. Behaviour names are read through :func:`session_env`; the
- toolchain names (``PATH``, an activated venv, nvm/pyenv/conda) reach that session's tool subprocesses
- through :func:`toolchain_environ`. Values naming this host (toolchain paths, the prefill file, the
- project-plugins check of the client's folder) apply only when the gateway proved the client is on its
- host (``local``); otherwise the session keeps the gateway's and is told so. Values are never logged.
- """
- from __future__ import annotations
- import json
- import os
- from contextlib import contextmanager
- from contextvars import ContextVar
- from tools.code_execution_env import is_secret_env_name
- # What main's CLI read per process and the gateway otherwise reads daemon-wide.
- BEHAVIOUR_ENV = ('HERMES_EPHEMERAL_SYSTEM_PROMPT', 'HERMES_PREFILL_MESSAGES_FILE', 'HERMES_INFERENCE_PROVIDER',
- 'HERMES_ENABLE_PROJECT_PLUGINS')
- # Behaviour values that name the client's host: a path, or the opt-in that inspects the client's folder.
- HOST_BEHAVIOUR = ('HERMES_PREFILL_MESSAGES_FILE', 'HERMES_ENABLE_PROJECT_PLUGINS')
- TOOL_ENV = ('PATH', 'VIRTUAL_ENV', 'GOPATH', 'GOROOT', 'CARGO_HOME', 'RUSTUP_HOME', 'JAVA_HOME')
- TOOL_ENV_PREFIXES = ('CONDA_', 'NODE_', 'NVM_', 'PYENV_')
- # ``terminal.client_env_passthrough`` names more non-secret toolchain variables for a profile.
- CONFIG_KEY = 'client_env_passthrough'
- # The session-start notice of a session whose client the gateway could not place on its own host.
- NOT_LOCAL_WARNING = ("this session uses the gateway's own PATH, toolchain and prefill file: the client's environment "
- 'was not applied because the client is not attached to this gateway locally.')
- _MAX_NAMES = 256
- _MAX_BYTES = 256 * 1024
- # (env, local) for the session executing here; None outside a shell client's session.
- _BOUND: ContextVar = ContextVar('session_client_env', default=None)
- def configured_names(config) -> frozenset:
- """The profile's extra tool names (``terminal.client_env_passthrough``)."""
- terminal = config.get('terminal') if isinstance(config, dict) else None
- raw = terminal.get(CONFIG_KEY) if isinstance(terminal, dict) else None
- return frozenset(name.strip() for name in raw if isinstance(name, str) and name.strip()) if isinstance(raw, list) else frozenset()
- def _travels(name: str, secret=None) -> bool:
- """A toolchain name may travel unless it is a credential by execute_code's secret policy (even when
- listed: ``NODE_AUTH_TOKEN`` matches ``NODE_``; secrets reach tools through ``terminal.env_passthrough``)
- or a Hermes control name (a delegated child's markers, Kanban pins). ``secret``: a session's frozen
- copy of that policy's substrings."""
- hidden = is_secret_env_name(name) if secret is None else any(s in name.upper() for s in secret)
- return not hidden and not name.startswith('HERMES_')
- def client_env_rules(config, *, local=True) -> dict:
- """The normalisation rules (plain data) a session's map is filtered by, frozen with it: an exact retry
- is judged by these, never by the profile's allowlist or the secret policy as they are later. A client
- not proven ``local`` keeps only the values that name nothing on this host (prompt, provider request)."""
- from tools.code_execution_env import _SECRET_SUBSTRINGS
- return {'behaviour': [n for n in BEHAVIOUR_ENV if local or n not in HOST_BEHAVIOUR],
- 'names': sorted(set(TOOL_ENV) | configured_names(config)) if local else [],
- 'prefixes': list(TOOL_ENV_PREFIXES) if local else [], 'secret': list(_SECRET_SUBSTRINGS)}
- def _kept(name: str, rules: dict) -> bool:
- return name in rules['behaviour'] or (_travels(name, rules['secret']) and (
- name in rules['names'] or name.startswith(tuple(rules['prefixes']))))
- def collect_client_env(environ=None, config=None) -> dict[str, str]:
- """Client side: this shell's allowlisted values (the profile's extra names included)."""
- environ = os.environ if environ is None else environ
- rules = client_env_rules(config)
- return {name: value for name, value in environ.items() if isinstance(value, str) and _kept(name, rules)}
- def normalise_client_env(value, rules) -> dict[str, str]:
- """The validated map filtered by ``rules`` (``None``: unfiltered, for a map frozen before rules were).
- Raises ``ValueError`` for anything but a bounded flat string-to-string map."""
- if (not isinstance(value, dict) or len(value) > _MAX_NAMES
- or any(not isinstance(k, str) or not isinstance(v, str) for k, v in value.items())
- or sum(len(k) + len(v) for k, v in value.items()) > _MAX_BYTES):
- raise ValueError('client_env must be a map of variable names to string values')
- return {name: value[name] for name in sorted(value) if rules is None or _kept(name, rules)}
- def accept_client_env(value, config, *, local=True) -> dict[str, str]:
- """Gateway side: the map filtered by the session profile's own current rules."""
- return normalise_client_env(value, client_env_rules(config, local=local))
- def retry_matches(committed: dict, request: dict) -> bool:
- """Whether a retried ``session.create`` (``request``: its params) carries the client environment the
- committed session (``committed``: its stored policy) froze. The complete retried map, normalised by
- the rules frozen with the session, must equal the stored one: an added name those rules keep, a
- missing stored name or a changed value is a different request; one they drop never counts. Staging
- and the transactional commit both judge by this. A session committed without a map (Desktop, one
- from before the field) still matches only a retry that sends none."""
- stored = committed.get('client_env_json')
- if stored is None or 'client_env' not in request:
- return stored is None and 'client_env' not in request
- rules = committed.get('client_env_rules_json')
- try:
- sent = normalise_client_env(request['client_env'], None if rules is None else json.loads(rules))
- except ValueError:
- return False
- return sent == json.loads(stored)
- @contextmanager
- def client_env_scope(env, *, local=True, rules=None):
- """Bind one session's client environment (``None``: the gateway's own) for this context; ``local``
- is the gateway's own proof, frozen in the session's policy, that the client runs on this host;
- ``rules`` the normalisation rules frozen with it (``client_env_rules``; ``None``: the built-ins)."""
- token = _BOUND.set(None if env is None else (env, bool(local), rules))
- try:
- yield
- finally:
- _BOUND.reset(token)
- def bound_client_env():
- bound = _BOUND.get()
- return None if bound is None else bound[0]
- def session_env(name: str, default: str = '') -> str:
- """A behaviour value for the session executing here: its client's (an unexported name is unset,
- as it was for main's process), else the gateway's own environment, which a client not attached
- locally also keeps for the values that name this host."""
- bound = _BOUND.get()
- if bound is None or (name in HOST_BEHAVIOUR and not bound[1]):
- return os.getenv(name, default)
- return bound[0].get(name, default)
- def tool_env() -> dict[str, str]:
- """The toolchain values this session's tool subprocesses start with (empty when unbound or remote)."""
- bound = _BOUND.get()
- if bound is None or not bound[1]:
- return {}
- return {name: value for name, value in bound[0].items() if name not in BEHAVIOUR_ENV and _travels(name)}
- def toolchain_environ(base=None) -> dict[str, str]:
- """The environment this session's tool subprocesses start from (``base``: the gateway's). Unbound
- (messaging, cron, Desktop): unchanged. Every client's session drops the gateway's own behaviour
- values it reads from its client (:func:`session_env`), so tools never see the daemon's ephemeral
- prompt or provider request in place of the session's. A client not attached locally keeps the
- host values (``HOST_BEHAVIOUR``) and the rest of the gateway's environment. A local shell client's
- session: its toolchain replaces the gateway's, and every toolchain name it did not export (built-in,
- or configured for its profile when the session was created) is unset, as in main's process: one
- client's venv or GEM_HOME never reaches another's session through the daemon it started. PATH is
- the exception: a client that sent none runs with the gateway's."""
- env = dict(os.environ if base is None else base)
- bound = _BOUND.get()
- if bound is None:
- return env
- for name in BEHAVIOUR_ENV:
- if bound[1] or name not in HOST_BEHAVIOUR:
- env.pop(name, None)
- if not bound[1]:
- return env
- rules = bound[2] or {'names': TOOL_ENV, 'prefixes': TOOL_ENV_PREFIXES, 'secret': None}
- names = {name for name in rules['names'] if _travels(name, rules['secret'])}
- prefixes = tuple(rules['prefixes'])
- kept = {k: v for k, v in env.items() if k == 'PATH' or not (k in names or k.startswith(prefixes))}
- return kept | tool_env()
|