From bb67389275ffc569ae4986e9f9ca95cff17c4e55 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 23:07:06 -0700 Subject: [PATCH] refactor(constants): compact docstrings/comments and section banners in hermes_constants --- hermes_constants.py | 325 ++++++++++++++------------------------------ 1 file changed, 99 insertions(+), 226 deletions(-) diff --git a/hermes_constants.py b/hermes_constants.py index 2ebc6c1bfb..c0078fe4b5 100644 --- a/hermes_constants.py +++ b/hermes_constants.py @@ -16,11 +16,8 @@ _profile_fallback_warned: bool = False _UNSET = object() _HERMES_HOME_OVERRIDE: ContextVar[str | object] = ContextVar("_HERMES_HOME_OVERRIDE", default=_UNSET) -# ── TUI busy-indicator styles ───────────────────────────────────────── -# Single source of truth shared by the CLI /indicator command, the TUI -# gateway config handler, and the /help command registry. Keep in sync -# with ``INDICATOR_STYLES`` / ``DEFAULT_INDICATOR_STYLE`` in -# ``ui-tui/src/app/interfaces.ts`` on the frontend side. +# TUI busy-indicator styles (CLI /indicator, TUI gateway config, /help registry). +# Keep in sync with INDICATOR_STYLES / DEFAULT_INDICATOR_STYLE in ui-tui/src/app/interfaces.ts. INDICATOR_STYLES: tuple[str, ...] = ("ascii", "emoji", "kaomoji", "unicode") DEFAULT_INDICATOR_STYLE: str = "kaomoji" @@ -28,8 +25,7 @@ DEFAULT_INDICATOR_STYLE: str = "kaomoji" def set_hermes_home_override(path: str | Path | None) -> Token: """Set a context-local Hermes home override and return its reset token. - In-process, per-task scoping; deliberately does not mutate ``os.environ`` (shared by every - thread in the process). + Deliberately does not mutate ``os.environ`` (shared by every thread in the process). """ value: str | object = _UNSET if path is None else str(path) return _HERMES_HOME_OVERRIDE.set(value) @@ -56,10 +52,7 @@ def _get_platform_default_hermes_home() -> Path: def _warn_profile_fallback_once() -> None: - """Warn once when HERMES_HOME is unset but a non-default profile is sticky-active. - - The fallback to the default profile is almost certainly wrong in that case. - """ + """Warn once when HERMES_HOME is unset but a non-default profile is sticky-active (fallback is wrong).""" global _profile_fallback_warned if _profile_fallback_warned: return @@ -71,9 +64,8 @@ def _warn_profile_fallback_once() -> None: active = "" if active and active != "default": _profile_fallback_warned = True - # Direct stderr, not ``logging``: this runs at module-import time from - # 30+ sites (often before logging is configured) and root-logger - # propagation would double-emit where a StreamHandler is attached. + # Direct stderr, not logging: runs at import time (often before logging is + # configured) and root-logger propagation would double-emit. msg = ( f"[HERMES_HOME fallback] HERMES_HOME is unset but active " f"profile is {active!r}. Falling back to {fallback_home}, which " @@ -90,11 +82,7 @@ def _warn_profile_fallback_once() -> None: def get_hermes_home() -> Path: - """Return the Hermes home directory — the single source of truth. - - Resolution order: context-local override (:func:`set_hermes_home_override`) → ``HERMES_HOME`` - env var → platform-native default. - """ + """Hermes home: context-local override → ``HERMES_HOME`` env var → platform default.""" override = get_hermes_home_override() if override: return Path(override) @@ -104,10 +92,9 @@ def get_hermes_home() -> Path: def hermes_home_key(path: str | Path | None = None) -> str: - """Return a stable key for a Hermes home/profile directory. + """Stable registry key for a Hermes home/profile dir. - Runtime registries use it to isolate plugin-owned entries while keeping built-in registrations - process-global. ``strict=False`` keeps working for profiles whose directories don't exist yet. + ``strict=False`` so profiles whose directories don't exist yet still get a key. """ candidate = Path(path) if path is not None else get_hermes_home() resolved = candidate.expanduser().resolve(strict=False) @@ -115,29 +102,22 @@ def hermes_home_key(path: str | Path | None = None) -> str: def get_process_hermes_home() -> Path: - """Return the Hermes home for the running process, ignoring task overrides. + """Hermes home of the running process, ignoring task overrides. - For machine/process-level dashboard-owned assets (theme YAML, dashboard plugin manifests) that - live under the server's launch home and must stay visible while a request is scoped to another - profile (e.g. embedded ``/chat`` under ``--open-profile``). Shared by :func:`get_hermes_home`. + For process-level assets (theme YAML, dashboard plugin manifests) that must stay visible while a + request is scoped to another profile (e.g. embedded ``/chat`` under ``--open-profile``). """ val = os.environ.get("HERMES_HOME", "").strip() return Path(val) if val else _get_platform_default_hermes_home() -# Memo for get_default_hermes_root(): ~80us of path resolution per call at 31+ -# sites (every _load_global_auth_store(), kanban, backup, gateway, update). The -# result depends only on (HERMES_HOME, native home), compared for free on each -# call, so it stays fresh even if a test or plugin mutates HERMES_HOME. +# get_default_hermes_root() memo keyed on (native home, HERMES_HOME) so it stays +# fresh when a test or plugin mutates HERMES_HOME; saves ~80us/call at 31+ sites. _default_hermes_root_memo: "tuple[str, str, Path] | None" = None def get_default_hermes_root() -> Path: - """Return the root Hermes directory for profile-level operations. - - In profile mode (``HERMES_HOME=/profiles/``) returns ```` so ``profile list`` - sees all profiles; handles both ``~/.hermes/profiles/x`` and Docker ``/opt/data/profiles/x``. - """ + """Root Hermes dir for profile-level ops: ```` when ``HERMES_HOME=/profiles/``.""" global _default_hermes_root_memo native_home = _get_platform_default_hermes_home() env_home = os.environ.get("HERMES_HOME", "") @@ -150,29 +130,23 @@ def get_default_hermes_root() -> Path: env_path = Path(env_home) try: env_path.resolve().relative_to(native_home.resolve()) # under ~/.hermes (normal or profile mode) - except ValueError: - # Docker / custom deployment: ``/profiles/`` roots at the grandparent, - # otherwise HERMES_HOME itself is the root. + except ValueError: # Docker/custom root: /profiles/ -> , else HERMES_HOME itself result = env_path.parent.parent if env_path.parent.name == "profiles" else env_path _default_hermes_root_memo = (str(native_home), env_home, result) return result -# Deletion marker lives beside the profile dir (not inside) so a stale mkdir -# from live serve/logging or an rmtree cannot erase the fact of deletion. +# Tombstone lives beside the profile dir (not inside) so a stale mkdir or rmtree cannot erase it. _DELETED_PROFILES_DIR = ".deleted" - -# Files marking a real Hermes home (a fresh home gains one on first use); -# arbitrary dirs with a ``profiles`` segment (``/srv/profiles/buildcache``) do not. +# Files marking a real Hermes home; arbitrary dirs with a ``profiles`` segment lack them. _HERMES_HOME_MARKERS = ("config.yaml", ".env", "state.db") def _is_hermes_profiles_root(profiles_dir: Path) -> bool: - """Return True when *profiles_dir* is a canonical ``/profiles``. + """True when *profiles_dir* is provably ``/profiles``. - Fires only for directories provably under a Hermes home: the classic ``~/.hermes`` layout, a - root carrying Hermes-home marker files (Docker/custom ``HERMES_HOME``), a ``profiles/.deleted`` - tombstone dir (only ``hermes profile delete`` creates it), or the resolved default Hermes root. + Accepts the classic ``~/.hermes`` layout, a root carrying Hermes-home marker files, a + ``profiles/.deleted`` tombstone dir (only ``profile delete`` creates it), or the default root. """ root = profiles_dir.parent if root.name == ".hermes": @@ -193,17 +167,15 @@ def _is_hermes_profiles_root(profiles_dir: Path) -> bool: def named_profile_home(path: str | Path) -> Path | None: """Return ``/profiles/`` when *path* is that home or under it. - Only ``.../profiles/`` where ```` does not start with ``.`` AND the ``profiles`` parent is - a real Hermes home (:func:`_is_hermes_profiles_root`); a default home whose path merely contains - a ``profiles`` segment is not a named profile. + Requires ```` not to start with ``.`` and the ``profiles`` parent to be a real Hermes home; + a default home whose path merely contains a ``profiles`` segment is not a named profile. """ current = Path(path) for candidate in (current, *current.parents): if (candidate.parent.name == "profiles" and not candidate.name.startswith(".") and _is_hermes_profiles_root(candidate.parent)): return candidate - # Stop at a default Hermes home: a coincidental ``profiles/`` ancestor is not a root. - if candidate.name == ".hermes": + if candidate.name == ".hermes": # default home: a coincidental profiles/ ancestor is not a root return None return None @@ -270,11 +242,9 @@ def get_bundled_skills_dir(default: Path | None = None) -> Path: def get_hermes_dir(new_subpath: str, old_name: str, *, home: Path | None = None) -> Path: - """Resolve a Hermes subdirectory with backward compatibility. + """Resolve a Hermes subdirectory, honouring a populated legacy ``/`` (no migration). - New installs get the consolidated layout (e.g. ``cache/images``); a populated legacy - ``/`` keeps being used — no migration. A bare empty ``/`` does NOT count - (install scaffolds, manual mkdir, cleared locations) so it cannot shadow real data at the new path. + An empty legacy dir does NOT count (install scaffolds, manual mkdir) so it cannot shadow the new path. """ home = home or get_hermes_home() old_path = home / old_name @@ -282,14 +252,11 @@ def get_hermes_dir(new_subpath: str, old_name: str, *, home: Path | None = None) def iter_hermes_node_dirs(home: Path | None = None) -> list[Path]: - """Return Hermes-managed Node.js directories in preferred lookup order. + """Hermes-managed Node dirs in lookup order; both Windows and POSIX shapes so migrated installs work. - Windows unpacks portable Node into ``%LOCALAPPDATA%\\hermes\\node``; POSIX uses - ``$HERMES_HOME/node/bin``. Both shapes are included everywhere so migrated installs work. + Keep in sync with hermesManagedNodePathEntries() in apps/desktop/electron/backend-env.ts. """ node_dir = (home or get_hermes_home()) / "node" - # Keep in sync with hermesManagedNodePathEntries() in - # apps/desktop/electron/backend-env.ts (Electron cannot import this module). return [node_dir, node_dir / "bin"] if sys.platform == "win32" else [node_dir / "bin", node_dir] @@ -304,8 +271,7 @@ def _candidate_node_command_names(command: str) -> list[str]: base = Path(command).name if sys.platform != "win32" or "." in base: return [base] - # Prefer npm.cmd: PowerShell may block npm.ps1 by policy and CreateProcess - # cannot launch a bare .ps1. + # Prefer npm.cmd: PowerShell may block npm.ps1 by policy; CreateProcess cannot launch a bare .ps1. return _WINDOWS_NODE_SHIMS.get(base.lower(), [f"{base}.cmd", f"{base}.exe", base]) @@ -330,7 +296,7 @@ def _first_runnable_managed(names: list[str]) -> tuple[str | None, bool]: def _run_version_probe(argv: list[str], **kwargs): - """Run ``argv`` (a ``--version`` probe) hidden; ``None`` when it cannot run.""" + """Run a hidden ``--version`` probe; ``None`` when it cannot run.""" import subprocess try: @@ -353,12 +319,11 @@ _HERMES_NODE_TARGET_MAJOR = int(os.environ.get("HERMES_NODE_TARGET_MAJOR", "22") _managed_node_heal_attempted = False _NODE_BOOTSTRAP_SCRIPT = Path(__file__).resolve().parent / "scripts" / "lib" / "node-bootstrap.sh" -# Install tree root; secure_parent_dir() refuses to chmod inside it. _INSTALL_ROOT = Path(__file__).resolve().parent def _is_executable_file(path: str) -> bool: - """``exists()`` follows symlinks — a dangling link never spawns a probe.""" + """``exists()`` follows symlinks, so a dangling link never spawns a probe.""" return os.path.exists(path) and os.access(path, os.X_OK) @@ -377,10 +342,9 @@ def hermes_managed_node_tree_present(home: Path | None = None) -> bool: def _path_under_any(path: str, roots: list[str]) -> bool: - """Return True when *path* sits inside one of *roots* (same drive). + """True when *path* sits inside one of *roots* (same drive). - Compared through ``normcase`` (no-op on POSIX): Windows paths are case-insensitive and psutil / - env vars can disagree on drive-letter casing. + Compared via ``normcase``: psutil and env vars can disagree on Windows drive-letter casing. """ path_norm = os.path.normcase(os.path.normpath(path)) for root in roots: @@ -394,11 +358,10 @@ def _path_under_any(path: str, roots: list[str]) -> bool: def managed_node_tree_in_use(home: Path | None = None) -> bool: - """Return True when any running process executes from the managed Node tree. + """True when a running process executes from the managed Node tree. - Windows locks running executables and loaded scripts against delete/overwrite, so the updater - must not rewrite ``%HERMES_HOME%\\node`` while the desktop app's Node processes hold it — - ``PermissionError: [WinError 5]`` on ``npm.cmd`` is the classic symptom (#80926). + Windows locks running executables against delete/overwrite, so the updater must not rewrite + ``%HERMES_HOME%\\node`` while the desktop app holds it (``[WinError 5]`` on ``npm.cmd``). """ if sys.platform != "win32": return False @@ -460,9 +423,9 @@ def _fetch_url(url: str, timeout: int) -> bytes | None: def _stage_windows_node_zip(home: Path, node_arch: str) -> Path | None: - """Download and extract the target-major portable Node zip into a sibling ``node.new-*`` dir. + """Download the target-major portable Node zip into a sibling ``node.new-*`` dir. - A sibling staging dir makes the later swap a same-volume rename. ``None`` on any failure. + A sibling makes the later swap a same-volume rename. ``None`` on any failure. """ import tempfile import uuid @@ -502,9 +465,8 @@ def _stage_windows_node_zip(home: Path, node_arch: str) -> Path | None: def _swap_node_tree(target: Path, staged: Path) -> bool | None: """Rename the live tree aside (``node.old-*``) and *staged* into place. - ``None`` when the OS refuses to move the live tree (a running process holds it): the old tree - is untouched and the next resolution retries. ``False`` when the staged tree cannot be moved in - (live tree rolled back). + ``None`` when the OS refuses to move the live tree (in use; untouched, retried next time), + ``False`` when the staged tree cannot be moved in (live tree rolled back). """ backup = target.parent / f"node.old-{staged.name.removeprefix('node.new-')}" had_live = target.exists() @@ -515,9 +477,8 @@ def _swap_node_tree(target: Path, staged: Path) -> bool | None: _print_managed_node_in_use_notice() shutil.rmtree(staged, ignore_errors=True) return None - # A rename preserves mtime, so a backup of a long-lived tree would look - # older than the litter-sweep cutoff to a concurrent heal. Touch it - # (best-effort — the swap already succeeded) so it is never swept mid-swap. + # Rename preserves mtime: touch the backup (best-effort) so a concurrent heal's + # litter sweep never removes it mid-swap. try: os.utime(backup, None) except OSError: @@ -541,15 +502,10 @@ def _swap_node_tree(target: Path, staged: Path) -> bool | None: def _heal_managed_node_windows(home: Path | None = None) -> bool | None: """Redownload the portable Node zip into ``%HERMES_HOME%\\node`` on Windows. - Returns ``True`` on success, ``False`` on a genuine failure (offline, download error, bad - archive), ``None`` when the tree is in use and the heal is deferred — callers must not record - the once-per-process attempt for ``None`` so a later call can retry. - - Staging-first: the new tree is fully extracted to a sibling ``node.new-*`` dir, the live tree - renamed aside (``node.old-*``), the staged tree renamed into place — so an interrupted heal - cannot gut the running install. Windows allows renaming a tree whose executables are running - (``FILE_SHARE_DELETE``); when the OS refuses the rename, that refusal *is* the in-use signal - and the heal defers instead of crashing with ``[WinError 5]`` on ``npm.cmd`` (#80926). + ``True`` on success, ``False`` on genuine failure (offline, bad archive), ``None`` when the + tree is in use and the heal is deferred — callers must not record the once-per-process attempt + for ``None``. Staging-first (extract to ``node.new-*``, rename live aside, rename staged in) so + an interrupted heal cannot gut the install; a refused rename *is* the in-use signal. """ import time @@ -559,13 +515,11 @@ def _heal_managed_node_windows(home: Path | None = None) -> bool | None: return False home = home or get_hermes_home() target = home / "node" - # Cheap pre-check; the rename-based swap below is the authoritative guard. + # Cheap pre-check; the rename-based swap is the authoritative guard. if managed_node_tree_in_use(home): _print_managed_node_in_use_notice() return None - # Sweep staging/backup litter from interrupted runs (locked files stay for - # next time). Only dirs older than 10 minutes, so a concurrent heal's - # in-flight swap (seconds old) is never disturbed. + # Sweep litter from interrupted runs; only dirs >10 min old so a concurrent in-flight swap survives. cutoff = time.time() - 600 for stale in (*home.glob("node.old-*"), *home.glob("node.new-*")): try: @@ -601,11 +555,9 @@ def _run_node_bootstrap(func: str, *, timeout: int, **extra_env: str) -> bool: def bootstrap_hermes_managed_node() -> str | None: - """Install a Hermes-managed Node tree and return its npm path. + """Install a Hermes-managed Node tree under ``$HERMES_HOME/node`` and return its npm path. - For when the only Node/npm on the machine belongs to the user (system, nvm, brew, Nix) and - cannot satisfy the repo's ``engines`` — Hermes never modifies a toolchain it does not own, so it - provisions its own tree under ``$HERMES_HOME/node`` (same tree a fresh install creates). + Hermes never modifies a user-owned toolchain (system, nvm, brew, Nix) that fails ``engines``. """ existing = find_hermes_node_executable("npm") if existing: @@ -613,8 +565,7 @@ def bootstrap_hermes_managed_node() -> str | None: if sys.platform == "win32": ok = _heal_managed_node_windows() else: - # HERMES_NODE_SKIP_LINKS=1 keeps node/npm/npx out of ~/.local/bin so the - # user's own toolchain on PATH is never shadowed. + # HERMES_NODE_SKIP_LINKS=1 keeps node/npm/npx out of ~/.local/bin (never shadow the user's toolchain). ok = _run_node_bootstrap("_nb_install_bundled_node", timeout=600, HERMES_NODE_SKIP_LINKS="1") if not ok: return None @@ -622,11 +573,9 @@ def bootstrap_hermes_managed_node() -> str | None: def heal_hermes_managed_node() -> bool: - """Redownload Hermes-managed Node when the tree exists but is broken. + """Redownload Hermes-managed Node when the tree exists but is broken; at most once per process. - At most once per process. POSIX shells out to ``heal_managed_node`` in node-bootstrap.sh; - Windows downloads the portable zip directly. A Windows in-use deferral does NOT record the - attempt so a later call can heal once the tree is free. + A Windows in-use deferral does NOT record the attempt so a later call can heal once free. """ global _managed_node_heal_attempted if _managed_node_heal_attempted or not hermes_managed_node_tree_present(): @@ -642,11 +591,7 @@ def heal_hermes_managed_node() -> bool: def _managed_node_tree_outdated(home: Path | None = None) -> bool: - """True when the managed tree's node runs but is below the target major. - - An outdated tree heals like a broken one (:func:`find_hermes_node_executable` triggers the - once-per-process heal), so existing users are upgraded on next launch. - """ + """True when the managed node runs but is below the target major (heals like a broken tree).""" for candidate in _iter_managed_node_candidates(_candidate_node_command_names("node"), home): result = _run_version_probe([str(candidate), "--version"]) if result is None: @@ -656,10 +601,8 @@ def _managed_node_tree_outdated(home: Path | None = None) -> bool: major = int(version.split(".")[0]) except (ValueError, IndexError): return False - # A pre-release counts as outdated however high its major: nodejs.org - # publishes headers only for final releases, so node-gyp cannot build - # node-pty against one and the install would stay broken forever. - # Mirrors node_satisfies_build() in scripts/install.sh. + # A pre-release is outdated whatever its major: nodejs.org publishes headers only for + # final releases, so node-gyp cannot build node-pty. Mirrors node_satisfies_build() in install.sh. if "-" in version: return True return major < _HERMES_NODE_TARGET_MAJOR @@ -667,11 +610,7 @@ def _managed_node_tree_outdated(home: Path | None = None) -> bool: def find_hermes_node_executable(command: str) -> str | None: - """Return a Hermes-managed Node/npm executable path, healing broken/outdated trees. - - When the heal fails (offline, download error) an outdated-but-runnable tree is still returned: - old Node beats no Node. - """ + """Hermes-managed Node/npm path, healing broken/outdated trees; heal failure still returns old Node.""" names = _candidate_node_command_names(command) resolved, broken_present = _first_runnable_managed(names) needs_heal = broken_present or (resolved is not None and _managed_node_tree_outdated()) @@ -683,11 +622,7 @@ def find_hermes_node_executable(command: str) -> str | None: def find_node_executable_on_path(command: str) -> str | None: - """Return a Node/npm executable from PATH with Windows shim ordering. - - ``shutil.which("npm")`` can pick the extensionless npm shim before ``.cmd`` on Windows; Python's - CreateProcess cannot execute that shim, so prefer the launchable variants explicitly. - """ + """Node/npm from PATH; on Windows prefer ``.cmd``/``.exe`` (CreateProcess cannot run the bare shim).""" if sys.platform != "win32": return shutil.which(command) command_str = str(command) @@ -703,11 +638,9 @@ def find_node_executable_on_path(command: str) -> str | None: def find_node_executable(command: str) -> str | None: - """Resolve a Node.js command, preferring healthy Hermes-managed installs. + """Resolve a Node command, preferring a healthy managed install. - For Hermes-owned subprocesses that must not break on a bad/missing/elevation-triggering system - Node on PATH. When a managed tree exists but cannot be healed, returns ``None`` rather than - falling back to system npm. + A managed tree that exists but cannot be healed yields ``None`` rather than system Node. """ managed = find_hermes_node_executable(command) if managed: @@ -731,26 +664,23 @@ def with_hermes_node_path(env: dict[str, str] | None = None) -> dict[str, str]: def agent_browser_runnable(path: str | None) -> bool: - """True only when *path* is an agent-browser CLI that actually runs (``--version`` exits 0). + """True when *path* is an agent-browser CLI that runs (``--version`` exits 0) or the npx fallback. - A dead/wrong-arch/hung binary is rejected so callers fall through to the next candidate. The - ``"npx agent-browser"`` fallback (two tokens, not a file) → True; npx validates at run time. + Dead/wrong-arch/hung binaries are rejected so callers try the next candidate. """ if not path: return False - # The npx fallback is a two-token command string, not a filesystem path. + # The npx fallback is a two-token command string, not a path; npx validates at run time. if " " in path and path.split()[0].endswith("npx"): return True return _is_executable_file(path) and _version_probe_ok(path) def _legacy_path_has_content(path: Path) -> bool: - """True iff *path* exists and has content worth honouring. + """True iff *path* is a non-directory file or a populated directory. - A populated directory or any non-directory file counts; an empty directory does not, so a stale - stub falls through to the new layout. Any ``OSError`` other than not-found means "assume - occupied" to avoid orphaning legacy data. Symlinks are judged on their target; a dangling one - does NOT count and must not shadow populated new-layout data. + Non-not-found ``OSError`` means "assume occupied" (never orphan legacy data). Symlinks are + judged on their target; a dangling one does NOT count. """ try: st = path.lstat() @@ -772,33 +702,22 @@ def _legacy_path_has_content(path: Path) -> bool: def display_hermes_home() -> str: - """User-friendly ``~/`` display string for HERMES_HOME (``~/.hermes/profiles/coder``). - - Use in user-facing messages instead of hardcoding ``~/.hermes``; for a real ``Path`` use - :func:`get_hermes_home`. - """ + """User-facing ``~/`` display string for HERMES_HOME (``~/.hermes/profiles/coder``).""" home = get_hermes_home() try: - # as_posix(): on Windows str() renders backslashes, giving mixed - # chimeras like ``~/AppData\Local\hermes/skills/`` once callers append. + # as_posix(): str() on Windows yields chimeras like ~/AppData\Local\hermes/skills/. return "~/" + home.relative_to(Path.home()).as_posix() except ValueError: return str(home) def secure_parent_dir(path: Path) -> None: - """Chmod ``0o700`` on the parent directory of *path*, but only if safe. - - Refuses ``/`` and any top-level directory (resolved parent with fewer than 3 parts) so a - misresolved ``HERMES_HOME`` can never brick the host. - """ + """Chmod ``0o700`` on *path*'s parent, refusing ``/`` and top-level dirs (misresolved HERMES_HOME).""" parent = path.parent.resolve() - # Refuse root and its direct children (/usr, /home, /var, /tmp, …). if parent == Path("/") or len(parent.parts) < 3: return - # Refuse the install tree: chmod 0700 breaks hermes-user traversal in Docker - # (UID 10000) — #25821, #93050. A credential file here usually means - # HERMES_HOME misresolved; surface it (this caused production lockouts). + # Refuse the install tree: chmod 0700 breaks hermes-user traversal in Docker (UID 10000). + # A credential file here means HERMES_HOME misresolved; surface it (caused production lockouts). if parent == _INSTALL_ROOT or _INSTALL_ROOT in parent.parents: import logging @@ -864,11 +783,10 @@ def _iter_real_home_candidates(env: dict[str, str] | None = None) -> list[str]: def get_real_home(env: dict[str, str] | None = None) -> str: - """Return the OS user's real home directory, avoiding Hermes profile HOME. + """The OS user's real home, avoiding the Hermes profile HOME. - ``HERMES_HOME`` scopes Hermes state; ``HOME`` belongs to the OS account and external CLIs that - keep credentials under ``~``. If a parent already runs with ``HOME={HERMES_HOME}/home``, repair - back to the account home when possible. + ``HOME`` belongs to the OS account and external CLIs keeping credentials under ``~``; a parent + already running with ``HOME={HERMES_HOME}/home`` is repaired back when possible. """ profile_home = _profile_home_path(env) seen: set[str] = set() @@ -889,11 +807,10 @@ _HOME_MODE_ALIASES = { def get_subprocess_home(env: dict[str, str] | None = None) -> str | None: - """Return a subprocess ``HOME`` override, if one should be applied. + """Subprocess ``HOME`` override, or ``None``. - ``auto`` (default): hosts keep the real user HOME, containers use ``{HERMES_HOME}/home``; a - host parent whose HOME is the profile home is repaired back to real HOME. ``real``: always - prefer the real OS-user HOME. ``profile``: always the profile home. + ``auto``: hosts keep real HOME (repairing a profile-home parent), containers use + ``{HERMES_HOME}/home``; ``real``: always real HOME; ``profile``: always the profile home. """ env = env or {} profile_home = _profile_home_path(env) @@ -931,9 +848,8 @@ VALID_REASONING_EFFORTS = ("minimal", "low", "medium", "high", "xhigh", "max", " def parse_reasoning_effort(effort) -> dict | None: """Parse a reasoning effort level into a config dict. - None for empty/unrecognized input (caller uses the default); ``{"enabled": False}`` for - "none" and its aliases ("false", "disabled", YAML boolean False) — ``reasoning_effort: - false``/``off``/``no`` must mean disabled, not "keep thinking". + ``None`` for empty/unrecognized input (caller uses the default); ``{"enabled": False}`` for + "none"/"false"/"disabled"/YAML False — ``reasoning_effort: false`` must mean disabled. """ if effort is None or effort is True: return None @@ -946,10 +862,9 @@ def parse_reasoning_effort(effort) -> dict | None: def _canonical_model_variants(model: str) -> list[str]: - """Bounded spelling variants for tolerant override matching, exact first, deduped in order. + """Spelling variants for tolerant override matching, exact first, deduped in order. - Version-dot recovery is applied to EACH base form so ``claude-opus-4.5``, ``claude-opus-4-5`` - and ``claude-opus.4.5`` all yield the same variant set. + Dot/dash recovery runs on EACH base form so ``x-4.5``, ``x-4-5`` and ``x.4.5`` share one variant set. """ _dash_to_dot = lambda s: re.sub(r'(\d)-(\d)', r'\1.\2', s) _dot_to_dash = lambda s: re.sub(r'(\d)\.(\d)', r'\1-\2', s) @@ -963,7 +878,6 @@ def _canonical_model_variants(model: str) -> list[str]: variants.append(v) def _add_with_derivatives(s): - """Add s plus its dots↔dashes and version-dot derivatives.""" dashed, dotted = s.replace('.', '-'), s.replace('-', '.') _add(s, dashed, dotted, _dash_to_dot(s), _dot_to_dash(s), _dash_to_dot(dashed), _dot_to_dash(dotted)) _add_with_derivatives(model) @@ -985,10 +899,9 @@ def _canonical_model_variants(model: str) -> list[str]: def resolve_per_model_reasoning_effort(model: str, overrides: dict | None) -> dict | None: - """Lookup a per-model reasoning_effort override with spelling tolerance. + """Per-model reasoning_effort override with spelling tolerance; first non-None parse wins. - Order: exact → dots↔dashes → bare model (provider stripped) → aggregator stripped → known - provider/aggregator prefixes prepended. First non-None parse_reasoning_effort result wins. + Order: exact → dots↔dashes → provider stripped → aggregator stripped → known prefixes prepended. """ if not overrides or not isinstance(overrides, dict) or not model: return None @@ -1001,10 +914,9 @@ def resolve_per_model_reasoning_effort(model: str, overrides: dict | None) -> di def resolve_reasoning_config(cfg: dict | None, model: str = "") -> dict | None: - """Resolve the effective reasoning config for *model* from a config dict. + """Effective reasoning config for *model*: per-model override, then global ``agent.reasoning_effort``. - Single chokepoint shared by every surface (CLI startup, gateway, Desktop/TUI, cron, ``/model``, - fallback activation): per-model override first, then the global ``agent.reasoning_effort``. + Single chokepoint for every surface (CLI, gateway, TUI, cron, ``/model``, fallback activation). """ cfg = cfg if isinstance(cfg, dict) else {} agent_cfg = cfg.get("agent") if isinstance(cfg.get("agent"), dict) else {} @@ -1019,8 +931,7 @@ def resolve_reasoning_config(cfg: dict | None, model: str = "") -> dict | None: if per_model is not None: return per_model - # Global fallback — keep the raw value: ``or ""`` would turn a YAML False - # into "" and silently re-enable thinking. + # Keep the raw value: ``or ""`` would turn a YAML False into "" and silently re-enable thinking. effort = agent_cfg.get("reasoning_effort", "") result = parse_reasoning_effort(effort) if effort and str(effort).strip() and result is None: @@ -1061,8 +972,7 @@ def windows_path_to_wsl(path: str) -> str | None: def wsl_unc_path_to_posix(path: str) -> str | None: - """Convert a Windows WSL UNC path (``\\\\wsl.localhost\\\\...`` or the - legacy ``\\\\wsl$\\...``) to a POSIX path inside the distro.""" + """Convert a ``\\\\wsl.localhost\\\\...`` (or legacy ``\\\\wsl$``) UNC path to POSIX.""" normalized = str(path or "").strip().replace("/", "\\") match = re.match(r"^\\\\wsl(?:\.localhost|\$)\\[^\\]+\\(.*)$", normalized, re.IGNORECASE) if not match: @@ -1072,10 +982,8 @@ def wsl_unc_path_to_posix(path: str) -> str | None: def translate_cwd_for_wsl_backend(cwd: str) -> str: - """Normalize a cross-boundary cwd when Hermes itself runs inside WSL. + """Map a Windows-host cwd (drive path or ``\\\\wsl.localhost\\`` UNC) to POSIX when Hermes runs in WSL. - A Windows-host UI (native picker / drive path / ``\\\\wsl.localhost\\`` UNC) can hand the WSL - backend a path it can't ``chdir`` into; map it to POSIX so picker, sidebar and sessions agree. No-op off WSL and for paths already POSIX. """ if not is_wsl(): @@ -1091,9 +999,7 @@ _container_detected: bool | None = None def is_container() -> bool: - """True inside a container (Docker/Podman/LXC markers, Kubernetes env, cgroup/mountinfo - markers); cached per process. - """ + """True inside a container (Docker/Podman/LXC/Kubernetes markers); cached per process.""" global _container_detected if _container_detected is None: _container_detected = _detect_container() @@ -1121,9 +1027,6 @@ def _detect_container() -> bool: return _proc_file_has_marker("/proc/self/mountinfo", ("kubepods", "containerd", "crio")) -# ─── Well-Known Paths ───────────────────────────────────────────────────────── - - def get_config_path() -> Path: """Return the path to ``config.yaml`` under HERMES_HOME.""" return get_hermes_home() / "config.yaml" @@ -1139,16 +1042,11 @@ def get_env_path() -> Path: return get_hermes_home() / ".env" -# ─── Network Preferences ───────────────────────────────────────────────────── - - def apply_ipv4_preference(force: bool = False) -> None: - """Monkey-patch ``socket.getaddrinfo`` to prefer IPv4 connections when *force* is True. + """Monkey-patch ``socket.getaddrinfo`` to prefer IPv4 when *force* is True. - On hosts with broken IPv6, Python tries AAAA first and hangs for the full TCP timeout before - falling back — this hits httpx, requests, urllib, the OpenAI SDK. ``family=AF_UNSPEC`` calls - resolve as ``AF_INET``; if no A record exists, fall back to full resolution so pure-IPv6 hosts - still work. + Broken-IPv6 hosts hang on AAAA for the full TCP timeout; ``AF_UNSPEC`` resolves as ``AF_INET``, + falling back to full resolution when no A record exists (pure-IPv6 hosts still work). """ if not force: return @@ -1170,27 +1068,17 @@ def apply_ipv4_preference(force: bool = False) -> None: socket.getaddrinfo = _ipv4_getaddrinfo # type: ignore[assignment] -# ─── Streaming Response Constants ──────────────────────────────────────────── - PARTIAL_STREAM_STUB_ID = "partial-stream-stub" - FINISH_REASON_LENGTH = "length" - - OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1" OPENROUTER_MODELS_URL = f"{OPENROUTER_BASE_URL}/models" - AI_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh/v1" -# ─── Venv layout ───────────────────────────────────────────────────────────── - def venv_bin_dir(venv_dir, *, windows: bool | None = None) -> Path: - """Directory holding a venv's executables (``Scripts`` / ``bin``). + """Venv executable dir (``Scripts``/``bin``); *windows* lets tests exercise Windows paths on Linux. - *windows* lets callers pass their own platform verdict: tests patch predicates such as - ``hermes_cli.main._is_windows`` to exercise Windows paths on Linux CI. Returned - unconditionally — callers differ on whether a missing venv is an error. + Returned unconditionally — callers differ on whether a missing venv is an error. """ if windows is None: windows = sys.platform == "win32" @@ -1198,11 +1086,7 @@ def venv_bin_dir(venv_dir, *, windows: bool | None = None) -> Path: def project_venv_dir(project_root) -> Path | None: - """The project's venv directory, ``venv`` or ``.venv``, when one exists. - - ``uv venv`` defaults to ``.venv`` while our installers create ``venv``; call sites that only - knew ``venv`` silently no-oped on ``.venv`` installs (#79542). - """ + """The project's ``venv`` or ``.venv`` dir when one exists (``uv venv`` defaults to ``.venv``).""" for name in ("venv", ".venv"): candidate = Path(project_root) / name if candidate.is_dir(): @@ -1216,11 +1100,8 @@ def venv_python_path(venv_dir, *, windows: bool | None = None) -> Path: return bin_dir / ("python.exe" if bin_dir.name == "Scripts" else "python") -# ─── Partial-update diagnostics ────────────────────────────────────────────── - -# First-party roots: an ImportError naming one means our own tree is -# inconsistent. `hermes_cli.update_cmd`'s post-update probe consumes this same -# set so the guard that BLOCKS and the hint that EXPLAINS never disagree. +# First-party roots: an ImportError naming one means our own tree is inconsistent. The +# update post-probe shares this set so the guard that BLOCKS and the hint that EXPLAINS agree. FIRST_PARTY_MODULE_ROOTS = frozenset({ "agent", "acp_adapter", "cli", "cron", "gateway", "model_tools", "plugins", "providers", "tools", "toolsets", "run_agent", "tui_gateway", "utils", @@ -1228,21 +1109,13 @@ FIRST_PARTY_MODULE_ROOTS = frozenset({ def is_first_party_module(name: str | None) -> bool: - """True when *name* is a module that ships with Hermes. - - Exact match on the first dotted segment; ``startswith`` would also claim third-party - ``agents``, ``agentops``, ``toolsets_x``. - """ + """True when *name* ships with Hermes (exact first segment; ``startswith`` would claim ``agentops``).""" root = str(name).split(".")[0] if name else "" return bool(root) and (root in FIRST_PARTY_MODULE_ROOTS or root.startswith("hermes_")) def partial_update_hint(exc: BaseException) -> list[str]: - """Recovery guidance lines when *exc* looks like a half-updated tree, else ``[]``. - - Users see an opaque crash with no hint that the *install* (not their config) is broken, and - ``hermes update`` is exactly what they need but least trust after a failed update. - """ + """Recovery guidance lines when *exc* looks like a half-updated tree, else ``[]``.""" # A missing third-party dep (bad venv, missing extra) is a different problem. if not isinstance(exc, ImportError) or isinstance(exc, ModuleNotFoundError): return []