proxy-aiops 0.3.1__tar.gz → 0.4.0__tar.gz

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.4.0 — 2026-07-20
+
+### Fixed
+- **Caddy config writes refuse the `admin` subtree.** The Caddy admin API is this tool's own transport, and `admin` is an ordinary top-level key in the config tree — so `set_config_value("admin/disabled", true)` tore down the listener mid-request and left the undo with nowhere to go.
+- 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.
+
 All notable changes to proxy-aiops are documented here. This project adheres
 to [Semantic Versioning](https://semver.org/).
 

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/PKG-INFO

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

proxy_aiops-0.4.0/RELEASE_NOTES.md

@@ -0,0 +1,49 @@
+# Release notes — proxy-aiops 0.4.0
+
+Previous release: 0.3.1.
+
+## In this tool
+
+- **Caddy config writes refuse the `admin` subtree.** The Caddy admin API is this tool's own transport, and `admin` is an ordinary top-level key in the config tree — so `set_config_value("admin/disabled", true)` tore down the listener mid-request and left the undo with nowhere to go. `load_config` likewise refuses a config that disables admin or moves its listener. The tool's own troubleshooting guide already listed this as a terminal state; it just did not stop itself causing it.
+
+## 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.

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/mcp_server/_shared.py

@@ -17,11 +17,12 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Optional
 
+import httpx
 from mcp.server.fastmcp import FastMCP
 
 from proxy_aiops.config import load_config
 from proxy_aiops.connection import ConnectionManager, ProxyApiError
-from proxy_aiops.governance import sanitize
+from proxy_aiops.governance import mark_unknown, sanitize
 from proxy_aiops.platform import UnsupportedOperation
 
 logger = logging.getLogger(__name__)
@@ -29,6 +30,29 @@ logger = logging.getLogger(__name__)
 _DOCTOR_HINT = "Run 'proxy-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.
+_UNDETERMINED_ERRORS = (
+    httpx.ReadTimeout,
+    httpx.WriteTimeout,
+    httpx.ReadError,
+    httpx.WriteError,
+    httpx.RemoteProtocolError,
+)
+
+
+# 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)
@@ -43,7 +67,7 @@ def _safe_error(exc: Exception, tool: str) -> str:
         UnsupportedOperation,
     )
     if isinstance(exc, _passthrough):
-        return sanitize(str(exc), 400)
+        return sanitize(str(exc), _ERROR_MAX)
     return f"{type(exc).__name__}: operation failed."
 
 
@@ -67,7 +91,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
 

{proxy_aiops-0.3.1 → proxy_aiops-0.4.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."
+        ),
     }

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/mcp_server/tools/writes.py

@@ -131,6 +131,12 @@ def set_config_value(
     Caddy applies the change immediately. On traefik/haproxy this raises the
     support matrix's teaching error. Pass dry_run=True to preview.
 
+    Refuses the 'admin' subtree: that configures the admin API this tool speaks
+    to, so disabling or moving it would end the connection the undo needs.
+    Change the admin block in caddy's own config file and reload locally. The
+    refusal applies under dry_run too — a preview whose real call would be
+    refused must report that, not a green 'wouldSet'.
+
     Args:
         path: Slash-separated config path (from search_config / list_routes,
             e.g. apps/http/servers/srv0/routes/0/handle/0/upstreams).
@@ -139,6 +145,9 @@ def set_config_value(
         target: Proxy 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_set_config_value(conn, path, value)
     if dry_run:
         return {"dryRun": True, "wouldSet": {"path": path, "value": value}}
     return ops.set_config_value(conn, path, value)
@@ -158,12 +167,20 @@ def delete_config_path(
     Requires an approver (PROXY_AUDIT_APPROVED_BY) under the
     graduated-autonomy policy. Pass dry_run=True to preview.
 
+    Refuses the 'admin' subtree and the config root: both remove the admin API
+    this tool speaks to, leaving the undo with no way to reach the server. The
+    refusal applies under dry_run too, which must report it rather than preview
+    a call that will be refused.
+
     Args:
         path: Slash-separated config path to delete.
         dry_run: If True, preview without deleting.
         target: Proxy 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_delete_config_path(path)
     if dry_run:
         return {"dryRun": True, "wouldDelete": {"path": path}}
     return ops.delete_config_path(conn, path)
@@ -183,12 +200,20 @@ def load_config(
     Requires an approver (PROXY_AUDIT_APPROVED_BY) under the
     graduated-autonomy policy. Pass dry_run=True to preview.
 
+    Refuses a config that disables the admin API or moves admin.listen off the
+    configured base_url — the undo re-POSTs the snapshot over that same API.
+    Send the admin block unchanged, or omit it. The refusal applies under
+    dry_run too, which must report it rather than preview a refused call.
+
     Args:
         config: The full config tree to load (a JSON object).
         dry_run: If True, preview without loading.
         target: Proxy target name from config; omit for the default.
     """
     conn = _get_connection(target)
+    # Ahead of the dry_run return: costs the same config_root GET the real call
+    # makes, and in exchange the preview can never contradict it.
+    ops.guard_load_config(conn, config)
     if dry_run:
         return {"dryRun": True, "wouldLoad": {"topLevelKeys": sorted(config or {})}}
     return ops.load_config(conn, config)

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/proxy_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}'[/]")

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/proxy_aiops/cli/configcmd.py

@@ -18,7 +18,7 @@ from proxy_aiops.cli._common import (
     cli_errors,
     console,
     double_confirm,
-    dry_run_print,
+    dry_run_preview,
     get_connection,
 )
 
@@ -88,8 +88,12 @@ def config_set(
     except json.JSONDecodeError as exc:
         raise ValueError(f"value must be valid JSON: {exc}") from exc
     if dry_run:
-        dry_run_print(operation="set_config_value", api_call=f"PATCH /config/{path}",
-                      parameters={"path": path, "value": value})
+        # Through the governed call: set_config_value refuses the admin subtree,
+        # so a preview must report that rather than a green banner.
+        dry_run_preview(
+            gov.set_config_value(path=path, value=parsed, dry_run=True, target=target),
+            operation="set_config_value", api_call=f"PATCH /config/{path}",
+            parameters={"path": path, "value": value})
         return
     double_confirm("set config value at", path)
     console.print_json(json.dumps(gov.set_config_value(path=path, value=parsed, target=target)))
@@ -106,8 +110,12 @@ def config_delete(
     from mcp_server.tools import writes as gov
 
     if dry_run:
-        dry_run_print(operation="delete_config_path", api_call=f"DELETE /config/{path}",
-                      parameters={"path": path})
+        # Through the governed call: delete_config_path refuses the admin subtree
+        # and the config root, so a preview must report that.
+        dry_run_preview(
+            gov.delete_config_path(path=path, dry_run=True, target=target),
+            operation="delete_config_path", api_call=f"DELETE /config/{path}",
+            parameters={"path": path})
         return
     double_confirm("delete config path", path)
     console.print_json(json.dumps(gov.delete_config_path(path=path, target=target)))

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/proxy_aiops/governance/__init__.py

@@ -16,6 +16,12 @@ State lives under ``ops_home()`` (default ``~/.proxy-aiops``).
 from proxy_aiops.governance.audit import AuditEngine, get_engine
 from proxy_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_budget
 from proxy_aiops.governance.decorators import PolicyDenied, governed_tool
+from proxy_aiops.governance.outcome import (
+    UNKNOWN_FIELD,
+    capture_prior_state,
+    is_unknown,
+    mark_unknown,
+)
 from proxy_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
 from proxy_aiops.governance.policy import TierDecision, get_policy_engine
 from proxy_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",

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/proxy_aiops/governance/decorators.py

@@ -34,6 +34,11 @@ from typing import Any
 
 from proxy_aiops.governance.audit import detect_agent, get_engine
 from proxy_aiops.governance.budget import BudgetExceeded, get_budget
+from proxy_aiops.governance.outcome import (
+    clear_prior_state,
+    is_unknown,
+    take_prior_state,
+)
 from proxy_aiops.governance.patterns import PatternMatch, get_pattern_engine
 from proxy_aiops.governance.policy import PolicyResult, get_policy_engine
 from proxy_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:`proxy_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)
 

proxy_aiops-0.4.0/proxy_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)

{proxy_aiops-0.3.1 → proxy_aiops-0.4.0}/proxy_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 proxy 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: