hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/guard.py

@@ -0,0 +1,367 @@
+"""
+The per-turn runtime guard (tool standard wave 2: S3 idempotency, S5 retry
+budgets). One TurnGuard is created per user message by every loop that runs
+tools (the terminal's Anthropic and OpenAI-compatible loops and the chat
+bridge) and passed to ToolRegistry.dispatch(..., guard=). The registry calls:
+
+    precheck(spec)            before argument validation: turn cap, per-tool budget
+    on_invalid(spec)          after invalid_args: one corrected retry is free
+    check_budgets(spec, args) before the approval gate (wave 3): per-resource and
+                              per-target budgets, so a refused call is never queued
+    before(spec, args)        per-resource budget, per-target retry budget,
+                              effect-ledger check + intent row
+    after(spec, args, env, ctx)  outcome row, counters, not_found resources
+    observe(spec, args, env)  an owner-approved call's outcome, counted in this turn
+
+The model never sees a key and cannot opt a call out. What persists across
+turns and restarts is the ledger (hyperclaw/tools/ledger.py); the budgets and
+the not-found set are per turn, as the standard says.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import time
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import effects as fx
+from .envelope import (REASON_CONFIRM, REASON_RESOURCE_MISSING, REASON_RETRY_BUDGET,
+                       REASON_TURN_CAP, REASON_UNKNOWN_TOOL, Status, ToolResult, make,
+                       new_receipt_id)
+from .ledger import CONFLICT_EFFECTS, EffectLedger, get_ledger
+
+log = logging.getLogger("hyperclaw.tools.guard")
+
+# Statuses that are not a failed attempt (they don't spend retry budget).
+_NOT_FAILURES = {Status.OK.value, Status.DUPLICATE.value, Status.NEEDS_APPROVAL.value,
+                 Status.BUDGET_EXHAUSTED.value, Status.INVALID_ARGS.value}
+
+CHAT_TOOL_CALL_CAP = 8      # chat surfaces (bridge/Telegram); the terminal keeps 25 rounds
+
+TOOL_CAP_NOTE = (
+    "[HyperClaw system note: the tool-call limit for one message ({limit}) was reached, so "
+    "this turn was stopped. These calls did NOT run: {names}.]"
+)
+
+_VERB = {"send": "send", "spend": "spend", "delete": "delete", "write": "write",
+         "system": "action"}
+
+
+def chat_tool_call_cap() -> int:
+    try:
+        return int(os.environ.get("HYPERCLAW_CHAT_TOOL_CALL_CAP", CHAT_TOOL_CALL_CAP))
+    except ValueError:
+        return CHAT_TOOL_CALL_CAP
+
+
+def _when(ts) -> str:
+    try:
+        return time.strftime("%Y-%m-%d %H:%M", time.localtime(float(ts)))
+    except (TypeError, ValueError):
+        return "earlier"
+
+
+def _display_target(target: str, tool: str) -> str:
+    if target.startswith("file:"):
+        return target[5:]
+    if target.startswith(tool + ":"):
+        return target[len(tool) + 1:]
+    return target
+
+
+class TurnGuard:
+    def __init__(self, *, conversation: str, surface: str,
+                 ledger: Optional[EffectLedger] = None, call_cap: Optional[int] = None,
+                 turn_id: Optional[str] = None, base_dir: Optional[str] = None,
+                 provenance: Optional[List[str]] = None, requester: str = "owner",
+                 approved: bool = False):
+        self.conversation = conversation
+        # Wave 3 (approval layer). provenance: the user's own words and the
+        # content they gave this conversation (a read-only fetch may only
+        # target a URL that appears verbatim here). requester: "owner" or
+        # "agent:<id>" for sub-agents. approved: set only for the run of an
+        # owner-approved payload (tools.approval.send).
+        self.provenance: List[str] = [p for p in (provenance or []) if isinstance(p, str)]
+        self.requester = requester
+        self.approved = approved
+        self.untrusted_seen = False   # a read of email/web/document content ran this turn
+        self.memory_saved_unprompted: List[str] = []   # own-words memories saved this turn
+        self.queued: List[str] = []   # approval ids queued this turn
+        self.surface = surface
+        self._ledger = ledger
+        self.call_cap = call_cap
+        self.turn_id = turn_id or uuid.uuid4().hex[:12]
+        self.base_dir = base_dir
+        self.calls = 0
+        self.failures: Dict[Tuple[str, str], int] = {}
+        self.invalid: Dict[str, int] = {}
+        self.missing: List[fx.Resource] = []
+        self.skipped: List[str] = []
+        self.cap_hit = False
+        # Every tool that ran this turn, with the status it really returned:
+        # the evidence the cost guard's stop message is built from.
+        self.results: List[Dict[str, Any]] = []
+
+    @property
+    def ledger(self) -> EffectLedger:
+        if self._ledger is None:
+            self._ledger = get_ledger()
+        return self._ledger
+
+    # ── before validation ──
+    def precheck(self, spec) -> Optional[ToolResult]:
+        if self.call_cap is not None and self.calls >= self.call_cap:
+            self.cap_hit = True
+            self.skipped.append(spec.name)
+            return make(Status.BUDGET_EXHAUSTED,
+                        f"{spec.name} was NOT run: the limit of {self.call_cap} tool calls for "
+                        f"one message was reached.", reason=REASON_TURN_CAP)
+        self.calls += 1
+        if self.failures.get((spec.name, "*"), 0) > spec.retry_budget:
+            return self._retry_refusal(spec, "*")
+        return None
+
+    def on_invalid(self, spec) -> None:
+        n = self.invalid.get(spec.name, 0) + 1
+        self.invalid[spec.name] = n
+        if n >= 2:  # one corrected retry is free; the next invalid_args counts
+            self.failures[(spec.name, "*")] = self.failures.get((spec.name, "*"), 0) + 1
+
+    def _retry_refusal(self, spec, tkey: str) -> ToolResult:
+        where = "" if tkey == "*" else f" on {tkey.split(':', 1)[-1]}"
+        return make(Status.BUDGET_EXHAUSTED,
+                    f"{spec.name} was NOT run: it already failed{where} this turn and its retry "
+                    f"budget ({spec.retry_budget}) is used up.", reason=REASON_RETRY_BUDGET)
+
+    # ── after validation, before the approval gate ──
+    def check_budgets(self, spec, args: dict) -> Optional[ToolResult]:
+        """The S5 refusals (still looking for something not found this turn;
+        retry budget used up), checked BEFORE a call is queued for approval,
+        so a call this turn would refuse is never put in front of the owner.
+        Writes nothing but the refusal row. before() repeats the same checks."""
+        res = fx.resources(spec.name, args, self.base_dir)
+        check = [r for r in res if r.kind != "path"] if spec.name in fx.CREATE_TOOLS else res
+        eff = None
+        if check:
+            for m in self.missing:
+                if any(fx.touches(r, m) for r in check):
+                    eff = fx.call_effect(spec, args)
+                    env = make(Status.BUDGET_EXHAUSTED,
+                               f"{spec.name} was NOT run: it is still looking for {m.value}, "
+                               f"which was not found earlier in this turn.",
+                               reason=REASON_RESOURCE_MISSING)
+                    self._log_refusal(spec, eff, args, env)
+                    return env
+        eff = fx.call_effect(spec, args)
+        tkey = "*"
+        if eff is not None and eff.target != spec.name:
+            tkey = eff.target
+        elif res and res[0].kind != "text":
+            tkey = str(res[0])
+        if self.failures.get((spec.name, tkey), 0) > spec.retry_budget:
+            env = self._retry_refusal(spec, tkey)
+            self._log_refusal(spec, eff, args, env)
+            return env
+        return None
+
+    def observe(self, spec, args: dict, env: ToolResult) -> None:
+        """An owner-approved call ran (tools.approval.send, under its own
+        guard, which wrote the ledger rows). Count its outcome in THIS turn's
+        budgets too, so a failed approved write is not retried this turn and
+        a not-found resource stays not found."""
+        tkey = "*"
+        try:
+            eff = fx.call_effect(spec, args)
+            res = fx.resources(spec.name, args, self.base_dir)
+            if eff is not None and eff.target != spec.name:
+                tkey = eff.target
+            elif res and res[0].kind != "text":
+                tkey = str(res[0])
+        except Exception:
+            res = []
+        self._count(spec, env, {"resources": res, "tkey": tkey})
+
+    # ── after validation, before running ──
+    def before(self, spec, args: dict) -> Tuple[Optional[ToolResult], Dict[str, Any]]:
+        res = fx.resources(spec.name, args, self.base_dir)
+        eff = fx.call_effect(spec, args)
+        ctx: Dict[str, Any] = {"resources": res, "effect": eff, "intent_id": None,
+                               "writes": [], "tkey": "*"}
+        if eff is not None and eff.target != spec.name:
+            ctx["tkey"] = eff.target
+        elif res and res[0].kind != "text":
+            ctx["tkey"] = str(res[0])
+
+        # S5 per resource: still going after something that was not found.
+        # A tool that creates a file may still create it at that path (its
+        # inputs, e.g. a download URL, are still checked).
+        check = [r for r in res if r.kind != "path"] if spec.name in fx.CREATE_TOOLS else res
+        if check:
+            for m in self.missing:
+                if any(fx.touches(r, m) for r in check):
+                    env = make(Status.BUDGET_EXHAUSTED,
+                               f"{spec.name} was NOT run: it is still looking for {m.value}, "
+                               f"which was not found earlier in this turn.",
+                               reason=REASON_RESOURCE_MISSING)
+                    self._log_refusal(spec, eff, args, env)
+                    return env, ctx
+
+        # S5 per tool (and target).
+        if self.failures.get((spec.name, ctx["tkey"]), 0) > spec.retry_budget:
+            env = self._retry_refusal(spec, ctx["tkey"])
+            self._log_refusal(spec, eff, args, env)
+            return env, ctx
+
+        # S3 effect ledger.
+        if spec.name == "bash":
+            return self._before_bash(spec, args, ctx)
+        if eff is None:
+            return None, ctx
+        try:
+            d = self.ledger.begin(
+                conversation=self.conversation, turn=self.turn_id, surface=self.surface,
+                tool=spec.name, effect=eff.effect, target=eff.target,
+                payload_hash=eff.payload_hash, key=eff.key, args=fx.summarize_args(args),
+                current_file_hash=fx.file_hash(eff.file_path),
+                expected_post_hash=eff.expected_post_hash, is_file=bool(eff.file_path),
+                allow_conflict=self.approved)
+        except Exception as e:
+            log.warning("effect ledger unavailable: %s", e, exc_info=True)
+            if eff.effect in CONFLICT_EFFECTS:
+                return make(Status.FAILED, f"{spec.name} was NOT run: the activity ledger is "
+                                           f"unavailable ({type(e).__name__}), so the runtime "
+                                           f"cannot guarantee it runs at most once."), ctx
+            return None, ctx
+        if d.action == "proceed":
+            ctx["intent_id"] = d.intent_id
+            return None, ctx
+        return self._held(spec, eff, d), ctx
+
+    def _held(self, spec, eff: fx.Effect, d) -> ToolResult:
+        prior = d.prior or {}
+        when = _when(prior.get("ts"))
+        receipt = prior.get("receipt_id")
+        target = _display_target(eff.target, spec.name)
+        original = {"tool": prior.get("tool"), "at": when, "receipt_id": receipt,
+                    "target": prior.get("target"), "status": prior.get("status")}
+        verb = _VERB.get(eff.effect, "action")
+        if d.action == "duplicate":
+            return make(Status.DUPLICATE,
+                        f"{spec.name} was NOT run: the same {verb} to {target} was already done "
+                        f"at {when} by {prior.get('tool')}"
+                        + (f" (receipt {receipt})." if receipt else "."),
+                        data={"original": original}, receipt_id=receipt)
+        if d.reason == "uncertain":
+            msg = (f"{spec.name} was NOT run: an identical {verb} to {target} at {when} has an "
+                   f"uncertain outcome; it may already have been sent. Ask the user to check "
+                   f"before trying again.")
+        else:
+            msg = (f"{spec.name} was NOT run: a different {verb} to {target} was already done at "
+                   f"{when}" + (f" (receipt {receipt})" if receipt else "") +
+                   f". Ask the user whether to {verb} this as well.")
+        return make(Status.NEEDS_APPROVAL, msg, data={"original": original},
+                    reason=REASON_CONFIRM)
+
+    def _before_bash(self, spec, args, ctx) -> Tuple[Optional[ToolResult], Dict[str, Any]]:
+        writes = fx.bash_file_writes(args.get("command", ""), self.base_dir)
+        ctx["writes"] = writes
+        ctx["pre"] = {w.path: fx.file_hash(w.path) for w in writes}
+        try:
+            for path, eff in fx.planned_file_effects(writes):
+                if eff is None:
+                    continue
+                d = self.ledger.check(conversation=self.conversation, effect="write",
+                                      target=eff.target, key=eff.key,
+                                      current_file_hash=fx.file_hash(path),
+                                      expected_post_hash=eff.expected_post_hash, is_file=True)
+                if d.action == "duplicate":
+                    env = self._held(spec, eff, d)
+                    self._log_refusal(spec, eff, args, env)
+                    return env, ctx
+            d = self.ledger.begin(conversation=self.conversation, turn=self.turn_id,
+                                  surface=self.surface, tool="bash", effect=spec.effect,
+                                  target="bash", payload_hash=fx.sha256(args.get("command", "")),
+                                  key=None, args=fx.summarize_args(args))
+            ctx["intent_id"] = d.intent_id
+        except Exception as e:
+            log.warning("effect ledger unavailable for bash: %s", e, exc_info=True)
+        return None, ctx
+
+    # ── after running ──
+    def after(self, spec, args: dict, env: ToolResult, ctx: Dict[str, Any]) -> ToolResult:
+        self._count(spec, env, ctx)
+        try:
+            self._record_outcome(spec, env, ctx)
+        except Exception as e:
+            log.warning("effect ledger: could not record outcome: %s", e, exc_info=True)
+        return env
+
+    def _count(self, spec, env: ToolResult, ctx: Dict[str, Any]) -> None:
+        status = env.status
+        eff = ctx.get("effect") if ctx else None
+        self.results.append({"tool": spec.name, "status": status,
+                             "target": _display_target(eff.target, spec.name)[:80]
+                             if eff is not None and eff.target else "",
+                             "receipt_id": env.receipt_id})
+        if spec.effect == "read" and status == Status.OK.value:
+            from .approval import PURE_COMPUTE
+            if spec.name not in PURE_COMPUTE:
+                self.untrusted_seen = True
+            # Connector content (email, calendar, documents, web): recorded in
+            # this conversation's taint ledger (hyperclaw.taint).
+            try:
+                from hyperclaw import taint
+                taint.mark_tool_result(spec.name, env, self.conversation, self.turn_id)
+            except Exception:
+                log.warning("taint ledger: could not record %s", spec.name, exc_info=True)
+        if status not in _NOT_FAILURES:
+            k = (spec.name, ctx.get("tkey", "*"))
+            self.failures[k] = self.failures.get(k, 0) + 1
+        if status == Status.NOT_FOUND.value and spec.name != "bash" \
+                and env.instruction != make(Status.NOT_FOUND, reason=REASON_UNKNOWN_TOOL).instruction:
+            for r in ctx.get("resources", []):
+                if r.kind == "path" and os.path.exists(r.value):
+                    continue  # e.g. edit_file "text not found": the file exists
+                if r not in self.missing:
+                    self.missing.append(r)
+
+    def _record_outcome(self, spec, env: ToolResult, ctx) -> None:
+        eff: Optional[fx.Effect] = ctx.get("effect")
+        if ctx.get("intent_id"):
+            post = fx.file_hash(eff.file_path) if (eff and eff.file_path) else None
+            self.ledger.finish(ctx["intent_id"], status=env.status, receipt_id=env.receipt_id,
+                               post_hash=post, message=env.message)
+        if spec.name == "bash" and ctx.get("writes"):
+            for path in dict.fromkeys(w.path for w in ctx["writes"]):
+                fe = fx.recorded_file_effect(path, ctx["writes"])
+                post = fx.file_hash(path)
+                if fe is None or post is None or post == ctx.get("pre", {}).get(path):
+                    continue  # nothing was written there (or nothing changed)
+                self.ledger.record(conversation=self.conversation, turn=self.turn_id,
+                                   surface=self.surface, tool="bash", effect="write",
+                                   target=fe.target, payload_hash=fe.payload_hash, key=fe.key,
+                                   status=Status.OK.value, receipt_id=new_receipt_id(),
+                                   ref=ctx.get("intent_id"), post_hash=post,
+                                   args=fx.summarize_args({"via": "bash", "path": path}),
+                                   message=f"bash wrote {path}")
+
+    def _log_refusal(self, spec, eff: Optional[fx.Effect], args, env: ToolResult) -> None:
+        """Refusals of effectful calls go in the activity log too."""
+        if eff is None and spec.name != "bash":
+            return
+        try:
+            self.ledger.record(conversation=self.conversation, turn=self.turn_id,
+                               surface=self.surface, tool=spec.name,
+                               effect=eff.effect if eff else spec.effect,
+                               target=eff.target if eff else spec.name,
+                               payload_hash=eff.payload_hash if eff else None,
+                               key=None, status=env.status, receipt_id=env.receipt_id,
+                               args=fx.summarize_args(args), message=env.message)
+        except Exception as e:
+            log.warning("effect ledger: could not record refusal: %s", e)
+
+    # ── turn end ──
+    def stop_note(self) -> str:
+        return TOOL_CAP_NOTE.format(limit=self.call_cap,
+                                    names=", ".join(self.skipped) or "none")