acp-hermes 0.2.5__tar.gz

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/.gitignore

@@ -0,0 +1,12 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GatewayStack
+
+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.

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/README.md

@@ -0,0 +1,137 @@
+# hermes-acp
+
+**Cost & quality X-ray plus deterministic governance for [Hermes Agent](https://github.com/NousResearch/hermes-agent)** — via the [Agentic Control Plane](https://agenticcontrolplane.com).
+
+[![PyPI](https://img.shields.io/pypi/v/hermes-acp)](https://pypi.org/project/hermes-acp/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Python](https://img.shields.io/pypi/pyversions/hermes-acp)](https://pypi.org/project/hermes-acp/)
+
+<p align="center"><img src="docs/assets/report-hero.svg" alt="acp-hermes report — real output: 164 calls, 83% cache hit rate, context composition, per-tool costs" width="860"></p>
+
+Two planes, one plugin:
+
+- **Local metering (no account, nothing leaves your machine)** — every model call and tool call your Hermes agent makes is metered into a local SQLite DB. `acp-hermes report` shows spend by model, cache hit rate, what actually fills your context, tool error rates, and cost per task. `report --json` gives agents their own economics so they can self-optimize.
+- **Cloud governance (optional, free — `acp-hermes login`)** — every tool call is checked against server-side policy (deny / ask / allow with inline approvals), audited with tenant + session attribution, and visible on a team dashboard across all your machines.
+
+Companion to the [Claude Code ACP plugin](https://github.com/agentic-control-plane/claude-code-acp-plugin). Same backend contract, same dashboard, same policies — wired into Hermes's Python plugin system instead of Claude Code's shell hooks.
+
+Full install guide with dashboard walkthrough: [agenticcontrolplane.com/integrations/hermes](https://agenticcontrolplane.com/integrations/hermes)
+
+## Install
+
+```bash
+pip install hermes-acp
+hermes plugins enable acp
+```
+
+That's it — local metering is on. After your next Hermes session:
+
+```bash
+acp-hermes report
+```
+
+```
+ACP local report — last 7 days (this machine, ~/.acp/hermes-local.db)
+
+MODEL SPEND
+  model                    calls   in-tok  out-tok  cache
+  gemini-pro-latest          164     827K     5.2K    83%
+
+CACHE  hit rate 83% (4.1M of 5.0M prompt tokens read from cache)
+
+CONTEXT COMPOSITION (share of prompt chars, all turns)
+  tool results 96% · system 0% · assistant 1% · user 3%
+  Tool results dominate your context — truncating or summarizing large
+  tool outputs is usually the cheapest big win.
+
+TOOLS (top by calls)
+  tool             calls  errors  avg ms   output
+  terminal           160       0    1201    492KB
+```
+
+(That's real output from the autonomous agent that runs our own ops backlog — [governed by the same plugin](https://agenticcontrolplane.com/blog/setup-hermes-autonomous-agent-safely).)
+
+Costs come from Hermes's own pricing engine (same numbers Hermes shows you), including OpenRouter and Bedrock routes. Unknown routes are reported as unpriced, never guessed.
+
+To add policies, approvals, and the cross-machine dashboard:
+
+```bash
+acp-hermes login
+```
+
+`login` opens the dashboard, exchanges your one-time auth token for a workspace API key, and writes it to `~/.acp/credentials`.
+
+## Configure
+
+For non-interactive setups (CI, devcontainers), skip the `login` step and provide the key directly:
+
+```bash
+export ACP_BEARER_TOKEN="gsk_yourslug_..."
+# or
+mkdir -p ~/.acp && echo "gsk_yourslug_..." > ~/.acp/credentials
+```
+
+The env var wins over the file.
+
+Local metering knobs:
+
+```bash
+export ACP_LOCAL_METERING=off      # disable local metering entirely
+export ACP_LOCAL_DB=/path/to.db    # move the DB (default ~/.acp/hermes-local.db)
+```
+
+## CLI
+
+```bash
+acp-hermes report            # local cost & quality X-ray (no account needed)
+acp-hermes report --days 30  # wider window
+acp-hermes report --json     # machine-readable — feed it back to your agent
+acp-hermes login             # browser auth + workspace provisioning (cloud plane)
+acp-hermes status            # check creds + gateway reachability
+acp-hermes logout            # remove ~/.acp/credentials
+```
+
+Optional — point at a non-default backend:
+
+```bash
+export ACP_API_BASE="https://api.agenticcontrolplane.com"  # default
+```
+
+## How it works
+
+The plugin registers four Hermes hooks:
+
+| Hook               | Plane | Behavior                                                   |
+|--------------------|-------|------------------------------------------------------------|
+| `pre_tool_call`    | cloud | POSTs to `/govern/tool-use`. Server returns `allow` / `deny` / `ask`. `deny` blocks with a system message; `ask` escalates to Hermes's native approval prompt; `allow` passes through. |
+| `post_tool_call`   | both  | Records duration, status, and result size locally; POSTs to `/govern/tool-output` for server-side audit, redaction logging, and DLP scanning when logged in. |
+| `post_api_request` | local | Records each LLM API request — model, token buckets (input / output / cache read / cache write / reasoning), latency — and prices it with Hermes's own pricing engine. |
+| `post_llm_call`    | local | Records context composition by role (system / user / assistant / tool results) per turn. |
+
+Local rows land in `~/.acp/hermes-local.db` (SQLite, WAL). Nothing is uploaded from the metering plane.
+
+### Fail-open
+
+Network errors, timeouts (>4s), malformed responses, a full disk, or a locked SQLite file all **fail open** — the tool call proceeds and (for network issues) a warning is written to stderr. ACP must never block or break your work.
+
+### "Ask" semantic
+
+An ACP `ask` decision escalates to **Hermes's native approval gate** — the same inline `[o]nce / [s]ession / [a]lways / [d]eny` prompt Hermes uses for dangerous shell commands. An `[a]lways` answer is scoped to the tool via the plugin's `rule_key` (`acp:<tool>`), so a standing approval never widens beyond the tool the human actually reviewed. (Versions ≤0.1.0 wrongly claimed Hermes had no approval surface and hard-blocked with a dashboard detour — upgrade.)
+
+### Client identity
+
+Sends `X-GS-Client: hermes-plugin/<version>` so the dashboard, policy router, and audit log can distinguish Hermes traffic from Claude Code / Cursor / Codex / etc.
+
+## Troubleshooting
+
+**`hermes-acp` opens an editor/ACP mode instead of this CLI.** Hermes itself ships a `hermes-acp` binary (ACP there = Agent Client Protocol, its editor integration) — install order decides which one owns the name. This package installs **`acp-hermes`** as the unambiguous primary command (0.2.1+); use that. `python -m acp_hermes.cli` also always works.
+
+**`acp-hermes report` says no metered activity.** The metering hooks only run inside Hermes — confirm the plugin is enabled (`hermes plugins list`, then `hermes plugins enable acp`) and run a session. Also check `ACP_LOCAL_METERING` isn't set to `off`.
+
+**Costs show n/a.** Pricing comes from Hermes's engine in-process; routes it can't price (unusual proxies, self-hosted endpoints) are honestly unpriced. Token counts are still exact.
+
+**No audit events appearing on the dashboard.** Check that `ACP_BEARER_TOKEN` is set in the shell that launched `hermes`, not just your `.zshrc` after the fact. Hermes inherits the env at process start.
+
+**Every tool call blocked.** Look at stderr. A `[ACP] gateway unreachable` warning means network failure (fail-open kicked in but something else blocked you — maybe a policy from another hook). A `[ACP] Denied by policy: …` means the server returned `deny`; check the policy in the ACP dashboard.
+
+## License
+
+MIT

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/docs/assets/report-hero.svg

@@ -0,0 +1,26 @@
+<svg viewBox="0 0 860 560" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="14">
+  <rect width="860" height="560" rx="12" fill="#0d1117" stroke="#30363d"/>
+  <circle cx="24" cy="24" r="6" fill="#ff5f57"/><circle cx="44" cy="24" r="6" fill="#febc2e"/><circle cx="64" cy="24" r="6" fill="#28c840"/>
+  <text x="430" y="29" fill="#8b949e" text-anchor="middle" font-size="12">acp-hermes report — live output from a governed Hermes agent</text>
+  <g fill="#c9d1d9">
+    <text x="28" y="64" fill="#7ee787">$ acp-hermes report</text>
+    <text x="28" y="92" fill="#8b949e">ACP local report — last 7 days (this machine, ~/.acp/hermes-local.db)</text>
+    <text x="28" y="126" fill="#79c0ff" font-weight="bold">MODEL SPEND</text>
+    <text x="28" y="148" fill="#8b949e">  model                    calls   in-tok  out-tok  cache</text>
+    <text x="28" y="170">  gemini-pro-latest          164     827K     5.2K    83%</text>
+    <text x="28" y="192">  total                      164     827K     5.2K</text>
+    <text x="28" y="226" fill="#79c0ff" font-weight="bold">CACHE</text>
+    <text x="28" y="248">  hit rate <tspan fill="#7ee787" font-weight="bold">83%</tspan>  (4.1M of 5.0M prompt tokens read from cache)</text>
+    <text x="28" y="282" fill="#79c0ff" font-weight="bold">CONTEXT COMPOSITION (share of prompt chars, all turns)</text>
+    <text x="28" y="304">  tool results <tspan fill="#ffa657">96%</tspan> · system 0% · assistant 1% · user 3%</text>
+    <text x="28" y="326" fill="#8b949e">  Tool results dominate your context — truncating or summarizing</text>
+    <text x="28" y="344" fill="#8b949e">  large tool outputs is usually the cheapest big win.</text>
+    <text x="28" y="378" fill="#79c0ff" font-weight="bold">TOOLS (top by calls)</text>
+    <text x="28" y="400" fill="#8b949e">  tool             calls  errors  avg ms   output</text>
+    <text x="28" y="422">  terminal           160       0    1201    492KB</text>
+    <text x="28" y="444">  execute_code         1       0     110     271B</text>
+    <text x="28" y="466">  skills_list          1       0       0     101B</text>
+    <text x="28" y="500" fill="#8b949e">— metered locally by the acp plugin. zero account, nothing leaves</text>
+    <text x="28" y="518" fill="#8b949e">  the machine. cloud mode adds allow/ask/deny policy + a console.</text>
+  </g>
+</svg>

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hermes-acp"
+version = "0.2.4"
+description = "ACP governance plugin for Hermes Agent — audit and veto every tool call via the Agentic Control Plane."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "GatewayStack" }]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://agenticcontrolplane.com"
+Documentation = "https://agenticcontrolplane.com/integrations/hermes"
+Source = "https://github.com/agentic-control-plane/hermes-acp-plugin"
+Issues = "https://github.com/agentic-control-plane/hermes-acp-plugin/issues"
+
+[project.entry-points."hermes_agent.plugins"]
+acp = "acp_hermes"
+
+[project.scripts]
+# acp-hermes is the primary, unambiguous name. hermes-acp is kept for
+# compatibility but Nous's hermes-agent ships its OWN bin of that name
+# (Agent Client Protocol editor mode) — install order decides who owns it.
+acp-hermes = "acp_hermes.cli:main"
+hermes-acp = "acp_hermes.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acp_hermes"]

acp_hermes-0.2.5/.claude/worktrees/coverage-cmd/src/acp_hermes/__init__.py

@@ -0,0 +1,310 @@
+"""ACP plugin for Hermes Agent: governance + local self-optimization data.
+
+Two independent planes, one plugin:
+
+Cloud governance (needs `hermes-acp login`):
+  - POST /govern/tool-use   — pre-call policy check, can deny / ask / allow
+  - POST /govern/tool-output — post-call observation, fire-and-forget
+  - An ACP `ask` decision escalates to Hermes's NATIVE approval gate
+    ({"action": "approve"}): the user answers [o]nce/[s]ession/[a]lways/[d]eny
+    inline, same as Hermes's own dangerous-shell tier.
+
+Local metering (works with ZERO credentials, nothing leaves the machine):
+  - post_api_request → model calls (tokens, cache buckets, cost via Hermes's
+    own pricing engine) into ~/.acp/hermes-local.db
+  - post_llm_call → context composition by role per turn
+  - post_tool_call → tool durations, status, result sizes
+  Read it back with `hermes-acp report` (or `report --json` for agents that
+  want to optimize themselves). ACP_LOCAL_METERING=off disables.
+
+Everything fails OPEN: an ACP outage, a full disk, or a locked SQLite file
+must never block a Hermes run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from . import local_store, pricing
+
+PLUGIN_VERSION = "0.2.4"
+CLIENT_ID = f"hermes-plugin/{PLUGIN_VERSION}"
+
+DEFAULT_API_BASE = "https://api.agenticcontrolplane.com"
+REQUEST_TIMEOUT_SECONDS = 4.0
+POST_HOOK_PAYLOAD_CEILING = 200 * 1024  # 200 KB, matches backend scan ceiling.
+
+
+def _api_base() -> str:
+    return os.environ.get("ACP_API_BASE", DEFAULT_API_BASE).rstrip("/")
+
+
+def _resolve_token() -> str | None:
+    token = os.environ.get("ACP_BEARER_TOKEN")
+    if token:
+        return token.strip()
+    try:
+        path = Path.home() / ".acp" / "credentials"
+        return path.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def _post_json(path: str, body: dict[str, Any], token: str) -> dict[str, Any] | None:
+    url = f"{_api_base()}{path}"
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "X-GS-Client": CLIENT_ID,
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+            raw = resp.read()
+            if not raw:
+                return {}
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return None
+    except (urllib.error.URLError, TimeoutError, ConnectionError) as exc:
+        sys.stderr.write(f"[ACP] gateway unreachable ({exc}); failing open\n")
+        return None
+
+
+def _block(message: str) -> dict[str, str]:
+    return {"action": "block", "message": message}
+
+
+def _pre_tool_call(
+    tool_name: str,
+    args: dict[str, Any],
+    task_id: str = "",
+    **_: Any,
+) -> dict[str, str] | None:
+    token = _resolve_token()
+    if not token:
+        return None  # Not configured — pass through.
+
+    body = {
+        "tool_name": tool_name,
+        "tool_input": args,
+        "session_id": task_id,
+        "hook_event_name": "PreToolUse",
+        "agent_tier": "interactive",
+    }
+    result = _post_json("/govern/tool-use", body, token)
+    if result is None:
+        return None  # Fail-open on network / parse error.
+
+    decision = result.get("decision")
+    reason = result.get("reason") or "policy did not return a reason"
+    if decision == "deny":
+        return _block(f"[ACP] Denied by policy: {reason}")
+    if decision == "ask":
+        # Escalate to Hermes's native human-approval gate — the same
+        # once/session/always/deny prompt its dangerous-shell tier uses.
+        # rule_key scopes an [a]lways answer to this tool under ACP's grain.
+        return {
+            "action": "approve",
+            "message": f"[ACP] Approval required: {reason}",
+            "rule_key": f"acp:{tool_name}",
+        }
+    return None
+
+
+def _post_tool_call(
+    tool_name: str,
+    args: dict[str, Any],
+    result: str = "",
+    task_id: str = "",
+    session_id: str = "",
+    turn_id: str = "",
+    duration_ms: int = 0,
+    status: str = "",
+    error_type: str = "",
+    **_: Any,
+) -> None:
+    output_str = result if isinstance(result, str) else json.dumps(result, default=str)
+
+    if local_store.metering_enabled():
+        try:
+            local_store.record_tool_call(
+                {
+                    "session_id": session_id or "",
+                    "task_id": task_id or "",
+                    "turn_id": turn_id or "",
+                    "tool_name": tool_name,
+                    "duration_ms": int(duration_ms or 0),
+                    "status": status or "",
+                    "error_type": error_type or "",
+                    "result_bytes": len(output_str.encode("utf-8", errors="replace")),
+                }
+            )
+        except Exception:
+            pass
+
+    token = _resolve_token()
+    if not token:
+        return
+
+    if len(output_str.encode("utf-8")) > POST_HOOK_PAYLOAD_CEILING:
+        output_str = output_str[:POST_HOOK_PAYLOAD_CEILING]
+
+    body = {
+        "tool_name": tool_name,
+        "tool_input": args,
+        "tool_output": output_str,
+        "session_id": task_id,
+        "duration_ms": duration_ms,
+        "hook_event_name": "PostToolUse",
+        "agent_tier": "interactive",
+    }
+    _post_json("/govern/tool-output", body, token)
+
+
+def _post_api_request(
+    model: str = "",
+    provider: str = "",
+    base_url: str = "",
+    api_mode: str = "",
+    usage: dict[str, Any] | None = None,
+    session_id: str = "",
+    task_id: str = "",
+    turn_id: str = "",
+    api_request_id: str = "",
+    api_duration: float = 0.0,
+    finish_reason: str = "",
+    message_count: int = 0,
+    **_: Any,
+) -> None:
+    """Meter one LLM API request into the local store. Never raises."""
+    if not local_store.metering_enabled():
+        return
+    try:
+        u = usage or {}
+        cost_usd, cost_status = pricing.estimate_cost_usd(
+            model, u, provider=provider, base_url=base_url
+        )
+        local_store.record_model_call(
+            {
+                "session_id": session_id or "",
+                "task_id": task_id or "",
+                "turn_id": turn_id or "",
+                "api_request_id": api_request_id or "",
+                "model": model or "",
+                "provider": provider or "",
+                "api_mode": api_mode or "",
+                "input_tokens": int(u.get("input_tokens") or 0),
+                "output_tokens": int(u.get("output_tokens") or 0),
+                "cache_read_tokens": int(u.get("cache_read_tokens") or 0),
+                "cache_write_tokens": int(u.get("cache_write_tokens") or 0),
+                "reasoning_tokens": int(u.get("reasoning_tokens") or 0),
+                "request_count": int(u.get("request_count") or 1),
+                "api_duration_ms": int((api_duration or 0) * 1000),
+                "finish_reason": finish_reason or "",
+                "message_count": int(message_count or 0),
+                "cost_usd": cost_usd,
+                "cost_status": cost_status,
+            }
+        )
+    except Exception:
+        pass
+
+
+def _bucket_for(role: str, part: Any) -> str:
+    if isinstance(part, dict):
+        ptype = str(part.get("type") or "")
+        if ptype in ("tool_result", "tool_response", "function_call_output"):
+            return "tool"
+    if role in ("tool", "function"):
+        return "tool"
+    if role in ("system", "developer"):
+        return "system"
+    if role in ("user", "assistant"):
+        return role
+    return "other"
+
+
+def _part_chars(part: Any) -> int:
+    if part is None:
+        return 0
+    if isinstance(part, str):
+        return len(part)
+    if isinstance(part, dict):
+        for key in ("text", "content", "output"):
+            if key in part:
+                return _part_chars(part[key])
+        try:
+            return len(json.dumps(part, default=str))
+        except Exception:
+            return len(str(part))
+    if isinstance(part, list):
+        return sum(_part_chars(p) for p in part)
+    return len(str(part))
+
+
+def _post_llm_call(
+    conversation_history: list[Any] | None = None,
+    session_id: str = "",
+    task_id: str = "",
+    turn_id: str = "",
+    model: str = "",
+    **_: Any,
+) -> None:
+    """Record context composition by role for one completed turn. Never raises."""
+    if not local_store.metering_enabled():
+        return
+    try:
+        buckets = {"system": 0, "user": 0, "assistant": 0, "tool": 0, "other": 0}
+        history = conversation_history or []
+        for msg in history:
+            role = str(
+                (msg.get("role") if isinstance(msg, dict) else getattr(msg, "role", "")) or ""
+            ).lower()
+            content = msg.get("content") if isinstance(msg, dict) else getattr(msg, "content", None)
+            parts = content if isinstance(content, list) else [content]
+            for part in parts:
+                buckets[_bucket_for(role, part)] += _part_chars(part)
+        local_store.record_turn(
+            {
+                "session_id": session_id or "",
+                "task_id": task_id or "",
+                "turn_id": turn_id or "",
+                "model": model or "",
+                "message_count": len(history),
+                "system_chars": buckets["system"],
+                "user_chars": buckets["user"],
+                "assistant_chars": buckets["assistant"],
+                "tool_chars": buckets["tool"],
+                "other_chars": buckets["other"],
+            }
+        )
+    except Exception:
+        pass
+
+
+def register(ctx: Any) -> None:
+    ctx.register_hook("pre_tool_call", _pre_tool_call)
+    ctx.register_hook("post_tool_call", _post_tool_call)
+    # Metering hooks — registered individually and fail-open so an older
+    # Hermes without these hook names still loads the governance plane.
+    for hook, fn in (
+        ("post_api_request", _post_api_request),
+        ("post_llm_call", _post_llm_call),
+    ):
+        try:
+            ctx.register_hook(hook, fn)
+        except Exception:
+            pass