@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/hermes_cli/managed_scope.py

@@ -0,0 +1,214 @@
+"""Managed scope — IT-pushed, user-immutable config & env layer.
+
+A system-level directory (default ``/etc/hermes``, root-owned and not
+user-writable) supplies ``config.yaml`` and ``.env`` values that WIN over the
+user's ``~/.hermes/config.yaml`` and ``~/.hermes/.env`` on a per-leaf-key basis.
+
+This is DISTINCT from ``hermes_cli.config.is_managed()`` / ``HERMES_MANAGED``,
+which is a coarse package-manager write-lock (declarative-distro / formula
+installs). That lock blocks all mutation; this layer injects specific immutable
+values. The two are independent and may coexist.
+
+v1 enforcement is filesystem permissions only — see
+``docs/design/managed-scope.md`` §7. v1 is Linux/POSIX-first; ``get_managed_dir()``
+is the single seam for adding macOS / Windows native locations later.
+
+Attribution: do not reference any third-party product by name in this file.
+"""
+from __future__ import annotations
+
+import copy
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Dict, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# POSIX default. Other-platform locations are a deliberate v2 item; when added,
+# they belong ONLY inside get_managed_dir().
+_DEFAULT_MANAGED_DIR = Path("/etc/hermes")
+
+_CACHE_LOCK = threading.Lock()
+# path_key -> (mtime_ns, size, parsed)
+_CONFIG_CACHE: Dict[str, tuple] = {}
+_ENV_CACHE: Dict[str, tuple] = {}
+
+
+def _under_pytest() -> bool:
+    """True when running inside the test suite.
+
+    Used to ignore the system default ``/etc/hermes`` during tests so a real
+    managed scope on a developer/CI box can't leak policy into the suite. Tests
+    that exercise managed scope set ``HERMES_MANAGED_DIR`` explicitly, which is
+    still honored (the override path below runs before this guard takes effect).
+    """
+    return "PYTEST_CURRENT_TEST" in os.environ
+
+
+def get_managed_dir() -> Optional[Path]:
+    """Resolve the managed-scope directory, or None when no scope is present.
+
+    Resolution (highest priority first):
+      1. ``$HERMES_MANAGED_DIR`` — deployment/bootstrap path override (IT-only;
+         never persisted to any .env). Honored only when set to a non-empty value
+         AND the directory exists.
+      2. ``/etc/hermes`` — POSIX default, when it exists. Ignored under pytest so
+         a real system managed scope can't leak into the test suite.
+
+    A non-existent directory at either tier resolves to None (no managed scope),
+    which is the common case and must be cheap + side-effect-free.
+    """
+    override = os.environ.get("HERMES_MANAGED_DIR", "").strip()
+    if override:
+        p = Path(override)
+        return p if p.is_dir() else None
+    if _under_pytest():
+        return None
+    return _DEFAULT_MANAGED_DIR if _DEFAULT_MANAGED_DIR.is_dir() else None
+
+
+def invalidate_managed_cache() -> None:
+    """Drop cached managed config/env. For tests and post-edit reloads."""
+    with _CACHE_LOCK:
+        _CONFIG_CACHE.clear()
+        _ENV_CACHE.clear()
+
+
+def _cached_read(path: Path, cache: Dict[str, tuple], parse):
+    """Shared (mtime_ns, size)-keyed read. Returns a deepcopy of the parsed value.
+
+    Returns ``None`` when the file is absent or fails to parse (fail-open). A
+    parse failure is logged LOUDLY — the admin needs to know their policy isn't
+    being applied — but never raises, so a malformed managed file can't brick
+    startup.
+    """
+    try:
+        st = path.stat()
+    except OSError:
+        return None  # absent
+    key = (st.st_mtime_ns, st.st_size)
+    path_key = str(path)
+    with _CACHE_LOCK:
+        hit = cache.get(path_key)
+        if hit is not None and hit[:2] == key:
+            return copy.deepcopy(hit[2])
+    try:
+        with open(path, encoding="utf-8") as f:
+            parsed = parse(f)
+    except Exception as exc:  # noqa: BLE001 — fail-open, but LOUD
+        logger.warning(
+            "managed scope: failed to parse %s: %s — IGNORING this managed file. "
+            "Admin policy from this file is NOT being applied. Fix and restart.",
+            path,
+            exc,
+        )
+        return None
+    with _CACHE_LOCK:
+        cache[path_key] = (key[0], key[1], copy.deepcopy(parsed))
+    return parsed
+
+
+def load_managed_config() -> dict:
+    """Parsed managed config.yaml, or {} when absent/malformed (fail-open)."""
+    managed_dir = get_managed_dir()
+    if managed_dir is None:
+        return {}
+    parsed = _cached_read(
+        managed_dir / "config.yaml",
+        _CONFIG_CACHE,
+        lambda f: yaml.safe_load(f) or {},
+    )
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def load_managed_env() -> Dict[str, str]:
+    """Parsed managed .env (KEY=VALUE), or {} when absent (fail-open)."""
+    managed_dir = get_managed_dir()
+    if managed_dir is None:
+        return {}
+    parsed = _cached_read(managed_dir / ".env", _ENV_CACHE, _parse_env)
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def apply_managed_overlay(config: dict) -> dict:
+    """Overlay administrator-pinned config values on top of an already-built dict.
+
+    The single, shared way for any config loader that builds its own dict
+    (rather than going through hermes_cli.config.load_config) to honor managed
+    scope. Mirrors hermes_cli.config._load_config_impl's managed merge exactly:
+
+      * expand the managed config's ``${VAR}`` refs against the PROCESS env only
+        (never user-config-defined refs), so a user cannot shadow a managed
+        literal via a ${VAR} they control;
+      * normalize the managed config's root ``model`` key (a bare ``model: x/y``
+        string is promoted to ``model.default``) so it can't clobber the dict
+        shape callers expect;
+      * leaf-level deep-merge managed ON TOP, so managed wins per-leaf while
+        sibling keys stay user-controlled.
+
+    Fail-open: returns ``config`` unchanged if no managed scope is present or on
+    any error — managed scope must never break a caller's startup. Mutates and
+    returns ``config`` (callers pass a dict they own).
+    """
+    try:
+        managed = load_managed_config()
+        if not managed:
+            return config
+        # Imported lazily to avoid an import cycle (config imports managed_scope).
+        from hermes_cli.config import _deep_merge, _expand_env_vars, _normalize_root_model_keys
+
+        managed_expanded = _normalize_root_model_keys(_expand_env_vars(managed))
+        # A bare ``model: x/y`` string in the managed file must merge as
+        # ``model.default`` — otherwise _deep_merge would replace the caller's
+        # ``model`` dict with a string and break every ``cfg["model"]["..."]``
+        # read. _normalize_root_model_keys only promotes the string when there
+        # are root provider/base_url keys to migrate, so handle the bare case
+        # here (matches cli.py's own string-model handling).
+        if isinstance(managed_expanded.get("model"), str):
+            managed_expanded = dict(managed_expanded)
+            managed_expanded["model"] = {"default": managed_expanded["model"]}
+        return _deep_merge(config, managed_expanded)
+    except Exception:  # noqa: BLE001 — overlay must never break a caller
+        logger.warning("managed scope: failed to apply config overlay", exc_info=True)
+        return config
+
+
+def _parse_env(f) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for line in f:
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        out[key.strip()] = value.strip().strip("\"'")
+    return out
+
+
+def _flatten_keys(d: dict, prefix: str = "") -> set:
+    keys: set = set()
+    for k, v in d.items():
+        dotted = f"{prefix}.{k}" if prefix else str(k)
+        if isinstance(v, dict) and v:
+            keys |= _flatten_keys(v, dotted)
+        else:
+            keys.add(dotted)
+    return keys
+
+
+def managed_config_keys() -> set:
+    """Dotted leaf keys pinned by the managed config (e.g. {'model.default'})."""
+    return _flatten_keys(load_managed_config())
+
+
+def is_key_managed(dotted_key: str) -> bool:
+    """True if the exact dotted config key is pinned by the managed layer."""
+    return dotted_key in managed_config_keys()
+
+
+def is_env_managed(name: str) -> bool:
+    """True if the env var name is pinned by the managed .env layer."""
+    return name in load_managed_env()

package/agent/hermes_cli/managed_uv.py

@@ -0,0 +1,254 @@
+"""Managed uv — one path, no guessing.
+
+Hermes owns its own uv binary at ``$HERMES_HOME/bin/uv`` (or ``uv.exe`` on
+Windows).  Every code path that needs uv resolves it from that single location.
+If the binary is missing, ``ensure_uv()`` bootstraps it via the official
+standalone installer with ``UV_UNMANAGED_INSTALL`` / ``UV_INSTALL_DIR`` pointed
+at ``$HERMES_HOME/bin`` so the installer writes directly there — no PATH
+probing, no conda guards, no multi-location resolution chains.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from hermes_constants import get_hermes_home
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+def managed_uv_path() -> Path:
+    """Return the path where Hermes keeps *its* uv binary.
+
+    ``$HERMES_HOME/bin/uv`` on POSIX, ``$HERMES_HOME\\bin\\uv.exe`` on
+    Windows.  The directory may not exist yet — callers should use
+    ``ensure_uv()`` to bootstrap it.
+    """
+    home = get_hermes_home()
+    if platform.system() == "Windows":
+        return home / "bin" / "uv.exe"
+    return home / "bin" / "uv"
+
+
+def resolve_uv() -> Optional[str]:
+    """Return the managed uv path if it exists, else ``None``.
+
+    No side effects — pure lookup.
+    """
+    p = managed_uv_path()
+    if p.is_file() and os.access(p, os.X_OK):
+        return str(p)
+    return None
+
+
+class _UvResult(str):
+    """``ensure_uv()`` return value that survives an update boundary.
+
+    ``ensure_uv()``'s arity has flipped between a single path string and a
+    ``(path, fresh_bootstrap)`` tuple across releases. ``hermes update`` runs
+    the call site from the *old*, already-imported ``hermes_cli.main`` against
+    this *freshly pulled* module, so the two can disagree on how many values
+    ``ensure_uv()`` returns. An install parked on a 2-tuple release runs
+    ``uv_bin, fresh_bootstrap = ensure_uv()`` against the single-value module
+    and crashes the first update: the returned path is a plain ``str``, which is
+    itself iterable, so the 2-target unpack walks its characters and raises
+    ``ValueError: too many values to unpack (expected 2)`` (and on the failure
+    path the ``None`` return raises ``TypeError: cannot unpack non-iterable
+    NoneType``). This wrapper answers to both conventions:
+
+        uv_bin = ensure_uv()         # behaves as the path str ("" when absent)
+        uv_bin, fresh = ensure_uv()  # unpacks as (path|None, fresh_bootstrap)
+
+    Missing uv is the empty string (falsy) instead of ``None`` so legacy
+    2-target call sites can still unpack a failure without raising, while
+    ``if not uv_bin`` keeps working for single-value callers.
+
+    POSIX only. This wrapper is **never** returned on Windows — see
+    ``ensure_uv()`` for why the ``__iter__`` override is unsafe there.
+    """
+
+    fresh_bootstrap: bool
+
+    def __new__(cls, path: Optional[str], fresh: bool = False) -> "_UvResult":
+        self = super().__new__(cls, path or "")
+        self.fresh_bootstrap = fresh
+        return self
+
+    def __iter__(self):
+        # Tuple-unpacking hook for legacy ``uv_bin, fresh = ensure_uv()`` sites.
+        # First element mirrors the historical contract: the path string, or
+        # ``None`` when uv is unavailable.
+        return iter(((str(self) or None), self.fresh_bootstrap))
+
+
+def _ensure_uv_path() -> Optional[str]:
+    """Resolve the managed uv path, installing it if necessary (plain ``str``/``None``)."""
+    existing = resolve_uv()
+    if existing:
+        return existing
+
+    target = managed_uv_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    print(f"  → Installing managed uv into {target.parent} ...")
+
+    try:
+        _install_uv(target)
+    except Exception as exc:
+        logger.warning("Managed uv install failed: %s", exc)
+        print(f"  ✗ Failed to install managed uv: {exc}")
+        return None
+
+    # Verify
+    result = resolve_uv()
+    if result:
+        version = subprocess.run(
+            [result, "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout.strip()
+        print(f"  ✓ Managed uv installed ({version})")
+    else:
+        print("  ✗ Managed uv install appeared to succeed but binary not found")
+    return result
+
+
+def ensure_uv():
+    """Return the managed uv path, installing it first if necessary.
+
+    On **POSIX** the result is a :class:`_UvResult` (a ``str`` subclass) that is
+    both usable directly as the path *and* unpackable as
+    ``(path, fresh_bootstrap)`` for older call sites parked on a 2-tuple
+    release — see :class:`_UvResult` for the update-boundary rationale.
+
+    On **Windows** we deliberately return a plain ``str``/``None`` instead.
+    ``subprocess`` there serializes the argv via ``subprocess.list2cmdline``,
+    which iterates every entry *as a string* (``for c in arg``). The dependency
+    installer passes uv straight into the command list (``[uv_bin, "pip", ...]``),
+    so a ``_UvResult`` — whose ``__iter__`` yields ``(path, fresh_bootstrap)``
+    rather than characters — would inject the bool into the command line and
+    crash the install with ``TypeError: sequence item 1: expected str instance,
+    bool found``. A plain ``str`` matches the historical Windows contract and is
+    subprocess-safe. (A single value cannot satisfy both 2-target unpacking and
+    Windows char-iteration: both use the iterator protocol, with contradictory
+    results.)
+
+    On failure the result is falsy — never raises — so callers can fall back to
+    pip gracefully.
+    """
+    result = _ensure_uv_path()
+    if platform.system() == "Windows":
+        # See docstring: a str subclass with an overridden __iter__ is unsafe as
+        # a Windows subprocess argument. Hand back the plain path (or None).
+        return result
+    return _UvResult(result)
+
+
+def update_managed_uv() -> Optional[str]:
+    """Run ``uv self update`` on the managed uv binary.
+
+    Call this during ``hermes update`` so the managed copy stays current.
+    Returns the managed path on success, ``None`` if uv isn't available or
+    the self-update fails (non-fatal — the old version still works).
+    """
+    existing = resolve_uv()
+    if not existing:
+        # Not installed yet — ensure_uv() will handle that elsewhere.
+        return None
+
+    result = subprocess.run(
+        [existing, "self", "update"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0:
+        version = subprocess.run(
+            [existing, "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout.strip()
+        print(f"  ✓ Managed uv updated ({version})")
+    else:
+        # Non-fatal — old uv still works fine.
+        logger.debug("uv self update failed (rc=%d): %s", result.returncode, result.stderr)
+    return existing
+
+
+# ---------------------------------------------------------------------------
+# Installer internals
+# ---------------------------------------------------------------------------
+
+def _install_uv(target: Path) -> None:
+    """Bootstrap uv into *target* using the official standalone installer.
+
+    Uses ``UV_UNMANAGED_INSTALL`` (POSIX) or ``UV_INSTALL_DIR`` (Windows)
+    so the astral installer writes the binary directly into
+    ``$HERMES_HOME/bin/`` instead of ``~/.local/bin/``.
+    """
+    system = platform.system()
+    env = {
+        **os.environ,
+        # Tell the astral installer to drop the binary in our dir, not
+        # ~/.local/bin.  UV_UNMANAGED_INSTALL is the POSIX env var; Windows
+        # uses UV_INSTALL_DIR.
+        "UV_UNMANAGED_INSTALL": str(target.parent),
+        "UV_INSTALL_DIR": str(target.parent),
+    }
+
+    if system == "Windows":
+        _install_uv_windows(env)
+    else:
+        _install_uv_posix(env)
+
+
+def _install_uv_posix(env: dict[str, str]) -> None:
+    """Download + sh the POSIX installer (two-stage to avoid curl|sh pitfalls)."""
+    with tempfile.NamedTemporaryFile(suffix=".sh", delete=False) as f:
+        installer_path = f.name
+
+    try:
+        subprocess.run(
+            ["curl", "-LsSf", "https://astral.sh/uv/install.sh", "-o", installer_path],
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["sh", installer_path],
+            env=env,
+            check=True,
+            capture_output=True,
+        )
+    finally:
+        try:
+            os.unlink(installer_path)
+        except OSError:
+            pass
+
+
+def _install_uv_windows(env: dict[str, str]) -> None:
+    """Invoke the PowerShell installer."""
+    cmd = (
+        'irm https://astral.sh/uv/install.ps1 | iex'
+    )
+    subprocess.run(
+        ["powershell", "-ExecutionPolicy", "Bypass", "-c", cmd],
+        env=env,
+        check=True,
+        capture_output=True,
+    )
+
+def rebuild_venv(uv_bin: str, venv_dir: Path, python_version: str = "3.11") -> bool:
+    True # dont remove me. ask ethernet

package/agent/hermes_cli/mcp_catalog.py

@@ -730,9 +730,12 @@ def install_entry(entry: CatalogEntry, *, enable: bool = True) -> None:
     server_cfg = _build_server_config(entry, install_dir)
     server_cfg["enabled"] = enable
 
-    cfg = load_config()
-    cfg.setdefault("mcp_servers", {})[entry.name] = server_cfg
-    save_config(cfg)
+    from hermes_cli.mcp_config import _save_mcp_server
+
+    if not _save_mcp_server(entry.name, server_cfg):
+        raise CatalogError(
+            f"catalog entry '{entry.name}' rejected: suspicious command/args configuration"
+        )
 
     # ── Probe + tool selection ──────────────────────────────────────────
     _apply_tool_selection(entry, prior_selection=prior_selection)