Files
hermes-agent/hermes_cli/plugins_session_env.py
alt-glitch 7defffc296 fix(lint): clear the findings ruff preview reports
Turning on ruff preview (needed for PLW1514, unspecified-encoding) also
widens some stable rules. Clearing what it reports first lets the config
change that enables it land with no ignore list:

- evals workers: 20 text-mode open() calls get encoding="utf-8".
- a2a and weixin adapters: legacy "# type:" comments become annotations.
- agent/lsp/client.py, gateway/run_turn.py: two prose comments started a
  line with "type:", which type checkers read as a type comment.
- sorted(x)[0] becomes min(x) (plugins_session_env, one test).
- test_plugin_session_fork: the attempts default is built per call
  instead of a shared list inside a tuple.

The pinned ruff 0.15.22 passes with today's config and with preview on.
2026-11-15 14:02:40 +05:30

94 lines
4.5 KiB
Python

"""Per-session environment values that plugins give a session's tool subprocesses (``ctx.register_session_env``).
Tools run in the shared gateway, so a variable of the client that shows a session (a terminal pane's
id, say) is not in the gateway's environment. A plugin declares the names and a resolver; every child
the session context reaches (terminal foreground and background, ``execute_code``'s ``terminal()``)
calls the resolvers of the active profile with the child's ``HERMES_SESSION_ID`` when it is spawned.
"""
from __future__ import annotations
import logging
import os
import re
import threading
from typing import Callable, Iterable, Mapping, Optional
logger = logging.getLogger(__name__)
Resolver = Callable[[str], Optional[Mapping[str, Optional[str]]]]
_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,127}")
_LOCK = threading.Lock()
_REGISTRATIONS: dict[object, tuple[str, Optional[str], frozenset[str], Resolver]] = {} # (scope, owner, names, resolver)
# Every name declared per profile scope, kept past its plugin's unload: a shell snapshot taken while a
# value was injected may hold it, and the name must stay excluded so no later command restores it.
# Another profile's shells never see these names (a multiplexed gateway serves several profiles).
_DECLARED: dict[str, set[str]] = {}
def _env_key(name: str) -> str:
"""The child-env key for ``name``: Windows' environment is case-insensitive and ``os.environ``
holds it upper-cased, so ``pane`` must replace or unset an inherited ``PANE``, never sit beside it."""
return name.upper() if os.name == "nt" else name
def register_session_env(scope: str, names: Iterable[str], resolver: Resolver, *,
owner: Optional[str] = None) -> Callable[[], None]:
"""Record ``resolver`` for ``names`` in profile ``scope``; return its release. ``HERMES_*`` stays core's.
A name a live registration of another ``owner`` (plugin) in ``scope`` declares is refused (``ValueError``
naming the holder): one plugin per name, never a silent last-wins between plugins. One owner's own
overlapping registrations stack: the latest live one's value wins."""
names = [names] if isinstance(names, str) else list(names)
if not names or any(not isinstance(n, str) or not _NAME_RE.fullmatch(n) or n.upper().startswith("HERMES_")
for n in names):
raise ValueError("session env names must be valid environment variable names outside HERMES_*")
if not callable(resolver):
raise TypeError("session env resolver must be callable")
token = object()
keys = frozenset(_env_key(n) for n in names)
with _LOCK:
clash = next(((min(keys & held), holder) for other, holder, held, _ in _REGISTRATIONS.values()
if other == scope and holder != owner and keys & held), None)
if clash is None:
_REGISTRATIONS[token] = (scope, owner, keys, resolver)
_DECLARED.setdefault(scope, set()).update(keys)
if clash is not None:
raise ValueError(f"session env {clash[0]!r} is already registered by {clash[1] or 'another plugin'!r}")
def release() -> None:
with _LOCK:
_REGISTRATIONS.pop(token, None)
return release
def session_env_names() -> frozenset[str]:
"""Every name declared in the active profile, unloaded plugins' included: none may be baked into (or
restored from) a shared shell snapshot."""
from hermes_constants import hermes_home_key
scope = hermes_home_key()
with _LOCK:
return frozenset(_DECLARED.get(scope, ()))
def resolve_session_env(session_id: str) -> dict[str, Optional[str]]:
"""The active profile's values for ``session_id`` (``None``: unset the name). A resolver that raises,
or returns something else than a map, contributes nothing; names it did not declare are ignored."""
with _LOCK:
registrations = tuple(_REGISTRATIONS.values())
if not session_id or not registrations:
return {}
from hermes_constants import hermes_home_key
scope = hermes_home_key()
out: dict[str, Optional[str]] = {}
for owner, _, names, resolver in registrations:
if owner != scope:
continue
try:
values = {_env_key(k): v for k, v in (resolver(session_id) or {}).items()
if isinstance(k, str) and _env_key(k) in names and (v is None or isinstance(v, str))}
except Exception:
logger.warning("Session env resolver %r failed for %s", resolver, session_id, exc_info=True)
continue
out.update(values)
return out