postgres-aiops 0.4.0__tar.gz → 0.6.0__tar.gz

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v0.6.0 — 2026-07-21
+
+### Changed (BREAKING)
+- **Removed the authorization layer** — read-only mode, the approver gate, and rules.yaml deny are gone. The skill no longer decides read vs write; that is the agent's judgement or the connecting account's permissions. `<PREFIX>_READ_ONLY` now has no effect (a startup warning is logged); `<PREFIX>_AUDIT_APPROVED_BY`/`_RATIONALE` are optional audit annotations.
+- The retained guarantee is **unbypassable audit over MCP and CLI alike** — no unaudited entry point. Harness = audit + runaway safety guard + undo + sanitize; `risk_level` is a descriptive audit label, not a gate.
+
+See RELEASE_NOTES.md for tool-specific changes.
+
+
+## v0.5.0 — 2026-07-20
+
+### Fixed
+- **`terminate_backend` / `cancel_query` refuse this tool's own backend**, and `update_setting` refuses the postmaster settings that would strand the undo at the next restart (`listen_addresses`, `port`, `max_connections`, `ssl`, `hba_file`, …).
+- A connection lost **mid-statement** now raises a dedicated error and is audited as `unknown`, not `error`..
+- Harness: a write whose response is lost is audited `status=unknown`, not `error` — it may have taken effect. Undo tokens gain `effectVerified` (undo.db migrated in place).
+- Harness: a dry-run no longer records an undo token, and no longer requires a named approver. Guards now run on the preview path.
+- Truncated strings end in an ellipsis instead of being cut silently; error messages are capped at 800 chars, not 300.
+
+See RELEASE_NOTES.md for the full detail.
+
 ## v0.3.0 — 2026-07-17
 
 ### Added

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.4.0
+Version: 0.6.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
-Author-email: wei <zhouwei008@gmail.com>
+Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -22,8 +22,8 @@ Description-Content-Type: text/markdown
 
 Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
 **psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
-**built-in governance harness**: unified audit log, policy engine, token/runaway
-budget guard, undo-token recording, and graduated-autonomy risk tiers.
+**built-in governance harness**: unified audit log, token/runaway
+budget guard, undo-token recording, and descriptive risk-tier labels.
 Beyond the mock test suite, the reads, a governed write, and its undo have been
 exercised against a live PostgreSQL 16.14 instance — see [`docs/VERIFICATION.md`](docs/VERIFICATION.md).
 
@@ -70,40 +70,25 @@ The flagship analyses accept injected records for pure/offline analysis, or pull
 live from a configured target. `top_queries`/`slow_query_rca` require the
 `pg_stat_statements` extension; the read role should have `pg_monitor`.
 
-## Security: read-only mode
+## What this tool does, and does not, decide
 
-This tool is meant to be handed to an AI agent, so its safety story is enforced
-by the server rather than requested in a prompt:
+It delivers PostgreSQL DBA operations — reads and writes — accurately and
+efficiently, and records every one of them. It does **not** decide whether a
+write is allowed to happen. That is the agent's judgement, or the permission of
+the account you connect it with: connect with a PostgreSQL role that has no
+write privileges (a read-only role, or one without INSERT/UPDATE/DELETE/DDL),
+and the writes fail at the server — the place that actually owns the
+permission.
 
-```bash
-export POSTGRES_READ_ONLY=1
-```
-
-With that set, the **10 write tools are never registered**. An MCP client
-lists **25 tools instead of 35** — the writes are not hidden, not
-gated behind a flag, and not merely refused when called. They are absent from
-the session. A model cannot invoke a tool it was never offered, and cannot be
-argued into one.
-
-That distinction is the whole point. A tool that exists but refuses still invites
-retry loops and "I'll describe the call instead" behaviour from smaller models,
-and it leaves a reviewer trusting a promise. An absent tool is a fact you can
-check: connect, list the tools, and see that the writes are not there.
-
-Enforcement is two layers deep, so the switch cannot be sidestepped by changing
-entry point:
-
-| Layer | What it does | Covers |
-|---|---|---|
-| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
-| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
-
-Read operations are unaffected, and every call is still audited to
-`~/.postgres-aiops/audit.db`.
+So there is no read-only switch, no policy file, no approval gate to configure.
+The one thing the tool guarantees is that nothing is silent: **every call, over
+MCP and over the CLI alike, lands an audit row** in `~/.postgres-aiops/audit.db`,
+and destructive writes still capture their before-state and record an inverse
+where one exists.
 
-> The read/write split is derived from each tool's declared `risk_level`, and a
-> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
-> tool's own documentation — so a write can't quietly present itself as a read.
+> Each tool declares a `risk_level`, carried into the audit row as a descriptive
+> tier (none/confirm/review) — so a reviewer can see at a glance that a row was
+> a high-risk delete. It is a label, not a gate.
 
 Running a smaller / local model? See
 [agent-guardrails.md](skills/postgres-aiops/references/agent-guardrails.md) — it lists
@@ -132,15 +117,18 @@ postgres-aiops-mcp
 
 Every MCP tool passes through the bundled `@governed_tool` harness:
 
-- **Audit** — every call (params, result, status, duration, risk tier, approver,
-  rationale) is logged to `~/.postgres-aiops/audit.db` (relocatable via
-  `POSTGRES_AIOPS_HOME`).
-- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
-- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
-  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE` — the env-var names
-  the bundled harness reads).
+- **Audit** — every call (params, result, status, duration, risk tier, and any
+  operator-supplied approver/rationale) is logged to `~/.postgres-aiops/audit.db`
+  (relocatable via `POSTGRES_AIOPS_HOME`). The CLI writes the same row the MCP
+  path does — there is no unaudited entry point.
+- **Runaway guard** — a safety backstop, not an authorization gate: the same call
+  hammered in a tight loop trips a circuit breaker. Disable with
+  `POSTGRES_RUNAWAY_MAX=0`; optional hard ceilings via `POSTGRES_MAX_TOOL_CALLS` /
+  `POSTGRES_MAX_TOOL_SECONDS`.
 - **Undo recording** — reversible writes record an inverse descriptor built from
   the fetched before-state.
+- **Risk tier** — a descriptive label on the audit row derived from `risk_level`;
+  it gates nothing.
 
 ## Scope
 

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/README.md

@@ -6,8 +6,8 @@
 
 Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
 **psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
-**built-in governance harness**: unified audit log, policy engine, token/runaway
-budget guard, undo-token recording, and graduated-autonomy risk tiers.
+**built-in governance harness**: unified audit log, token/runaway
+budget guard, undo-token recording, and descriptive risk-tier labels.
 Beyond the mock test suite, the reads, a governed write, and its undo have been
 exercised against a live PostgreSQL 16.14 instance — see [`docs/VERIFICATION.md`](docs/VERIFICATION.md).
 
@@ -54,40 +54,25 @@ The flagship analyses accept injected records for pure/offline analysis, or pull
 live from a configured target. `top_queries`/`slow_query_rca` require the
 `pg_stat_statements` extension; the read role should have `pg_monitor`.
 
-## Security: read-only mode
+## What this tool does, and does not, decide
 
-This tool is meant to be handed to an AI agent, so its safety story is enforced
-by the server rather than requested in a prompt:
+It delivers PostgreSQL DBA operations — reads and writes — accurately and
+efficiently, and records every one of them. It does **not** decide whether a
+write is allowed to happen. That is the agent's judgement, or the permission of
+the account you connect it with: connect with a PostgreSQL role that has no
+write privileges (a read-only role, or one without INSERT/UPDATE/DELETE/DDL),
+and the writes fail at the server — the place that actually owns the
+permission.
 
-```bash
-export POSTGRES_READ_ONLY=1
-```
-
-With that set, the **10 write tools are never registered**. An MCP client
-lists **25 tools instead of 35** — the writes are not hidden, not
-gated behind a flag, and not merely refused when called. They are absent from
-the session. A model cannot invoke a tool it was never offered, and cannot be
-argued into one.
-
-That distinction is the whole point. A tool that exists but refuses still invites
-retry loops and "I'll describe the call instead" behaviour from smaller models,
-and it leaves a reviewer trusting a promise. An absent tool is a fact you can
-check: connect, list the tools, and see that the writes are not there.
-
-Enforcement is two layers deep, so the switch cannot be sidestepped by changing
-entry point:
-
-| Layer | What it does | Covers |
-|---|---|---|
-| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
-| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
-
-Read operations are unaffected, and every call is still audited to
-`~/.postgres-aiops/audit.db`.
+So there is no read-only switch, no policy file, no approval gate to configure.
+The one thing the tool guarantees is that nothing is silent: **every call, over
+MCP and over the CLI alike, lands an audit row** in `~/.postgres-aiops/audit.db`,
+and destructive writes still capture their before-state and record an inverse
+where one exists.
 
-> The read/write split is derived from each tool's declared `risk_level`, and a
-> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
-> tool's own documentation — so a write can't quietly present itself as a read.
+> Each tool declares a `risk_level`, carried into the audit row as a descriptive
+> tier (none/confirm/review) — so a reviewer can see at a glance that a row was
+> a high-risk delete. It is a label, not a gate.
 
 Running a smaller / local model? See
 [agent-guardrails.md](skills/postgres-aiops/references/agent-guardrails.md) — it lists
@@ -116,15 +101,18 @@ postgres-aiops-mcp
 
 Every MCP tool passes through the bundled `@governed_tool` harness:
 
-- **Audit** — every call (params, result, status, duration, risk tier, approver,
-  rationale) is logged to `~/.postgres-aiops/audit.db` (relocatable via
-  `POSTGRES_AIOPS_HOME`).
-- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
-- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
-  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE` — the env-var names
-  the bundled harness reads).
+- **Audit** — every call (params, result, status, duration, risk tier, and any
+  operator-supplied approver/rationale) is logged to `~/.postgres-aiops/audit.db`
+  (relocatable via `POSTGRES_AIOPS_HOME`). The CLI writes the same row the MCP
+  path does — there is no unaudited entry point.
+- **Runaway guard** — a safety backstop, not an authorization gate: the same call
+  hammered in a tight loop trips a circuit breaker. Disable with
+  `POSTGRES_RUNAWAY_MAX=0`; optional hard ceilings via `POSTGRES_MAX_TOOL_CALLS` /
+  `POSTGRES_MAX_TOOL_SECONDS`.
 - **Undo recording** — reversible writes record an inverse descriptor built from
   the fetched before-state.
+- **Risk tier** — a descriptive label on the audit row derived from `risk_level`;
+  it gates nothing.
 
 ## Scope
 

postgres_aiops-0.6.0/RELEASE_NOTES.md

@@ -0,0 +1,33 @@
+# Release notes — postgres-aiops 0.6.0
+
+Previous release: 0.5.0.
+
+## BREAKING — the authorization layer is removed
+
+This tool no longer decides whether a write is permitted. Read-only mode
+(`<PREFIX>_READ_ONLY`), the graduated-approval / approver gate, and the
+`rules.yaml` deny engine are **all gone**. Whether an operation runs is the
+agent's judgement, or the permission of the account you connect it with — point
+it at a read-only credential and the write fails at the server, the place that
+actually owns the permission.
+
+What the tool guarantees instead is that **nothing is silent**: every operation,
+over MCP **and** the CLI alike, lands a row in the audit log — there is no
+unaudited entry point. Destructive writes still capture their before-state and
+record an undo token where a clean inverse exists.
+
+- If you set `<PREFIX>_READ_ONLY=1`, it now has **no effect** and the MCP server
+  logs a warning at startup. Restrict writes via the connecting account instead.
+- `<PREFIX>_AUDIT_APPROVED_BY` / `<PREFIX>_AUDIT_RATIONALE` still work, but are now
+  **optional audit annotations** — recorded on the row when set, never required.
+- The declared `risk_level` is carried into the audit row as a descriptive tier
+  (a label, not a gate).
+
+The governance harness is now: **audit (MCP+CLI, unbypassable) · runaway/budget
+safety guard · undo recording · output sanitize**. `policy.py` is a small
+risk-tier classifier; `governance/readonly.py` is deleted.
+
+
+## Also in this tool
+
+- **`explain --analyze` is now genuinely read-only.** ANALYZE executes the statement, so a `SELECT ... INTO` could create a table; it now runs inside a rolled-back transaction, so no side effect can persist.

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/SECURITY.md

@@ -46,9 +46,12 @@ Every MCP tool runs through the bundled `@governed_tool` harness
 - **Token/runaway budget** — hard ceilings (`POSTGRES_MAX_TOOL_CALLS` /
   `POSTGRES_MAX_TOOL_SECONDS` — the env-var names the bundled harness reads) plus
   an on-by-default guard that trips a tight poll/retry loop.
-- **Graduated risk tiers** — `~/.postgres-aiops/rules.yaml` `risk_tiers` gate
-  writes by environment/tag; the highest tiers require a recorded approver
-  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE`).
+- **Risk tiers** — a descriptive label (`none`/`confirm`/`review`) carried into
+  the audit row from each tool's declared `risk_level`; it gates nothing. The
+  harness does not decide whether a write is permitted — that is the agent's
+  judgement or the connecting account's permissions. `POSTGRES_AUDIT_APPROVED_BY`
+  / `POSTGRES_AUDIT_RATIONALE` are optional annotations recorded on the audit
+  row, never required, never blocking.
 - **Undo-token recording** — reversible writes fetch the **real before-state
   first** and record a faithful inverse (`create_index`↔`drop_index`, where drop
   captures `pg_get_indexdef`; `update_setting` restores the prior value).

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/docs/VERIFICATION.md

@@ -28,9 +28,10 @@ suite predicts. Sections left open below are **not** claimed.
   (with `drop_index` capturing `pg_get_indexdef` **before** dropping), and
   `update_setting` capturing the prior value. Irreversible ops (terminate,
   cancel, vacuum, analyze, reindex, reset stats) declare no undo.
-- Governance persistence: audited rows land in the SQLite audit DB, and the
-  secure-by-default approver gate refuses high-risk writes with no `rules.yaml`
-  and no `POSTGRES_AUDIT_APPROVED_BY`.
+- Governance persistence: audited rows land in the SQLite audit DB. The harness
+  authorizes nothing — there is no read-only, deny-rule, or approver gate to
+  test; an approver, when supplied, is recorded on the audit row as an optional
+  annotation.
 
 ## Prerequisites for a live run
 
@@ -113,10 +114,12 @@ are open — record them as gaps rather than silently passing.
       long-running backend (**open gap** — not exercised live).
 - [ ] `remediate reindex` on a real index (**open gap**).
 
-### 6. Governance actually gates
-- [x] ✅ With no `~/.postgres-aiops/rules.yaml`, a high-risk write was refused
-      until `POSTGRES_AUDIT_APPROVED_BY` named an approver (secure-by-default);
-      the approver and `POSTGRES_AUDIT_RATIONALE` appear in the audit row.
+### 6. Governance records, it does not gate
+- [x] ✅ The harness authorizes nothing — there is no read-only, deny-rule, or
+      approver gate to test. A high-risk write ran with no approver set and
+      landed an `ok` audit row; when `POSTGRES_AUDIT_APPROVED_BY` and
+      `POSTGRES_AUDIT_RATIONALE` were set, they appeared in the audit row as
+      optional annotations.
 - [x] ✅ Relocation: with `POSTGRES_AIOPS_HOME` set, `audit.db`, the undo store,
       and `secrets.enc` all land under that directory.
 - [ ] A tight poll loop trips the runaway budget guard rather than hammering the

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/mcp_server/_shared.py

@@ -20,14 +20,30 @@ from typing import Any, Optional
 from mcp.server.fastmcp import FastMCP
 
 from postgres_aiops.config import load_config
-from postgres_aiops.connection import ConnectionManager, PgError
-from postgres_aiops.governance import sanitize
+from postgres_aiops.connection import ConnectionManager, PgConnectionLostError, PgError
+from postgres_aiops.governance import mark_unknown, sanitize
 
 logger = logging.getLogger(__name__)
 
 _DOCTOR_HINT = "Run 'postgres-aiops doctor' to verify connectivity and credentials."
 
 
+# Long enough to carry the remediation sentence. These messages teach the
+# caller what to do instead, and that clause comes last — a 300-char cap cut
+# it off silently on every refusal long enough to need one.
+_ERROR_MAX = 800
+
+
+# Failures that leave the statement's fate genuinely undetermined. Raised
+# only from the statement-executing path, so it means an ESTABLISHED link
+# died mid-statement — not that the server was unreachable. The driver gives
+# both the same class, so the connection layer discriminates by position and
+# raises a dedicated class; this layer only has to recognise it.
+# PostgreSQL rolls back on backend termination, so usually nothing landed —
+# but a COMMIT whose acknowledgement was lost did land.
+_UNDETERMINED_ERRORS = (PgConnectionLostError,)
+
+
 def _safe_error(exc: Exception, tool: str) -> str:
     """Return an agent-safe error string; log full detail server-side only."""
     logger.error("Tool %s failed", tool, exc_info=True)
@@ -41,7 +57,7 @@ def _safe_error(exc: Exception, tool: str) -> str:
         PgError,
     )
     if isinstance(exc, _passthrough):
-        return sanitize(str(exc), 300)
+        return sanitize(str(exc), _ERROR_MAX)
     return f"{type(exc).__name__}: operation failed."
 
 
@@ -65,7 +81,13 @@ def tool_errors(shape: str = "dict") -> Callable:
                     return [{"error": msg, "hint": _DOCTOR_HINT}]
                 if shape == "str":
                     return f"Error: {msg} {_DOCTOR_HINT}"
-                return {"error": msg, "hint": _DOCTOR_HINT}
+                payload = {"error": msg, "hint": _DOCTOR_HINT}
+                # Flatten the exception into a dict and its type is gone
+                # for good — so classify here, while it is still known,
+                # whether the operation may nonetheless have taken effect.
+                if isinstance(e, _UNDETERMINED_ERRORS):
+                    return mark_unknown(payload)
+                return payload
 
         return wrapper
 

postgres_aiops-0.6.0/mcp_server/server.py

@@ -0,0 +1,51 @@
+"""MCP server wrapping postgres-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``postgres_aiops`` ops package and is wrapped with the
+postgres-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed PostgreSQL DBA operations (preview).
+For PostgreSQL servers/clusters via psycopg 3.
+
+Source: https://github.com/AIops-tools/Postgres-AIops
+License: MIT
+"""
+
+import logging
+import os
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    activity,
+    analysis,
+    indexes,
+    queries,
+    remediation,
+    replication,
+    server,
+    tables,
+    undo,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+logger = logging.getLogger(__name__)
+
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    # Read-only mode was removed. Warn a deployment that still exports the old
+    # switch so it gets one audible signal instead of silently gaining writes.
+    if os.environ.get("POSTGRES_READ_ONLY"):
+        logger.warning(
+            "POSTGRES_READ_ONLY is set but no longer has any effect — "
+            "read-only mode was removed. Writes ARE enabled. Restrict them via "
+            "the connecting account's permissions instead (a read-only socket / "
+            "scope-limited token)."
+        )
+    mcp.run(transport="stdio")

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/mcp_server/tools/remediation.py

@@ -1,7 +1,7 @@
 """PostgreSQL maintenance MCP tools (guarded writes).
 
 The state-changing tools. Every one is wrapped with the governance harness
-(audit + graduated approval tier) and takes a ``dry_run`` preview. Reversible
+(audit + risk-tier tagging) 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 record none.
 
@@ -73,12 +73,18 @@ def terminate_backend(pid: int, dry_run: bool = False, target: Optional[str] = N
     Captures the backend's pid + query for the audit trail; a terminate cannot be
     undone, so no undo is offered. Pass dry_run=True to preview.
 
+    Refuses this tool's own backend pid — including under dry_run, which must
+    report a refusal rather than preview a call that will be refused.
+
     Args:
         pid: Backend process id (from list_activity).
         dry_run: If True, preview without terminating.
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    # Ahead of the dry_run return: a preview whose real call would be refused
+    # must say so, or the caller reads the refusal as transient and retries.
+    ops.guard_terminate_backend(conn, pid, "terminate_backend")
     if dry_run:
         return {"dryRun": True, "wouldTerminate": {"pid": pid}}
     return ops.terminate_backend(conn, pid)
@@ -93,12 +99,16 @@ def cancel_query(pid: int, dry_run: bool = False, target: Optional[str] = None)
     Captures the backend's pid + query for audit; a cancel has no undo. Pass
     dry_run=True to preview.
 
+    Refuses this tool's own backend pid — the query it would cancel is this very
+    call. Enforced under dry_run too.
+
     Args:
         pid: Backend process id (from list_activity).
         dry_run: If True, preview without cancelling.
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    ops.guard_terminate_backend(conn, pid, "cancel_query")
     if dry_run:
         return {"dryRun": True, "wouldCancel": {"pid": pid}}
     return ops.cancel_query(conn, pid)
@@ -283,6 +293,11 @@ def update_setting(
     performed automatically. The prior value is captured so the harness records an
     undo that sets it back. Pass dry_run=True to preview.
 
+    Refuses the connection-affecting postmaster settings (listen_addresses,
+    port, max_connections, superuser_reserved_connections, ssl, hba_file):
+    nothing breaks now, but the operator's next restart applies them and strands
+    the undo. Enforced under dry_run too.
+
     Args:
         name: The configuration parameter name (e.g. work_mem).
         value: The new value (as a string).
@@ -290,6 +305,9 @@ def update_setting(
         target: Target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    # Static denylist, so this costs nothing and cannot diverge from the real
+    # call — a preview of a refused setting must report the refusal.
+    ops.guard_update_setting(name)
     if dry_run:
         return {"dryRun": True, "wouldSet": {"name": name, "value": value}}
     return ops.update_setting(conn, name, value)

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/mcp_server/tools/undo.py

@@ -3,10 +3,9 @@
 Every governed write records a replayable inverse descriptor (tool + params) to
 ``undo.db``. This module closes the loop: ``undo_apply`` looks up a recorded
 descriptor and dispatches it to the named governed tool, so the inverse runs on
-the SAME governance path as any other call (audited, budget-checked, and — if
-the inverse itself is destructive — re-gated by its own risk tier / approver
-requirement). ``undo_apply`` is itself governed; the real risk is enforced by
-the inner tool it calls.
+the SAME governance path as any other call (audited, budget-checked, and
+tagged with its own risk tier). ``undo_apply`` is itself governed; audit and
+risk-tier labeling for the inverse are handled by the inner tool it calls.
 
 Note: recorded ``undo_params`` are the redacted safe-params captured at record
 time, so an inverse that would need a secret value cannot be replayed here — by
@@ -36,6 +35,11 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
     Each entry names the original tool, the inverse tool that ``undo_apply``
     would run, and a human note. Use the ``undoId`` with ``undo_apply``.
 
+    Each entry carries ``effectVerified``. False means the original write
+    lost its response, so the change it reverses is PROBABLE, not confirmed —
+    check the live state before applying, and do not report the result as a
+    restore of a state that may never have been reached.
+
     Args:
         limit: Max rows to return (default 50).
         target: Unused (undo state is host-local); accepted for CLI uniformity.
@@ -52,6 +56,7 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
                 "originalTool": r["tool"],
                 "inverseTool": r["undo_tool"],
                 "note": r.get("note", ""),
+                "effectVerified": bool(r.get("effect_verified", 1)),
             }
             for r in rows
         ],
@@ -67,9 +72,9 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
 def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None) -> dict:
     """[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
 
-    The inverse runs through its own governed tool, so its real risk tier and
-    any approver requirement are enforced there. Pass dry_run=True to preview
-    the inverse call without executing it. A token can only be applied once.
+    The inverse runs through its own governed tool, so its risk tier and audit
+    row are recorded there. Pass dry_run=True to preview the inverse call
+    without executing it. A token can only be applied once.
 
     Args:
         undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
@@ -86,12 +91,27 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
         )
 
     inverse_tool = rec["undo_tool"]
+    # Unreadable parameters must stop the replay, not be replaced with {}.
+    # Defaulting dispatched the inverse tool with NO ARGUMENTS: for a tool whose
+    # parameters all have defaults that runs a real, unintended operation, and
+    # dry_run previewed it as a legitimate no-arg inverse. Refusing is the only
+    # honest answer — the recorded intent is gone, so there is nothing to apply.
+    raw = rec["undo_params"]
     try:
-        params = json.loads(rec["undo_params"]) if rec["undo_params"] else {}
-    except (ValueError, TypeError):
-        params = {}
+        params = json.loads(raw) if raw else {}
+    except (ValueError, TypeError) as exc:
+        raise ValueError(
+            f"Undo '{undo_id}' has unreadable recorded parameters, so its inverse "
+            f"cannot be replayed. Inspect the row in undo.db and re-run the "
+            f"inverse tool '{inverse_tool}' by hand if the change still needs "
+            f"reversing."
+        ) from exc
     if not isinstance(params, dict):
-        params = {}
+        raise ValueError(
+            f"Undo '{undo_id}' recorded parameters of type "
+            f"'{type(params).__name__}' rather than an object, so its inverse "
+            f"cannot be replayed. Re-run the inverse tool '{inverse_tool}' by hand."
+        )
 
     fn = _resolve_tool(inverse_tool)
     if fn is None:
@@ -99,10 +119,12 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
             f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
         )
 
+    effect_verified = bool(rec.get("effect_verified", 1))
     if dry_run:
         return {
             "dryRun": True,
             "undoId": undo_id,
+            "effectVerified": effect_verified,
             "wouldApply": {"tool": inverse_tool, "params": params},
         }
 
@@ -121,6 +143,15 @@ def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None
     return {
         "undoId": undo_id,
         "applied": applied,
+        "effectVerified": effect_verified,
         "inverseTool": inverse_tool,
         "result": result,
+        "note": (
+            ""
+            if effect_verified
+            else "The original write lost its response, so it was never confirmed "
+            "to have taken effect. This inverse ran regardless; report the "
+            "CURRENT server state, not a restore that may have had nothing "
+            "to restore."
+        ),
     }

{postgres_aiops-0.4.0 → postgres_aiops-0.6.0}/postgres_aiops/cli/_common.py

@@ -27,10 +27,18 @@ DryRunOption = Annotated[
 
 
 def _cli_error_types() -> tuple[type[BaseException], ...]:
-    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    """Exceptions translated to a one-line teaching error instead of a traceback.
+
+    ``PolicyDenied``/``BudgetExceeded`` are raised by ``@governed_tool`` OUTSIDE
+    the tool body, so ``tool_errors`` never sees them and they never arrive as
+    an ``{"error": ...}`` dict. Their message is the teaching text (which
+    approver to set, which budget was hit) — without them here a refusal
+    reaches the CLI as a traceback instead.
+    """
     from postgres_aiops.connection import PgError
+    from postgres_aiops.governance import BudgetExceeded, PolicyDenied
 
-    return (PgError, KeyError, OSError, ValueError)
+    return (PgError, PolicyDenied, BudgetExceeded, KeyError, OSError, ValueError)
 
 
 def cli_errors(fn: Callable) -> Callable:
@@ -95,6 +103,28 @@ def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = No
     console.print("[magenta]  Run without --dry-run to execute.[/]\n")
 
 
+def dry_run_preview(
+    preview: Any, *, operation: str, api_call: str, parameters: dict | None = None
+) -> None:
+    """Render a GOVERNED dry-run result as the human-readable DRY-RUN banner.
+
+    ``preview`` must come from calling the governed tool with ``dry_run=True``,
+    so every guard it carries has already run against the real target. A refusal
+    arrives as ``{"error": ...}`` (``tool_errors`` flattens the exception) — it is
+    printed like any other CLI error and exits non-zero, exactly as the real
+    write would. Printing a green banner for a call that is about to be refused
+    is the preview being wrong, not merely incomplete.
+
+    On the allowed path the banner is byte-for-byte what it always was: routing
+    through the governed call buys the guard and the audit row, not a new
+    serialization.
+    """
+    if isinstance(preview, dict) and preview.get("error"):
+        console.print(f"[red]Error: {preview['error']}[/]")
+        raise typer.Exit(1)
+    dry_run_print(operation=operation, api_call=api_call, parameters=parameters)
+
+
 def double_confirm(action: str, resource: str) -> None:
     """Require two confirmations for a destructive operation."""
     console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")