underwrit-client 0.3.0__tar.gz → 0.4.0.dev2__tar.gz

underwrit_client-0.4.0.dev2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Underwrit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

underwrit_client-0.4.0.dev2/NOTICE

@@ -0,0 +1,5 @@
+underwrit-client
+Copyright 2026 Underwrit
+
+MIT License (see LICENSE). The Underwrit data plane and control plane this
+client talks to are licensed separately, under the Underwrit Software Licence.

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/PKG-INFO

@@ -1,14 +1,17 @@
 Metadata-Version: 2.4
 Name: underwrit-client
-Version: 0.3.0
+Version: 0.4.0.dev2
 Summary: Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did.
 License: MIT
-Project-URL: Homepage, https://github.com/underwrit-io/dataplane
+Project-URL: Homepage, https://underwrit.io
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Security
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
 
 # underwrit-client
 
@@ -53,3 +56,17 @@ The full routes are in the Underwrit README; this client adds nothing the servic
   checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
 - 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
 - `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.
+- `decide(..., usage={"usd": 0.42}, delegation=["planner", "ops"], components={"model": "m-1"})`
+  reports cost, the agents behind the call and what the agent is built from; the chain keeps names
+  and digests only.
+- `preview(tool, args, session=… | environment=…)` asks the gate without recording anything;
+  `gates()` lists its stages and codes.
+- `verify(decision_id, "passed" | "failed" | "inconclusive")` lands a verification after the
+  outcome; `verifications_due()` and `approval_load()` need a reader's token.
+- `compensate(decision_id, tool, args, reason=…)` proposes an undo for a decision whose outcome is
+  uncertain or whose verification failed. It always goes to a person; claim it once approved. It
+  does not clear the original's scope hold.
+
+## Licence
+
+MIT (see LICENSE). The Underwrit planes this client talks to are licensed separately.

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/README.md

@@ -41,3 +41,17 @@ The full routes are in the Underwrit README; this client adds nothing the servic
   checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
 - 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
 - `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.
+- `decide(..., usage={"usd": 0.42}, delegation=["planner", "ops"], components={"model": "m-1"})`
+  reports cost, the agents behind the call and what the agent is built from; the chain keeps names
+  and digests only.
+- `preview(tool, args, session=… | environment=…)` asks the gate without recording anything;
+  `gates()` lists its stages and codes.
+- `verify(decision_id, "passed" | "failed" | "inconclusive")` lands a verification after the
+  outcome; `verifications_due()` and `approval_load()` need a reader's token.
+- `compensate(decision_id, tool, args, reason=…)` proposes an undo for a decision whose outcome is
+  uncertain or whose verification failed. It always goes to a person; claim it once approved. It
+  does not clear the original's scope hold.
+
+## Licence
+
+MIT (see LICENSE). The Underwrit planes this client talks to are licensed separately.

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "underwrit-client"
-version = "0.3.0"
+version = "0.4.0.dev2"
 description = "Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did."
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,7 +17,7 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/underwrit-io/dataplane"
+Homepage = "https://underwrit.io"
 
 [project.scripts]
 underwrit-hook = "underwrit_client.integrations.claude_code:main"

underwrit_client-0.4.0.dev2/underwrit_client/__init__.py

@@ -0,0 +1,456 @@
+"""underwrit-client: integrate an agent runtime with an Underwrit data plane in under twenty lines.
+
+    from underwrit_client import Underwrit, Held
+
+    underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
+    with underwrit.session(agent="ops-assistant", environment="production",
+                      intent="Restart api during incident 4417") as s:
+        logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")          # decided, run, recorded
+        try:
+            s.call("k8s/rollout_restart", restart, deployment="api")        # held? raises Held
+        except Held as h:
+            print("waiting on a person:", h.decision["id"])
+
+Standard library only. Every method maps to one data-plane route, and the shapes returned are the
+service's own — nothing is reinterpreted here.
+
+**`Held` is the contract.** When the data plane says `act: "hold"`, the wrapped call is not made
+and `Held` is raised with the decision attached, so a runtime can park the task, show the decision
+id, and come back with `claim()` once a person has answered. In shadow mode `act` is `"proceed"`
+and nothing is raised; the verdict is still recorded.
+
+**A claim before an approved execution.** `claim()` presents the same arguments again and is told
+whether the approval still holds — same arguments, same relevant state, still within its validity
+window, not already used. Use it immediately before executing anything that was held.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+__version__ = "0.4.0"
+__all__ = ["Underwrit", "Session", "Held", "UnderwritError", "guarded", "tool_definition_digest"]
+
+
+def tool_definition_digest(definition: dict) -> str:
+    """SHA-256 over the canonical JSON of a tool's `name`, `description` and `inputSchema`.
+
+    The same construction as `underwrit.scope.tool_definition_digest`, kept here so a runtime
+    needs only this package: those three keys and no others, keys sorted, `,`/`:` separators, no
+    whitespace, non-ASCII left as UTF-8. Pass the result as `tool_definition_digest` to `decide()`
+    and again to `claim()`; the data plane refuses a claim whose digest differs from the one the
+    decision was made against.
+    """
+    import hashlib
+
+    if not isinstance(definition, dict):
+        raise TypeError("a tool definition is a mapping with name, description and inputSchema")
+    canon = {"name": str(definition.get("name") or ""),
+             "description": str(definition.get("description") or ""),
+             "inputSchema": definition.get("inputSchema") if isinstance(definition.get("inputSchema"), dict) else {}}
+    return hashlib.sha256(json.dumps(canon, sort_keys=True, separators=(",", ":"),
+                                     ensure_ascii=False).encode("utf-8")).hexdigest()
+
+
+class UnderwritError(Exception):
+    """The data plane refused or failed a request. `status` is the HTTP status."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"{status}: {message}")
+        self.status = status
+        self.message = message
+
+
+class Held(Exception):
+    """The action must not proceed until a person answers, or was refused.
+
+    `decision` is the data plane's response — its `id` is what to resolve, and `reasons` say why.
+    """
+
+    def __init__(self, decision: dict, reason: str = ""):
+        rs = decision.get("reasons") or ([reason] if reason else [])
+        super().__init__(f"{decision.get('verdict', 'held')}: {'; '.join(rs) or 'held for a person'}")
+        self.decision = decision
+        self.reason = reason or (rs[0] if rs else "")
+        # What the data plane said beside the verdict, so a runtime can act on it without parsing.
+        self.id: str = str(decision.get("id") or "")
+        self.verdict: str = str(decision.get("verdict") or "")
+        self.budgeted: bool = bool(decision.get("budgeted"))
+        self.duplicate: bool = bool(decision.get("duplicate"))
+        self.quorum: dict | None = decision.get("quorum") if isinstance(decision.get("quorum"), dict) else None
+        self.risk: int = int(decision.get("risk") or 0)
+        # What to tell the model: don't retry, tell the user it waits for approval. Safe to show it.
+        self.guidance: dict = decision.get("agentGuidance") if isinstance(decision.get("agentGuidance"), dict) else {}
+
+
+class Underwrit:
+    def __init__(self, url: str, token: str, *, timeout: float = 10.0, retries: int = 3,
+                 max_retry_wait: float = 30.0, sleep: Callable[[float], None] = time.sleep):
+        self.url = url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.retries = retries
+        self.max_retry_wait = max_retry_wait
+        self._sleep = sleep
+
+    # -- transport -------------------------------------------------------------------------
+
+    def _call(self, method: str, path: str, body: dict | None = None) -> dict:
+        """One request. 429 and 503 are retried, honouring Retry-After, up to `retries` times and
+        never longer than `max_retry_wait` per wait; every other error is the caller's."""
+        attempt = 0
+        while True:
+            req = urllib.request.Request(
+                f"{self.url}{path}",
+                data=json.dumps(body).encode("utf-8") if body is not None else None,
+                headers={"Content-Type": "application/json", "Authorization": f"Bearer {self.token}"},
+                method=method,
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    return json.loads(r.read().decode("utf-8") or "{}")
+            except urllib.error.HTTPError as e:
+                try:
+                    payload = json.loads(e.read().decode("utf-8") or "{}")
+                except ValueError:
+                    payload = {}
+                if e.code in (429, 503) and attempt < self.retries:
+                    attempt += 1
+                    try:
+                        wait = float(e.headers.get("Retry-After") or payload.get("retryAfterSeconds") or 0)
+                    except (TypeError, ValueError):
+                        wait = 0.0
+                    self._sleep(min(self.max_retry_wait, wait or min(2.0 ** attempt, self.max_retry_wait)))
+                    continue
+                raise UnderwritError(e.code, payload.get("error", "") or e.reason) from None
+            except urllib.error.URLError as e:
+                raise UnderwritError(0, f"cannot reach {self.url}: {e.reason}") from None
+
+    # -- the routes ------------------------------------------------------------------------
+
+    def open_session(self, *, session: str = "", agent: str = "", environment: str = "",
+                     intent: str = "", actor: str = "", task_policy: dict | None = None) -> "Session":
+        s = self._call("POST", "/v1/sessions", {"session": session, "agent": agent,
+                                                "environment": environment, "intent": intent,
+                                                "actor": actor,
+                                                **({"taskPolicy": task_policy} if task_policy else {})})
+        return Session(self, s["id"], s)
+
+    session = open_session
+
+    def decide(self, session: str, tool: str, arguments: dict | None = None, *,
+               preconditions: Any = None, idempotency_key: str = "", signals: dict | None = None,
+               scope: str | None = None, tool_definition_digest: str | None = None,
+               usage: dict | None = None, delegation: list | None = None,
+               components: dict | None = None) -> dict:
+        """`signals` carries an external classifier's verdict ({"taint": True, "risk": 80,
+        "source": "my-classifier"}); it can raise taint and risk, never lower them.
+
+        `scope` names the target this action reaches when the data plane's own derivation (the
+        tool's declared authority fields, else identifier-looking argument keys) would be wrong or
+        too wide; the plane records a keyed digest of it, never the string. An unknown outcome
+        holds the scope for every later proposal on it. `tool_definition_digest` pins the tool's
+        definition into the approval; present the same one at `claim()`.
+
+        `usage` is what this call costs, by unit ({"usd": 0.42, "tokens": 1800}); the policy's spend
+        limits are sums over a session's reported usage. `delegation` is the chain of agents that
+        proposed the call, outermost first, held to the policy's maximum depth. `components` is a
+        manifest of what the agent is built from (model, prompt digest, tool versions); the chain
+        keeps its keys and digest. All three are recorded as names and digests, never values.
+        """
+        body: dict = {"session": session, "tool": tool, "arguments": arguments or {}}
+        if usage:
+            body["usage"] = usage
+        if delegation:
+            body["delegation"] = delegation
+        if components:
+            body["components"] = components
+        if preconditions is not None:
+            body["preconditions"] = preconditions
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+        if signals:
+            body["signals"] = signals
+        if scope:
+            body["scope"] = scope
+        if tool_definition_digest:
+            body["toolDefinitionDigest"] = tool_definition_digest
+        return self._call("POST", "/v1/decide", body)
+
+    def preview(self, tool: str, arguments: dict | None = None, *, session: str = "",
+                environment: str = "", intent: str = "", taint: list | None = None,
+                task_policy: dict | None = None, policy: dict | None = None, **v1) -> dict:
+        """"Ask the gate": what this proposal would get right now, recording nothing.
+
+        Against an existing `session`, or a hypothetical one (`environment`, `intent`, `taint`,
+        `task_policy`); `policy` judges it against a candidate policy instead of the live one. The
+        answer has `preview: True, recorded: False` — it is not evidence, and the decision that
+        counts is still `decide()`'s. `usage`, `delegation` and `components` are accepted as in
+        `decide()`.
+        """
+        body: dict = {"tool": tool, "arguments": arguments or {}}
+        for k, v in (("session", session), ("environment", environment), ("intent", intent), ("taint", taint),
+                     ("taskPolicy", task_policy), ("policy", policy)):
+            if v:
+                body[k] = v
+        body.update({k: v for k, v in v1.items() if k in ("usage", "delegation", "components") and v})
+        return self._call("POST", "/v1/preview", body)
+
+    def gates(self) -> dict:
+        """The stages the gate asks, in order, and every code a decision can carry."""
+        return self._call("GET", "/v1/gates")
+
+    def verify(self, decision_id: str, status: str, *, checks: list | None = None, summary: str = "") -> dict:
+        """A verification that lands after the outcome (`passed`, `failed` or `inconclusive`) —
+        for a check that takes minutes to settle, inside the policy's post-check window."""
+        if status not in ("passed", "failed", "inconclusive"):
+            raise ValueError("status must be passed, failed or inconclusive")
+        body: dict = {"decision": decision_id, "status": status}
+        if checks:
+            body["checks"] = checks
+        if summary:
+            body["summary"] = summary
+        return self._call("POST", "/v1/verify", body)
+
+    def verifications_due(self, *, include_verified: bool = False) -> dict:
+        """Open post-checks, oldest first, with how many are overdue. Needs the `read` grant."""
+        return self._call("GET", "/v1/verifications/due" + ("?all=1" if include_verified else ""))
+
+    def approval_load(self, days: int = 7) -> dict:
+        """Holds per tool over the last `days`, and how fast people answered. Needs `read`."""
+        return self._call("GET", f"/v1/approvals/load?days={int(days)}")
+
+    def compensate(self, decision_id: str, tool: str, arguments: dict | None = None, *, reason: str,
+                   idempotency_key: str = "", tool_definition_digest: str | None = None) -> dict:
+        """Propose an action that undoes or repairs `decision_id`, whose effect is unknown.
+
+        Allowed when its outcome is uncertain, its verification failed, or a scope hold it placed
+        still stands. The proposal always goes to a person (`act: "hold"`), so the usual path is:
+        `compensate()`, wait for the answer, then `claim()` with the same arguments and run it. It
+        does not clear the original's hold — probe, reconcile or release that once the undo ran.
+        """
+        if not reason or not reason.strip():
+            raise ValueError("compensate() needs a reason; a person reads it before approving")
+        body: dict = {"tool": tool, "arguments": arguments or {}, "reason": reason}
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+        if tool_definition_digest:
+            body["toolDefinitionDigest"] = tool_definition_digest
+        return self._call("POST", f"/v1/decisions/{decision_id}/compensate", body)
+
+    def receipt(self, seq: int) -> dict:
+        """The per-entry receipt: leaf index, tree size, root, inclusion proof and the signed
+        checkpoint. `pending: True` until a checkpoint covers the entry."""
+        return self._call("GET", f"/v1/receipts/{int(seq)}")
+
+    def pending(self, limit: int = 100, offset: int = 0) -> dict:
+        return self._call("GET", f"/v1/pending?limit={int(limit)}&offset={int(offset)}")
+
+    def claim(self, decision_id: str, arguments: dict, *,
+              preconditions: Any = None, tool_definition_digest: str | None = None) -> dict:
+        """Revalidate an approval against the arguments about to be executed.
+
+        `arguments` is required: the approval is bound to it, and the data plane refuses a claim
+        that presents nothing to check. Pass the same mapping `decide` was given — `{}` if the
+        action genuinely takes no arguments — and the same `tool_definition_digest` if the
+        decision was given one: a definition that changed in between is refused.
+        """
+        if not isinstance(arguments, dict):
+            raise TypeError("claim() needs the arguments the approval was bound to; pass {} for "
+                            "an action that takes none")
+        body: dict = {"arguments": arguments}
+        if preconditions is not None:
+            body["preconditions"] = preconditions
+        if tool_definition_digest:
+            body["toolDefinitionDigest"] = tool_definition_digest
+        return self._call("POST", f"/v1/decisions/{decision_id}/claim", body)
+
+    def outcome(self, decision_id: str, status: str, detail: str = "", *,
+                verification: dict | None = None, reconcile: bool = False) -> dict:
+        body: dict = {"decision": decision_id, "status": status, "detail": detail}
+        if verification:
+            body["verification"] = verification
+        if reconcile:
+            body["reconcile"] = True
+        return self._call("POST", "/v1/outcome", body)
+
+    def decision(self, decision_id: str) -> dict:
+        return self._call("GET", f"/v1/decisions/{decision_id}")
+
+    def wait(self, decision_id: str, timeout: float = 300.0) -> dict:
+        """Block until a held decision is answered (or expires), or `timeout` passes; returns it.
+
+        Long-polls the data plane (`?wait=`, at most a minute per request), so a person's answer is
+        seen at once without asking every few seconds. Check `lifecycle` on what comes back:
+        `approved` means `claim()` and run, anything else but `held` means don't.
+        """
+        end = time.monotonic() + max(0.0, timeout)
+        while True:
+            left = end - time.monotonic()
+            step = max(0, min(60, int(left)))
+            saved = self.timeout
+            self.timeout = max(saved, step + 10)
+            try:
+                d = self._call("GET", f"/v1/decisions/{decision_id}" + (f"?wait={step}" if step else ""))
+            finally:
+                self.timeout = saved
+            if d.get("lifecycle") != "held" or left <= 1:
+                return d
+
+    # -- durable suspension: park a held step, resume it when it settles ------------------
+
+    def park(self, decision_id: str, *, kind: str, key: str, resume_url: str = "", state: dict | None = None) -> dict:
+        """Hand a held decision to the plane and stop waiting; see `underwrit_client.durable`."""
+        return self._call("POST", f"/v1/decisions/{decision_id}/park",
+                          {"kind": kind, "key": key, "resumeUrl": resume_url, "state": state or {}})
+
+    def parked(self, *, settled: bool | None = None, kind: str = "") -> dict:
+        q = [f"settled={'1' if settled else '0'}"] if settled is not None else []
+        q += [f"kind={kind}"] if kind else []
+        return self._call("GET", "/v1/parked" + ("?" + "&".join(q) if q else ""))
+
+    def ack_parked(self, decision_id: str) -> dict:
+        return self._call("POST", f"/v1/parked/{decision_id}/ack", {})
+
+    # -- scope holds: an unknown outcome holds the target ----------------------------------
+
+    def scope_holds(self, *, include_cleared: bool = False) -> dict:
+        """Active scope holds, or every hold ever placed. Needs the `read` grant."""
+        return self._call("GET", "/v1/scope-holds" + ("?all=1" if include_cleared else ""))
+
+    def scope_hold(self, hold_id: str) -> dict:
+        return self._call("GET", f"/v1/scope-holds/{hold_id}")
+
+    def probe_scope_hold(self, hold_id: str, status: str, detail: str) -> dict:
+        """Clear a hold with a read-back from an independent source. The plane records the
+        status, a digest of `detail` and its length — never the text."""
+        return self._call("POST", f"/v1/scope-holds/{hold_id}/probe", {"status": status, "detail": detail})
+
+    def release_scope_hold(self, hold_id: str, reason: str) -> dict:
+        """Release a hold as a person. Approver credential; two of them where enforcement is on."""
+        return self._call("POST", f"/v1/scope-holds/{hold_id}/release", {"reason": reason})
+
+    def close(self, session: str, status: str = "succeeded") -> dict:
+        return self._call("POST", f"/v1/sessions/{session}/close", {"status": status})
+
+    def evidence(self, session: str) -> dict:
+        return self._call("GET", f"/v1/evidence/{session}")
+
+    def health(self) -> dict:
+        return self._call("GET", "/v1/health")
+
+
+class Session:
+    """One agent session. A context manager: closes on exit, `failed` if an exception escaped."""
+
+    def __init__(self, underwrit: Underwrit, session_id: str, meta: dict | None = None):
+        self.underwrit = underwrit
+        self.id = session_id
+        self.meta = meta or {}
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        try:
+            self.underwrit.close(self.id, "failed" if exc_type else "succeeded")
+        except UnderwritError:
+            pass
+        return False
+
+    def decide(self, tool: str, arguments: dict | None = None, **kw) -> dict:
+        return self.underwrit.decide(self.id, tool, arguments, **kw)
+
+    def outcome(self, decision_id: str, status: str, detail: str = "", **kw) -> dict:
+        return self.underwrit.outcome(decision_id, status, detail, **kw)
+
+    def claim(self, decision_id: str, arguments: dict, **kw) -> dict:
+        return self.underwrit.claim(decision_id, arguments, **kw)
+
+    def preview(self, tool: str, arguments: dict | None = None, **kw) -> dict:
+        return self.underwrit.preview(tool, arguments, session=self.id, **kw)
+
+    def verify(self, decision_id: str, status: str, **kw) -> dict:
+        return self.underwrit.verify(decision_id, status, **kw)
+
+    def compensate(self, decision_id: str, tool: str, arguments: dict | None = None, **kw) -> dict:
+        return self.underwrit.compensate(decision_id, tool, arguments, **kw)
+
+    def call(self, tool: str, fn: Callable[..., Any], /, *args, preconditions: Any = None,
+             idempotency_key: str = "", verify: Callable[[Any], dict] | None = None,
+             signals: dict | None = None, scope: str | None = None,
+             tool_definition_digest: str | None = None, **kwargs) -> Any:
+        """Decide, then run `fn(*args, **kwargs)`, then report what happened. Raises `Held`.
+
+        The keyword arguments are the action's arguments as the data plane sees them; positional
+        arguments are passed through to `fn` but are not part of the decision. `scope` and
+        `tool_definition_digest` go to `decide()` and are not arguments of the action.
+        """
+        d = self.decide(tool, kwargs, preconditions=preconditions, idempotency_key=idempotency_key, signals=signals,
+                        scope=scope, tool_definition_digest=tool_definition_digest)
+        if d.get("act") == "hold":
+            raise Held(d)
+        return self._run(d["id"], fn, args, kwargs, verify)
+
+    def resume(self, decision_id: str, fn: Callable[..., Any], /, *args,
+               preconditions: Any = None, verify: Callable[[Any], dict] | None = None,
+               tool_definition_digest: str | None = None, **kwargs) -> Any:
+        """After a person answered: claim the approval with the same arguments, then run.
+
+        `preconditions` and `tool_definition_digest` must be the same ones `call()` was given: the
+        data plane refuses a claim that omits preconditions a decision was bound to, because the
+        approver relied on that state and a claim that does not present it has not rechecked it —
+        and refuses one whose tool definition differs from the one the decision was made against.
+        """
+        c = self.claim(decision_id, kwargs, preconditions=preconditions,
+                       tool_definition_digest=tool_definition_digest)
+        if not c.get("ok") and c.get("act") == "hold":
+            raise Held(c.get("decision") or {"id": decision_id}, c.get("reason", ""))
+        return self._run(decision_id, fn, args, kwargs, verify)
+
+    def _run(self, decision_id, fn, args, kwargs, verify):
+        try:
+            result = fn(*args, **kwargs)
+        except TimeoutError as exc:
+            # A timeout may mean the action completed and the response was lost. Recorded as
+            # uncertain, which the data plane refuses to let a retry overwrite silently.
+            self.outcome(decision_id, "uncertain", str(exc)[:2000])
+            raise
+        except Exception as exc:
+            self.outcome(decision_id, "failed", str(exc)[:2000])
+            raise
+        detail = result if isinstance(result, str) else json.dumps(result, default=str)[:2000]
+        ver = None
+        if verify is not None:
+            try:
+                ver = verify(result)
+            except Exception as exc:  # noqa: BLE001 — a broken check is a failed verification
+                ver = {"status": "failed", "summary": f"verification raised {type(exc).__name__}"}
+        self.outcome(decision_id, "succeeded", detail, verification=ver)
+        return result
+
+
+def guarded(session: Session, tool: str | None = None, **opts):
+    """Decorate a tool function so every call goes through the session first.
+
+        @guarded(session, "bank/send_money")
+        def send_money(amount, recipient): ...
+
+    The function must be called with keyword arguments; they are the action's arguments.
+    """
+
+    def wrap(fn):
+        name = tool or fn.__name__
+
+        @functools.wraps(fn)
+        def inner(**kwargs):
+            return session.call(name, fn, **opts, **kwargs)
+
+        return inner
+
+    return wrap

underwrit_client-0.4.0.dev2/underwrit_client/durable.py

@@ -0,0 +1,104 @@
+"""Durable suspension: a held step stops the workflow instead of holding a process open.
+
+    from underwrit_client.durable import Resumer
+
+    resumer = Resumer(uw, secret=os.environ["UNDERWRIT_RESUME_WEBHOOK_SECRET"])
+    resumer.on("temporal", temporal.resume_with(temporal_client))
+    resumer.on("langgraph", langgraph.resume_with(graph))
+
+    # In the web handler that UNDERWRIT_RESUME_ALLOW lets the plane call:
+    resumer.handle(request.body, request.headers)
+    # On worker start-up, for anything settled while it was down or whose webhook was lost:
+    resumer.catch_up()
+
+A handler gets the resume (`decision`, `kind`, `key`, `state`, `outcome`: approved | denied |
+expired) and resumes the run the engine knows by `key`. The step itself then calls
+`Session.resume()`, which claims the approval against the same arguments before running; a denied
+or expired step is told so and does not run. Each resume is acknowledged after its handler returns,
+so one delivered twice is resumed once, and one whose handler failed is offered again.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import inspect
+import json
+import time
+from typing import Any, Callable
+
+from . import Underwrit
+
+
+class BadResume(Exception):
+    """The body is not a resume this plane signed (or it is too old to trust)."""
+
+
+def verify(body: bytes, headers: dict, secret: str, *, tolerance: float = 300.0, now: float | None = None) -> dict:
+    """The resume, if its signature verifies; raises BadResume otherwise. Header names are matched
+    case-insensitively."""
+    h = {str(k).lower(): str(v) for k, v in (headers or {}).items()}
+    if secret:
+        ts, sig = h.get("x-underwrit-timestamp", ""), h.get("x-underwrit-signature", "")
+        if not ts or not sig.startswith("sha256="):
+            raise BadResume("unsigned resume")
+        want = hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(want, sig[7:]):
+            raise BadResume("signature does not verify")
+        try:
+            if abs((now or time.time()) - float(ts)) > tolerance:
+                raise BadResume("resume is too old")
+        except ValueError:
+            raise BadResume("bad timestamp") from None
+    doc = json.loads(body.decode("utf-8"))
+    if doc.get("event") != "decision.resume":
+        raise BadResume("not a resume")
+    return doc
+
+
+class Resumer:
+    def __init__(self, client: Underwrit, *, secret: str = ""):
+        self.client = client
+        self.secret = secret
+        self.handlers: dict[str, Callable[[dict], Any]] = {}
+
+    def on(self, kind: str, handler: Callable[[dict], Any]) -> "Resumer":
+        self.handlers[kind] = handler
+        return self
+
+    def dispatch(self, resume: dict) -> Any:
+        handler = self.handlers.get(resume.get("kind", "")) or self.handlers.get("*")
+        if handler is None:
+            raise LookupError(f"no handler for {resume.get('kind')!r} resumes")
+        result = handler(resume)
+        if inspect.isawaitable(result):
+            result = asyncio.run(_awaited(result))
+        out = self.client.ack_parked(resume["decision"])
+        return {"result": result, "alreadyAcked": out.get("alreadyAcked", False)}
+
+    async def adispatch(self, resume: dict) -> Any:
+        """`dispatch` from inside an event loop (an async web handler, a Temporal client)."""
+        handler = self.handlers.get(resume.get("kind", "")) or self.handlers.get("*")
+        if handler is None:
+            raise LookupError(f"no handler for {resume.get('kind')!r} resumes")
+        result = handler(resume)
+        if inspect.isawaitable(result):
+            result = await result
+        out = await asyncio.to_thread(self.client.ack_parked, resume["decision"])
+        return {"result": result, "alreadyAcked": out.get("alreadyAcked", False)}
+
+    def handle(self, body: bytes, headers: dict) -> Any:
+        return self.dispatch(verify(body, headers, self.secret))
+
+    def catch_up(self, kind: str = "") -> list[str]:
+        done = []
+        for p in self.client.parked(settled=True, kind=kind).get("parked", []):
+            if p["kind"] in self.handlers or "*" in self.handlers:
+                self.dispatch({**p, "event": "decision.resume"})
+                done.append(p["decision"])
+        return done
+
+
+async def _awaited(aw):
+    return await aw

underwrit_client-0.4.0.dev2/underwrit_client/integrations/autogen.py

@@ -0,0 +1,56 @@
+"""AutoGen AgentChat: a held tool call ends the turn; the resume reloads the team and continues.
+
+    from underwrit_client.integrations import autogen as uw_autogen
+
+    send_money = uw_autogen.guarded_tool(session, "bank/send_money", send_money_impl,
+                                         run_id=run_id, resume_url=RESUME_URL)
+    # ... the team runs; a held call returns a message saying it waits for approval, and
+    # the caller saves `await team.save_state()` under run_id and stops.
+
+    async def load(run_id):                      # the team as it was, from your store
+        team = build_team(); await team.load_state(STORE[run_id]); return team
+
+    resumer.on("autogen", uw_autogen.resume_with(load))
+
+On an approval the reloaded team is run with a message naming the decision; the tool, called again
+with the same arguments, claims the approval and runs. On a denial it is told not to.
+"""
+
+from __future__ import annotations
+
+from .. import Session
+
+
+def guarded_tool(session: Session, tool: str, fn, *, run_id: str, resume_url: str = "", preconditions=None):
+    """Wrap a tool for an AutoGen agent. A hold is parked and reported to the model, not raised."""
+    approved: dict[str, str] = {}
+
+    def _run(**kwargs):
+        d = session.decide(tool, kwargs, preconditions=preconditions)
+        if d.get("act") == "hold":
+            prior = d.get("duplicate") and d.get("lifecycle") == "approved"
+            if prior or approved.get(d["id"]) == "approved":
+                return session.resume(d["id"], fn, preconditions=preconditions, **kwargs)
+            session.underwrit.park(d["id"], kind="autogen", key=run_id, resume_url=resume_url)
+            g = d.get("agentGuidance") or {}
+            return (g.get("tellUser") or f"{tool} is waiting for a person to approve it (decision {d['id']}). "
+                    "Do not retry; the run continues once it is answered.")
+        return session._run(d["id"], fn, (), kwargs, None)
+    _run.__name__ = getattr(fn, "__name__", tool.replace("/", "_"))
+    _run.__doc__ = getattr(fn, "__doc__", None)
+    _run.underwrit_approved = approved
+    return _run
+
+
+def resume_with(load, *, message: str = ""):
+    """A Resumer handler: `load(run_id)` returns the team; it is run with the outcome."""
+    async def handler(resume: dict):
+        team = load(resume["key"])
+        if hasattr(team, "__await__"):
+            team = await team
+        outcome = resume.get("outcome", "")
+        task = message or (f"Decision {resume['decision']} on {resume.get('tool', 'the held step')} was {outcome}. "
+                           + ("Call the tool again with the same arguments to run it." if outcome == "approved"
+                              else "Do not run it; tell the user."))
+        return await team.run(task=task)
+    return handler

underwrit_client-0.4.0.dev2/underwrit_client/integrations/crewai.py

@@ -0,0 +1,49 @@
+"""CrewAI Flows: a held step ends the flow run; the resume kicks off the persisted flow again.
+
+    from underwrit_client.integrations import crewai as uw_crewai
+
+    @persist
+    class Payout(Flow[PayoutState]):
+        @start()
+        def propose(self):
+            d = uw_crewai.propose(session, "bank/send_money", self.state.args, flow_id=self.state.id,
+                                  resume_url=RESUME_URL)
+            self.state.decision = d["id"]
+            return d
+
+        @router(propose)
+        def route(self, d):
+            return "pay" if d["act"] == "proceed" else "parked"     # "parked": the run ends here
+
+        @listen("pay")
+        def pay(self):
+            return session.resume(self.state.decision, send_money, **self.state.args)
+
+    resumer.on("crewai", uw_crewai.resume_with(Payout))
+
+`@persist` keeps the state under its id. The resume calls `kickoff` with that id and the outcome,
+so the restored flow can route to `pay` (approved) or stop (denied, expired); `pay` claims the
+approval against the same arguments before running.
+"""
+
+from __future__ import annotations
+
+from .. import Session
+
+
+def propose(session: Session, tool: str, arguments: dict, *, flow_id: str, resume_url: str = "",
+            preconditions=None) -> dict:
+    d = session.decide(tool, arguments, preconditions=preconditions)
+    if d.get("act") == "hold":
+        session.underwrit.park(d["id"], kind="crewai", key=flow_id, resume_url=resume_url)
+    return d
+
+
+def resume_with(flow_cls, *, start_method: str | None = None):
+    """A Resumer handler: kick the persisted flow off again with the decision's outcome."""
+    def handler(resume: dict):
+        flow = flow_cls()
+        inputs = {"id": resume["key"], "underwrit_decision": resume["decision"],
+                  "underwrit_outcome": resume.get("outcome", "")}
+        return flow.kickoff(inputs=inputs) if start_method is None else getattr(flow, start_method)(**inputs)
+    return handler

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/underwrit_client/integrations/langgraph.py

@@ -15,10 +15,15 @@ from __future__ import annotations
 from .. import Held, Session
 
 
-def guarded_tool(session: Session, tool: str, fn, *, preconditions=None, verify=None):
+def guarded_tool(session: Session, tool: str, fn, *, preconditions=None, verify=None,
+                 thread_id: str = "", resume_url: str = ""):
+    """With `thread_id`, a hold is also parked: the plane resumes the thread when it settles
+    (`resume_with(graph)` below), so nothing has to poll and no worker waits."""
     def _run(**kwargs):
         d = session.decide(tool, kwargs, preconditions=preconditions)
         if d.get("act") == "hold":
+            if thread_id:
+                session.underwrit.park(d["id"], kind="langgraph", key=thread_id, resume_url=resume_url)
             try:
                 from langgraph.types import interrupt  # type: ignore
             except ImportError:
@@ -31,3 +36,17 @@ def guarded_tool(session: Session, tool: str, fn, *, preconditions=None, verify=
     _run.__name__ = getattr(fn, "__name__", tool)
     _run.__doc__ = getattr(fn, "__doc__", None)
     return _run
+
+
+def resume_with(graph):
+    """A durable Resumer handler: resume the checkpointed thread with the decision's outcome.
+
+    The interrupted node re-runs with `interrupt()` returning the resume value; a denied or expired
+    decision is refused by the claim inside `session.resume`, which raises `Held`.
+    """
+    def handler(resume: dict):
+        from langgraph.types import Command  # type: ignore
+
+        value = {"underwrit": {"decision": resume["decision"], "outcome": resume.get("outcome", "")}}
+        return graph.invoke(Command(resume=value), config={"configurable": {"thread_id": resume["key"]}})
+    return handler

underwrit_client-0.4.0.dev2/underwrit_client/integrations/temporal.py

@@ -0,0 +1,83 @@
+"""Temporal: a held step suspends the workflow on a signal; the resume sends it.
+
+    from underwrit_client.integrations import temporal as uw_temporal
+
+    # An activity proposes the step and, if it is held, parks it under the workflow's id.
+    @activity.defn
+    async def propose(req: dict) -> dict:
+        return uw_temporal.propose(session, req["tool"], req["arguments"],
+                                   workflow_id=activity.info().workflow_id, resume_url=RESUME_URL)
+
+    @workflow.defn
+    class Payout(uw_temporal.Waiting):
+        @workflow.run
+        async def run(self, req):
+            d = await workflow.execute_activity(propose, req, start_to_close_timeout=timedelta(seconds=30))
+            if d["act"] == "hold":
+                outcome = await self.underwrit_wait(d["id"])   # no worker is busy while a person decides
+                if outcome != "approved":
+                    return {"status": outcome}
+            return await workflow.execute_activity(execute, {**req, "decision": d["id"]}, ...)
+
+    resumer.on("temporal", uw_temporal.resume_with(temporal_client))
+
+The workflow waits on the `underwrit_resume` signal with `workflow.wait_condition`, which is
+durable: the worker can restart, and the history replays to the same wait. The `execute` activity
+calls `Session.resume()`, which claims the approval with the same arguments before running.
+"""
+
+from __future__ import annotations
+
+from .. import Session
+
+SIGNAL = "underwrit_resume"
+
+
+def propose(session: Session, tool: str, arguments: dict, *, workflow_id: str, resume_url: str = "",
+            preconditions=None) -> dict:
+    """Decide; on a hold, park it under `workflow_id` and return at once."""
+    d = session.decide(tool, arguments, preconditions=preconditions)
+    if d.get("act") == "hold":
+        session.underwrit.park(d["id"], kind="temporal", key=workflow_id, resume_url=resume_url)
+    return d
+
+
+class Waiting:
+    """Mix into a workflow class: a signal handler and `underwrit_wait(decision_id)`."""
+
+    def __init__(self) -> None:
+        self._underwrit_outcomes: dict[str, str] = {}
+
+    def underwrit_resume(self, resume: dict) -> None:
+        if not hasattr(self, "_underwrit_outcomes"):
+            self._underwrit_outcomes = {}
+        self._underwrit_outcomes[str(resume.get("decision"))] = str(resume.get("outcome") or "denied")
+
+    async def underwrit_wait(self, decision_id: str, timeout=None) -> str:
+        from temporalio import workflow  # type: ignore
+
+        if not hasattr(self, "_underwrit_outcomes"):
+            self._underwrit_outcomes = {}
+        await workflow.wait_condition(lambda: decision_id in self._underwrit_outcomes, timeout=timeout)
+        return self._underwrit_outcomes[decision_id]
+
+
+def _register_signal() -> None:
+    """Make `underwrit_resume` a Temporal signal when temporalio is installed."""
+    try:
+        from temporalio import workflow  # type: ignore
+    except ImportError:
+        return
+    Waiting.underwrit_resume = workflow.signal(name=SIGNAL)(Waiting.underwrit_resume)
+
+
+_register_signal()
+
+
+def resume_with(client):
+    """A Resumer handler: signal the parked workflow (`client` is a `temporalio.client.Client`)."""
+    async def handler(resume: dict):
+        handle = client.get_workflow_handle(resume["key"])
+        await handle.signal(SIGNAL, {"decision": resume["decision"], "outcome": resume.get("outcome", "")})
+        return resume["key"]
+    return handler

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/underwrit_client.egg-info/PKG-INFO

@@ -1,14 +1,17 @@
 Metadata-Version: 2.4
 Name: underwrit-client
-Version: 0.3.0
+Version: 0.4.0.dev2
 Summary: Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did.
 License: MIT
-Project-URL: Homepage, https://github.com/underwrit-io/dataplane
+Project-URL: Homepage, https://underwrit.io
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Security
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
 
 # underwrit-client
 
@@ -53,3 +56,17 @@ The full routes are in the Underwrit README; this client adds nothing the servic
   checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
 - 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
 - `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.
+- `decide(..., usage={"usd": 0.42}, delegation=["planner", "ops"], components={"model": "m-1"})`
+  reports cost, the agents behind the call and what the agent is built from; the chain keeps names
+  and digests only.
+- `preview(tool, args, session=… | environment=…)` asks the gate without recording anything;
+  `gates()` lists its stages and codes.
+- `verify(decision_id, "passed" | "failed" | "inconclusive")` lands a verification after the
+  outcome; `verifications_due()` and `approval_load()` need a reader's token.
+- `compensate(decision_id, tool, args, reason=…)` proposes an undo for a decision whose outcome is
+  uncertain or whose verification failed. It always goes to a person; claim it once approved. It
+  does not clear the original's scope hold.
+
+## Licence
+
+MIT (see LICENSE). The Underwrit planes this client talks to are licensed separately.

{underwrit_client-0.3.0 → underwrit_client-0.4.0.dev2}/underwrit_client.egg-info/SOURCES.txt

@@ -1,6 +1,9 @@
+LICENSE
+NOTICE
 README.md
 pyproject.toml
 underwrit_client/__init__.py
+underwrit_client/durable.py
 underwrit_client/task.py
 underwrit_client.egg-info/PKG-INFO
 underwrit_client.egg-info/SOURCES.txt
@@ -8,9 +11,12 @@ underwrit_client.egg-info/dependency_links.txt
 underwrit_client.egg-info/entry_points.txt
 underwrit_client.egg-info/top_level.txt
 underwrit_client/integrations/__init__.py
+underwrit_client/integrations/autogen.py
 underwrit_client/integrations/claude_code.py
+underwrit_client/integrations/crewai.py
 underwrit_client/integrations/google_adk.py
 underwrit_client/integrations/http_interceptor.py
 underwrit_client/integrations/langgraph.py
 underwrit_client/integrations/openai_agents.py
-underwrit_client/integrations/otel.py
+underwrit_client/integrations/otel.py
+underwrit_client/integrations/temporal.py

underwrit_client-0.3.0/underwrit_client/__init__.py

@@ -1,265 +0,0 @@
-"""underwrit-client: integrate an agent runtime with an Underwrit data plane in under twenty lines.
-
-    from underwrit_client import Underwrit, Held
-
-    underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
-    with underwrit.session(agent="ops-assistant", environment="production",
-                      intent="Restart api during incident 4417") as s:
-        logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")          # decided, run, recorded
-        try:
-            s.call("k8s/rollout_restart", restart, deployment="api")        # held? raises Held
-        except Held as h:
-            print("waiting on a person:", h.decision["id"])
-
-Standard library only. Every method maps to one data-plane route, and the shapes returned are the
-service's own — nothing is reinterpreted here.
-
-**`Held` is the contract.** When the data plane says `act: "hold"`, the wrapped call is not made
-and `Held` is raised with the decision attached, so a runtime can park the task, show the decision
-id, and come back with `claim()` once a person has answered. In shadow mode `act` is `"proceed"`
-and nothing is raised; the verdict is still recorded.
-
-**A claim before an approved execution.** `claim()` presents the same arguments again and is told
-whether the approval still holds — same arguments, same relevant state, still within its validity
-window, not already used. Use it immediately before executing anything that was held.
-"""
-
-from __future__ import annotations
-
-import functools
-import json
-import time
-import urllib.error
-import urllib.request
-from typing import Any, Callable
-
-__version__ = "0.3.0"
-__all__ = ["Underwrit", "Session", "Held", "UnderwritError", "guarded"]
-
-
-class UnderwritError(Exception):
-    """The data plane refused or failed a request. `status` is the HTTP status."""
-
-    def __init__(self, status: int, message: str):
-        super().__init__(f"{status}: {message}")
-        self.status = status
-        self.message = message
-
-
-class Held(Exception):
-    """The action must not proceed until a person answers, or was refused.
-
-    `decision` is the data plane's response — its `id` is what to resolve, and `reasons` say why.
-    """
-
-    def __init__(self, decision: dict, reason: str = ""):
-        rs = decision.get("reasons") or ([reason] if reason else [])
-        super().__init__(f"{decision.get('verdict', 'held')}: {'; '.join(rs) or 'held for a person'}")
-        self.decision = decision
-        self.reason = reason or (rs[0] if rs else "")
-        # What the data plane said beside the verdict, so a runtime can act on it without parsing.
-        self.id: str = str(decision.get("id") or "")
-        self.verdict: str = str(decision.get("verdict") or "")
-        self.budgeted: bool = bool(decision.get("budgeted"))
-        self.duplicate: bool = bool(decision.get("duplicate"))
-        self.quorum: dict | None = decision.get("quorum") if isinstance(decision.get("quorum"), dict) else None
-        self.risk: int = int(decision.get("risk") or 0)
-
-
-class Underwrit:
-    def __init__(self, url: str, token: str, *, timeout: float = 10.0, retries: int = 3,
-                 max_retry_wait: float = 30.0, sleep: Callable[[float], None] = time.sleep):
-        self.url = url.rstrip("/")
-        self.token = token
-        self.timeout = timeout
-        self.retries = retries
-        self.max_retry_wait = max_retry_wait
-        self._sleep = sleep
-
-    # -- transport -------------------------------------------------------------------------
-
-    def _call(self, method: str, path: str, body: dict | None = None) -> dict:
-        """One request. 429 and 503 are retried, honouring Retry-After, up to `retries` times and
-        never longer than `max_retry_wait` per wait; every other error is the caller's."""
-        attempt = 0
-        while True:
-            req = urllib.request.Request(
-                f"{self.url}{path}",
-                data=json.dumps(body).encode("utf-8") if body is not None else None,
-                headers={"Content-Type": "application/json", "Authorization": f"Bearer {self.token}"},
-                method=method,
-            )
-            try:
-                with urllib.request.urlopen(req, timeout=self.timeout) as r:
-                    return json.loads(r.read().decode("utf-8") or "{}")
-            except urllib.error.HTTPError as e:
-                try:
-                    payload = json.loads(e.read().decode("utf-8") or "{}")
-                except ValueError:
-                    payload = {}
-                if e.code in (429, 503) and attempt < self.retries:
-                    attempt += 1
-                    try:
-                        wait = float(e.headers.get("Retry-After") or payload.get("retryAfterSeconds") or 0)
-                    except (TypeError, ValueError):
-                        wait = 0.0
-                    self._sleep(min(self.max_retry_wait, wait or min(2.0 ** attempt, self.max_retry_wait)))
-                    continue
-                raise UnderwritError(e.code, payload.get("error", "") or e.reason) from None
-            except urllib.error.URLError as e:
-                raise UnderwritError(0, f"cannot reach {self.url}: {e.reason}") from None
-
-    # -- the routes ------------------------------------------------------------------------
-
-    def open_session(self, *, session: str = "", agent: str = "", environment: str = "",
-                     intent: str = "", actor: str = "", task_policy: dict | None = None) -> "Session":
-        s = self._call("POST", "/v1/sessions", {"session": session, "agent": agent,
-                                                "environment": environment, "intent": intent,
-                                                "actor": actor,
-                                                **({"taskPolicy": task_policy} if task_policy else {})})
-        return Session(self, s["id"], s)
-
-    session = open_session
-
-    def decide(self, session: str, tool: str, arguments: dict | None = None, *,
-               preconditions: Any = None, idempotency_key: str = "", signals: dict | None = None) -> dict:
-        """`signals` carries an external classifier's verdict ({"taint": True, "risk": 80,
-        "source": "my-classifier"}); it can raise taint and risk, never lower them."""
-        body: dict = {"session": session, "tool": tool, "arguments": arguments or {}}
-        if preconditions is not None:
-            body["preconditions"] = preconditions
-        if idempotency_key:
-            body["idempotencyKey"] = idempotency_key
-        if signals:
-            body["signals"] = signals
-        return self._call("POST", "/v1/decide", body)
-
-    def receipt(self, seq: int) -> dict:
-        """The per-entry receipt: leaf index, tree size, root, inclusion proof and the signed
-        checkpoint. `pending: True` until a checkpoint covers the entry."""
-        return self._call("GET", f"/v1/receipts/{int(seq)}")
-
-    def pending(self, limit: int = 100, offset: int = 0) -> dict:
-        return self._call("GET", f"/v1/pending?limit={int(limit)}&offset={int(offset)}")
-
-    def claim(self, decision_id: str, arguments: dict | None = None, *,
-              preconditions: Any = None) -> dict:
-        body: dict = {}
-        if arguments is not None:
-            body["arguments"] = arguments
-        if preconditions is not None:
-            body["preconditions"] = preconditions
-        return self._call("POST", f"/v1/decisions/{decision_id}/claim", body)
-
-    def outcome(self, decision_id: str, status: str, detail: str = "", *,
-                verification: dict | None = None, reconcile: bool = False) -> dict:
-        body: dict = {"decision": decision_id, "status": status, "detail": detail}
-        if verification:
-            body["verification"] = verification
-        if reconcile:
-            body["reconcile"] = True
-        return self._call("POST", "/v1/outcome", body)
-
-    def decision(self, decision_id: str) -> dict:
-        return self._call("GET", f"/v1/decisions/{decision_id}")
-
-    def close(self, session: str, status: str = "succeeded") -> dict:
-        return self._call("POST", f"/v1/sessions/{session}/close", {"status": status})
-
-    def evidence(self, session: str) -> dict:
-        return self._call("GET", f"/v1/evidence/{session}")
-
-    def health(self) -> dict:
-        return self._call("GET", "/v1/health")
-
-
-class Session:
-    """One agent session. A context manager: closes on exit, `failed` if an exception escaped."""
-
-    def __init__(self, underwrit: Underwrit, session_id: str, meta: dict | None = None):
-        self.underwrit = underwrit
-        self.id = session_id
-        self.meta = meta or {}
-
-    def __enter__(self) -> "Session":
-        return self
-
-    def __exit__(self, exc_type, exc, tb) -> bool:
-        try:
-            self.underwrit.close(self.id, "failed" if exc_type else "succeeded")
-        except UnderwritError:
-            pass
-        return False
-
-    def decide(self, tool: str, arguments: dict | None = None, **kw) -> dict:
-        return self.underwrit.decide(self.id, tool, arguments, **kw)
-
-    def outcome(self, decision_id: str, status: str, detail: str = "", **kw) -> dict:
-        return self.underwrit.outcome(decision_id, status, detail, **kw)
-
-    def claim(self, decision_id: str, arguments: dict | None = None, **kw) -> dict:
-        return self.underwrit.claim(decision_id, arguments, **kw)
-
-    def call(self, tool: str, fn: Callable[..., Any], /, *args, preconditions: Any = None,
-             idempotency_key: str = "", verify: Callable[[Any], dict] | None = None,
-             signals: dict | None = None, **kwargs) -> Any:
-        """Decide, then run `fn(*args, **kwargs)`, then report what happened. Raises `Held`.
-
-        The keyword arguments are the action's arguments as the data plane sees them; positional
-        arguments are passed through to `fn` but are not part of the decision.
-        """
-        d = self.decide(tool, kwargs, preconditions=preconditions, idempotency_key=idempotency_key, signals=signals)
-        if d.get("act") == "hold":
-            raise Held(d)
-        return self._run(d["id"], fn, args, kwargs, verify)
-
-    def resume(self, decision_id: str, fn: Callable[..., Any], /, *args,
-               preconditions: Any = None, verify: Callable[[Any], dict] | None = None,
-               **kwargs) -> Any:
-        """After a person answered: claim the approval with the same arguments, then run."""
-        c = self.claim(decision_id, kwargs, preconditions=preconditions)
-        if not c.get("ok") and c.get("act") == "hold":
-            raise Held(c.get("decision") or {"id": decision_id}, c.get("reason", ""))
-        return self._run(decision_id, fn, args, kwargs, verify)
-
-    def _run(self, decision_id, fn, args, kwargs, verify):
-        try:
-            result = fn(*args, **kwargs)
-        except TimeoutError as exc:
-            # A timeout may mean the action completed and the response was lost. Recorded as
-            # uncertain, which the data plane refuses to let a retry overwrite silently.
-            self.outcome(decision_id, "uncertain", str(exc)[:2000])
-            raise
-        except Exception as exc:
-            self.outcome(decision_id, "failed", str(exc)[:2000])
-            raise
-        detail = result if isinstance(result, str) else json.dumps(result, default=str)[:2000]
-        ver = None
-        if verify is not None:
-            try:
-                ver = verify(result)
-            except Exception as exc:  # noqa: BLE001 — a broken check is a failed verification
-                ver = {"status": "failed", "summary": f"verification raised {type(exc).__name__}"}
-        self.outcome(decision_id, "succeeded", detail, verification=ver)
-        return result
-
-
-def guarded(session: Session, tool: str | None = None, **opts):
-    """Decorate a tool function so every call goes through the session first.
-
-        @guarded(session, "bank/send_money")
-        def send_money(amount, recipient): ...
-
-    The function must be called with keyword arguments; they are the action's arguments.
-    """
-
-    def wrap(fn):
-        name = tool or fn.__name__
-
-        @functools.wraps(fn)
-        def inner(**kwargs):
-            return session.call(name, fn, **opts, **kwargs)
-
-        return inner
-
-    return wrap