queue-aiops 0.9.3__tar.gz → 0.10.0__tar.gz

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "queue-aiops",
   "displayName": "Queue AIops",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Governed redis + rabbitmq ops: memory/latency/backlog/churn RCA, policies. 28 tools.",
   "author": {
     "name": "Wei Zhou",

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "queue-aiops==0.9.3",
+        "queue-aiops==0.10.0",
         "queue-aiops-mcp"
       ]
     }

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## v0.10.0 — 2026-10-15
+
+### Added
+- MCP tool annotations derived from each tool's governance `risk_level`, so
+  clients can gate approval from `tools/list` alone. `low` tools advertise
+  `readOnlyHint: true`; every other tool advertises `readOnlyHint: false` and
+  `destructiveHint: true`. The `medium` tier includes deletes and hard
+  power-offs, so a tool is never advertised as non-destructive on the strength
+  of its tier. `idempotentHint` only repeats an explicit declaration. The exact
+  level is published in `_meta` under `io.github.AIops-tools/riskLevel`. These
+  are hints for the client; audit and undo are unchanged.
+
+## v0.9.4 — 2026-09-16
+
+### Fixed
+- `redis_memory_pressure_rca`'s top-level `pressure` flag no longer decides by
+  comparing another finding's `cause` against the literal sentence "Healthy —
+  within thresholds". The flag is behaviourally unchanged, but rewording that
+  sentence — or normalising its em dash in a style sweep — would have reported
+  pressure on a healthy broker. It now reads the measured condition captured
+  before the healthy placeholder is appended, and an AST-based structural test
+  pins the whole package against a decision being taken on a finding's prose —
+  either operand order, the literal hoisted into a constant, `.get()`, `in`,
+  `startswith`, slicing and `.lower()` are all rejected.
+- `agent-guardrails.md` and `SKILL.md` claimed the four RCAs "rank findings
+  worst-first" and that "priority is in the payload, not implied by list
+  position". Neither was ever true here: there is no `rank` key, and findings are
+  appended in the order the checks run. The claim sat in the table headed "what
+  the tool enforces — do not waste prompt budget on these", so it actively told
+  operators to drop the prompt that would have compensated. A broker at 12 % of
+  `maxmemory` with 35 GiB of oversized keys reports the fragmentation finding
+  first, purely because fragmentation is checked earlier. The docs now say order
+  is not severity, and point at the `evidence` number each finding does carry.
+
 ## v0.9.3 — 2026-09-15
 
 ### Fixed

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: queue-aiops
-Version: 0.9.3
+Version: 0.10.0
 Summary: Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/RELEASE_NOTES.md

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

queue_aiops-0.10.0/mcp_server/_annotations.py

@@ -0,0 +1,66 @@
+"""Derive MCP tool annotations from the governance risk level.
+
+Every tool already declares ``risk_level`` on ``@governed_tool``; this module
+publishes it to MCP clients as the standard ``ToolAnnotations`` hints plus the
+exact level under ``_meta``, so a client can gate approval without reading our
+docstrings.
+
+Only the safe direction is ever asserted:
+
+- ``low`` → ``readOnlyHint: true``. Backed by the smoke-test invariant that
+  ``risk_level == "low"`` exactly when the docstring says ``[READ]``.
+- anything else → ``readOnlyHint: false, destructiveHint: true``. The
+  ``medium`` tier is NOT non-destructive — it holds deletes, hard power-offs,
+  state kills and stat resets — so claiming ``destructiveHint: false`` from the
+  tier would tell a client it may skip approval for a delete. Over-warning
+  costs a confirmation prompt; under-warning costs data.
+- ``idempotentHint`` only echoes an explicit ``@governed_tool(idempotent=True)``
+  declaration; it is never inferred.
+- ``openWorldHint`` is left unset (spec default ``true``): every tool talks to
+  an external system.
+
+This file is identical across the AIops line; keep it that way.
+"""
+
+from typing import Any
+
+from mcp.types import ToolAnnotations
+
+RISK_META_KEY = "io.github.AIops-tools/riskLevel"
+RISK_LEVELS = frozenset({"low", "medium", "high", "critical"})
+
+
+def annotations_for(risk_level: str, idempotent: bool) -> ToolAnnotations:
+    """Return the MCP hints that a tool of ``risk_level`` may honestly claim."""
+    if risk_level not in RISK_LEVELS:
+        raise ValueError(
+            f"unknown risk_level {risk_level!r}; expected one of {sorted(RISK_LEVELS)}"
+        )
+    if risk_level == "low":
+        return ToolAnnotations(read_only_hint=True)
+    return ToolAnnotations(
+        read_only_hint=False,
+        destructive_hint=True,
+        idempotent_hint=idempotent,
+    )
+
+
+def apply_risk_annotations(server: Any) -> None:
+    """Replace every registered tool with a copy carrying its risk annotations.
+
+    Fails fast on a tool without ``@governed_tool`` metadata: an unannotated
+    tool would be advertised with the spec defaults, i.e. as a destructive
+    write with no stated risk level — wrong for a read, silent for a write.
+    """
+    tools = server._tool_manager._tools  # same private registry undo.py relies on
+    for name, tool in list(tools.items()):
+        risk_level = getattr(tool.fn, "_risk_level", None)
+        if risk_level is None:
+            raise RuntimeError(f"tool {name!r} has no @governed_tool risk_level")
+        idempotent = bool(getattr(tool.fn, "_idempotent", False))
+        tools[name] = tool.model_copy(
+            update={
+                "annotations": annotations_for(risk_level, idempotent),
+                "meta": {**(tool.meta or {}), RISK_META_KEY: risk_level},
+            }
+        )

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/mcp_server/server.py

@@ -17,6 +17,7 @@ License: MIT
 import logging
 import os
 
+from mcp_server._annotations import apply_risk_annotations
 from mcp_server._shared import _safe_error, mcp, tool_errors
 
 # Importing the tool modules registers every @mcp.tool() onto the shared
@@ -30,6 +31,10 @@ from mcp_server.tools import (  # noqa: F401 — side effects
     writes,
 )
 
+# Publish each tool's governance risk level as MCP annotations. Runs after
+# every tool module has registered, so no tool is advertised unannotated.
+apply_risk_annotations(mcp)
+
 __all__ = ["mcp", "main", "_safe_error", "tool_errors"]
 
 logger = logging.getLogger(__name__)

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "queue-aiops==0.9.3",
+        "queue-aiops==0.10.0",
         "queue-aiops-mcp"
       ]
     }

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/queue-aiops",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Governed redis + rabbitmq ops: memory/latency/backlog/churn RCA, policies. 28 tools.",
   "private": true,
   "license": "MIT",

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "queue-aiops"
-version = "0.9.3"
+version = "0.10.0"
 description = "Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/queue_aiops/ops/analysis.py

@@ -126,6 +126,10 @@ def redis_memory_pressure_rca(
             "evidence": {"bigKeys": big[:10]},
         })
 
+    # Captured before the healthy placeholder is appended. The flag reports the measured
+    # condition — did any check fire — and is never derived from another finding's prose:
+    # a reworded sentence would otherwise report pressure on a healthy broker.
+    pressure = bool(findings)
     if not findings:
         findings.append({
             "cause": "Healthy — within thresholds",
@@ -133,7 +137,7 @@ def redis_memory_pressure_rca(
             "evidence": {"usedPctOfMax": used_of_max, "fragmentationRatio": frag},
         })
     return {
-        "pressure": any(f["cause"] != "Healthy — within thresholds" for f in findings),
+        "pressure": pressure,
         "usedPctOfMax": used_of_max,
         "maxmemoryPolicy": policy,
         "fragmentationRatio": frag,

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Queue-AIops",
     "source": "github"
   },
-  "version": "0.9.3",
+  "version": "0.10.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "queue-aiops",
-      "version": "0.9.3",
+      "version": "0.10.0",
       "transport": {
         "type": "stdio"
       }

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/skills/queue-aiops/SKILL.md

@@ -121,8 +121,8 @@ skill.
    works before you read numbers off it.
 2. `queue-aiops redis memory` → used vs `maxmemory`, the eviction policy in force, and
    the fragmentation ratio, straight from `INFO memory`.
-3. `queue-aiops analyze memory --used-pct 85` → ranked findings, each citing its measured
-   number: **noeviction near the limit** (the dangerous one — writes will start failing
+3. `queue-aiops analyze memory --used-pct 85` → findings in check order, each citing its measured
+   number (order is not severity — weigh them all): **noeviction near the limit** (the dangerous one — writes will start failing
    with OOM rather than evicting), active eviction in progress, fragmentation versus real
    swapping, and oversized keys.
 4. `queue-aiops redis bigkeys --count 500` → a SCAN-budgeted sample of the largest keys,

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/skills/queue-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" | RabbitMQ omits `idle_since` for an active queue; a Redis primary reports no `master_link_status`; an unnamed client has no name. Those come back as `null`, never as `""`. |
 | "Tell me if the output was cut off" | `redis_slowlog`, `redis_clients`, `redis_big_keys`, `list_queues`, `list_connections`, `list_channels` and `list_policies` all return `{"<items>": [...], "returned": N, "limit": L, "truncated": true/false}`. Truncation is measured — one extra entry is requested from Redis — not guessed from a length coincidence. |
-| "Preserve the ordering / tell me what's most urgent" | `rabbitmq_queue_backlog_rca`, `redis_memory_pressure_rca`, `redis_latency_rca` and `connection_churn_analysis` rank findings worst-first, each carrying the measured number it was based on. Priority is in the payload, not implied by list position. |
+| "Make it show the number it judged on" | Every finding from `rabbitmq_queue_backlog_rca`, `redis_memory_pressure_rca`, `redis_latency_rca` and `connection_churn_analysis` carries the measured value it was based on under `evidence`, so a claim can always be checked against a number rather than taken on the model's word. |
 | "Don't run KEYS * on production" | `redis_big_keys` uses SCAN under a hard key budget and sizes only an evenly-spaced subset with MEMORY USAGE. There is no code path that can issue `KEYS *`. `coveragePct` reports how partial the walk was. |
 | "Confirm before anything destructive" | `delete_queue` and `purge_queue` require a `--dry-run`-able preview plus double confirmation at the CLI. |
 | "Log what you did" | Every governed call is audited to `~/.queue-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. |
@@ -40,7 +40,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.
-Copy this into your agent's system prompt:
+
+⚠️ **Finding order is not priority.** These RCAs append findings in the order the checks
+run, not worst-first, and there is no `rank` key in the payload. A broker at 12 % of
+`maxmemory` with 35 GiB of oversized keys reports the fragmentation finding first purely
+because fragmentation is checked before big keys. Do not let the model treat `findings[0]`
+as the headline — make it weigh every finding's `evidence` and say which one it acted on.
+(Earlier versions of this file claimed these lists were ranked worst-first. They never were.)
+
+Recommended setup for a local model (adapt it to your agent client):
 
 ```text
 You operate a RabbitMQ broker or a Redis instance through the queue-aiops MCP

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/tests/test_analysis.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import ast
+from pathlib import Path
+
 import pytest
 
 from queue_aiops.ops import analysis as ops
@@ -200,3 +203,68 @@ def test_churn_healthy_reports_metrics():
     })
     assert out["findings"][0]["action"] == "No action needed."
     assert out["metrics"]["channels"] == 8
+
+
+@pytest.mark.unit
+def test_no_decision_is_derived_from_a_findings_display_text():
+    """A rule's input is never another rule's display text.
+
+    `pressure` used to be `any(f["cause"] != "Healthy — within thresholds" ...)`, so
+    rewording that sentence — or normalising its em dash in a style sweep — would have
+    reported pressure on a healthy broker. The check is AST-based on purpose: a regex on
+    the source missed the shape that produced the original incident in another repo
+    (`"critical blocker" in f["signal"]`, literal on the left), and also fired on prose
+    inside comments and docstrings. Walking the tree catches either operand order, the
+    literal hoisted into a constant, `.get()`, `.lower()`, slicing and `startswith`, and
+    ignores comments entirely.
+    """
+    offenders = []
+    for path in _scanned_sources():
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Compare):
+                operands = [node.left, *node.comparators]
+                if any(_reads_display_text(o) for o in operands) and not _is_none_check(node):
+                    offenders.append(f"{path.name}:{node.lineno}: {ast.unparse(node)}")
+            elif isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) \
+                    and node.func.attr in _TEXT_PREDICATES and _reads_display_text(node.func.value):
+                offenders.append(f"{path.name}:{node.lineno}: {ast.unparse(node)}")
+    assert offenders == [], ("a decision is being derived from a finding's prose:\n"
+                             + "\n".join(offenders))
+
+
+_DISPLAY_KEYS = {"cause", "action", "signal", "note", "summary"}
+_TEXT_PREDICATES = {"startswith", "endswith", "count", "find", "index"}
+
+
+def _scanned_sources():
+    """Every module that could post-process a finding — not just the one that builds them.
+
+    `governance/` is excluded: it is vendored verbatim across the line and held byte-identical
+    by the drift gate, so it is not this repo's to edit.
+    """
+    root = Path(ops.__file__).parents[2]
+    found = sorted(root.glob("queue_aiops/**/*.py")) + sorted(root.glob("mcp_server/**/*.py"))
+    files = [p for p in found if "governance" not in p.parts]
+    assert len(files) > 10, f"source sweep found only {len(files)} modules — the glob is wrong"
+    return files
+
+
+def _reads_display_text(node):
+    """True if evaluating this expression reads a finding's display field, however wrapped."""
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Subscript) and isinstance(sub.slice, ast.Constant) \
+                and sub.slice.value in _DISPLAY_KEYS:
+            return True
+        if isinstance(sub, ast.Call) and isinstance(sub.func, ast.Attribute) \
+                and sub.func.attr == "get" and sub.args \
+                and isinstance(sub.args[0], ast.Constant) \
+                and sub.args[0].value in _DISPLAY_KEYS:
+            return True
+    return False
+
+
+def _is_none_check(node):
+    """`f["cause"] is None` is a presence test, not a decision taken on the prose."""
+    return all(isinstance(op, (ast.Is, ast.IsNot)) for op in node.ops) and all(
+        isinstance(c, ast.Constant) and c.value is None for c in node.comparators)

queue_aiops-0.10.0/tests/test_tool_annotations.py

@@ -0,0 +1,128 @@
+"""Invariants for the MCP annotations derived from ``risk_level``.
+
+Asserted on ``list_tools()`` — the payload a client actually receives — not on
+the internal registry, so a regression in how annotations reach the wire fails
+here too. This file is identical across the AIops line.
+"""
+
+import asyncio
+import re
+from types import SimpleNamespace
+
+import pytest
+from mcp.server import MCPServer
+
+import mcp_server.server as server
+from mcp_server._annotations import (
+    RISK_META_KEY,
+    annotations_for,
+    apply_risk_annotations,
+)
+
+
+@pytest.fixture(scope="module")
+def listed():
+    return asyncio.run(server.mcp.list_tools())
+
+
+@pytest.fixture(scope="module")
+def registry():
+    return server.mcp._tool_manager._tools
+
+
+def test_every_tool_is_annotated(listed):
+    assert listed, "no tools listed"
+    missing = [t.name for t in listed if t.annotations is None or not t.meta]
+    assert not missing, f"tools advertised without annotations: {missing}"
+
+
+def test_meta_carries_the_declared_risk_level(listed, registry):
+    wrong = [t.name for t in listed if t.meta.get(RISK_META_KEY) != registry[t.name].fn._risk_level]
+    assert not wrong, f"_meta risk level differs from @governed_tool: {wrong}"
+
+
+def test_read_only_hint_true_exactly_for_low_risk(listed):
+    wrong = [
+        t.name for t in listed if t.annotations.read_only_hint != (t.meta[RISK_META_KEY] == "low")
+    ]
+    assert not wrong, f"readOnlyHint disagrees with risk_level: {wrong}"
+
+
+def test_no_write_claims_to_be_non_destructive(listed):
+    # medium holds deletes and hard power-offs; the tier cannot prove safety.
+    wrong = [
+        t.name
+        for t in listed
+        if not t.annotations.read_only_hint and t.annotations.destructive_hint is not True
+    ]
+    assert not wrong, f"writes advertised as non-destructive: {wrong}"
+
+
+def test_idempotent_hint_only_echoes_an_explicit_declaration(listed, registry):
+    wrong = [
+        t.name
+        for t in listed
+        if t.annotations.idempotent_hint and not registry[t.name].fn._idempotent
+    ]
+    assert not wrong, f"idempotentHint inferred without a declaration: {wrong}"
+
+
+def test_open_world_hint_is_never_narrowed(listed):
+    assert all(t.annotations.open_world_hint in (None, True) for t in listed)
+
+
+@pytest.mark.parametrize("level", ["low", "medium", "high", "critical"])
+def test_mapping_per_level(level):
+    hints = annotations_for(level, idempotent=False)
+    if level == "low":
+        assert hints.read_only_hint is True
+        assert hints.destructive_hint is None
+    else:
+        assert hints.read_only_hint is False
+        assert hints.destructive_hint is True
+        assert hints.idempotent_hint is False
+
+
+def test_declared_idempotent_write_is_echoed():
+    assert annotations_for("medium", idempotent=True).idempotent_hint is True
+
+
+def test_unknown_risk_level_is_rejected():
+    with pytest.raises(ValueError, match="unknown risk_level"):
+        annotations_for("Low", idempotent=False)
+
+
+def test_ungoverned_tool_fails_fast():
+    fake_tool = SimpleNamespace(fn=lambda: None, meta=None)
+    fake = SimpleNamespace(_tool_manager=SimpleNamespace(_tools={"rogue": fake_tool}))
+    with pytest.raises(RuntimeError, match="rogue"):
+        apply_risk_annotations(fake)
+
+
+def test_meta_key_is_the_published_contract():
+    # Clients match on this literal; it must be a valid, non-reserved _meta key.
+    assert RISK_META_KEY == "io.github.AIops-tools/riskLevel"
+    prefix, name = RISK_META_KEY.split("/")
+    label = re.compile(r"^[A-Za-z]([A-Za-z0-9-]*[A-Za-z0-9])?$")
+    labels = prefix.split(".")
+    assert all(label.match(part) for part in labels)
+    assert not {"mcp", "modelcontextprotocol"} & {part.lower() for part in labels}
+    assert re.match(r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$", name)
+
+
+def test_existing_meta_survives_on_a_real_tool():
+    fresh = MCPServer("annotations-test")
+
+    def probe() -> str:
+        return "ok"
+
+    probe._risk_level = "medium"
+    probe._idempotent = True
+    fresh.tool(meta={"x": 1})(probe)
+    apply_risk_annotations(fresh)
+
+    (listed_tool,) = asyncio.run(fresh.list_tools())
+    assert listed_tool.meta == {"x": 1, RISK_META_KEY: "medium"}
+    assert listed_tool.annotations.destructive_hint is True
+    assert listed_tool.annotations.idempotent_hint is True
+    assert fresh._tool_manager._tools["probe"].fn is probe

{queue_aiops-0.9.3 → queue_aiops-0.10.0}/uv.lock

@@ -812,7 +812,7 @@ wheels = [
 
 [[package]]
 name = "queue-aiops"
-version = "0.9.3"
+version = "0.10.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },