hermes-profile-kit 3.0.0__py3-none-any.whl

hermes_profile_kit-3.0.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: hermes-profile-kit
+Version: 3.0.0
+Summary: Interactive multi-profile setup utility for Hermes Agent
+Author: NewTurn2017
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: packaging>=23
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13
+Requires-Dist: pyyaml>=6
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# hermes-profile-kit
+
+Interactive multi-profile setup utility for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/NewTurn2017/hermes-profile-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/NewTurn2017/hermes-profile-kit/actions/workflows/ci.yml)
+
+> 🇰🇷 [한국어 README](README.ko.md)
+
+## Quick start
+
+```bash
+pipx install hermes-profile-kit
+hpk setup
+```
+
+The wizard walks you through 4 profiles (`coder` / `assistant` / `research` / `community-bot`), prompts for the right tokens per channel (Anthropic, Telegram, Slack, Discord, Brave, Exa), and optionally enables recommended plugins (Honcho memory, Brave search tool).
+
+## What hpk does (and doesn't)
+
+- ✅ Creates and configures four isolated Hermes profiles.
+- ✅ Walks you through BotFather, Slack app, Discord devportal flows.
+- ✅ Atomic, idempotent `.env` writes (chmod 600). Re-running is safe.
+- ✅ Daily upstream-sync via GitHub Actions — kit stays current with Hermes changes.
+- ❌ Does not install Hermes itself (see [Hermes installation](https://github.com/NousResearch/hermes-agent#installation)).
+- ❌ Does not start gateway services automatically.
+- ❌ Does not invoke any hermes command that isn't verified in upstream.
+
+## How it stays correct
+
+`hpk` never embeds a hermes command that hasn't been observed in the upstream argparse tree. CI AST-parses `hermes_cli/main.py` daily, regenerates `docs/commands.md` and `build/cmd_index.json`, and opens a PR when drift is detected.
+
+## Profiles
+
+| Profile | Role | Model tier | Channels |
+|---|---|---|---|
+| `coder` | Full-stack dev assistant | Sonnet | CLI |
+| `assistant` | Personal daily assistant | Sonnet | CLI + Telegram |
+| `research` | Web-search-backed research | Opus | CLI |
+| `community-bot` | Korean dev community helper | Haiku | Telegram + Discord |
+
+## Customization
+
+| Goal | Edit |
+|---|---|
+| Change model | `~/.hermes/profiles/<name>/config.yaml` |
+| Change persona | `~/.hermes/profiles/<name>/SOUL.md` |
+| Add new profile | `profiles/<name>/{SOUL.md,config.yaml,.env.example}` + add to `manifest.yaml` → `hpk setup` |
+| Enable a plugin | Add to `manifest.yaml` `plugins:` + reference from `recommended_plugins` |
+
+API keys go in `~/.hermes/profiles/<name>/.env`. They're plain text with `chmod 600` — the kit deliberately does not pretend to encrypt them.
+
+## Commands
+
+```bash
+hpk setup [profile...]    # interactive wizard
+hpk verify                # doctor + FILL_IN scan
+hpk doctor                # hpk's own health
+hpk reset [profile...]    # remove kit-created profiles
+hpk plugin list           # show recommended_plugins
+hpk sync --dry-run        # local drift check
+```
+
+## License
+
+MIT. See `LICENSE`.

hermes_profile_kit-3.0.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+hermes_profile_kit-3.0.0.dist-info/licenses/LICENSE,sha256=iTBxQ9WZ2-L-KeZMp8W-407SjHn6qfJUre0ttsxOcRs,1088
+hpk/__init__.py,sha256=SHKS8O7Zr5v3GtKtenjHsi8UzlQ-pqiEloZsaoQGGE8,102
+hpk/__main__.py,sha256=FZiPysFNO838bO1S3ReezODEpqTCxbCo7xrdbg3HOXk,64
+hpk/cli.py,sha256=tRG4P2ss6jXxyxRu9MeCFGOyWHZ_eztgYIR1c7j8Oxc,5457
+hpk/hermes.py,sha256=0RsBq9XuRoNX61C1Xv4n_QN0jaB13ycss0ou6ESD2ag,1778
+hpk/manifest.py,sha256=iIxLmDy960tQqlNpqS7ZzAhZ0ImXI-6ivYnbNbp1hC4,4696
+hpk/plugins.py,sha256=RBagxzlF7RzteZQhIMWjm0yFdUrdvr7pDtGS30KISDw,1334
+hpk/profiles.py,sha256=A7pqO3jgbUqxv8cI50A7EypbHHBji6DRRnzg6hB9HaM,2038
+hpk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hpk/ui.py,sha256=Fc0olJay5kTe3WK0iI-4rrWZZRhwwsgjbcQ_ePowD1E,811
+hpk/verify.py,sha256=r1gsnpWEw_Tci4EH3JsvkZoPqPUp69vD9HrzSEn0lbY,1399
+hpk/wizard.py,sha256=co7TpS0cF-TU3TgYq3hPxG0_ADXom6cVcJOEXWPH9_4,6219
+hpk/codegen/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hpk/codegen/argparse_walker.py,sha256=xG_qjHHuXoAuZh-dg7dbzoMP7r2edZsXFenIHMXVzB4,5450
+hpk/codegen/cmd_index.py,sha256=t23QycYW85T-3aXnetm02l459zF2uDNYUIlihljEExg,380
+hpk/codegen/validate.py,sha256=pC6Z-yJUfJcfFEel3VgUC_myaXLdOQDq1jBfjjQ21Fw,962
+hpk/tokens/__init__.py,sha256=OV-ow_cjpwVY70Xy5cCi7khakwzSAaSesJXENLbNktQ,1007
+hpk/tokens/anthropic.py,sha256=cGqck4UpE9iGQFZjhWDrFIUXzGdH4lxBdfbCt3a5eAc,860
+hpk/tokens/base.py,sha256=pzFX1YY3ZZic4CflHhvZ5kfPy_3BHQnk7AFvlnpjXH0,714
+hpk/tokens/brave.py,sha256=cWPwyPSBVcude3le1gQO0GfOvniL5_tzaAB_bllV8NU,392
+hpk/tokens/discord.py,sha256=GHAZSV8VUkX5tCY86xNlBVUEhB95Bl0koZeuNUTgr1w,908
+hpk/tokens/exa.py,sha256=Ty4cwnG82Zi5cEMBE9ZsD50Rgvqri3n4SjcSXXdMVMY,356
+hpk/tokens/openai_codex.py,sha256=4nucup4V3NaYdq88kWSq2s0DGklJZgUG8qhQRhXuT_M,1906
+hpk/tokens/slack.py,sha256=PrUpsR_HzerVxSnW9UKeljptBn_sW6ylovLxrRqdghM,2284
+hpk/tokens/telegram.py,sha256=j7FdJ5sVpTzFgNSpifnwR-_Kqjsmets_TDvapyrjaLA,1008
+hermes_profile_kit-3.0.0.dist-info/METADATA,sha256=_dJBcFic2z9BLwiAHKHF98JWyxvmtbyvmXIztqzViow,3471
+hermes_profile_kit-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hermes_profile_kit-3.0.0.dist-info/entry_points.txt,sha256=mTD3trrxMLeXb8GSa2I7FMWMkZcGnpdnvMSJgbiZdvE,37
+hermes_profile_kit-3.0.0.dist-info/top_level.txt,sha256=0z09FxxjgTbwE_GASKtD2h_UYtNVRrXvwOkNermRB58,4
+hermes_profile_kit-3.0.0.dist-info/RECORD,,

hermes_profile_kit-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hermes_profile_kit-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hpk = hpk.cli:main

hermes_profile_kit-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hermes-profile-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_profile_kit-3.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hpk

hpk/__init__.py

@@ -0,0 +1,3 @@
+"""hermes-profile-kit — interactive multi-profile setup for Hermes Agent."""
+
+__version__ = "3.0.0"

hpk/__main__.py

@@ -0,0 +1,4 @@
+from hpk.cli import main
+
+if __name__ == "__main__":
+    main()

hpk/cli.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from hpk import __version__, ui, verify, wizard
+from hpk.manifest import Manifest, ManifestValidationError, load_manifest
+
+
+def _manifest_path() -> Path:
+    return Path.cwd() / "manifest.yaml"
+
+
+def _load() -> Manifest:
+    try:
+        return load_manifest(_manifest_path())
+    except ManifestValidationError as e:
+        ui.err(f"manifest invalid: {e}")
+        sys.exit(40)
+    except FileNotFoundError:
+        ui.err(f"manifest.yaml not found at {_manifest_path()}")
+        sys.exit(40)
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(version=__version__, prog_name="hpk")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """hpk — interactive multi-profile setup for Hermes Agent."""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(setup)
+
+
+@main.command()
+@click.argument("profile", nargs=-1)
+@click.option("--force", is_flag=True, help="Overwrite SOUL.md/config.yaml even if present.")
+@click.option("--skip-tokens", is_flag=True)
+@click.option("--skip-plugins", is_flag=True)
+def setup(
+    profile: tuple[str, ...],
+    force: bool,
+    skip_tokens: bool,
+    skip_plugins: bool,
+) -> None:
+    """Interactive multi-profile setup."""
+    manifest = _load()
+    try:
+        wizard.run_wizard(
+            manifest,
+            targets=list(profile),
+            force=force,
+            skip_tokens=skip_tokens,
+            skip_plugins=skip_plugins,
+        )
+    except wizard.HermesNotInstalledError as e:
+        ui.err(str(e))
+        sys.exit(10)
+    except wizard.HermesVersionTooOldError as e:
+        ui.err(str(e))
+        sys.exit(11)
+    except wizard.PreflightError as e:
+        ui.err(str(e))
+        sys.exit(30)
+
+
+@main.command()
+@click.argument("profile", nargs=-1)
+def verify_cmd(profile: tuple[str, ...]) -> None:
+    """Run hermes doctor + FILL_IN scan."""
+    manifest = _load()
+    names = list(profile) or [p.name for p in manifest.profiles]
+    r = verify.run_verify(names)
+    for name in r.passing:
+        ui.ok(f"{name}: doctor green")
+    for name, reason in r.failing:
+        ui.err(f"{name}: {reason}")
+    for name, rows in r.fill_in_remaining.items():
+        for line, key in rows:
+            ui.warn(f"{name}/.env:{line}: {key} still FILL_IN")
+    sys.exit(0 if r.ok else 30)
+
+
+@main.command()
+def doctor() -> None:
+    """Check hpk's own health: hermes presence, manifest validity, codegen freshness."""
+    manifest = _load()
+    from hpk import hermes as _h
+
+    try:
+        v = _h.get_version()
+        ui.ok(f"hermes {v}")
+    except _h.HermesNotFoundError:
+        ui.err("hermes not found")
+        sys.exit(10)
+    ui.ok(f"manifest valid; pinned to {manifest.upstream.pinned_commit}")
+
+
+@main.command()
+@click.argument("profile", nargs=-1)
+@click.option("--yes", is_flag=True, help="Skip confirmation.")
+@click.option("--backup", is_flag=True, help="Export profile before deleting.")
+def reset(profile: tuple[str, ...], yes: bool, backup: bool) -> None:
+    """Remove profiles created by this kit (never touches default ~/.hermes/)."""
+    manifest = _load()
+    names = list(profile) or [p.name for p in manifest.profiles]
+    if not yes:
+        click.confirm(f"Really delete profiles: {', '.join(names)}?", abort=True)
+    from hpk import hermes as _h
+
+    for n in names:
+        if backup:
+            _h.run_raw(["hermes", "profile", "export", n])
+        _h.run_raw(["hermes", "profile", "delete", n, "--yes"])
+        ui.ok(f"deleted {n}")
+
+
+@main.group()
+def plugin() -> None:
+    """List, enable, or disable manifest-declared recommended plugins."""
+
+
+@plugin.command("list")
+def plugin_list() -> None:
+    manifest = _load()
+    for p in manifest.profiles:
+        ids = [rp.id for rp in p.recommended_plugins]
+        ui.console.print(f"  {p.name}: {ids or '(none)'}")
+
+
+@plugin.command("enable")
+@click.argument("profile")
+@click.argument("plugin_id")
+def plugin_enable(profile: str, plugin_id: str) -> None:
+    manifest = _load()
+    plugins_catalog = manifest.plugins
+    if plugin_id not in plugins_catalog:
+        ui.err(f"unknown plugin: {plugin_id}")
+        sys.exit(40)
+    from hpk import plugins as _p
+
+    _p.run_plugin(plugins_catalog[plugin_id], profile=profile)
+    ui.ok(f"enabled {plugin_id} for {profile}")
+
+
+@plugin.command("disable")
+@click.argument("profile")
+@click.argument("plugin_id")
+def plugin_disable(profile: str, plugin_id: str) -> None:
+    ui.warn(f"manual disable required for {plugin_id} on {profile}; see plugin docs")
+
+
+@main.command()
+@click.option(
+    "--upstream",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Path to a local hermes-agent clone. Without it, sync prints guidance and exits.",
+)
+@click.option("--dry-run", is_flag=True, help="Run --check mode (no writes).")
+def sync(upstream: Path | None, dry_run: bool) -> None:
+    """Local upstream-drift check (CI does it daily). Requires an upstream clone."""
+    import subprocess as _sp
+
+    if upstream is None:
+        ui.warn("hpk sync needs --upstream PATH (a local hermes-agent clone).")
+        ui.warn("CI's daily upstream-sync workflow does this automatically.")
+        sys.exit(0)
+    cmd = [sys.executable, "scripts/regen_docs.py", "--upstream", str(upstream)]
+    if dry_run:
+        cmd.append("--check")
+    r = _sp.run(cmd)
+    sys.exit(50 if r.returncode else 0)
+
+
+main.add_command(verify_cmd, name="verify")

hpk/codegen/argparse_walker.py

@@ -0,0 +1,158 @@
+"""AST-walk a Python source string/file containing an argparse-based CLI and
+produce a stable flat list of {path, params, help, hidden} nodes per (sub)command.
+
+Used at CI time only. Handles the upstream hermes_cli/main.py shape:
+- argparse.ArgumentParser() at module/function scope
+- nested subparsers via parser.add_subparsers() then xxx.add_parser("name", ...)
+- params via parser.add_argument("--flag", ...) or parser.add_argument("pos", ...)
+- help=argparse.SUPPRESS marks command or argument as hidden
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+
+def _is_suppress(node: ast.expr) -> bool:
+    return (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "argparse"
+        and node.attr == "SUPPRESS"
+    )
+
+
+def _str_kwarg(call: ast.Call, name: str) -> str | None:
+    for kw in call.keywords:
+        if (
+            kw.arg == name
+            and isinstance(kw.value, ast.Constant)
+            and isinstance(kw.value.value, str)
+        ):
+            return kw.value.value
+    return None
+
+
+def _bool_kwarg(call: ast.Call, name: str) -> bool:
+    for kw in call.keywords:
+        if kw.arg == name and isinstance(kw.value, ast.Constant):
+            return bool(kw.value.value)
+    return False
+
+
+def _str_action(call: ast.Call) -> str | None:
+    for kw in call.keywords:
+        if (
+            kw.arg == "action"
+            and isinstance(kw.value, ast.Constant)
+            and isinstance(kw.value.value, str)
+        ):
+            return kw.value.value
+    return None
+
+
+def _has_suppress_help(call: ast.Call) -> bool:
+    for kw in call.keywords:
+        if kw.arg == "help" and _is_suppress(kw.value):
+            return True
+    return False
+
+
+def _param_from_add_argument(call: ast.Call) -> dict[str, Any] | None:
+    """Build a param dict from a parser.add_argument(...) call. Returns None if unparseable."""
+    if not call.args or not isinstance(call.args[0], ast.Constant):
+        return None
+    first = call.args[0].value
+    if not isinstance(first, str):
+        return None
+    is_option = first.startswith("-")
+    name = first.lstrip("-").replace("-", "_")
+    opts: list[str] = []
+    for a in call.args:
+        if isinstance(a, ast.Constant) and isinstance(a.value, str):
+            opts.append(a.value)
+    action = _str_action(call)
+    return {
+        "name": name,
+        "opts": opts,
+        "is_flag": is_option and action in ("store_true", "store_false"),
+        "required": _bool_kwarg(call, "required"),
+        "type": "STRING",
+        "help": None if _has_suppress_help(call) else _str_kwarg(call, "help"),
+        "hidden": _has_suppress_help(call),
+    }
+
+
+def walk_argparse(source: str) -> list[dict[str, Any]]:
+    """Return a flat list of {path, params, help, hidden} for every leaf subparser.
+
+    The root ArgumentParser is not emitted; only its (recursively) descendant
+    subparsers register as nodes.
+    """
+    tree = ast.parse(source)
+
+    parser_path: dict[str, str] = {}  # parser-var → its path ("" for root)
+    subparsers_parent: dict[str, str] = {}  # subparsers-var → parent parser's path
+    nodes: dict[str, dict[str, Any]] = {}  # parser-var → node dict
+    order: list[str] = []  # discovery order of subparser-vars
+
+    # Pass 1: discover parser/subparsers/sub-parser variables and collect nodes.
+    for n in ast.walk(tree):
+        if not isinstance(n, ast.Assign) or len(n.targets) != 1:
+            continue
+        target = n.targets[0]
+        if not isinstance(target, ast.Name):
+            continue
+        var = target.id
+        val = n.value
+        if not isinstance(val, ast.Call) or not isinstance(val.func, ast.Attribute):
+            continue
+        func = val.func
+        if not isinstance(func.value, ast.Name):
+            continue
+        attr = func.attr
+        recv = func.value.id
+
+        if attr == "ArgumentParser" and recv == "argparse":
+            parser_path[var] = ""
+            continue
+
+        if attr == "add_subparsers" and recv in parser_path:
+            subparsers_parent[var] = parser_path[recv]
+            continue
+
+        if attr == "add_parser" and recv in subparsers_parent:
+            if not val.args or not isinstance(val.args[0], ast.Constant):
+                continue
+            cmd = val.args[0].value
+            if not isinstance(cmd, str):
+                continue
+            parent = subparsers_parent[recv]
+            path = f"{parent} {cmd}".strip()
+            parser_path[var] = path
+            nodes[var] = {
+                "path": path,
+                "params": [],
+                "help": None if _has_suppress_help(val) else _str_kwarg(val, "help"),
+                "hidden": _has_suppress_help(val),
+            }
+            order.append(var)
+
+    # Pass 2: attach add_argument calls to their parser nodes.
+    for n in ast.walk(tree):
+        if not isinstance(n, ast.Expr) or not isinstance(n.value, ast.Call):
+            continue
+        call = n.value
+        if not isinstance(call.func, ast.Attribute) or call.func.attr != "add_argument":
+            continue
+        if not isinstance(call.func.value, ast.Name):
+            continue
+        recv = call.func.value.id
+        if recv not in nodes:
+            continue
+        param = _param_from_add_argument(call)
+        if param is not None:
+            nodes[recv]["params"].append(param)
+
+    return [nodes[v] for v in order]

hpk/codegen/cmd_index.py

@@ -0,0 +1,12 @@
+import json
+from pathlib import Path
+from typing import Any, cast
+
+
+def dump(nodes: list[dict[str, Any]], path: Path) -> None:
+    sorted_nodes = sorted(nodes, key=lambda n: n["path"])
+    path.write_text(json.dumps(sorted_nodes, indent=2, sort_keys=True) + "\n")
+
+
+def load(path: Path) -> list[dict[str, Any]]:
+    return cast(list[dict[str, Any]], json.loads(path.read_text()))

hpk/codegen/validate.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hpk.manifest import Plugin
+
+
+def _normalize_cmd(cmd: str) -> str:
+    """Strip 'hermes ' prefix and '{profile}' substitution markers for comparison."""
+    parts = [p for p in cmd.split() if p not in ("hermes", "{profile}")]
+    return " ".join(parts)
+
+
+def find_missing_commands(plugins: dict[str, Plugin], cmd_index: list[dict[str, Any]]) -> list[str]:
+    """Return plugin ids whose upstream_command is not present in cmd_index."""
+    paths = {n["path"] for n in cmd_index}
+    missing: list[str] = []
+    for pid, plugin in plugins.items():
+        if plugin.upstream_command is None:
+            # Kit-local plugins (install_path) have nothing to validate against upstream.
+            continue
+        normalized = _normalize_cmd(plugin.upstream_command)
+        if not any(p == normalized or normalized.endswith(f" {p}") for p in paths):
+            missing.append(pid)
+    return missing

hpk/hermes.py

@@ -0,0 +1,60 @@
+"""Subprocess wrapper around the installed `hermes` binary.
+
+Never imports hermes internals. Every interaction goes through subprocess so
+the kit stays decoupled from upstream API changes.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from collections.abc import Sequence
+
+
+class HermesNotFoundError(RuntimeError):
+    """`hermes` binary is not on PATH."""
+
+
+class HermesVersionError(RuntimeError):
+    """Installed hermes does not meet a required version constraint."""
+
+
+def _run(cmd: Sequence[str], *, check: bool = False) -> subprocess.CompletedProcess[str]:
+    if shutil.which("hermes") is None:
+        raise HermesNotFoundError("hermes binary not found on PATH")
+    return subprocess.run(list(cmd), capture_output=True, text=True, check=check)
+
+
+_VERSION_RE = re.compile(r"Hermes Agent v(\d+\.\d+\.\d+)")
+
+
+def get_version() -> str:
+    """Return the installed Hermes version as `X.Y.Z`."""
+    r = _run(["hermes", "--version"])
+    m = _VERSION_RE.search(r.stdout)
+    if not m:
+        raise HermesVersionError(f"unparseable version output: {r.stdout!r}")
+    return m.group(1)
+
+
+def profile_exists(name: str) -> bool:
+    r = _run(["hermes", "profile", "show", name])
+    return r.returncode == 0
+
+
+def run_profile_create(name: str) -> subprocess.CompletedProcess[str]:
+    return _run(["hermes", "profile", "create", name], check=True)
+
+
+def run_doctor(profile: str | None = None) -> subprocess.CompletedProcess[str]:
+    cmd: list[str] = ["hermes"]
+    if profile is not None:
+        cmd += ["-p", profile]
+    cmd += ["doctor"]
+    return _run(cmd)
+
+
+def run_raw(cmd: Sequence[str]) -> subprocess.CompletedProcess[str]:
+    """Escape hatch for plugins.py to invoke arbitrary verified hermes commands."""
+    return _run(cmd)