hermeskill-hermes 0.1.0a1__tar.gz

hermeskill_hermes-0.1.0a1/.gitignore

@@ -0,0 +1,26 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+*.db
+*.sqlite
+.env
+.env.local
+~/.hermeskill/
+.idea/
+.vscode/
+*.log
+.maestro/
+.claude/settings.local.json
+learn/
+TODO.md
+PUBLISH_READINESS.md

hermeskill_hermes-0.1.0a1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: hermeskill-hermes
+Version: 0.1.0a1
+Summary: Hermeskill apoptosis plugin for Hermes Agent — install once, your agent never runs away again
+Project-URL: Homepage, https://github.com/theopitori/hermeskill
+Project-URL: Documentation, https://github.com/theopitori/hermeskill#readme
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: hermeskill>=0.1.0a1
+Description-Content-Type: text/markdown
+
+# hermeskill-hermes
+
+[Hermeskill](https://github.com/theopitori/hermeskill) apoptosis supervision
+for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Drops in as
+a plugin: Hermeskill watches every tool call and LLM turn in your Hermes session
+and terminates the agent cleanly if it enters a runaway loop, exceeds its
+cost/token cap, runs past a wall-clock deadline, or calls a tool outside the
+policy allowlist.
+
+## Install & enable (zero config)
+
+```bash
+# Install Hermes with the Hermeskill plugin in its environment:
+uv tool install hermes-agent --with hermeskill-hermes
+
+# Install the Hermeskill CLI (`--with hermes-agent` lets enable-hermes read
+# Hermes' config), then put uv's tool dir on PATH and restart your shell:
+uv tool install hermeskill --with hermes-agent
+uv tool update-shell
+
+# Enable it (one shot — flips plugins.enabled in your Hermes config):
+hermeskill enable-hermes
+```
+
+That's it. **No API key, no control plane, no env vars.** Hermes auto-discovers
+the plugin via the `hermes_agent.plugins` entry-point group; `hermeskill
+enable-hermes` adds `hermeskill` to `plugins.enabled`. Run `hermes` and every
+session is supervised. When a runaway is killed, the death certificate prints to
+your terminal and saves to `~/.hermeskill/kills/`.
+
+> **Why `hermeskill enable-hermes` and not `hermes plugins enable hermeskill`?** The
+> latter (and the interactive `hermes plugins` UI) only manage **git-installed**
+> plugins under `~/.hermes/plugins/` — they don't see pip/entry-point plugins
+> like this one. `hermeskill enable-hermes` writes the supported `plugins.enabled`
+> config key for you. (To do it by hand: add `hermeskill` to `plugins.enabled` in
+> `~/.hermes/config.yaml`, Windows `%LOCALAPPDATA%\hermes\config.yaml`.)
+
+## Configure (optional — for a control plane)
+
+Everything above works with nothing set. These add control-plane archival, a
+fleet view, manual kill, and grants:
+
+```bash
+export HERMESKILL_API_KEY=sk-...                                   # ⇒ enables the control plane; unset = local-only
+export HERMESKILL_BASE_URL=https://your-control-plane.example.com  # default localhost:8000
+export HERMESKILL_AGENT_NAME=my-coding-agent                       # display name
+export HERMESKILL_POLICY=coding-default                            # policy
+export HERMESKILL_LOCAL_CERT=0                                     # disable the local cert print/save (default: on)
+```
+
+Or add the same keys to `~/.hermes/.env`, or run `hermeskill init` once to persist
+them to `~/.hermeskill/config.toml`. With a key set, every session is also
+queryable via the operator CLI (`hermeskill fleet`).
+
+## What it does
+
+| Condition | What happens |
+|-----------|-------------|
+| Agent calls the same tool 5× in a row with identical inputs | Kill (`loop`) |
+| Cumulative LLM cost exceeds policy cap | Kill (`token_runaway`) |
+| Session runs longer than policy wall-clock cap | Kill (`wall_clock`) |
+| Agent calls a tool not in the policy allowlist | Kill (`tool_scope_violation`) |
+| Operator issues `hermeskill kill <agent_id>` | Kill (`manual_kill`) |
+| Operator issues a grant | Suppress one symptom type for up to 24 h |
+
+## How the kill works
+
+Hermes hooks are non-blocking — they can't raise out of the agent loop.
+Hermeskill uses Hermes' canonical interception path: when an apoptosis check
+fires, the plugin's `pre_tool_call` callback returns
+
+```python
+{"action": "block", "message": "hermeskill apoptosis: <reason>. End the session."}
+```
+
+Hermes refuses to run the tool and surfaces that message as the tool error
+to the LLM. The harm is halted **immediately** — no further tool execution,
+no further cost — and every subsequent tool call also blocks until the
+agent's loop ends naturally. At session end, `on_session_end` fires and the
+plugin posts a death certificate (full symptom log, shutdown sequence,
+feedback URL) to the control plane.
+
+This is the same pattern Hermes' built-in `security-guidance` plugin uses
+for its strict block mode, and it's documented in PR #26759 as the canonical
+interception path for "rate limiting, security restrictions, approval
+workflows."
+
+## Policies
+
+Shipped defaults:
+
+| Policy | Loop cap | Cost cap | Wall-clock cap |
+|--------|----------|----------|----------------|
+| `strict` | 3 repeats / 15 actions | $2.00 | 5 min |
+| `coding-default` | 5 repeats / 20 actions | $25.00 | 30 min |
+| `permissive` | 10 repeats / 40 actions | $100.00 | 2 h |
+
+## Operator CLI
+
+```bash
+hermeskill fleet
+hermeskill logs <agent_id>
+hermeskill kill <agent_id> --reason "infinite loop in file search"
+hermeskill grant <agent_id> --symptoms loop --duration 1h --reason "known flaky task"
+hermeskill revoke <grant_id>
+```
+
+See the [repo root README](https://github.com/theopitori/hermeskill#readme)
+for the full operator workflow, security model, and deployment guide.
+
+## Hermes hooks used
+
+The plugin attaches to five hooks (see `hermes_cli/plugins.py::VALID_HOOKS`):
+
+| Hook | Why |
+|---|---|
+| `pre_tool_call` | The checkpoint — runs all symptom checks; returns the block directive if armed |
+| `post_tool_call` | Records tool outcome; re-runs cost/wall-clock checks |
+| `pre_llm_call` | Lifecycle marker (model name) |
+| `post_api_request` | Token + cost accounting (this hook carries `usage` in v0.14, not `post_llm_call`) |
+| `on_session_end` | Flush death cert, tear down background worker |
+
+## License
+
+[MIT](https://github.com/theopitori/hermeskill/blob/main/LICENSE) © 2026 Hermeskill Contributors

hermeskill_hermes-0.1.0a1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "hermeskill-hermes"
+version = "0.1.0a1"
+description = "Hermeskill apoptosis plugin for Hermes Agent — install once, your agent never runs away again"
+readme = "src/hermeskill_hermes/README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "hermeskill>=0.1.0a1",
+]
+
+[project.urls]
+Homepage = "https://github.com/theopitori/hermeskill"
+Documentation = "https://github.com/theopitori/hermeskill#readme"
+
+# Hermes Agent plugin auto-discovery: when this package is installed,
+# Hermes finds it via importlib.metadata. The loader does
+# `module = ep.load(); getattr(module, "register")` — so the entry-point
+# value must resolve to the MODULE (which exposes register(ctx)), NOT the
+# function itself. Pointing at `hermeskill_hermes:register` would make
+# ep.load() return the function, and getattr(function, "register") is
+# None → "no register() function". See hermes_cli/plugins.py
+# ::_load_entrypoint_module + _load_plugin.
+[project.entry-points."hermes_agent.plugins"]
+hermeskill = "hermeskill_hermes"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hermeskill_hermes"]
+
+# Ship plugin.yaml inside the wheel so the directory-install path
+# (cp -r into ~/.hermes/plugins/hermeskill/) also has a valid manifest.
+# Entry-point installs don't read this file but won't reject it either.
+[tool.hatch.build.targets.wheel.force-include]
+"src/hermeskill_hermes/plugin.yaml" = "hermeskill_hermes/plugin.yaml"

hermeskill_hermes-0.1.0a1/src/hermeskill_hermes/README.md

@@ -0,0 +1,125 @@
+# hermeskill-hermes
+
+[Hermeskill](https://github.com/theopitori/hermeskill) apoptosis supervision
+for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Drops in as
+a plugin: Hermeskill watches every tool call and LLM turn in your Hermes session
+and terminates the agent cleanly if it enters a runaway loop, exceeds its
+cost/token cap, runs past a wall-clock deadline, or calls a tool outside the
+policy allowlist.
+
+## Install & enable (zero config)
+
+```bash
+# Install Hermes with the Hermeskill plugin in its environment:
+uv tool install hermes-agent --with hermeskill-hermes
+
+# Install the Hermeskill CLI (`--with hermes-agent` lets enable-hermes read
+# Hermes' config), then put uv's tool dir on PATH and restart your shell:
+uv tool install hermeskill --with hermes-agent
+uv tool update-shell
+
+# Enable it (one shot — flips plugins.enabled in your Hermes config):
+hermeskill enable-hermes
+```
+
+That's it. **No API key, no control plane, no env vars.** Hermes auto-discovers
+the plugin via the `hermes_agent.plugins` entry-point group; `hermeskill
+enable-hermes` adds `hermeskill` to `plugins.enabled`. Run `hermes` and every
+session is supervised. When a runaway is killed, the death certificate prints to
+your terminal and saves to `~/.hermeskill/kills/`.
+
+> **Why `hermeskill enable-hermes` and not `hermes plugins enable hermeskill`?** The
+> latter (and the interactive `hermes plugins` UI) only manage **git-installed**
+> plugins under `~/.hermes/plugins/` — they don't see pip/entry-point plugins
+> like this one. `hermeskill enable-hermes` writes the supported `plugins.enabled`
+> config key for you. (To do it by hand: add `hermeskill` to `plugins.enabled` in
+> `~/.hermes/config.yaml`, Windows `%LOCALAPPDATA%\hermes\config.yaml`.)
+
+## Configure (optional — for a control plane)
+
+Everything above works with nothing set. These add control-plane archival, a
+fleet view, manual kill, and grants:
+
+```bash
+export HERMESKILL_API_KEY=sk-...                                   # ⇒ enables the control plane; unset = local-only
+export HERMESKILL_BASE_URL=https://your-control-plane.example.com  # default localhost:8000
+export HERMESKILL_AGENT_NAME=my-coding-agent                       # display name
+export HERMESKILL_POLICY=coding-default                            # policy
+export HERMESKILL_LOCAL_CERT=0                                     # disable the local cert print/save (default: on)
+```
+
+Or add the same keys to `~/.hermes/.env`, or run `hermeskill init` once to persist
+them to `~/.hermeskill/config.toml`. With a key set, every session is also
+queryable via the operator CLI (`hermeskill fleet`).
+
+## What it does
+
+| Condition | What happens |
+|-----------|-------------|
+| Agent calls the same tool 5× in a row with identical inputs | Kill (`loop`) |
+| Cumulative LLM cost exceeds policy cap | Kill (`token_runaway`) |
+| Session runs longer than policy wall-clock cap | Kill (`wall_clock`) |
+| Agent calls a tool not in the policy allowlist | Kill (`tool_scope_violation`) |
+| Operator issues `hermeskill kill <agent_id>` | Kill (`manual_kill`) |
+| Operator issues a grant | Suppress one symptom type for up to 24 h |
+
+## How the kill works
+
+Hermes hooks are non-blocking — they can't raise out of the agent loop.
+Hermeskill uses Hermes' canonical interception path: when an apoptosis check
+fires, the plugin's `pre_tool_call` callback returns
+
+```python
+{"action": "block", "message": "hermeskill apoptosis: <reason>. End the session."}
+```
+
+Hermes refuses to run the tool and surfaces that message as the tool error
+to the LLM. The harm is halted **immediately** — no further tool execution,
+no further cost — and every subsequent tool call also blocks until the
+agent's loop ends naturally. At session end, `on_session_end` fires and the
+plugin posts a death certificate (full symptom log, shutdown sequence,
+feedback URL) to the control plane.
+
+This is the same pattern Hermes' built-in `security-guidance` plugin uses
+for its strict block mode, and it's documented in PR #26759 as the canonical
+interception path for "rate limiting, security restrictions, approval
+workflows."
+
+## Policies
+
+Shipped defaults:
+
+| Policy | Loop cap | Cost cap | Wall-clock cap |
+|--------|----------|----------|----------------|
+| `strict` | 3 repeats / 15 actions | $2.00 | 5 min |
+| `coding-default` | 5 repeats / 20 actions | $25.00 | 30 min |
+| `permissive` | 10 repeats / 40 actions | $100.00 | 2 h |
+
+## Operator CLI
+
+```bash
+hermeskill fleet
+hermeskill logs <agent_id>
+hermeskill kill <agent_id> --reason "infinite loop in file search"
+hermeskill grant <agent_id> --symptoms loop --duration 1h --reason "known flaky task"
+hermeskill revoke <grant_id>
+```
+
+See the [repo root README](https://github.com/theopitori/hermeskill#readme)
+for the full operator workflow, security model, and deployment guide.
+
+## Hermes hooks used
+
+The plugin attaches to five hooks (see `hermes_cli/plugins.py::VALID_HOOKS`):
+
+| Hook | Why |
+|---|---|
+| `pre_tool_call` | The checkpoint — runs all symptom checks; returns the block directive if armed |
+| `post_tool_call` | Records tool outcome; re-runs cost/wall-clock checks |
+| `pre_llm_call` | Lifecycle marker (model name) |
+| `post_api_request` | Token + cost accounting (this hook carries `usage` in v0.14, not `post_llm_call`) |
+| `on_session_end` | Flush death cert, tear down background worker |
+
+## License
+
+[MIT](https://github.com/theopitori/hermeskill/blob/main/LICENSE) © 2026 Hermeskill Contributors

hermeskill_hermes-0.1.0a1/src/hermeskill_hermes/__init__.py

@@ -0,0 +1,256 @@
+"""Hermeskill Hermes plugin — apoptosis supervision for Hermes Agent.
+
+Installation
+------------
+
+    pip install hermeskill-hermes
+
+Hermes auto-discovers the plugin via the ``hermes_agent.plugins`` entry-point
+group declared in this package's ``pyproject.toml``. No directory copy is
+required. Plugins are opt-in, so enable it by adding ``hermeskill`` to
+``plugins.enabled`` in ``~/.hermes/config.yaml`` (Windows:
+``%LOCALAPPDATA%\\hermes\\config.yaml``)::
+
+    plugins:
+      enabled:
+        - hermeskill
+
+Note: ``hermes plugins enable hermeskill`` and the interactive ``hermes plugins``
+UI only manage git-installed plugins under ``~/.hermes/plugins/`` — they do not
+list pip-installed (entry-point) plugins, which are enabled via the config key
+above. The runtime loader (PluginManager.discover_and_load) still honours
+``plugins.enabled`` for entry-point plugins.
+
+For the legacy directory-install path, copy this package into
+``~/.hermes/plugins/hermeskill/`` (``plugin.yaml`` is shipped alongside the
+sources for that case).
+
+Configuration (env vars or ``~/.hermes/.env``)
+----------------------------------------------
+
+    HERMESKILL_API_KEY      — control-plane API key (OPTIONAL). Without it, Hermeskill
+                           runs local-only: in-process symptom checks still kill
+                           runaways and the death cert prints/saves locally; only
+                           control-plane archival, fleet visibility, manual kill,
+                           and grants need a key + reachable control plane.
+    HERMESKILL_BASE_URL     — control plane URL (default: http://localhost:8000)
+    HERMESKILL_AGENT_NAME   — display name for this session (default: "hermes")
+    HERMESKILL_POLICY       — policy name (default: "coding-default")
+    HERMESKILL_LOCAL_CERT   — print/save the death cert locally on a kill
+                           (default: on; set 0 to disable)
+
+How it works
+------------
+
+Hermes calls ``register(ctx)`` once per session. The plugin attaches five
+keyword-only hook callbacks against the real Hermes v0.14 hook API
+(see ``hermes_cli/plugins.py``):
+
+    pre_tool_call       — checkpoint; may return {"action": "block", ...}
+    post_tool_call      — record outcome
+    pre_llm_call        — lifecycle marker
+    post_api_request    — token + cost accounting (carries the usage dict)
+    on_session_end      — flush death cert, tear down worker
+
+If an apoptosis condition fires (loop, cost, wall-clock, scope, manual kill),
+the plugin's ``pre_tool_call`` returns Hermes' standard block directive on
+every subsequent call. The agent gets a tool error response and the harm
+is halted immediately — no further tool execution, no further cost. The
+session ends cooperatively at the next natural turn boundary, at which
+point ``on_session_end`` posts the death certificate.
+
+Public surface
+--------------
+
+    register(ctx)         — Hermes plugin entry point (sync, called by runtime)
+    async_register(ctx)   — async variant for callers inside a running loop
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from hermeskill.client import HermeskillClient
+from hermeskill.config import SDKConfig
+
+from hermeskill_hermes.plugin import HermeskillPlugin
+
+logger = logging.getLogger("hermeskill_hermes")
+
+__version__ = "0.1.0a1"
+
+_current_plugin: HermeskillPlugin | None = None
+
+
+def register(ctx: Any) -> None:
+    """Hermes plugin entry point. Called once by the Hermes runtime at session start.
+
+    ``ctx`` is the Hermes :class:`PluginContext` (v0.14). We use:
+        ctx.register_hook(event_name, callback)   — wire lifecycle hooks
+    No other ctx surface is required for the cooperative-kill design.
+    """
+    global _current_plugin
+
+    # Resolve via SDKConfig so agent name / policy can come from
+    # ~/.hermeskill/config.toml (written by `hermeskill init`) or env vars, not just
+    # env. The adapter owns the Hermes-specific defaults when unset.
+    config = SDKConfig.load()
+    name = config.agent_name or "hermes"
+    policy = config.policy or "coding-default"
+    # No API key → run in local-only mode: in-process symptom checks still
+    # kill runaways and the death cert prints/saves locally; only control-plane
+    # archival, fleet visibility, manual kill, and grants are unavailable.
+    keyless = not config.api_key
+    client = HermeskillClient.from_config(config, allow_keyless=True)
+
+    plugin = HermeskillPlugin(
+        name=name,
+        policy=policy,
+        client=client,
+        forced_offline=keyless,
+        local_cert=config.local_cert,
+    )
+
+    # Run async setup on the plugin's own session loop thread. Hermes calls
+    # register() synchronously; plugin.start() blocks only the calling thread
+    # (never an event loop) until registration completes. Callers already
+    # inside a running loop should use async_register() instead, which awaits
+    # the same setup without blocking their loop.
+    plugin.start()
+
+    _current_plugin = plugin
+
+    _register_hooks(ctx)
+    logger.info("hermeskill: plugin registered for session (agent=%r, policy=%r)", name, policy)
+
+
+async def async_register(ctx: Any) -> None:
+    """Async variant of register() for callers inside a running event loop."""
+    global _current_plugin
+
+    # Resolve via SDKConfig so agent name / policy can come from
+    # ~/.hermeskill/config.toml (written by `hermeskill init`) or env vars, not just
+    # env. The adapter owns the Hermes-specific defaults when unset.
+    config = SDKConfig.load()
+    name = config.agent_name or "hermes"
+    policy = config.policy or "coding-default"
+    keyless = not config.api_key
+    client = HermeskillClient.from_config(config, allow_keyless=True)
+
+    plugin = HermeskillPlugin(
+        name=name,
+        policy=policy,
+        client=client,
+        forced_offline=keyless,
+        local_cert=config.local_cert,
+    )
+    await plugin.astart()
+
+    _current_plugin = plugin
+
+    _register_hooks(ctx)
+    logger.info("hermeskill: plugin async-registered for session (agent=%r, policy=%r)", name, policy)
+
+
+def _register_hooks(ctx: Any) -> None:
+    """Wire all five hook callbacks. Names match Hermes' VALID_HOOKS set."""
+    ctx.register_hook("pre_tool_call", _on_pre_tool_call)
+    ctx.register_hook("post_tool_call", _on_post_tool_call)
+    ctx.register_hook("pre_llm_call", _on_pre_llm_call)
+    # post_api_request (NOT post_llm_call) carries the token-usage dict in
+    # Hermes v0.14. post_llm_call's canonical payload is just
+    # {session_id, model, platform} — no usage data — so it's useless for
+    # cost tracking. See hermes_cli/hooks.py::_DEFAULT_PAYLOADS.
+    ctx.register_hook("post_api_request", _on_post_api_request)
+    ctx.register_hook("on_session_end", _on_session_end)
+
+
+# --- hook dispatch -----------------------------------------------------------
+# Hermes invokes hooks via cb(**kwargs) (plugins.py::invoke_hook line ~1559).
+# All wrappers MUST be keyword-only and tolerate unknown kwargs via **_extra,
+# so newer Hermes versions adding payload fields don't break us.
+
+
+def _on_pre_tool_call(
+    *,
+    tool_name: str = "",
+    args: Any = None,
+    session_id: str = "",
+    task_id: str = "",
+    tool_call_id: str = "",
+    **_extra: Any,
+) -> dict[str, str] | None:
+    """Hermes invokes this before every tool call.
+
+    Returns ``{"action": "block", "message": ...}`` if apoptosis has fired
+    (Hermes turns that into a tool error the agent sees); ``None`` otherwise.
+    """
+    if _current_plugin is None:
+        return None
+    return _current_plugin.pre_tool_call(tool_name=tool_name, args=args)
+
+
+def _on_post_tool_call(
+    *,
+    tool_name: str = "",
+    args: Any = None,
+    result: Any = None,
+    duration_ms: float = 0,
+    session_id: str = "",
+    task_id: str = "",
+    tool_call_id: str = "",
+    **_extra: Any,
+) -> None:
+    if _current_plugin is None:
+        return
+    _current_plugin.post_tool_call(tool_name=tool_name, args=args, result=result)
+
+
+def _on_pre_llm_call(
+    *,
+    session_id: str = "",
+    user_message: Any = None,
+    conversation_history: Any = None,
+    is_first_turn: bool = False,
+    model: str = "",
+    platform: str = "",
+    **_extra: Any,
+) -> None:
+    if _current_plugin is None:
+        return
+    _current_plugin.pre_llm_call(model=model)
+
+
+def _on_post_api_request(
+    *,
+    session_id: str = "",
+    task_id: str = "",
+    platform: str = "",
+    model: str = "",
+    provider: str = "",
+    base_url: str = "",
+    api_mode: str = "",
+    api_call_count: int = 0,
+    api_duration: float = 0,
+    finish_reason: str = "",
+    message_count: int = 0,
+    response_model: str = "",
+    usage: dict[str, Any] | None = None,
+    assistant_content_chars: int = 0,
+    assistant_tool_call_count: int = 0,
+    **_extra: Any,
+) -> None:
+    if _current_plugin is None:
+        return
+    _current_plugin.post_api_request(
+        model=model,
+        usage=usage or {},
+        api_duration=api_duration,
+    )
+
+
+def _on_session_end(*, session_id: str = "", **_extra: Any) -> None:
+    if _current_plugin is None:
+        return
+    _current_plugin.session_end()