queue-aiops 0.1.0__py3-none-any.whl

mcp_server/tools/writes.py

@@ -0,0 +1,355 @@
+"""Governed broker-write MCP tools (the only state-changing tools).
+
+Every tool is wrapped with the governance harness (audit + graduated approval
+tier) and takes a ``dry_run`` preview. Reversible writes pass an ``undo=``
+callback that turns the fetched before-state into an inverse descriptor the
+harness records; irreversible ones (kill_client, purge_queue) record only the
+priorState in the result.
+
+Risk tiers: purge_queue / delete_queue = high (destroy messages / a queue);
+redis_config_set / redis_kill_client / declare_queue / set_policy /
+delete_policy = medium.
+"""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.ops import writes as ops
+
+# ── undo descriptors (built from the fetched before-state) ──────────────────
+
+
+def _config_set_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of redis_config_set: set the parameter back to its prior value."""
+    if not isinstance(result, dict):
+        return None
+    prior = (result.get("priorState") or {}).get("value")
+    if prior is None:
+        return None
+    return {
+        "tool": "redis_config_set",
+        "params": {"parameter": params.get("parameter"), "value": prior},
+        "skill": "queue-aiops",
+        "note": "Inverse of redis_config_set: restore the parameter's prior value.",
+    }
+
+
+def _delete_queue_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of delete_queue: re-declare the queue with the captured definition.
+
+    The queue's *messages* are gone — this restores the definition only, and the
+    note says so.
+    """
+    if not isinstance(result, dict):
+        return None
+    prior = result.get("priorState") or {}
+    return {
+        "tool": "declare_queue",
+        "params": {
+            "vhost": params.get("vhost"),
+            "name": params.get("name"),
+            "durable": bool(prior.get("durable", True)),
+            "auto_delete": bool(prior.get("autoDelete", False)),
+            "arguments": prior.get("arguments") or {},
+        },
+        "skill": "queue-aiops",
+        "note": "Inverse of delete_queue: re-declare the captured definition "
+        "(messages are NOT restored).",
+    }
+
+
+def _declare_queue_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of declare_queue: delete the queue — only when it was newly created."""
+    if not isinstance(result, dict):
+        return None
+    if (result.get("priorState") or {}).get("existed"):
+        return None  # the queue predates this call; deleting it would not be an undo
+    return {
+        "tool": "delete_queue",
+        "params": {"vhost": params.get("vhost"), "name": params.get("name")},
+        "skill": "queue-aiops",
+        "note": "Inverse of declare_queue: delete the queue that was created.",
+    }
+
+
+def _set_policy_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of set_policy: restore the prior policy, or delete it if it is new."""
+    if not isinstance(result, dict):
+        return None
+    prior_state = result.get("priorState") or {}
+    prior = prior_state.get("policy")
+    if prior_state.get("existed") and isinstance(prior, dict):
+        return {
+            "tool": "set_policy",
+            "params": {
+                "vhost": params.get("vhost"),
+                "name": params.get("name"),
+                "pattern": prior.get("pattern"),
+                "definition": prior.get("definition") or {},
+                "priority": int(prior.get("priority") or 0),
+                "apply_to": prior.get("applyTo") or "all",
+            },
+            "skill": "queue-aiops",
+            "note": "Inverse of set_policy: restore the prior policy fields.",
+        }
+    return {
+        "tool": "delete_policy",
+        "params": {"vhost": params.get("vhost"), "name": params.get("name")},
+        "skill": "queue-aiops",
+        "note": "Inverse of set_policy: delete the policy that was newly created.",
+    }
+
+
+def _delete_policy_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of delete_policy: re-create the captured policy."""
+    if not isinstance(result, dict):
+        return None
+    prior = (result.get("priorState") or {}).get("policy")
+    if not isinstance(prior, dict):
+        return None
+    return {
+        "tool": "set_policy",
+        "params": {
+            "vhost": params.get("vhost"),
+            "name": params.get("name"),
+            "pattern": prior.get("pattern"),
+            "definition": prior.get("definition") or {},
+            "priority": int(prior.get("priority") or 0),
+            "apply_to": prior.get("applyTo") or "all",
+        },
+        "skill": "queue-aiops",
+        "note": "Inverse of delete_policy: re-create the captured policy.",
+    }
+
+
+# ── redis writes ─────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_config_set_undo)
+@tool_errors("dict")
+def redis_config_set(
+    parameter: str,
+    value: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Set one redis config parameter; reversible.
+
+    Reads the parameter first (CONFIG GET) so the harness records an undo that
+    restores its prior value. Runtime-only — not persisted to the config file.
+    Pass dry_run=True to preview.
+
+    Args:
+        parameter: Config parameter name (e.g. maxmemory-policy), from redis_config_get.
+        value: New value.
+        dry_run: If True, preview without changing.
+        target: redis target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldSet": {"parameter": parameter, "value": value}}
+    return ops.config_set(conn, parameter, value)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def redis_kill_client(
+    client_id: int = 0,
+    addr: str = "",
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Disconnect one redis client by id or addr. IRREVERSIBLE.
+
+    Captures the client's CLIENT LIST row as priorState (who/where/last
+    command) before the kill — the connection cannot be restored, so no undo
+    is recorded; most clients transparently reconnect. Pass dry_run=True to
+    preview.
+
+    Args:
+        client_id: Client id from redis_clients (preferred).
+        addr: Or the client's 'ip:port' address.
+        dry_run: If True, preview without disconnecting.
+        target: redis target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldKill": {"clientId": client_id, "addr": addr}}
+    return ops.kill_client(conn, client_id=client_id, addr=addr)
+
+
+# ── rabbitmq queue writes ────────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="high")
+@tool_errors("dict")
+def purge_queue(
+    vhost: str,
+    name: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=high] Purge all ready messages from a rabbitmq queue. IRREVERSIBLE.
+
+    Reads the queue first so priorState carries the message count about to be
+    destroyed (audit evidence); unacked messages are not purged. No undo —
+    purged messages cannot be restored. Requires an approver
+    (QUEUE_AUDIT_APPROVED_BY) under the graduated-autonomy policy. Pass
+    dry_run=True to preview.
+
+    Args:
+        vhost: The queue's vhost (the default vhost is '/').
+        name: Queue name (from list_queues).
+        dry_run: If True, preview without purging.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldPurge": {"vhost": vhost, "queue": name}}
+    return ops.purge_queue(conn, vhost, name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high", undo=_delete_queue_undo)
+@tool_errors("dict")
+def delete_queue(
+    vhost: str,
+    name: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=high] Delete a rabbitmq queue; the undo re-declares its definition.
+
+    Reads the queue first so priorState carries the definition (durable /
+    auto_delete / arguments) and message count; the recorded undo re-declares
+    the queue with those properties — its messages are NOT restored. Requires
+    an approver (QUEUE_AUDIT_APPROVED_BY) under the graduated-autonomy policy.
+    Pass dry_run=True to preview.
+
+    Args:
+        vhost: The queue's vhost (the default vhost is '/').
+        name: Queue name (from list_queues).
+        dry_run: If True, preview without deleting.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldDelete": {"vhost": vhost, "queue": name}}
+    return ops.delete_queue(conn, vhost, name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_declare_queue_undo)
+@tool_errors("dict")
+def declare_queue(
+    vhost: str,
+    name: str,
+    durable: bool = True,
+    auto_delete: bool = False,
+    arguments: Optional[dict[str, Any]] = None,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Declare (create) a rabbitmq queue; undo deletes it if new.
+
+    Records whether the queue already existed; the undo (delete) is recorded
+    only for a newly-created queue. Also the replay target for delete_queue's
+    undo. Pass dry_run=True to preview.
+
+    Args:
+        vhost: The queue's vhost (the default vhost is '/').
+        name: Queue name to declare.
+        durable: Survive broker restarts (default True).
+        auto_delete: Delete when the last consumer disconnects (default False).
+        arguments: Optional x-arguments (e.g. {'x-queue-type': 'quorum'}).
+        dry_run: If True, preview without declaring.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {
+            "dryRun": True,
+            "wouldDeclare": {
+                "vhost": vhost, "queue": name, "durable": durable,
+                "autoDelete": auto_delete, "arguments": arguments or {},
+            },
+        }
+    return ops.declare_queue(
+        conn, vhost, name, durable=durable, auto_delete=auto_delete, arguments=arguments
+    )
+
+
+# ── rabbitmq policy writes ───────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_set_policy_undo)
+@tool_errors("dict")
+def set_policy(
+    vhost: str,
+    name: str,
+    pattern: str,
+    definition: dict[str, Any],
+    priority: int = 0,
+    apply_to: str = "all",
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Create/update a rabbitmq policy; reversible.
+
+    Reads the policy first: the recorded undo restores the prior policy fields,
+    or deletes the policy when it is newly created. Pass dry_run=True to
+    preview.
+
+    Args:
+        vhost: The policy's vhost (the default vhost is '/').
+        name: Policy name.
+        pattern: Regex the policy matches queue/exchange names against.
+        definition: Policy definition object (e.g. {'max-length': 100000}).
+        priority: Policy priority (higher wins; default 0).
+        apply_to: 'queues', 'exchanges', or 'all' (default).
+        dry_run: If True, preview without changing.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {
+            "dryRun": True,
+            "wouldSetPolicy": {
+                "vhost": vhost, "policy": name, "pattern": pattern,
+                "definition": definition, "priority": priority, "applyTo": apply_to,
+            },
+        }
+    return ops.set_policy(
+        conn, vhost, name, pattern, definition, priority=priority, apply_to=apply_to
+    )
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_delete_policy_undo)
+@tool_errors("dict")
+def delete_policy(
+    vhost: str,
+    name: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Delete a rabbitmq policy; the undo re-creates it.
+
+    Reads the policy first so the recorded undo can re-create it exactly. Pass
+    dry_run=True to preview.
+
+    Args:
+        vhost: The policy's vhost (the default vhost is '/').
+        name: Policy name (from list_policies).
+        dry_run: If True, preview without deleting.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldDeletePolicy": {"vhost": vhost, "policy": name}}
+    return ops.delete_policy(conn, vhost, name)

queue_aiops/__init__.py

@@ -0,0 +1,14 @@
+"""queue-aiops — governed redis + rabbitmq broker operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, output sanitize) is
+bundled under ``queue_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("queue-aiops")
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"

queue_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for queue-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``queue-aiops = "queue_aiops.cli:app"`` works unchanged.
+"""
+
+from queue_aiops.cli._root import app
+
+__all__ = ["app"]

queue_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for queue-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from queue_aiops.connection import QueueApiError
+
+    return (QueueApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None) -> tuple[Any, Any]:
+    """Return a (conn, config) tuple for the given target."""
+    from queue_aiops.config import load_config
+    from queue_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

queue_aiops/cli/_root.py

@@ -0,0 +1,62 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from queue_aiops.cli._common import cli_errors
+from queue_aiops.cli.analyze import analyze_app
+from queue_aiops.cli.doctor import doctor_cmd
+from queue_aiops.cli.init import init_cmd
+from queue_aiops.cli.overview import overview_cmd
+from queue_aiops.cli.rabbit_cmds import rabbitmq_app
+from queue_aiops.cli.redis_cmds import redis_app
+from queue_aiops.cli.secret import secret_app
+from queue_aiops.cli.undo import undo_app
+
+app = typer.Typer(
+    name="queue-aiops",
+    help="Governed AI-ops for redis + rabbitmq: memory/latency/backlog/churn "
+    "RCAs, slowlog and big-key sampling, queues/policies, and governed writes "
+    "(config set, client kill, purge/delete queue, policies).",
+    no_args_is_help=True,
+)
+
+app.add_typer(redis_app, name="redis")
+app.add_typer(rabbitmq_app, name="rabbitmq")
+app.add_typer(analyze_app, name="analyze")
+app.add_typer(secret_app, name="secret")
+app.add_typer(undo_app, name="undo")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        queue-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: queue-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force queue-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

queue_aiops/cli/analyze.py

@@ -0,0 +1,85 @@
+"""``queue-aiops analyze`` — the flagship RCA analyses (read-only)."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from queue_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+analyze_app = typer.Typer(
+    name="analyze",
+    help="Flagship RCAs: redis memory pressure + latency, rabbitmq queue "
+    "backlog, and connection churn (both platforms).",
+    no_args_is_help=True,
+)
+
+
+@analyze_app.command("memory")
+@cli_errors
+def analyze_memory(
+    used_pct: Annotated[
+        float, typer.Option("--used-pct", help="used/maxmemory %% pressure threshold")
+    ] = 85.0,
+    target: TargetOption = None,
+) -> None:
+    """redis memory-pressure RCA: maxmemory, eviction, fragmentation, big keys."""
+    from queue_aiops.ops import analysis as ops
+    from queue_aiops.ops._util import as_obj, num
+
+    conn, _ = get_connection(target)
+    telemetry = ops.pull_memory_telemetry(conn)
+    console.print_json(json.dumps(ops.redis_memory_pressure_rca(
+        as_obj(telemetry.get("memory")),
+        evicted_keys=num(telemetry.get("evictedKeys")),
+        big_keys=as_obj(telemetry.get("bigKeys")),
+        used_pct=used_pct,
+    )))
+
+
+@analyze_app.command("latency")
+@cli_errors
+def analyze_latency(
+    slow_us: Annotated[
+        float, typer.Option("--slow-us", help="Slowlog threshold in microseconds")
+    ] = 10_000.0,
+    target: TargetOption = None,
+) -> None:
+    """redis latency RCA: slowlog digest, blocked clients, fork/AOF stalls."""
+    from queue_aiops.ops import analysis as ops
+
+    conn, _ = get_connection(target)
+    telemetry = ops.pull_latency_telemetry(conn)
+    console.print_json(json.dumps(ops.redis_latency_rca(telemetry, slow_us=slow_us)))
+
+
+@analyze_app.command("backlog")
+@cli_errors
+def analyze_backlog(
+    vhost: Annotated[
+        str | None, typer.Option("--vhost", help="Restrict to one vhost")
+    ] = None,
+    top: Annotated[int, typer.Option("--top", help="Queue rows, deepest first")] = 20,
+    target: TargetOption = None,
+) -> None:
+    """rabbitmq queue-backlog RCA: consumers, unacked pileups, watermark blocks."""
+    from queue_aiops.ops import analysis as ops
+
+    conn, _ = get_connection(target)
+    telemetry = ops.pull_backlog_telemetry(conn, vhost)
+    console.print_json(json.dumps(ops.rabbitmq_queue_backlog_rca(
+        telemetry.get("queues", []), nodes=telemetry.get("nodes", []), top=top,
+    )))
+
+
+@analyze_app.command("churn")
+@cli_errors
+def analyze_churn(target: TargetOption = None) -> None:
+    """Connection-churn analysis (both platforms): counts, rates, by source."""
+    from queue_aiops.ops import analysis as ops
+
+    conn, _ = get_connection(target)
+    snapshot = ops.pull_churn_snapshot(conn)
+    console.print_json(json.dumps(ops.connection_churn_analysis(snapshot)))

queue_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from queue_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check environment, config, secrets, and connectivity."""
+    from queue_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))