agentguard-hermes-plugin 0.1.0__py3-none-any.whl

agentguard_hermes/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agentguard_hermes/cli.py

@@ -0,0 +1,55 @@
+import argparse
+import importlib.resources
+import os
+import shutil
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentguard-hermes",
+        description="AgentGuard security monitoring plugin for Hermes Agent",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    install_cmd = sub.add_parser("install", help="Install the plugin into Hermes data directory")
+    install_cmd.add_argument(
+        "--hermes-dir",
+        default=os.path.expanduser("~/.hermes"),
+        metavar="DIR",
+        help="Hermes data directory (default: ~/.hermes)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "install":
+        _install(args.hermes_dir)
+
+
+def _install(hermes_dir: str) -> None:
+    plugin_dir = os.path.join(hermes_dir, "plugins", "agentguard")
+    os.makedirs(plugin_dir, exist_ok=True)
+
+    pkg = importlib.resources.files("agentguard_hermes")
+
+    with importlib.resources.as_file(pkg / "plugin.yaml") as src:
+        shutil.copy2(src, os.path.join(plugin_dir, "plugin.yaml"))
+
+    with importlib.resources.as_file(pkg / "plugin.py") as src:
+        shutil.copy2(src, os.path.join(plugin_dir, "__init__.py"))
+
+    print(f"AgentGuard plugin installed → {plugin_dir}")
+    print()
+    print("Configure via environment variables before starting Hermes:")
+    print()
+    print("  AGENTGUARD_TIMEPLUS_URL     (default: http://localhost:3218)")
+    print("  AGENTGUARD_USERNAME         (default: proton)")
+    print("  AGENTGUARD_PASSWORD")
+    print("  AGENTGUARD_AGENT_ID         (default: hostname)")
+    print("  AGENTGUARD_DEPLOYMENT_ID    (default: local)")
+    print("  AGENTGUARD_DEPLOYMENT_NAME  (default: Local Dev)")
+    print("  AGENTGUARD_STREAM           (default: agentguard_hook_events)")
+
+
+if __name__ == "__main__":
+    main()

agentguard_hermes/plugin.py

@@ -0,0 +1,142 @@
+"""
+AgentGuard plugin for Hermes Agent.
+
+Forwards raw Hermes plugin hook events to the AgentGuard Timeplus stream.
+All kwargs are stored verbatim in event_data. conversation_history is dropped
+— it only contains user/assistant turns (no system prompt) and grows
+unboundedly. The system prompt is not exposed by any Hermes plugin hook.
+
+Plugin hooks (CLI + gateway):
+  on_session_start      session_id, model, platform
+  on_session_end        session_id, completed, interrupted, model, platform
+  on_session_finalize   session_id (may be None), platform
+  on_session_reset      session_id, platform
+  pre_llm_call          session_id, conversation_history, is_first_turn, model, platform, sender_id
+  post_llm_call         session_id, conversation_history, model, platform
+  pre_tool_call         tool_name, args, task_id, session_id, tool_call_id
+  post_tool_call        tool_name, args, result, task_id, session_id, tool_call_id
+  pre_api_request       session_id, model, provider, approx_input_tokens, message_count, ...
+  post_api_request      session_id, model, provider, usage{tokens}, api_duration, ...
+
+Hook name mapping (Hermes → AgentGuard):
+  on_session_end        → "conversation_end"  (fires per chat turn, not true session end)
+  on_session_finalize   → "on_session_end"    (true session teardown)
+  all others            → unchanged
+
+Run ID: session_id (all events in a session share the same run_id).
+
+Install: drop plugin.yaml + __init__.py into ~/.hermes/plugins/agentguard/
+
+Config via environment variables:
+  AGENTGUARD_TIMEPLUS_URL    AGENTGUARD_STREAM   AGENTGUARD_USERNAME
+  AGENTGUARD_PASSWORD        AGENTGUARD_AGENT_ID AGENTGUARD_DEPLOYMENT_ID
+  AGENTGUARD_DEPLOYMENT_NAME
+"""
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.request
+from base64 import b64encode
+from datetime import datetime, timezone
+
+_TIMEPLUS_URL    = os.environ.get("AGENTGUARD_TIMEPLUS_URL", "http://localhost:3218")
+_STREAM          = os.environ.get("AGENTGUARD_STREAM", "agentguard_hook_events")
+_USERNAME        = os.environ.get("AGENTGUARD_USERNAME", "proton")
+_PASSWORD        = os.environ.get("AGENTGUARD_PASSWORD", "")
+_AGENT_ID        = os.environ.get("AGENTGUARD_AGENT_ID") or socket.gethostname()
+_DEPLOYMENT_ID   = os.environ.get("AGENTGUARD_DEPLOYMENT_ID", "local")
+_DEPLOYMENT_NAME = os.environ.get("AGENTGUARD_DEPLOYMENT_NAME", "Local Dev")
+
+_COLUMNS = [
+    "hook_name", "event_time", "session_id", "run_id",
+    "agent_id", "deployment_id", "deployment_name", "session_key",
+    "tool_name", "provider", "model", "hook_decision",
+    "block_reason", "event_data", "agent_type",
+]
+
+_SKIP_KEYS = {"conversation_history"}
+
+
+def _ingest(rows: list) -> None:
+    url = f"{_TIMEPLUS_URL.rstrip('/')}/proton/v1/ingest/streams/{_STREAM}"
+    payload = json.dumps({"columns": _COLUMNS, "data": rows}).encode()
+    req = urllib.request.Request(url, data=payload, method="POST")
+    req.add_header("Content-Type", "application/json")
+    if _USERNAME:
+        token = b64encode(f"{_USERNAME}:{_PASSWORD}".encode()).decode()
+        req.add_header("Authorization", f"Basic {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            resp.read()
+    except urllib.error.URLError as e:
+        print(f"[agentguard] ingest error: {e}", flush=True)
+
+
+def _make_row(hook_name: str, kwargs: dict, *, session_id: str = None) -> list:
+    sid = session_id if session_id is not None else (
+        kwargs.get("session_id") or kwargs.get("task_id") or ""
+    )
+    data = {k: v for k, v in kwargs.items() if k not in _SKIP_KEYS}
+    return [
+        hook_name,
+        datetime.now(timezone.utc).isoformat(),
+        sid,
+        sid,          # run_id = session_id
+        _AGENT_ID,
+        _DEPLOYMENT_ID,
+        _DEPLOYMENT_NAME,
+        "",           # session_key — not available in plugin hooks
+        kwargs.get("tool_name") or "",
+        kwargs.get("provider") or "",
+        kwargs.get("model") or "",
+        "observe",
+        "",
+        json.dumps(data, default=str),
+        "hermes",
+    ]
+
+
+def _hook(hook_name: str):
+    def _cb(**kwargs):
+        _ingest([_make_row(hook_name, kwargs)])
+    _cb.__name__ = f"_{hook_name}"
+    return _cb
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle hooks with non-trivial semantics
+# ---------------------------------------------------------------------------
+
+def _on_session_end(**kwargs):
+    """
+    Hermes fires this after every run_conversation() call (per chat turn).
+    Reported as 'conversation_end' — NOT treated as session termination by AgentGuard.
+    """
+    _ingest([_make_row("conversation_end", kwargs)])
+
+
+def _on_session_finalize(**kwargs):
+    """
+    True session teardown (CLI exit, /new, /reset, gateway GC).
+    Reported as 'on_session_end' so AgentGuard marks the session as closed.
+    """
+    sid = kwargs.get("session_id") or ""
+    _ingest([_make_row("on_session_end", kwargs, session_id=sid)])
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration — called by Hermes on plugin load
+# ---------------------------------------------------------------------------
+def register(ctx):
+    ctx.register_hook("on_session_start",    _hook("on_session_start"))
+    ctx.register_hook("on_session_end",      _on_session_end)       # per-turn → conversation_end
+    ctx.register_hook("on_session_finalize", _on_session_finalize)  # true end → on_session_end
+    ctx.register_hook("on_session_reset",    _hook("on_session_reset"))
+    ctx.register_hook("pre_llm_call",        _hook("pre_llm_call"))
+    ctx.register_hook("post_llm_call",       _hook("post_llm_call"))
+    ctx.register_hook("pre_api_request",     _hook("pre_api_request"))
+    ctx.register_hook("post_api_request",    _hook("post_api_request"))
+    ctx.register_hook("pre_tool_call",       _hook("pre_tool_call"))
+    ctx.register_hook("post_tool_call",      _hook("post_tool_call"))

agentguard_hermes/plugin.yaml

@@ -0,0 +1,14 @@
+name: agentguard
+version: 1.0.0
+description: "Forwards Hermes session and tool events to AgentGuard for real-time security monitoring."
+hooks:
+  - on_session_start
+  - on_session_end
+  - on_session_finalize
+  - on_session_reset
+  - pre_llm_call
+  - post_llm_call
+  - pre_api_request
+  - post_api_request
+  - pre_tool_call
+  - post_tool_call

agentguard_hermes_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: agentguard-hermes-plugin
+Version: 0.1.0
+Summary: AgentGuard security monitoring plugin for Hermes Agent
+Project-URL: Homepage, https://github.com/timeplus/agentguard
+Project-URL: Repository, https://github.com/timeplus/agentguard
+License: Apache-2.0
+Keywords: agentguard,ai-agent,hermes,monitoring,observability,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agentguard-hermes
+
+AgentGuard security monitoring plugin for [Hermes Agent](https://github.com/nousresearch/hermes-agent).
+
+Forwards Hermes session, LLM, and tool-call events to an [AgentGuard](https://github.com/timeplus/agentguard) Timeplus stream for real-time observability and security monitoring.
+
+## Installation
+
+```bash
+pip install agentguard-hermes-plugin
+agentguard-hermes install
+```
+
+This copies the plugin into `~/.hermes/plugins/agentguard/` where Hermes auto-loads it on startup.
+
+## Configuration
+
+Set environment variables before starting Hermes:
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTGUARD_TIMEPLUS_URL` | `http://localhost:3218` | Timeplus Enterprise HTTP endpoint |
+| `AGENTGUARD_USERNAME` | `proton` | Timeplus username |
+| `AGENTGUARD_PASSWORD` | _(empty)_ | Timeplus password |
+| `AGENTGUARD_AGENT_ID` | hostname | Identifier for this agent instance |
+| `AGENTGUARD_DEPLOYMENT_ID` | `local` | Deployment environment tag |
+| `AGENTGUARD_DEPLOYMENT_NAME` | `Local Dev` | Human-readable deployment name |
+| `AGENTGUARD_STREAM` | `agentguard_hook_events` | Target Timeplus stream |
+
+### Example
+
+```bash
+export AGENTGUARD_TIMEPLUS_URL=http://timeplus.example.com:3218
+export AGENTGUARD_USERNAME=proton
+export AGENTGUARD_PASSWORD=secret
+export AGENTGUARD_DEPLOYMENT_ID=production
+export AGENTGUARD_DEPLOYMENT_NAME="Production Hermes"
+
+hermes
+```
+
+## What gets captured
+
+Every Hermes hook event is forwarded to the `agentguard_hook_events` stream:
+
+| Hermes hook | Sent as | Description |
+|---|---|---|
+| `on_session_start` | `on_session_start` | New session begins |
+| `on_session_end` | `conversation_end` | Single chat turn completed |
+| `on_session_finalize` | `on_session_end` | Session fully torn down (CLI exit, `/reset`) |
+| `on_session_reset` | `on_session_reset` | Session rotated via `/new` |
+| `pre_llm_call` | `pre_llm_call` | Before each LLM turn |
+| `post_llm_call` | `post_llm_call` | After each LLM turn |
+| `pre_api_request` | `pre_api_request` | Before each raw API call (token metrics) |
+| `post_api_request` | `post_api_request` | After each raw API call |
+| `pre_tool_call` | `pre_tool_call` | Before each tool execution |
+| `post_tool_call` | `post_tool_call` | After each tool execution |
+
+`conversation_history` is stripped from all events before ingestion — it is unbounded and contains no information not already available from the individual turn events.
+
+## Custom install path
+
+```bash
+agentguard-hermes install --hermes-dir /path/to/hermes/data
+```
+
+## Manual installation (Makefile / Docker)
+
+If you run Hermes via the provided Docker Compose setup in `agents/hermes/`:
+
+```bash
+make configure   # copies plugin into .hermes/plugins/agentguard/
+make cli         # start Hermes CLI with AgentGuard env vars pre-set
+make start       # start Hermes gateway + web dashboard
+```
+
+## Publishing to PyPI
+
+```bash
+pip install hatch
+cd agents/hermes/agentguard-plugin
+hatch build     # produces dist/agentguard_hermes_plugin-*.whl
+hatch publish
+```

agentguard_hermes_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+agentguard_hermes/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+agentguard_hermes/cli.py,sha256=v0bcMqSprY0afhs4cOc3V3_v6wx2ZiJ6nbFpAqIuql8,1818
+agentguard_hermes/plugin.py,sha256=sU8Tpch7aN0VMerBvuJ_gTh61OxP6gtyx3dbRva_x9o,5984
+agentguard_hermes/plugin.yaml,sha256=lTRr22MHEf6HHiJHXgfxIB79aiqbf781-ZcuISsVXoo,341
+agentguard_hermes_plugin-0.1.0.dist-info/METADATA,sha256=nNCFrHU2MwyM1qCfTPZoTwXZe8jzS_P2NODMVLKEk-U,3884
+agentguard_hermes_plugin-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentguard_hermes_plugin-0.1.0.dist-info/entry_points.txt,sha256=jnGpaZskCqHUbTirwLgwwyrBP2Kn5hm_vLQhk-BszdI,65
+agentguard_hermes_plugin-0.1.0.dist-info/RECORD,,

agentguard_hermes_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentguard_hermes_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentguard-hermes = agentguard_hermes.cli:main