queue-aiops 0.2.2__tar.gz → 0.3.0__tar.gz

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.3.0 — 2026-07-20
+
+### Fixed
+- **`redis_config_set` refuses the parameters that lock this tool out of the server**: `requirepass`, `masterauth`, `bind`, `protected-mode`, `maxclients`, `port`, `unixsocket`, `aclfile`, and anything `tls-*`.
+- `list_clients` no longer returns this tool's own connection, and `redis_kill_client` refuses it — by id or by address.
+- 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.1.1 — 2026-07-17
 
 ### Fixed

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: queue-aiops
-Version: 0.2.2
+Version: 0.3.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 <zhouwei008@gmail.com>
+Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11

queue_aiops-0.3.0/RELEASE_NOTES.md

@@ -0,0 +1,50 @@
+# Release notes — queue-aiops 0.3.0
+
+Previous release: 0.2.2.
+
+## In this tool
+
+- **`redis_config_set` refuses the parameters that lock this tool out of the server**: `requirepass`, `masterauth`, `bind`, `protected-mode`, `maxclients`, `port`, `unixsocket`, `aclfile`, and anything `tls-*`. Setting `requirepass` invalidated the stored credential, and the recorded undo then needed a connection that could no longer authenticate. The refusal happens **before** the prior value is read, which also stops the live password being copied into `audit.db` and the undo store.
+- `list_clients` no longer returns this tool's own connection, and `redis_kill_client` refuses it — by id or by address. The two sibling tools already filtered themselves out on the read path; Redis did not.
+
+## Every tool in the line: previews and undetermined outcomes
+
+This release fixes three harness defects that were silently degrading the audit
+trail and the undo store.
+
+**A write that loses its response is no longer recorded as a failure.** The
+harness assumed a sanitized error meant nothing had happened. That assumption is
+false in exactly the case that matters most: when a write severs its own
+connection, the request has already landed, the response cannot come back, and
+the operation was recorded as `status=error` with **no undo token created at
+all**. Transport-level failures are now audited as `status=unknown`, the result
+says plainly that the operation may have taken effect and should be verified
+before retrying, and a write that stashed its before-state has its inverse
+recorded anyway — flagged `effectVerified: false`, which `undo_list` and
+`undo_apply` both surface. Existing `undo.db` files are migrated in place; their
+rows read as verified, which is accurate, since the old code only ever recorded
+on the confirmed path.
+
+**A dry-run no longer writes an undo token.** Previews were recording inverses
+built from a before-state they never had: the undo callback's permissive default
+filled the gap with a guess, producing a real, applicable token for an operation
+that never happened.
+
+**A dry-run no longer demands a named approver.** Requiring an approval in order
+to ask whether something needs approval inverts what a preview is for. The tier
+is still computed and still audited, so the preview can tell you an approver
+will be needed; it just no longer refuses to answer. The write itself is gated
+exactly as before.
+
+The invariant, now stated: **a dry_run may read; it must never write.** Guards
+run on the preview path, which means a preview can and does report that an
+operation would be refused.
+
+## Also line-wide
+
+- **Truncated text now ends in an ellipsis** instead of being cut silently. This
+  line already treats a silent cut as a defect for lists; it was doing exactly
+  that to strings.
+- **Error messages are capped at 800 characters, not 300.** These messages end
+  with what to do instead, so the cap was removing the most useful sentence of
+  every long refusal.

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/mcp_server/_shared.py

@@ -17,17 +17,46 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Optional
 
+import httpx
+import redis
 from mcp.server.fastmcp import FastMCP
 
 from queue_aiops.config import load_config
 from queue_aiops.connection import ConnectionManager, QueueApiError
-from queue_aiops.governance import sanitize
+from queue_aiops.governance import mark_unknown, sanitize
 
 logger = logging.getLogger(__name__)
 
 _DOCTOR_HINT = "Run 'queue-aiops doctor' to verify connectivity and credentials."
 
 
+# Failures that leave the request's fate genuinely undetermined: the bytes
+# went out and either the response or the rest of the connection was lost. A
+# write that hits one of these MAY have taken effect on the server.
+#
+# Deliberately narrow. Connect errors and pool timeouts mean the request never
+# left this process, and an API error carrying a status means the server
+# answered — all are ordinary failures where nothing, or a known something,
+# happened. Marking them 'unknown' would cry wolf on every unreachable host.
+# redis TimeoutError means the command went out and the reply did not come
+# back. redis ConnectionError is excluded: it also covers a connection that
+# was never established.
+_UNDETERMINED_ERRORS = (
+    httpx.ReadTimeout,
+    httpx.WriteTimeout,
+    httpx.ReadError,
+    httpx.WriteError,
+    httpx.RemoteProtocolError,
+    redis.exceptions.TimeoutError,
+)
+
+
+# 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
+
+
 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 +70,7 @@ def _safe_error(exc: Exception, tool: str) -> str:
         QueueApiError,
     )
     if isinstance(exc, _passthrough):
-        return sanitize(str(exc), 300)
+        return sanitize(str(exc), _ERROR_MAX)
     return f"{type(exc).__name__}: operation failed."
 
 
@@ -65,7 +94,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
 

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/mcp_server/tools/undo.py

@@ -41,6 +41,11 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
     length coincidence: when it is true there are MORE tokens than shown, so
     re-run with a higher ``limit`` rather than reporting the list as complete.
 
+    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, capped at 500).
         target: Unused (undo state is host-local); accepted for CLI uniformity.
@@ -61,6 +66,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
         ],
@@ -105,10 +111,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},
         }
 
@@ -127,6 +135,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."
+        ),
     }

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/mcp_server/tools/writes.py

@@ -141,6 +141,13 @@ def redis_config_set(
     restores its prior value. Runtime-only — not persisted to the config file.
     Pass dry_run=True to preview.
 
+    Refuses the parameters that would lock this tool out of the instance
+    (requirepass, masterauth, bind, port, protected-mode, maxclients,
+    unixsocket, aclfile, tls-*) — the undo could never be replayed over a
+    connection those settings break. Change those in redis.conf and restart.
+    The refusal applies under dry_run too: a preview whose real call would be
+    refused must report that, not a green 'wouldSet'.
+
     Args:
         parameter: Config parameter name (e.g. maxmemory-policy), from redis_config_get.
         value: New value.
@@ -148,6 +155,9 @@ def redis_config_set(
         target: redis 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_config_set(parameter)
     if dry_run:
         return {"dryRun": True, "wouldSet": {"parameter": parameter, "value": value}}
     return ops.config_set(conn, parameter, value)
@@ -169,6 +179,10 @@ def redis_kill_client(
     is recorded; most clients transparently reconnect. Pass dry_run=True to
     preview.
 
+    Refuses this tool's own connection, by id or by addr — including under
+    dry_run, which must report a refusal rather than preview a call that will be
+    refused.
+
     Args:
         client_id: Client id from redis_clients (preferred).
         addr: Or the client's 'ip:port' address.
@@ -176,6 +190,9 @@ def redis_kill_client(
         target: redis 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_kill_client(conn, client_id=client_id, addr=addr)
     if dry_run:
         return {"dryRun": True, "wouldKill": {"clientId": client_id, "addr": addr}}
     return ops.kill_client(conn, client_id=client_id, addr=addr)

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "queue-aiops"
-version = "0.2.2"
+version = "0.3.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"
 requires-python = ">=3.11"
-authors = [{ name = "wei", email = "zhouwei008@gmail.com" }]
+authors = [{ name = "Wei Zhou", email = "zhouwei008@gmail.com" }]
 dependencies = [
     "redis>=5.0,<7.0",
     "httpx>=0.27,<1.0",

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/cli/_common.py

@@ -68,6 +68,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}'[/]")

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/cli/redis_cmds.py

@@ -13,7 +13,7 @@ from queue_aiops.cli._common import (
     cli_errors,
     console,
     double_confirm,
-    dry_run_print,
+    dry_run_preview,
     get_connection,
 )
 
@@ -128,8 +128,13 @@ def redis_config_set(
     from mcp_server.tools import writes as gov
 
     if dry_run:
-        dry_run_print(operation="redis_config_set", api_call="CONFIG SET",
-                      parameters={"parameter": parameter, "value": value})
+        # Through the governed call: redis_config_set refuses the self-affecting
+        # parameters, so a preview must report that rather than a green banner.
+        dry_run_preview(
+            gov.redis_config_set(parameter=parameter, value=value, dry_run=True,
+                                 target=target),
+            operation="redis_config_set", api_call="CONFIG SET",
+            parameters={"parameter": parameter, "value": value})
         return
     double_confirm("set config parameter", parameter)
     console.print_json(
@@ -150,8 +155,13 @@ def redis_kill_client(
 
     who = str(client_id) if client_id else addr
     if dry_run:
-        dry_run_print(operation="redis_kill_client", api_call="CLIENT KILL",
-                      parameters={"client_id": client_id, "addr": addr})
+        # Through the governed call: redis_kill_client refuses this tool's own
+        # connection, so a preview must report that rather than a green banner.
+        dry_run_preview(
+            gov.redis_kill_client(client_id=client_id, addr=addr, dry_run=True,
+                                  target=target),
+            operation="redis_kill_client", api_call="CLIENT KILL",
+            parameters={"client_id": client_id, "addr": addr})
         return
     double_confirm("kill client", who or "(unspecified)")
     console.print_json(

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/connection.py

@@ -161,6 +161,23 @@ class QueueConnection:
         out = self._redis_call("CLIENT LIST", "client_list")
         return [c for c in out if isinstance(c, dict)] if isinstance(out, list) else []
 
+    def redis_client_id(self) -> int | None:
+        """This connection's own client id (CLIENT ID), or None if undeterminable.
+
+        Used to keep the tool's own connection out of ``list_clients`` and to
+        refuse ``kill_client`` against it — killing the connection you are
+        calling through is an operation that destroys its own reversibility, and
+        a kill has no undo to begin with.
+
+        ``None`` means UNKNOWN and callers must treat it as such: never as
+        "it is me", and never as "it is not me" in a way that hides a real row.
+        """
+        try:
+            out = self._redis_call("CLIENT ID", "client_id")
+            return int(out) if out is not None else None
+        except Exception:  # noqa: BLE001 — unknown identity, never a false "it is me"
+            return None
+
     def redis_client_kill_id(self, client_id: int) -> int:
         """CLIENT KILL ID <id>; returns the number of clients killed."""
         out = self._redis_call(

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/governance/__init__.py

@@ -16,6 +16,12 @@ State lives under ``ops_home()`` (default ``~/.queue-aiops``).
 from queue_aiops.governance.audit import AuditEngine, get_engine
 from queue_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_budget
 from queue_aiops.governance.decorators import PolicyDenied, governed_tool
+from queue_aiops.governance.outcome import (
+    UNKNOWN_FIELD,
+    capture_prior_state,
+    is_unknown,
+    mark_unknown,
+)
 from queue_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
 from queue_aiops.governance.policy import TierDecision, get_policy_engine
 from queue_aiops.governance.readonly import READ_ONLY_ENV, is_read_only
@@ -28,6 +34,10 @@ __all__ = [
     "opt_str",
     "is_read_only",
     "READ_ONLY_ENV",
+    "capture_prior_state",
+    "mark_unknown",
+    "is_unknown",
+    "UNKNOWN_FIELD",
     "PolicyDenied",
     "get_engine",
     "AuditEngine",

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/governance/decorators.py

@@ -34,6 +34,11 @@ from typing import Any
 
 from queue_aiops.governance.audit import detect_agent, get_engine
 from queue_aiops.governance.budget import BudgetExceeded, get_budget
+from queue_aiops.governance.outcome import (
+    clear_prior_state,
+    is_unknown,
+    take_prior_state,
+)
 from queue_aiops.governance.patterns import PatternMatch, get_pattern_engine
 from queue_aiops.governance.policy import PolicyResult, get_policy_engine
 from queue_aiops.governance.readonly import is_read_only, read_only_denial
@@ -155,7 +160,7 @@ class _CallState:
         "skill", "tool_name", "agent", "start", "status", "result",
         "policy_result", "pattern_match", "audit", "policy",
         "safe_params", "env", "risk_level", "timeout_seconds",
-        "rationale", "approved_by", "risk_tier", "undo",
+        "rationale", "approved_by", "risk_tier", "undo", "dry_run",
     )
 
     def __init__(
@@ -169,6 +174,10 @@ class _CallState:
         timeout_seconds: int,
         undo: Any = None,
     ) -> None:
+        # A previous call on this thread/task may have captured before-state
+        # that its own wrapper never consumed (it raised past _annotate_result).
+        # Start clean so one call's prior state can never be recorded as another's.
+        clear_prior_state()
         self.undo = undo
         self.skill = _infer_skill(func)
         self.tool_name = func.__name__
@@ -187,6 +196,10 @@ class _CallState:
         # log and participate in env scoping (previously only kwargs did).
         params = _bind_params(signature, args, kwargs)
         self.safe_params = _redact(params, sensitive)
+        # Previews are governed like any other call — audited, policy-checked,
+        # budget-counted — but they change nothing, so two things must not apply
+        # to them: the named-approver gate, and undo recording.
+        self.dry_run = bool(params.get("dry_run", False))
         env = params.get("target", params.get("env", ""))
         self.env = str(env) if env else ""
 
@@ -269,7 +282,15 @@ def _pre_check(state: _CallState) -> None:
         params=state.safe_params,
     )
     state.risk_tier = tier.tier
-    if tier.requires_approver and not state.approved_by:
+    # A preview is not the operation. Requiring a named human approver before a
+    # caller may ask "would this even be permitted?" inverts what a preview is
+    # for — you would have to obtain the approval in order to learn whether the
+    # thing needs one, or would be refused outright. The tier is still computed
+    # and still audited, so the preview can TELL the caller an approver will be
+    # needed; it just does not demand one to answer. Deny rules, budget, the
+    # read-only switch and every self-lockout guard still apply, and the write
+    # itself is gated normally.
+    if tier.requires_approver and not state.approved_by and not state.dry_run:
         reason = (
             f"Operation '{state.tool_name}' on '{state.env or 'target'}' requires "
             f"'{tier.tier}' approval (rule: {tier.rule}) but no approver is recorded. "
@@ -322,17 +343,51 @@ def _annotate_result(state: _CallState, result: Any) -> Any:
 
 
 def _record_undo(state: _CallState, result: Any) -> None:
-    """Compute and persist the inverse descriptor for a successful write.
+    """Compute and persist the inverse descriptor for a write.
+
+    Two paths:
 
-    Best-effort: a broken undo callable or store must never fail the call.
-    Attaches ``_undo_id`` to dict results so the agent / pilot can reference it.
+    * **Confirmed** — the tool returned normally, so ``result`` carries the
+      before-state its undo callable needs. Recorded ``effect_verified=True``.
+    * **Undetermined** — the response was lost (see
+      :mod:`queue_aiops.governance.outcome`). The change may be live, so an
+      inverse still matters, but ``result`` is only an error payload. An
+      inverse is recorded ONLY when the write explicitly stashed its
+      before-state via ``capture_prior_state``; synthesizing one from an
+      empty result would produce a *wrong* inverse, which is worse than none.
+
+    Best-effort throughout: a broken undo callable or store must never fail
+    the call. Attaches ``_undo_id`` to dict results for later reference.
     """
     if state.undo is None:
         return
-    if isinstance(result, dict) and result.get("error"):
-        return  # sanitized failure — no change happened, so no inverse to record
+    if state.dry_run:
+        # A preview changed nothing, so there is nothing to invert — and the
+        # descriptor it would produce is actively dangerous. An undo callable
+        # reads the before-state out of the result, and a preview has none, so
+        # permissive defaults (``(result.get("priorState") or {}).get("running",
+        # True)``) fill the gap with a guess. That yielded a REAL, applicable
+        # start_container token for a stop that never happened.
+        return
+
+    verified = True
+    undo_input = result
+    if is_unknown(result):
+        prior = take_prior_state()
+        if prior is None:
+            _log.warning(
+                "%s.%s outcome undetermined and no prior state captured — "
+                "no inverse recorded; the change may be live and unrecorded",
+                state.skill, state.tool_name,
+            )
+            return
+        verified = False
+        undo_input = {"priorState": prior, "outcomeUnknown": True}
+    elif isinstance(result, dict) and result.get("error"):
+        return  # definite failure — no change happened, so no inverse
+
     try:
-        descriptor = state.undo(state.safe_params, result)
+        descriptor = state.undo(state.safe_params, undo_input)
     except Exception:  # noqa: BLE001 — undo computation must not fail the call
         _log.warning("undo callable for %s.%s raised", state.skill, state.tool_name,
                      exc_info=True)
@@ -347,6 +402,7 @@ def _record_undo(state: _CallState, result: Any) -> None:
             tool=state.tool_name,
             undo_descriptor=descriptor,
             orig_params=state.safe_params,
+            effect_verified=verified,
         )
         if undo_id and isinstance(result, dict):
             result.setdefault("_undo_id", undo_id)
@@ -374,7 +430,7 @@ def _finalize(state: _CallState) -> None:
     # dicts BEFORE this harness sees them) must not be audited as success —
     # compliance exception reports are built from this status.
     if state.status == "ok" and isinstance(state.result, dict) and state.result.get("error"):
-        state.status = "error"
+        state.status = "unknown" if is_unknown(state.result) else "error"
 
     duration = int((time.time() - state.start) * 1000)
 

queue_aiops-0.3.0/queue_aiops/governance/outcome.py

@@ -0,0 +1,104 @@
+"""Tell "the write did not happen" apart from "we cannot tell whether it happened".
+
+A governed write that loses its response is not a failed write. The request may
+already have landed; the only thing that certainly failed is our knowledge of
+the outcome. The harness used to collapse both into ``status='error'`` with no
+undo token — and it did so precisely where the operation was most dangerous,
+because the two coincide:
+
+    a write whose target is the very thing serving this tool's API
+    → the change takes effect
+    → the response never comes back, because what would have sent it is gone
+    → sanitized to {"error": ...} → audited as a FAILURE → no inverse recorded
+
+The audit trail then reports that the destructive call failed while the change
+is live and unrecorded. For a line whose product is "governed and reversible",
+a row that confidently states the wrong outcome is worse than a missing one.
+
+Two primitives fix that:
+
+``mark_unknown`` / ``is_unknown``
+    The MCP layer's ``tool_errors`` classifies the exception it caught. Only
+    errors that leave the request's fate genuinely undetermined (a read
+    timeout, a half-closed socket, a protocol error mid-response) are marked.
+    A connect error or a pool timeout means the request never left, and an HTTP
+    status error means the server answered — both are ordinary failures and are
+    NOT marked. The distinction is per-tool knowledge, so each tool's
+    ``mcp_server/_shared.py`` owns the exception tuple; this module only carries
+    the marker.
+
+``capture_prior_state`` / ``take_prior_state``
+    An undo callable receives ``(params, result)``. When the write raises, the
+    before-state that was read moments earlier dies with the exception and no
+    inverse can be computed. A write that wants its undo to survive a lost
+    response stashes the before-state *before* issuing the mutating request::
+
+        before = conn.get(...)
+        capture_prior_state({"running": before["running"]})
+        conn.post(...)                      # may never return
+
+    The harness then records the inverse even on the unknown path, flagged
+    ``effect_verified=False`` so nobody mistakes it for a confirmed change.
+    Opt-in by design: fabricating a descriptor from an empty result would
+    produce a *wrong* inverse, which is worse than none.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+# Public result field. Explicit rather than inferred: a caller must never have
+# to guess from the error text whether the operation may have taken effect.
+UNKNOWN_FIELD = "outcomeUnknown"
+
+_UNKNOWN_NOTE = (
+    "The request was sent but no usable response came back, so this operation "
+    "MAY have taken effect on the server. Verify the current state before "
+    "retrying — a blind retry could apply it twice."
+)
+
+# Set by a write immediately before it issues its mutating request; consumed by
+# the harness. A ContextVar (not a module global) so concurrent calls and async
+# tools never read each other's state.
+_prior_state: ContextVar[dict[str, Any] | None] = ContextVar(
+    "governed_prior_state", default=None
+)
+
+
+def mark_unknown(payload: dict[str, Any]) -> dict[str, Any]:
+    """Return a NEW error payload flagged as having an undetermined outcome."""
+    marked = dict(payload)
+    marked[UNKNOWN_FIELD] = True
+    marked["note"] = _UNKNOWN_NOTE
+    return marked
+
+
+def is_unknown(result: Any) -> bool:
+    """True when ``result`` is an error payload whose effect is undetermined."""
+    return isinstance(result, dict) and result.get(UNKNOWN_FIELD) is True
+
+
+def capture_prior_state(state: dict[str, Any]) -> None:
+    """Stash before-state so the inverse survives a lost response.
+
+    Call this AFTER reading the before-state and BEFORE issuing the mutating
+    request. Overwrites any previously captured state for this call.
+    """
+    _prior_state.set(dict(state))
+
+
+def take_prior_state() -> dict[str, Any] | None:
+    """Consume the captured before-state (harness-internal).
+
+    Consuming rather than peeking keeps one call's state from leaking into the
+    next on a reused thread or task.
+    """
+    state = _prior_state.get()
+    _prior_state.set(None)
+    return state
+
+
+def clear_prior_state() -> None:
+    """Drop any captured state. Called at the start of every governed call."""
+    _prior_state.set(None)

{queue_aiops-0.2.2 → queue_aiops-0.3.0}/queue_aiops/governance/sanitize.py

@@ -31,18 +31,27 @@ def sanitize(text: str | None, max_len: int = 500) -> str:
     payload past the cut-off by padding with junk control characters.
     ``None`` sanitizes to ``""``.
 
+    A truncated result ends in an ellipsis (U+2026) so the cut is visible. This
+    line already treats a silent cut as a defect for lists — a capped page that
+    looks complete gets reported as the whole set — and a capped string is the
+    same failure at a smaller scale: a shortened error message reads as the
+    whole explanation, and its remediation sentence, which comes last, is gone
+    without a trace.
+
     Args:
         text: Untrusted text from queue API responses.
         max_len: Maximum length after truncation. Default 500.
 
     Returns:
-        Cleaned, truncated string safe for LLM consumption.
+        Cleaned string, ellipsis-terminated when it had to be cut.
     """
     if text is None:
         return ""
     stripped = _CONTROL_CHAR_RE.sub("", str(text))
     cleaned = "".join(c for c in stripped if unicodedata.category(c) != "Cf")
-    return cleaned[:max_len]
+    if len(cleaned) <= max_len:
+        return cleaned
+    return cleaned[: max(0, max_len - 1)] + "\u2026"
 
 
 def opt_str(value: object | None, max_len: int = 500) -> str | None: