proxy-aiops 0.9.2__tar.gz → 0.9.4__tar.gz

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "proxy-aiops",
   "displayName": "Proxy AIops",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.",
   "author": {
     "name": "Wei Zhou",

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "proxy-aiops==0.9.2",
+        "proxy-aiops==0.9.4",
         "proxy-aiops-mcp"
       ]
     }

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.9.4 — 2026-09-17
+
+### Fixed
+- `agent-guardrails.md` promised, in the table headed "what the tool enforces — do not
+  waste prompt budget on these", that all four RCAs "rank findings worst-first" with
+  "priority in the payload". `backend_health_rca` sorts its findings on an internal score
+  removed before return, and `route_conflict_analysis` is in the proxy's own evaluation
+  order — route priority, which is not returned, and which is match order rather than
+  severity. `error_rate_rca` and `cert_expiry_sweep` are genuinely checkable (`errorRatePct`
+  with a `critical`/`warning` `severity`, and `daysToExpiry`), and the row now says only
+  that. The copyable system prompt gained a line about not reading priority off position.
+
+## v0.9.3 — 2026-09-15
+
+### Fixed
+- CLI commands that read the engine without calling an MCP tool now write an
+  audit row, as every MCP call does: they run through the same `@governed_tool`
+  harness, budget and runaway guard included. Before, an operator's CLI reads
+  left no trace in `audit.db`, contrary to the documented guarantee that MCP
+  and CLI are audited alike. A test fails if any engine command escapes it.
+
 ## v0.9.2 — 2026-09-12
 
 ### Changed

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proxy-aiops
-Version: 0.9.2
+Version: 0.9.4
 Summary: Governed AI-ops for Traefik + Caddy + HAProxy reverse proxies / load balancers: routes, services, upstream health, TLS cert expiry sweep, 5xx error-rate RCA, route conflict analysis, and governed writes (caddy config, haproxy server state/weight) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/RELEASE_NOTES.md

@@ -1,5 +1,8 @@
 # Release notes — proxy-aiops 0.5.0
 
+> Historical — this file covers the 0.5.0 release only and is not updated.
+> For every release since, see [CHANGELOG.md](CHANGELOG.md) and the GitHub releases.
+
 Previous release: 0.4.0.
 
 ## BREAKING — the authorization layer is removed

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "proxy-aiops==0.9.2",
+        "proxy-aiops==0.9.4",
         "proxy-aiops-mcp"
       ]
     }

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/proxy-aiops",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.",
   "private": true,
   "license": "MIT",

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/_common.py

@@ -153,3 +153,43 @@ def double_confirm(action: str, resource: str) -> None:
         f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
         abort=True,
     )
+
+
+def audited(fn: Callable) -> Callable:
+    """Audit a CLI command that reaches the engine without calling an MCP tool.
+
+    MCP tools write their audit row through ``@governed_tool``; a CLI command that
+    called the ops layer directly used to write none, so an operator's CLI reads
+    left no trail. This runs the command through the same harness: one audit row per
+    invocation (tool = the command function, params = its options), plus the budget
+    and runaway guard. ``typer.Exit`` is how a command ends: exit code 0 is audited
+    ``ok``, a non-zero code ``error``, and the exit is re-raised unchanged. Any other
+    exception is audited ``error`` and propagates to ``cli_errors`` as before.
+    """
+    import functools as _functools
+
+    from proxy_aiops.governance import governed_tool
+
+    @_functools.wraps(fn)
+    def body(*args: Any, **kwargs: Any) -> Any:
+        try:
+            fn(*args, **kwargs)
+        except typer.Exit as exc:
+            code = exc.exit_code
+            outcome: dict[str, Any] = {"_exitCode": code}
+            if code:
+                outcome["error"] = f"command exited with code {code}"
+            return outcome
+        return None
+
+    governed = governed_tool(risk_level="low")(body)
+
+    @_functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        result = governed(*args, **kwargs)
+        if isinstance(result, dict) and "_exitCode" in result:
+            raise typer.Exit(result["_exitCode"])
+        return None
+
+    wrapper._is_audited_cli = True  # type: ignore[attr-defined]
+    return wrapper

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/analyze.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from proxy_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 analyze_app = typer.Typer(
     name="analyze",
@@ -18,6 +18,7 @@ analyze_app = typer.Typer(
 
 @analyze_app.command("health")
 @cli_errors
+@audited
 def analyze_health(
     service: Annotated[
         str | None, typer.Option("--service", "-s", help="Filter by service/backend")
@@ -38,6 +39,7 @@ def analyze_health(
 
 @analyze_app.command("errors")
 @cli_errors
+@audited
 def analyze_errors(
     error_rate_pct: Annotated[
         float, typer.Option("--rate", help="5xx %% at/above which a service is flagged")
@@ -63,6 +65,7 @@ def analyze_errors(
 
 @analyze_app.command("conflicts")
 @cli_errors
+@audited
 def analyze_conflicts(target: TargetOption = None) -> None:
     """Route conflict & shadow analysis: shadowed / dead routes, redirect loops."""
     from proxy_aiops.ops import analysis as analysis_ops

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/certs.py

@@ -7,10 +7,11 @@ from typing import Annotated
 
 import typer
 
-from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from proxy_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 
 @cli_errors
+@audited
 def certs_cmd(
     sweep: Annotated[
         bool,

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/configcmd.py

@@ -15,6 +15,7 @@ import typer
 from proxy_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    audited,
     checked,
     cli_errors,
     console,
@@ -33,6 +34,7 @@ config_app = typer.Typer(
 
 @config_app.command("snapshot")
 @cli_errors
+@audited
 def config_snapshot(target: TargetOption = None) -> None:
     """The live config tree / merged dynamic state (sanitised)."""
     from proxy_aiops.ops import configread as ops
@@ -43,6 +45,7 @@ def config_snapshot(target: TargetOption = None) -> None:
 
 @config_app.command("search")
 @cli_errors
+@audited
 def config_search(
     query: Annotated[str, typer.Argument(help="Substring to find in keys/values")],
     target: TargetOption = None,
@@ -62,6 +65,7 @@ def config_search(
 
 @config_app.command("get")
 @cli_errors
+@audited
 def config_get(
     path: Annotated[str, typer.Argument(help="Config path (e.g. apps/http/servers)")],
     target: TargetOption = None,

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/overview.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import json
 
-from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from proxy_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 
 @cli_errors
+@audited
 def overview_cmd(target: TargetOption = None) -> None:
     """One-shot summary: platform/version + route/service counts + upstream health."""
     from proxy_aiops.ops import overview as ops

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/routes.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from proxy_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 routes_app = typer.Typer(
     name="routes",
@@ -19,6 +19,7 @@ routes_app = typer.Typer(
 
 @routes_app.command("list")
 @cli_errors
+@audited
 def routes_list(
     host: Annotated[
         str | None, typer.Option("--host", "-H", help="Filter by hostname")
@@ -34,6 +35,7 @@ def routes_list(
 
 @routes_app.command("show")
 @cli_errors
+@audited
 def routes_show(
     name: Annotated[str, typer.Argument(help="Route name (from 'routes list')")],
     target: TargetOption = None,
@@ -47,6 +49,7 @@ def routes_show(
 
 @routes_app.command("find")
 @cli_errors
+@audited
 def routes_find(
     host: Annotated[str, typer.Argument(help="Hostname to match")],
     path: Annotated[str, typer.Option("--path", "-p", help="Request path")] = "/",

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/proxy_aiops/cli/services.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from proxy_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 services_app = typer.Typer(
     name="services",
@@ -18,6 +18,7 @@ services_app = typer.Typer(
 
 @services_app.command("list")
 @cli_errors
+@audited
 def services_list(target: TargetOption = None) -> None:
     """List services/backends with per-service server-up counts."""
     from proxy_aiops.ops import services as ops
@@ -28,6 +29,7 @@ def services_list(target: TargetOption = None) -> None:
 
 @services_app.command("show")
 @cli_errors
+@audited
 def services_show(
     name: Annotated[str, typer.Argument(help="Service name (from 'services list')")],
     target: TargetOption = None,
@@ -41,6 +43,7 @@ def services_show(
 
 @services_app.command("upstreams")
 @cli_errors
+@audited
 def services_upstreams(
     service: Annotated[
         str | None, typer.Option("--service", "-s", help="Filter by service/backend")

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proxy-aiops"
-version = "0.9.2"
+version = "0.9.4"
 description = "Governed AI-ops for Traefik + Caddy + HAProxy reverse proxies / load balancers: routes, services, upstream health, TLS cert expiry sweep, 5xx error-rate RCA, route conflict analysis, and governed writes (caddy config, haproxy server state/weight) with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Proxy-AIops",
     "source": "github"
   },
-  "version": "0.9.2",
+  "version": "0.9.4",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "proxy-aiops",
-      "version": "0.9.2",
+      "version": "0.9.4",
       "transport": {
         "type": "stdio"
       }

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/skills/proxy-aiops/references/agent-guardrails.md

@@ -31,7 +31,7 @@ What the tool *does* guarantee is that you can always see what happened:
 |---|---|
 | "Don't invent a value when a field is missing" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `""`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |
 | "Tell me if the output was cut off" | `search_config`, `traffic_stats` and `error_counters` return `{"matches"/"services": [...], "returned": N, "limit": L, "truncated": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |
-| "Preserve the ordering / tell me what's most urgent" | `backend_health_rca`, `error_rate_rca`, `route_conflict_analysis` and `cert_expiry_sweep` rank findings worst-first with the measured number attached. Priority is in the payload, not implied by list position. |
+| "Make it show the number it judged on" | `error_rate_rca` returns `errorRatePct`, `vsBaselineX` against the fleet baseline and a `severity` of `critical`/`warning` on every flagged service; `cert_expiry_sweep` returns `daysToExpiry` and a `bucket` per certificate, and orders by `daysToExpiry`. Both orderings are therefore checkable from the payload itself. |
 | "Confirm before anything destructive" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |
 | "Log what you did" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |
 | "Don't get stuck retrying" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |
@@ -39,6 +39,15 @@ What the tool *does* guarantee is that you can always see what happened:
 ## What still needs a prompt
 
 These are model-behaviour problems the harness cannot fix from the outside.
+
+⚠️ **Two of the four orderings cannot be checked, for different reasons.**
+`backend_health_rca` sorts its `findings` worst-first on an internal score that is removed
+before the payload is returned, and its findings carry neither a `rank` nor a `severity`.
+`route_conflict_analysis` is ordered by the proxy's own **evaluation order** (route priority,
+which is not returned) — that is match order, not severity: a shadowed route appearing first
+says nothing about how bad the shadowing is. `error_rate_rca` and `cert_expiry_sweep` are
+different: they sort on `errorRatePct` and `daysToExpiry`, both of which are in the payload.
+
 Copy this into your agent's system prompt:
 
 ```text
@@ -57,6 +66,10 @@ READING RESULTS
 - Read the whole result before concluding. If a result contains a "truncated"
   field that is true, say so and narrow the query instead of treating the
   partial result as complete.
+- `backend_health_rca` findings and `route_conflict_analysis` results are not ordered by
+  severity — the latter is in the proxy's match order. Weigh `backend_health_rca` findings on
+  their own `serversTotal`/`up`/`down`/`maint` counts. `route_conflict_analysis` results carry
+  no number at all — read `shadowedBy`, `reason` or `chain` and say which one you acted on.
 - A null field means this platform does not express that concept, or did not
   report it. Report it as "not available" — never infer it.
 - An "unsupported" field is a capability statement about the platform, not an

proxy_aiops-0.9.4/tests/test_cli_audited.py

@@ -0,0 +1,131 @@
+"""Every CLI command that reaches the engine is audited.
+
+MCP tools write their audit row through ``@governed_tool``. CLI commands that called
+the ops layer directly wrote none: on 2026-09-15 a read command of every tool in the
+line, run in a scratch home, left no audit.db while the harness itself worked. Each
+such command is now wrapped in ``audited`` (``cli/_common.py``); commands that call an
+MCP tool are audited by that tool. This pins the helper's behaviour and that no
+engine command escapes it.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import sqlite3
+import textwrap
+
+import pytest
+import typer
+from typer.main import get_command
+
+from proxy_aiops.cli import app
+from proxy_aiops.cli._common import audited
+
+pytestmark = pytest.mark.unit
+
+#: Local-only commands: they never reach the engine (``undo`` goes through MCP tools).
+EXEMPT = {"init", "doctor", "secret", "mcp", "undo"}
+
+
+def _leaves() -> list[tuple[list[str], object]]:
+    found: list[tuple[list[str], object]] = []
+
+    def walk(cmd, path):
+        if hasattr(cmd, "list_commands"):
+            for name, sub in cmd.commands.items():
+                walk(sub, path + [name])
+        else:
+            found.append((path, cmd))
+
+    walk(get_command(app), [])
+    return found
+
+
+def _chain(fn):
+    seen = []
+    while fn is not None and fn not in seen:
+        seen.append(fn)
+        fn = getattr(fn, "__wrapped__", None)
+    return seen
+
+
+def _calls_an_mcp_tool(fn) -> bool:
+    source = inspect.getsource(fn)
+    if "mcp_server" in source:
+        return True
+    names = set()
+    for node in ast.parse(open(inspect.getsourcefile(fn)).read()).body:
+        if isinstance(node, ast.ImportFrom) and (node.module or "").startswith("mcp_server"):
+            names |= {a.asname or a.name for a in node.names}
+    used = {n.id for n in ast.walk(ast.parse(textwrap.dedent(source))) if isinstance(n, ast.Name)}
+    return bool(names & used)
+
+
+def test_every_engine_command_is_audited():
+    commands = [(path, cmd) for path, cmd in _leaves() if path and path[0] not in EXEMPT]
+    assert commands, "no commands found: the walker is broken, not the CLI clean"
+    missing = [
+        " ".join(path) for path, cmd in commands
+        if not any(getattr(f, "_is_audited_cli", False) for f in _chain(cmd.callback))
+        and not _calls_an_mcp_tool(inspect.unwrap(cmd.callback))
+    ]
+    assert not missing, f"CLI commands that leave no audit row: {missing}"
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    import proxy_aiops.governance.audit as audit_mod
+    import proxy_aiops.governance.budget as budget_mod
+
+    monkeypatch.setenv("PROXY_AIOPS_HOME", str(tmp_path))
+    audit_mod.reset_engine()
+    budget_mod.reset_budget()
+    yield tmp_path
+    audit_mod.reset_engine()
+    budget_mod.reset_budget()
+
+
+def _rows(home) -> list[tuple[str, str]]:
+    con = sqlite3.connect(home / "audit.db")
+    try:
+        return con.execute("SELECT tool, status FROM audit_log ORDER BY id").fetchall()
+    finally:
+        con.close()
+
+
+def test_audited_records_success_exit_codes_and_exceptions(home):
+    @audited
+    def cmd_ok(target=None):
+        return None
+
+    @audited
+    def cmd_exit_zero(target=None):
+        raise typer.Exit()
+
+    @audited
+    def cmd_exit_one(target=None):
+        raise typer.Exit(1)
+
+    @audited
+    def cmd_raises(target=None):
+        raise RuntimeError("engine unreachable")
+
+    cmd_ok()
+    with pytest.raises(typer.Exit) as zero:
+        cmd_exit_zero()
+    assert zero.value.exit_code == 0
+    with pytest.raises(typer.Exit) as one:
+        cmd_exit_one()
+    assert one.value.exit_code == 1
+    with pytest.raises(RuntimeError, match="engine unreachable"):
+        cmd_raises()
+    assert _rows(home) == [("cmd_ok", "ok"), ("cmd_exit_zero", "ok"),
+                           ("cmd_exit_one", "error"), ("cmd_raises", "error")]
+
+
+def test_audited_keeps_the_command_signature_for_typer():
+    def cmd(limit: int = 5, target: str | None = None) -> None:
+        return None
+
+    assert list(inspect.signature(audited(cmd)).parameters) == ["limit", "target"]

{proxy_aiops-0.9.2 → proxy_aiops-0.9.4}/uv.lock

@@ -529,7 +529,7 @@ wheels = [
 
 [[package]]
 name = "proxy-aiops"
-version = "0.9.2"
+version = "0.9.4"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },