wardn 0.1.0.dev0__py3-none-any.whl

wardn/__init__.py

@@ -0,0 +1,32 @@
+"""wardn — bounded, auditable action governor for LLM agents.
+
+The MCP stdio proxy (`wardn proxy`) is the primary surface. The engine API
+below is public: `govern_call` + `Engine` + `LedgerWriter` are the whole
+enforcement loop for embedding wardn in front of any tool-calling boundary,
+MCP or not (see docs/embedding.md). Compatibility promises attach to the
+ledger format and the proxy CLI; the Python API aims for the same but may
+still move in minor versions before 1.0.
+"""
+
+from ._version import __version__
+from .approvals import QueueError
+from .diff import LedgerDiff, RunSummary, diff_ledgers, render_diff
+from .engine import Engine, classify
+from .ledger import (LEDGER_FORMAT, Folded, LedgerError, LedgerWriter,
+                     ReplayDivergence, fold, read_ledger, replay)
+from .orchestrator import govern_call, refusal_result, text_of
+from .policy import (POLICY_FORMAT, Budget, Policy, PolicyError, Rule,
+                     policy_from_json)
+from .revert import RevertError, RevertMismatch, revert
+from .types import Decision, ToolAnnotations, ToolRequest, WardnError
+
+__all__ = [
+    "__version__",
+    "Budget", "Decision", "Engine", "Folded", "LEDGER_FORMAT", "LedgerDiff",
+    "LedgerError", "LedgerWriter", "POLICY_FORMAT", "Policy", "PolicyError",
+    "QueueError", "ReplayDivergence", "RevertError", "RevertMismatch",
+    "Rule", "RunSummary", "ToolAnnotations", "ToolRequest", "WardnError",
+    "classify", "diff_ledgers", "fold", "govern_call", "policy_from_json",
+    "read_ledger", "refusal_result", "render_diff", "replay", "revert",
+    "text_of",
+]

wardn/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

wardn/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0.dev0"

wardn/approvals.py

@@ -0,0 +1,103 @@
+"""The approval queue: one JSON file per run, shared between the proxy
+(which parks and polls) and `wardn review` (which lists and decides).
+
+Writes are atomic (temp file + os.replace) and reads retry briefly, since
+the two sides race on Windows file locks. Verdicts land in the ledger as
+approval events; the queue file itself is working state, not the record.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from .types import WardnError
+
+QUEUE_FORMAT = "wardn-queue/1"
+
+_RETRIES = 40
+_RETRY_SLEEP = 0.05
+
+
+class QueueError(WardnError):
+    pass
+
+
+def _read(path: Path) -> dict:
+    if not path.exists():
+        return {"format": QUEUE_FORMAT, "items": []}
+    for attempt in range(_RETRIES):
+        try:
+            doc = json.loads(path.read_text(encoding="utf-8"))
+            if doc.get("format") != QUEUE_FORMAT:
+                raise QueueError(f"{path}: not a {QUEUE_FORMAT} file")
+            return doc
+        except (json.JSONDecodeError, PermissionError, OSError):
+            if attempt == _RETRIES - 1:
+                raise
+            time.sleep(_RETRY_SLEEP)
+    raise QueueError(f"{path}: unreadable")
+
+
+def _write(path: Path, doc: dict) -> None:
+    tmp = path.with_name(path.name + ".tmp")
+    for attempt in range(_RETRIES):
+        try:
+            tmp.write_text(json.dumps(doc, indent=2), encoding="utf-8")
+            os.replace(tmp, path)
+            return
+        except (PermissionError, OSError):
+            if attempt == _RETRIES - 1:
+                raise
+            time.sleep(_RETRY_SLEEP)
+
+
+def park(path, item_id: str, seq: int, server: str, tool: str, args: dict,
+         rule: str, reason: str) -> None:
+    path = Path(path)
+    doc = _read(path)
+    if any(item["id"] == item_id for item in doc["items"]):
+        raise QueueError(
+            f"{path}: item {item_id!r} already queued — one queue file per "
+            "run; point --queue somewhere fresh")
+    doc["items"].append({"id": item_id, "seq": seq, "server": server,
+                         "tool": tool, "args": args, "rule": rule,
+                         "reason": reason, "verdict": None, "by": None})
+    _write(path, doc)
+
+
+def pending(path) -> list:
+    return [item for item in _read(Path(path))["items"]
+            if item["verdict"] is None]
+
+
+def verdict(path, item_id: str):
+    """(verdict, by) once decided, else None."""
+    for item in _read(Path(path))["items"]:
+        if item["id"] == item_id:
+            if item["verdict"] is None:
+                return None
+            return item["verdict"], item["by"]
+    return None
+
+
+def decide(path, item_id: str, decision: str, by: str) -> dict:
+    if decision not in ("approve", "deny"):
+        raise QueueError(f"verdict must be approve or deny, not {decision!r}")
+    if not by:
+        raise QueueError("an approver name is required (--by) — verdicts "
+                         "are recorded, anonymous ones are worthless")
+    path = Path(path)
+    doc = _read(path)
+    for item in doc["items"]:
+        if item["id"] == item_id:
+            if item["verdict"] is not None:
+                raise QueueError(f"{item_id!r} already decided: "
+                                 f"{item['verdict']} by {item['by']}")
+            item["verdict"] = decision
+            item["by"] = by
+            _write(path, doc)
+            return item
+    raise QueueError(f"{path}: no queued item {item_id!r}")

wardn/cli.py

@@ -0,0 +1,149 @@
+"""wardn CLI: proxy, review, replay, revert, diff.
+
+Exit codes, family convention: 0 ok, 2 refusal/error (bad policy, replay
+divergence, revert mismatch, ...), 4 drift from `wardn diff`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import approvals
+from ._version import __version__
+from .diff import diff_ledgers, render_diff
+from .ledger import replay
+from .policy import policy_from_json
+from .proxy import Proxy, ServerSpec, servers_from_json, stdio_caller
+from .revert import revert
+from .types import WardnError
+
+
+def _trailing_cmd(args_list: list) -> list:
+    cmd = list(args_list)
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    return cmd
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="wardn",
+        description="bounded, auditable action governor for LLM agents")
+    parser.add_argument("--version", action="version",
+                        version=f"wardn {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("proxy",
+                       help="govern one or more MCP servers over stdio")
+    p.add_argument("--policy", required=True, help="policy JSON file")
+    p.add_argument("--ledger", required=True, help="ledger file to write")
+    p.add_argument("--queue", default=None,
+                   help="approval queue file (default: <ledger>.queue.json)")
+    p.add_argument("--servers", default=None, metavar="JSON",
+                   help="JSON file naming several downstream servers "
+                        "(MCP client config shape: {\"mcpServers\": {name: "
+                        "{command, args}}}); instead of a trailing command")
+    p.add_argument("--server-name", default="server",
+                   help="name for the trailing-command server, for policy "
+                        "matching (default: server)")
+    p.add_argument("--run-id", default="run",
+                   help="workload label in the ledger header — keep it "
+                        "identical across runs you intend to compare")
+    p.add_argument("server_cmd", nargs=argparse.REMAINDER,
+                   help="-- followed by the downstream MCP server command")
+
+    r = sub.add_parser("review", help="list or decide quarantined calls")
+    r.add_argument("action", choices=["list", "approve", "deny"])
+    r.add_argument("item_id", nargs="?")
+    r.add_argument("--queue", required=True, help="the run's queue file")
+    r.add_argument("--by", default="",
+                   help="who is deciding (recorded in the ledger)")
+
+    rp = sub.add_parser("replay",
+                        help="re-derive every decision from policy + "
+                             "ledger, offline; no server needed")
+    rp.add_argument("--policy", required=True, help="the policy that ran")
+    rp.add_argument("--ledger", required=True, help="the run's ledger")
+
+    rv = sub.add_parser("revert",
+                        help="undo the run's recorded effects against a "
+                             "live server, from the ledger alone")
+    rv.add_argument("--ledger", required=True, help="the run's ledger")
+    rv.add_argument("--out", default=None,
+                    help="revert ledger to write "
+                         "(default: <ledger>.revert.jsonl)")
+    rv.add_argument("server_cmd", nargs=argparse.REMAINDER,
+                    help="-- followed by the MCP server command to undo "
+                         "against")
+
+    d = sub.add_parser("diff",
+                       help="compare two ledgers' decisions; exit 4 on drift")
+    d.add_argument("ledger_a", help="ledger JSONL (e.g. yesterday's run)")
+    d.add_argument("ledger_b", help="ledger JSONL (e.g. today's)")
+    d.add_argument("--show-attempts", type=int, default=0, metavar="N",
+                   help="also list up to N attempts unique to each side")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "proxy":
+            cmd = _trailing_cmd(args.server_cmd)
+            if args.servers and cmd:
+                parser.error("give either --servers or a trailing command, "
+                             "not both")
+            if args.servers:
+                specs = servers_from_json(Path(args.servers))
+            elif cmd:
+                specs = [ServerSpec(name=args.server_name, cmd=tuple(cmd))]
+            else:
+                parser.error("no downstream server (give --servers, or the "
+                             "command after --)")
+            queue = args.queue or (str(args.ledger) + ".queue.json")
+            return Proxy(policy=policy_from_json(Path(args.policy)),
+                         servers=specs, ledger_path=args.ledger,
+                         queue_path=queue, run_id=args.run_id).run()
+
+        if args.command == "review":
+            if args.action == "list":
+                items = approvals.pending(args.queue)
+                if not items:
+                    print("nothing pending")
+                    return 0
+                for item in items:
+                    print(f"{item['id']}  {item['tool']}  "
+                          f"{json.dumps(item['args'], separators=(',', ':'))}"
+                          f"  rule={item['rule']}  — {item['reason']}")
+                return 0
+            if not args.item_id:
+                parser.error("approve/deny take the item id (see: review list)")
+            item = approvals.decide(args.queue, args.item_id, args.action,
+                                    args.by)
+            print(f"{item['id']}: {item['verdict']} by {item['by']}")
+            return 0
+
+        if args.command == "replay":
+            count = replay(policy_from_json(Path(args.policy)), args.ledger)
+            print(f"replayed {count} attempt(s) — every decision reproduced "
+                  "by this policy")
+            return 0
+
+        if args.command == "revert":
+            cmd = _trailing_cmd(args.server_cmd)
+            if not cmd:
+                parser.error("no server command (give it after --)")
+            out = args.out or (str(args.ledger) + ".revert.jsonl")
+            with stdio_caller(cmd) as caller:
+                applied = revert(args.ledger, caller, out)
+            print(f"applied {applied} undo(s) — revert ledger: {out}")
+            return 0
+
+        if args.command == "diff":
+            result = diff_ledgers(args.ledger_a, args.ledger_b)
+            print(render_diff(result, show_attempts=args.show_attempts))
+            return 0 if result.same else 4
+    except WardnError as exc:
+        print(f"wardn: {exc}", file=sys.stderr)
+        return 2
+    return 0

wardn/diff.py

@@ -0,0 +1,154 @@
+"""wardn diff: run-to-run drift in the decision surface.
+
+Two ledgers from the same workload should describe the same governed
+activity: same policy, same attempts, same decisions. `diff_ledgers`
+compares exactly that — every attempt with its decision and (for
+quarantined calls) the recorded verdict — and never the server's result
+content: what came back is the server's business, what was attempted and
+allowed is the gate's. Comparison is an order-insensitive multiset, mendr
+style: a run that made the same attempts in a different order with
+identical decisions is not drift. (Bounds are order-dependent, so a
+reorder that changes WHICH call gets refused changes the multiset and is
+drift.)
+
+`LedgerDiff.same` is the CI verdict; the CLI turns False into exit 4 —
+the family convention (mendr's diff exits 4 on drift too). Everything
+else is the explanation: per-rule and per-effect counts A -> B, declared
+spend, and the exact attempts unique to each side.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from .ledger import fold, read_ledger
+
+# The decision surface: what the diff compares, per attempt. seq is order
+# (excluded — the multiset is order-insensitive); the approver's name is
+# audit detail, not a decision (excluded); capture and result events are
+# the world's side of the story (excluded).
+_DECISION_FIELDS = ("server", "tool", "args", "matched_rule", "effect",
+                    "effect_source", "disposition", "reason", "cost",
+                    "refusal")
+
+
+@dataclass(frozen=True)
+class RunSummary:
+    """One ledger's governed activity, reduced to what diff compares."""
+    run_id: str
+    policy_hash: str
+    attempts: int
+    per_rule: dict     # rule id -> {"attempts": n, "committed": n}
+    per_effect: dict   # effect -> committed count
+    spend: float       # declared cost of committed calls
+
+
+@dataclass(frozen=True)
+class LedgerDiff:
+    """What changed between two runs of (presumably) the same workload.
+
+    `same` is the CI verdict: identical policy, identical decision
+    surface. The count fields are the explanation a human reads when it
+    is False."""
+    a: RunSummary
+    b: RunSummary
+    only_in_a: tuple   # canonical JSON strings, one per unmatched attempt
+    only_in_b: tuple
+
+    @property
+    def policies_match(self) -> bool:
+        return self.a.policy_hash == self.b.policy_hash
+
+    @property
+    def same(self) -> bool:
+        return self.policies_match and not self.only_in_a \
+            and not self.only_in_b
+
+
+def _summarize(path) -> tuple:
+    """(RunSummary, decision-surface multiset) for one ledger."""
+    header, events = read_ledger(path)
+    per_rule: dict = {}
+    per_effect: dict = {}
+    spend = 0.0
+    multiset: dict = {}
+    folded = fold(events)
+    for entry in folded:
+        attempt = entry.attempt
+        rule = per_rule.setdefault(attempt["matched_rule"],
+                                   {"attempts": 0, "committed": 0})
+        rule["attempts"] += 1
+        if entry.committed:
+            rule["committed"] += 1
+            per_effect[attempt["effect"]] = \
+                per_effect.get(attempt["effect"], 0) + 1
+            spend = round(spend + attempt["cost"], 10)
+        record = {field: attempt[field] for field in _DECISION_FIELDS}
+        record["verdict"] = \
+            entry.approval["verdict"] if entry.approval else None
+        key = json.dumps(record, sort_keys=True, separators=(",", ":"))
+        multiset[key] = multiset.get(key, 0) + 1
+    summary = RunSummary(
+        run_id=header["run_id"],
+        policy_hash=header["provenance"]["policy_hash"],
+        attempts=len(folded), per_rule=per_rule, per_effect=per_effect,
+        spend=spend)
+    return summary, multiset
+
+
+def _only_in(mine: dict, theirs: dict) -> tuple:
+    extra = []
+    for key, count in mine.items():
+        extra.extend([key] * max(0, count - theirs.get(key, 0)))
+    return tuple(sorted(extra))
+
+
+def diff_ledgers(path_a, path_b) -> LedgerDiff:
+    """Compare two ledger files' decision surfaces."""
+    a, multiset_a = _summarize(path_a)
+    b, multiset_b = _summarize(path_b)
+    return LedgerDiff(a=a, b=b,
+                      only_in_a=_only_in(multiset_a, multiset_b),
+                      only_in_b=_only_in(multiset_b, multiset_a))
+
+
+def render_diff(diff: LedgerDiff, show_attempts: int = 0) -> str:
+    """Human/CI-readable drift report. `show_attempts` > 0 also lists up
+    to that many attempts unique to each side."""
+    a, b = diff.a, diff.b
+    lines = ["wardn ledger diff"]
+    if not diff.policies_match:
+        lines.append(f"  POLICY DRIFT: {a.policy_hash} vs {b.policy_hash}")
+    if a.run_id != b.run_id:
+        lines.append(f"  note: run_id {a.run_id!r} vs {b.run_id!r} — "
+                     "comparable runs should share the label")
+    lines.append(f"  attempts: {a.attempts} -> {b.attempts}")
+    for rid in sorted(set(a.per_rule) | set(b.per_rule)):
+        ra = a.per_rule.get(rid, {"attempts": 0, "committed": 0})
+        rb = b.per_rule.get(rid, {"attempts": 0, "committed": 0})
+        marker = "  " if ra == rb else "~ "
+        lines.append(
+            f"  {marker}{rid}: attempts {ra['attempts']} -> {rb['attempts']}"
+            f", committed {ra['committed']} -> {rb['committed']}"
+            f", refused {ra['attempts'] - ra['committed']} -> "
+            f"{rb['attempts'] - rb['committed']}")
+    for effect in sorted(set(a.per_effect) | set(b.per_effect)):
+        na = a.per_effect.get(effect, 0)
+        nb = b.per_effect.get(effect, 0)
+        marker = "  " if na == nb else "~ "
+        lines.append(f"  {marker}effect {effect}: committed {na} -> {nb}")
+    if a.spend or b.spend:
+        marker = "  " if a.spend == b.spend else "~ "
+        lines.append(f"  {marker}declared spend: "
+                     f"{json.dumps(a.spend)} -> {json.dumps(b.spend)}")
+    if diff.same:
+        lines.append("  ledgers match: same policy, same attempts, "
+                     "same decisions")
+    else:
+        lines.append(f"  attempts only in A: {len(diff.only_in_a)}; "
+                     f"only in B: {len(diff.only_in_b)}")
+        for label, extras in (("A", diff.only_in_a), ("B", diff.only_in_b)):
+            for key in extras[:show_attempts]:
+                lines.append(f"    only in {label}: {key}")
+    return "\n".join(lines)

wardn/engine.py

@@ -0,0 +1,105 @@
+"""The decision engine. Pure bookkeeping, no I/O, no clock.
+
+A decision is a pure function of policy + request + annotations + the
+counters accumulated so far; the counters advance only when a call is
+actually committed for forwarding (`note_forwarded`). Offline replay drives
+this same class from the ledger and must land on identical decisions.
+"""
+
+from __future__ import annotations
+
+from .matchers import match_matches
+from .policy import Policy, Rule
+from .types import EFFECT_RANK, Decision, ToolAnnotations, ToolRequest
+
+
+def _annotation_effect(ann: ToolAnnotations | None) -> str | None:
+    if ann is None:
+        return None
+    if ann.read_only:
+        return "read"
+    if ann.destructive:
+        return "destructive"
+    if ann.read_only is None and ann.destructive is None:
+        return None
+    return "write"
+
+
+def classify(rule: Rule | None, ann: ToolAnnotations | None) -> tuple[str, str]:
+    """(effect, source). Declared wins; an annotation may tighten a
+    declaration but never loosen it; with neither, a tool is a write."""
+    declared = rule.effect if rule else None
+    derived = _annotation_effect(ann)
+    if declared is not None:
+        if derived is not None and EFFECT_RANK[derived] > EFFECT_RANK[declared]:
+            return derived, "declared+tightened"
+        return declared, "declared"
+    if derived is not None:
+        return derived, "annotation"
+    return "write", "unclassified"
+
+
+class Engine:
+    def __init__(self, policy: Policy):
+        self.policy = policy
+        self.rule_calls: dict = {}   # rule id -> forwarded calls
+        self.run_calls = 0
+        self.run_writes = 0
+        self.run_spend = 0.0
+
+    # -- deciding -----------------------------------------------------------
+
+    def decide(self, req: ToolRequest,
+               ann: ToolAnnotations | None = None) -> Decision:
+        rule = self._match(req)
+        effect, effect_source = classify(rule, ann)
+        cost = rule.cost_per_call if rule else 0.0
+        disposition = rule.disposition if rule else self.policy.default
+        matched = rule.id if rule else "default"
+        reason = rule.reason if rule else ""
+
+        if disposition == "deny":
+            refusal = f"rule {rule.id}: deny" if rule else "default: no rule matched"
+        else:
+            # allow and quarantine both eventually forward, so bounds apply
+            # to both — and bounds precede approval: nobody gets paged about
+            # a call the budget refuses anyway.
+            refusal = self._check_bounds(rule, effect, cost)
+
+        return Decision(matched_rule=matched, effect=effect,
+                        effect_source=effect_source, disposition=disposition,
+                        reason=reason, cost=cost, refusal=refusal)
+
+    def _match(self, req: ToolRequest) -> Rule | None:
+        for rule in self.policy.rules:
+            if match_matches(rule.match, req.server, req.tool, req.args):
+                return rule
+        return None
+
+    def _check_bounds(self, rule: Rule | None, effect: str, cost: float) -> str:
+        budget = self.policy.budget
+        if rule is not None and rule.max_calls is not None \
+                and self.rule_calls.get(rule.id, 0) + 1 > rule.max_calls:
+            return f"rule {rule.id}: bound max_calls={rule.max_calls} exceeded"
+        if budget.max_calls is not None \
+                and self.run_calls + 1 > budget.max_calls:
+            return f"budget: max_calls={budget.max_calls} exceeded"
+        if effect in ("write", "destructive") and budget.max_writes is not None \
+                and self.run_writes + 1 > budget.max_writes:
+            return f"budget: max_writes={budget.max_writes} exceeded"
+        if budget.max_spend is not None \
+                and round(self.run_spend + cost, 10) > budget.max_spend:
+            return f"budget: max_spend={budget.max_spend} exceeded"
+        return ""
+
+    # -- bookkeeping --------------------------------------------------------
+
+    def note_forwarded(self, decision: Decision) -> None:
+        """Advance the counters for a call committed for forwarding."""
+        if decision.matched_rule != "default":
+            self.rule_calls[decision.matched_rule] = \
+                self.rule_calls.get(decision.matched_rule, 0) + 1
+        self.run_calls += 1
+        if decision.effect in ("write", "destructive"):
+            self.run_writes += 1
+        self.run_spend = round(self.run_spend + decision.cost, 10)