graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/agents/langgraph/app/app_utils/approvals.py

@@ -0,0 +1,1349 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Human approval of gated outbound API calls: the records, who decides, the ledger.
+
+An API's `approval` block in `api-policy.yaml` gates calls; `api_client.py`
+pauses the run before a gated call is sent, with an interrupt whose value
+describes the exact request. When a run ends paused that way, the chat
+runtime (`chat.py`) records one pending approval per interrupt here
+(`ApprovalStore.add`) and ends the stream with `message.end` status
+`awaiting_approval` and the approval (`ApprovalRecord.public()`).
+
+Deciding is the action `approval.decide` of the auth policy, then this rule
+(`may_decide`): `requester` in `approvers` lets the principal who started the
+run (the thread's owner: only the owner runs on a thread) decide; `role:<x>`
+lets any principal holding role `x` decide, except the requester, who may
+approve their own call only when `requester` is listed. Anyone else gets 403.
+A decision is one atomic change of a pending, unexpired row
+(`ApprovalStore.decide`), so of two concurrent decisions one wins and the
+other finds the approval no longer pending. The run then resumes with the
+decision; the tool runs again, and `api_client` sends the call only when the
+decision approves exactly the request it rebuilds (the same `call_hash`) and
+`ApprovalStore.consume` (the ledger) marks the approval used: once, on the
+thread it was made for. A tool call that runs again without a decision (a run
+continued or replayed through LangGraph Server's own API) asks the ledger
+first (`ApprovalStore.bound_approvals`) and sends no call an approval was
+asked for.
+
+Records (table `approvals`, `agent_approvals` under langgraph-server, in the
+app's database; in process memory without one, and under `langgraph dev` also
+in the file `.langgraph_api/agent_approvals.json` beside the dev server's own
+threads, see `dev_ledger_path`): the thread, the run that
+paused, the interrupt, the requester's hashed id and the roles and public
+attributes the run acted with (never credentials), the tool call that asked
+(the model message and its call id), the call (API, method, path, operation
+id, `call_hash`, and in `payload` the query and JSON body as the approver sees
+them, with the fields the tool named in `redact=` masked),
+the approvers, the status (`pending`, `approved`, `rejected`, `expired`), the
+decider's hashed id, the decision time and comment, when the approval was
+used, and when it expires (`approval.timeout_s` after it was requested). A
+decision relayed to another agent also keeps, in `payload`, the approval it
+decides there (`nested`) and the call that will then happen (`effect`), and
+expires 5 s before that approval at the latest. A call an agent's request
+paused (under the fastapi runtime) also keeps the user's own words that agent
+forwarded (`origin`, never shown): the run a decision resumes acts on them
+(`resume_principal`). Once
+decided or expired the query and body (and those of every nested call and of
+the effect) are dropped from the record unless `TRACE_CAPTURE=full`, and the
+user's words whatever it says. A pending approval past its expiry is expired (=
+rejected): the runtime's sweep marks it every `SWEEP_INTERVAL_S` seconds and
+every read treats it so. Deleting a thread deletes its approvals.
+
+Who sees an approval (`may_view`): the thread's owner, a principal who may
+decide it, and roles in `AUTH_READ_ACROSS_ROLES` (listing only; they see the
+query and body only under `TRACE_CAPTURE=full`).
+
+Agents calling agents: a thread's owner is its subject and, for a thread an
+agent started for its user, that agent (`threads.ThreadRecord.actor`). The
+user (a direct principal with that subject) is the requester of every
+approval on the thread, whichever agent started it: they see it and, when
+`requester` is listed, decide it. A delegated principal (an agent presenting
+the user's token) sees only the approvals of threads started under its own
+subject and actor; its roles never count as a role approver or a read-across
+role. It decides only a gate whose rule opted into `decide_with: relayed` and
+lists its actor in `relayers`, only on a thread it started itself, and only
+with the approval's `digest` (`decide_refusal`, `digest_refusal`): it then
+delivers the person's decision, recorded as `decided_via`. Under the default
+`decide_with: direct` the person decides with their own credentials. How the
+approvers decide is bound to the approval when it is asked, as the approvers
+are. The requester's actor is recorded with the approval (`requester_actor`)
+and restored when a role approver's decision resumes the run
+(`resume_principal`).
+
+`langgraph dev` keeps its threads in `.langgraph_api/` and loads them again
+after a restart or a hot reload (a code change reloads the server), so the
+approvals that bind their tool calls must outlive the process too: without
+them, a run continued without input or replayed from a checkpoint would find
+no record of a rejected, pending or used approval and, once the policy no
+longer gates the call, send it. There the store writes its records to
+`.langgraph_api/agent_approvals.json` (mode 0600) before a change takes
+effect (a pending approval before the run ends awaiting it, a decision
+before the run resumes, a use before the call is sent) and reads them at
+startup; a file it cannot read stops the startup, and while a write fails
+the store answers nothing (every lookup fails, so calls are refused) until
+it writes again. Deleting `.langgraph_api/` resets the threads and their
+approvals together. Without file persistence (`LANGGRAPH_DISABLE_FILE_PERSISTENCE`)
+the dev server keeps no threads either, and the approvals stay in memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import json
+import logging
+import os
+import threading
+import uuid
+from collections import OrderedDict
+from collections.abc import Iterable, Mapping
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from {{cookiecutter.agent_directory}}.app_utils.api_client import (
+    A2A_OPERATION_KEY,
+    APPROVAL_DECISION,
+    APPROVAL_INTERRUPT,
+    DECIDE_DIRECT,
+    DECIDE_RELAYED,
+    DECIDE_WITH_VALUES,
+    DEFAULT_APPROVAL_TIMEOUT_S,
+    MAX_APPROVAL_TIMEOUT_S,
+    MIN_APPROVAL_TIMEOUT_S,
+    NESTED_MAX_DEPTH,
+    REQUESTER_APPROVER,
+    ROLE_APPROVER_PREFIX,
+    RPC_METHOD_KEY,
+    BoundApproval,
+)
+from {{cookiecutter.agent_directory}}.app_utils.auth import (
+    Principal,
+    actor_of_attributes,
+    owner_key_of,
+    read_across_roles,
+    with_origin,
+)
+from {{cookiecutter.agent_directory}}.app_utils.db import Database, StorageNotReady, capture_full
+from {{cookiecutter.agent_directory}}.app_utils.threads import ThreadRecord
+
+logger = logging.getLogger(__name__)
+
+PENDING = "pending"
+APPROVED = "approved"
+REJECTED = "rejected"
+EXPIRED = "expired"
+STATUSES = (PENDING, APPROVED, REJECTED, EXPIRED)
+
+# Decisions a decider sends (`POST /threads/{id}/approvals/{approval_id}`).
+APPROVE = "approve"
+REJECT = "reject"
+DECISIONS = {APPROVE: APPROVED, REJECT: REJECTED}
+
+# Error codes clients see.
+CODE_APPROVAL_PENDING = "approval_pending"  # 409 on /chat while an approval is pending
+CODE_NOT_PENDING = "approval_not_pending"  # 409 on a decision: already decided
+CODE_EXPIRED = "approval_expired"  # 410 on a decision: it expired
+CODE_NOT_AN_APPROVER = "not_an_approver"  # 403 on a decision: not one of its approvers
+CODE_DIRECT_ONLY = "approval_direct_only"  # 403: an agent may not decide it for the person
+CODE_DIGEST_MISMATCH = "approval_digest_mismatch"  # 409: decided on another view of the call
+NOT_AN_APPROVER_DETAIL = "You may not decide this approval (see its approvers)."
+DIGEST_MISMATCH_DETAIL = (
+    "The decision was taken on a different view of the call; fetch the approval again."
+)
+# `sha256:<hex>`, at most this long in a decision.
+DIGEST_MAX_CHARS = 80
+DIGEST_PREFIX = "sha256:"
+
+# How often every replica marks pending approvals past their expiry `expired`.
+SWEEP_INTERVAL_S = 30.0
+# Approvals kept without a database (the oldest decided ones go first).
+MEMORY_APPROVALS_CAP = 10_000
+COMMENT_MAX_CHARS = 1000
+# Payload keys dropped once an approval is decided or expired (unless TRACE_CAPTURE=full).
+CALL_CONTENT_KEYS = ("query", "body")
+# The user's own words the request that paused carried (`credentials["@origin"]`, which an
+# agent calling for them forwarded): kept in the payload while the approval waits, so the run
+# it resumes acts on them whoever delivers the decision (`resume_principal`); dropped once it
+# is decided or expired, whatever TRACE_CAPTURE says, and never shown.
+ORIGIN_PAYLOAD_KEY = "origin"
+# A decision relayed to another agent: the approval it decides there (`nested`, recursive:
+# its `call`, and the approval that one relays in turn) and the call that will then happen
+# (`effect`). Their query and body go with the call's once decided.
+NESTED_KEY = "nested"
+EFFECT_KEY = "effect"
+# The relayed approval must still be open downstream when the person decides here: this
+# approval expires this long before it at the latest.
+NESTED_EXPIRY_MARGIN_S = 5
+# What a call to a JSON-RPC API was, read from its body (`api_client.derive_rpc`): kept in
+# the payload (only for such calls), part of which call the approval is bound to, and of the
+# approver's view.
+RPC_KEYS = (RPC_METHOD_KEY, A2A_OPERATION_KEY)
+
+# Where `langgraph dev` keeps its threads (relative to the directory it runs in),
+# and the file the app keeps their approvals in there.
+DEV_STATE_DIR = ".langgraph_api"
+DEV_LEDGER_FILE = "agent_approvals.json"
+# Version 2 (0.3) adds each approval's requester actor, how it is decided (`decide_with`,
+# `relayers`), `decided_via` and `display_digest`; a version-1 file reads with the defaults.
+LEDGER_FILE_VERSION = 2
+LEDGER_FILE_VERSIONS = (1, 2)
+_DATETIME_FIELDS = ("decided_at", "used_at", "created_at", "expires_at")
+
+
+def dev_ledger_path() -> Path | None:
+    """The file the approvals are kept in under `langgraph dev`, else None.
+
+    `langgraph dev` runs LangGraph Server's in-memory edition, which keeps its
+    threads in `.langgraph_api/` of the directory it runs in (unless file
+    persistence is off): the approvals are kept there too, so both survive a
+    restart or a hot reload. Everywhere else they live in the app's database
+    (or, with the fastapi runtime's in-memory checkpointer, in memory with
+    the threads).
+    """
+    edition = (os.environ.get("LANGGRAPH_RUNTIME_EDITION") or "").strip().lower()
+    if edition != "inmem":
+        return None
+    disabled = (os.environ.get("LANGGRAPH_DISABLE_FILE_PERSISTENCE") or "").strip().lower()
+    if disabled == "true":
+        return None
+    return Path(DEV_STATE_DIR) / DEV_LEDGER_FILE
+
+
+class LedgerUnavailable(StorageNotReady):
+    """The approvals file cannot be written or read: the store answers nothing (a 503)."""
+
+
+def utcnow() -> datetime:
+    return datetime.now(tz=UTC)
+
+
+def _iso(value: datetime | None) -> str | None:
+    return value.isoformat() if value is not None else None
+
+
+def _as_datetime(value: Any) -> datetime | None:
+    """A stored time as an aware datetime in UTC (naive: read as UTC).
+
+    Postgres answers `timestamptz` in the session's time zone: normalised, an
+    approval reads back with the very times it was written with (`public()`
+    shows them, and a relay that reads the ledger binds them in its decision).
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        parsed = value
+    else:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    return parsed.astimezone(UTC) if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, default=str)
+
+
+def _decode(value: Any) -> Any:
+    return json.loads(value) if isinstance(value, str) else value
+
+
+def is_approval_interrupt(value: Any) -> bool:
+    """Whether an interrupt value is a gated API call's (raised by `api_client`)."""
+    return isinstance(value, Mapping) and value.get("type") == APPROVAL_INTERRUPT
+
+
+@dataclass
+class ApprovalRecord:
+    approval_id: str
+    thread_id: str
+    run_id: str
+    interrupt_id: str
+    requester_hash: str
+    api: str
+    method: str
+    path: str
+    call_hash: str
+    approvers: list[str]
+    payload: dict[str, Any]
+    expires_at: datetime
+    operation_id: str | None = None
+    tool_call_id: str | None = None
+    # The model message that made the tool call (with `tool_call_id`, the tool call).
+    message_id: str | None = None
+    requester_context: dict[str, Any] = field(default_factory=dict)
+    status: str = PENDING
+    decided_by: str | None = None
+    decided_at: datetime | None = None
+    comment: str | None = None
+    used_at: datetime | None = None
+    created_at: datetime = field(default_factory=utcnow)
+    # The agent the requester's run acted through ("" for a direct requester).
+    requester_actor: str = ""
+    # How the requester decides, bound when the approval was asked: `direct`, or `relayed`
+    # by the agents in `relayers`.
+    decide_with: str = DECIDE_DIRECT
+    relayers: list[str] = field(default_factory=list)
+    # The agent that delivered the decision (a relayed decision), else None.
+    decided_via: str | None = None
+    # What the approver was shown, hashed (`approval_digest`): a relayed decision names it.
+    display_digest: str | None = None
+
+    def rpc(self) -> dict[str, str]:
+        """What a call to a JSON-RPC API was (`rpc_method`, `a2a_operation`); empty otherwise."""
+        return {
+            key: self.payload[key] for key in RPC_KEYS if isinstance(self.payload.get(key), str)
+        }
+
+    def effective_status(self, now: datetime | None = None) -> str:
+        """The status, with a pending approval past its expiry read as `expired`."""
+        if self.status == PENDING and self.expires_at <= (now or utcnow()):
+            return EXPIRED
+        return self.status
+
+    def is_pending(self, now: datetime | None = None) -> bool:
+        return self.effective_status(now) == PENDING
+
+    def public(self, *, include_call: bool = True, now: datetime | None = None) -> dict[str, Any]:
+        """The approval as clients see it (never the call hash, the interrupt or the rule).
+
+        `query` and `body` are there when `include_call` and the record still
+        holds them (pending, or `TRACE_CAPTURE=full`).
+        """
+        out: dict[str, Any] = {
+            "approval_id": self.approval_id,
+            "thread_id": self.thread_id,
+            "run_id": self.run_id,
+            "status": self.effective_status(now),
+            "api": self.api,
+            "method": self.method,
+            "path": self.path,
+            "operation_id": self.operation_id,
+        }
+        if include_call:
+            for key in CALL_CONTENT_KEYS:
+                if key in self.payload:
+                    out[key] = self.payload[key]
+        out.update(self.rpc())
+        for key in (EFFECT_KEY, NESTED_KEY):
+            if isinstance(self.payload.get(key), dict):
+                out[key] = (
+                    self.payload[key]
+                    if include_call
+                    else without_nested_call({key: self.payload[key]})[key]
+                )
+        out.update(
+            {
+                "tool": self.payload.get("tool"),
+                "reason": self.payload.get("reason"),
+                "approvers": list(self.approvers),
+                "decide_with": self.decide_with,
+                "requester": self.requester_hash,
+                "requester_actor": self.requester_actor or None,
+                "decided_via": self.decided_via,
+                "digest": self.display_digest,
+                "created_at": _iso(self.created_at),
+                "expires_at": _iso(self.expires_at),
+                "decided_by": self.decided_by,
+                "decided_at": _iso(self.decided_at),
+                "comment": self.comment,
+            }
+        )
+        return out
+
+
+def approval_view(record: ApprovalRecord) -> dict[str, Any]:
+    """The call as the approver sees it while the approval is pending (masked fields masked).
+
+    `rpc_method` and `a2a_operation` are what a call to a JSON-RPC API was, read
+    from its body; None for any other call.
+    """
+    rpc = record.rpc()
+    return {
+        "api": record.api,
+        "method": record.method,
+        "path": record.path,
+        "operation_id": record.operation_id,
+        "rpc_method": rpc.get(RPC_METHOD_KEY),
+        "a2a_operation": rpc.get(A2A_OPERATION_KEY),
+        "query": record.payload.get("query"),
+        "body": record.payload.get("body"),
+    }
+
+
+def _nested_expiry(nested: Any) -> datetime | None:
+    """The earliest `expires_at` of a relayed approval chain (`nested`), or None."""
+    earliest: datetime | None = None
+    level, depth = nested, 0
+    while isinstance(level, Mapping) and depth < NESTED_MAX_DEPTH:
+        try:
+            expiry = _as_datetime(level.get("expires_at"))
+        except (TypeError, ValueError):
+            expiry = None
+        if expiry is not None and (earliest is None or expiry < earliest):
+            earliest = expiry
+        level, depth = level.get(NESTED_KEY), depth + 1
+    return earliest
+
+
+def without_nested_call(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """`payload` with the query and body of its relayed approvals' calls, at every level
+    (`nested.call`, `nested.nested.call`, ...), and of its `effect`, taken out."""
+
+    def strip(level: Any, depth: int) -> Any:
+        if not isinstance(level, Mapping) or depth >= NESTED_MAX_DEPTH:
+            return level
+        out = dict(level)
+        if isinstance(out.get("call"), Mapping):
+            out["call"] = {k: v for k, v in out["call"].items() if k not in CALL_CONTENT_KEYS}
+        if NESTED_KEY in out:
+            out[NESTED_KEY] = strip(out[NESTED_KEY], depth + 1)
+        return out
+
+    out = dict(payload)
+    if isinstance(out.get(NESTED_KEY), Mapping):
+        out[NESTED_KEY] = strip(out[NESTED_KEY], 0)
+    if isinstance(out.get(EFFECT_KEY), Mapping):
+        out[EFFECT_KEY] = {k: v for k, v in out[EFFECT_KEY].items() if k not in CALL_CONTENT_KEYS}
+    return out
+
+
+def approval_digest(view: Mapping[str, Any]) -> str:
+    """`sha256:<hex>` of the approver's view of a call (canonical JSON): what a relayed
+    decision names, so a decision taken on another view is refused."""
+    text = json.dumps(view, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)
+    return DIGEST_PREFIX + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def record_from_interrupt(
+    value: Mapping[str, Any],
+    *,
+    interrupt_id: str,
+    thread_id: str,
+    run_id: str,
+    requester: Principal,
+    now: datetime | None = None,
+    origin: Mapping[str, Any] | None = None,
+) -> ApprovalRecord:
+    """A pending approval for the interrupt a gated call raised (`is_approval_interrupt`).
+
+    `origin` is the user's own words the paused request carried (`auth.origin_of`),
+    kept until the approval is decided so the resumed run acts on them.
+    """
+    now = now or utcnow()
+    raw_timeout = value.get("timeout_s")
+    timeout = (
+        raw_timeout
+        if isinstance(raw_timeout, int) and not isinstance(raw_timeout, bool)
+        else DEFAULT_APPROVAL_TIMEOUT_S
+    )
+    timeout = min(max(timeout, MIN_APPROVAL_TIMEOUT_S), MAX_APPROVAL_TIMEOUT_S)
+    approvers = [str(a) for a in value.get("approvers") or [] if isinstance(a, str)]
+    decide_with = value.get("decide_with")
+    if decide_with not in DECIDE_WITH_VALUES:
+        decide_with = DECIDE_DIRECT  # a call paused before 0.3
+    relayers = value.get("relayers") if decide_with == DECIDE_RELAYED else None
+    payload = {
+        "query": value.get("query") or {},
+        "body": value.get("body"),
+        "tool": value.get("tool"),
+        "reason": value.get("reason"),
+    }
+    payload.update({key: value[key] for key in RPC_KEYS if isinstance(value.get(key), str)})
+    payload.update(
+        {key: value[key] for key in (NESTED_KEY, EFFECT_KEY) if isinstance(value.get(key), dict)}
+    )
+    if origin is not None and isinstance(origin.get("text"), str):
+        payload[ORIGIN_PAYLOAD_KEY] = dict(origin)
+    expires_at = now + timedelta(seconds=timeout)
+    downstream = _nested_expiry(payload.get(NESTED_KEY))
+    if downstream is not None:
+        # Never ask the person to approve what has expired where it happens.
+        expires_at = min(expires_at, downstream - timedelta(seconds=NESTED_EXPIRY_MARGIN_S))
+    record = ApprovalRecord(
+        approval_id=uuid.uuid4().hex,
+        thread_id=thread_id,
+        run_id=run_id,
+        interrupt_id=str(interrupt_id),
+        requester_hash=requester.hashed_id(),
+        requester_actor=requester.actor.id if requester.actor is not None else "",
+        requester_context={
+            "roles": [str(r) for r in requester.roles],
+            "attributes": requester.public_attributes(),
+        },
+        api=str(value.get("api") or ""),
+        method=str(value.get("method") or "").upper(),
+        path=str(value.get("path") or ""),
+        operation_id=str(value["operation_id"]) if value.get("operation_id") else None,
+        call_hash=str(value.get("call_hash") or ""),
+        tool_call_id=str(value["tool_call_id"]) if value.get("tool_call_id") else None,
+        message_id=str(value["message_id"]) if value.get("message_id") else None,
+        approvers=approvers,
+        payload=payload,
+        created_at=now,
+        expires_at=expires_at,
+        decide_with=str(decide_with),
+        relayers=[str(r) for r in relayers or [] if isinstance(r, str)],
+    )
+    record.display_digest = approval_digest(approval_view(record))
+    return record
+
+
+def decision_value(record: ApprovalRecord, decision: str) -> dict[str, Any]:
+    """The resume value for the interrupt of `record`: `approve`, `reject` or `expired`,
+    or `pending` for a call whose approval still waits (another one was decided).
+
+    It names the call it was taken for (API, method, path, and for a JSON-RPC
+    call its `rpc_method` and `a2a_operation`): the client applies it to that
+    call whatever the policy says about gating it by then, so a rejected or
+    expired call is never sent and a pending one pauses again.
+    `approvers` (and how they decide: `decide_with`, `relayers`) are the ones
+    the approval was asked of: the client refuses an approval whose approvers,
+    or how they decide, differ from what the policy's gate names when the call
+    is about to be sent.
+    """
+    return {
+        "type": APPROVAL_DECISION,
+        "approval_id": record.approval_id,
+        "decision": decision,
+        "api": record.api,
+        "method": record.method,
+        "path": record.path,
+        "call_hash": record.call_hash,
+        "approvers": list(record.approvers),
+        "decide_with": record.decide_with,
+        "relayers": list(record.relayers),
+        "comment": record.comment,
+        **record.rpc(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Who decides, who sees
+# ---------------------------------------------------------------------------
+
+
+def role_approvers(approvers: Iterable[str]) -> set[str]:
+    return {
+        a[len(ROLE_APPROVER_PREFIX) :]
+        for a in approvers
+        if isinstance(a, str) and a.startswith(ROLE_APPROVER_PREFIX)
+    }
+
+
+# The thread an approval was asked on: its `ThreadRecord`, or the owner's subject alone
+# (a direct thread), as older callers pass it.
+ThreadOwner = ThreadRecord | str | None
+
+
+def thread_owner(owner: ThreadOwner) -> tuple[str, str]:
+    """`(subject, actor)` of a thread (`actor` "" for a direct thread)."""
+    if isinstance(owner, ThreadRecord):
+        return owner.principal_id or "", owner.actor or ""
+    return owner or "", ""
+
+
+def is_requester(principal: Principal, owner: ThreadOwner) -> bool:
+    """The principal the thread's runs act for: the thread's owner (only the owner runs on it).
+
+    The subject directly, whichever agent started the thread; an agent only on
+    a thread started under its own subject and actor.
+    """
+    subject, actor = thread_owner(owner)
+    if not subject or principal.id != subject:
+        return False
+    return principal.actor is None or principal.actor.id == actor
+
+
+def decide_refusal(
+    principal: Principal,
+    owner: ThreadOwner,
+    approvers: Iterable[str],
+    *,
+    decide_with: str = DECIDE_DIRECT,
+    relayers: Iterable[str] = (),
+) -> tuple[str, str] | None:
+    """Why `principal` may not approve or reject (`(code, detail)`, a 403), or None.
+
+    A direct principal: the requester decides only when `requester` is
+    listed, never through a role (no self-approval unless the policy asks for
+    requester confirmation); anyone else through a listed `role:` it holds. A
+    delegated principal (an agent) decides only on a thread it started for
+    that user (else it learns nothing more than that it is no approver), when
+    the rule is `decide_with: relayed` with `requester` listed (else
+    `approval_direct_only`: the person decides with their own credentials),
+    and when its actor is one of the rule's `relayers`. It must also send the
+    approval's digest (`digest_refusal`).
+    """
+    approvers = list(approvers)
+    if principal.actor is not None:
+        if not is_requester(principal, owner):
+            return CODE_NOT_AN_APPROVER, NOT_AN_APPROVER_DETAIL
+        if decide_with != DECIDE_RELAYED or REQUESTER_APPROVER not in approvers:
+            return (
+                CODE_DIRECT_ONLY,
+                "This approval must be decided by the person at this agent (decide_with: "
+                f"direct), not relayed by agent {principal.actor.id}.",
+            )
+        if principal.actor.id not in set(relayers):
+            return (
+                CODE_NOT_AN_APPROVER,
+                f"{principal.actor.id} may not relay decisions for this approval.",
+            )
+        return None
+    if is_requester(principal, owner):
+        allowed = REQUESTER_APPROVER in approvers
+    else:
+        allowed = bool(role_approvers(approvers) & set(principal.roles))
+    return None if allowed else (CODE_NOT_AN_APPROVER, NOT_AN_APPROVER_DETAIL)
+
+
+def may_decide(
+    principal: Principal,
+    owner: ThreadOwner,
+    approvers: Iterable[str],
+    *,
+    decide_with: str = DECIDE_DIRECT,
+    relayers: Iterable[str] = (),
+) -> bool:
+    """Whether `principal` may approve or reject: see `decide_refusal`."""
+    refusal = decide_refusal(
+        principal, owner, approvers, decide_with=decide_with, relayers=relayers
+    )
+    return refusal is None
+
+
+def digest_refusal(principal: Principal, record: ApprovalRecord, digest: Any) -> bool:
+    """Whether a decision's `digest` refuses it (409 `approval_digest_mismatch`).
+
+    A delegated decider (a relayer) must name the digest of the view the
+    person approved (`ApprovalRecord.display_digest`); a direct decider may,
+    and a digest it sends is checked too.
+    """
+    if digest is None and principal.actor is None:
+        return False
+    expected = record.display_digest
+    return not (isinstance(digest, str) and expected is not None and digest == expected)
+
+
+def reads_across(principal: Principal) -> bool:
+    """A direct principal holding a read-across role (a delegated one never reads across)."""
+    return not principal.delegated and bool(set(principal.roles) & read_across_roles())
+
+
+def may_view(principal: Principal, owner: ThreadOwner, approvers: Iterable[str]) -> bool:
+    """The owner, a decider, or a read-across role (for listing)."""
+    return (
+        is_requester(principal, owner)
+        or may_decide(principal, owner, approvers)
+        or reads_across(principal)
+    )
+
+
+def sees_call(principal: Principal, owner: ThreadOwner, approvers: Iterable[str]) -> bool:
+    """Whether the viewer sees the call's query and body: the owner and the deciders
+    do (they need them); read-across roles only under `TRACE_CAPTURE=full`."""
+    return (
+        is_requester(principal, owner) or may_decide(principal, owner, approvers) or capture_full()
+    )
+
+
+def resume_principal(
+    record: ApprovalRecord,
+    owner: ThreadOwner,
+    decider: Principal,
+    origin: Mapping[str, Any] | None = None,
+) -> Principal:
+    """Who the resumed run acts as: always the requester, never another decider.
+
+    When the requester decides (the same subject and actor, or the subject
+    itself on a thread its agent started), their own principal of this
+    request (its credentials included, for `auth: forward` APIs). When
+    someone else does (a role approver), the requester with the roles, public
+    attributes and actor the run had when it paused; credentials are never
+    stored, so an `auth: forward` call approved by someone else has none and
+    is not sent.
+
+    An agent's run acts on the user's words of the request that paused it
+    (`origin`, which the approval kept: `ORIGIN_PAYLOAD_KEY`), never on those
+    a decision it relays carries (the person's words when approving, at the
+    agent that asked): its tools check the same words again, and a relay it
+    makes in turn rebuilds the very call the person approved. The person
+    deciding directly acts with their own words.
+    """
+    subject, actor = thread_owner(owner)
+    if decider.actor is None and decider.id == subject:
+        return decider
+    if decider.owner_key() == owner_key_of(subject, actor):
+        return with_origin(decider, origin)
+    context = record.requester_context or {}
+    attributes = dict(context.get("attributes") or {})
+    rebuilt = Principal(
+        id=subject,
+        roles=[str(r) for r in context.get("roles") or []],
+        attributes=attributes,
+        actor=actor_of_attributes(attributes),
+    )
+    return with_origin(rebuilt, origin) if origin is not None else rebuilt
+
+
+# ---------------------------------------------------------------------------
+# The store (and the ledger `api_client` consults)
+# ---------------------------------------------------------------------------
+
+
+def _without_call(payload: Mapping[str, Any]) -> dict[str, Any]:
+    kept = {k: v for k, v in payload.items() if k != ORIGIN_PAYLOAD_KEY}
+    if capture_full():
+        return kept
+    return without_nested_call({k: v for k, v in kept.items() if k not in CALL_CONTENT_KEYS})
+
+
+_COLUMNS = (
+    "approval_id, thread_id, run_id, interrupt_id, requester_hash, requester_context, api, "
+    "method, path, operation_id, call_hash, tool_call_id, message_id, approvers, payload, "
+    "status, decided_by, decided_at, comment, used_at, created_at, expires_at, requester_actor, "
+    "decide_with, relayers, decided_via, display_digest"
+)
+
+
+def _cleared_payload() -> str:
+    """The SQL of the payload with the call cleared, unless the first parameter is true
+    (TRACE_CAPTURE=full): its query and body, those of the relayed approvals' calls at
+    every level (as `without_nested_call`), and those of its `effect`. The user's words
+    (`ORIGIN_PAYLOAD_KEY`) go whatever the parameter says."""
+    paths = ["'{effect,query}'", "'{effect,body}'"]
+    for depth in range(1, NESTED_MAX_DEPTH + 1):
+        prefix = ",".join([NESTED_KEY] * depth)
+        # A text[] literal such as '{nested,call,body}' (built without doubled braces).
+        paths += ["'{" + prefix + ",call," + key + "}'" for key in CALL_CONTENT_KEYS]
+    cleared = " ".join(f"#- {path}" for path in paths)
+    return (
+        f"(CASE WHEN %s THEN payload ELSE (payload - 'query' - 'body') {cleared} END)"
+        f" - '{ORIGIN_PAYLOAD_KEY}'"
+    )
+
+
+# Clears the call from the payload unless the first parameter is true (TRACE_CAPTURE=full).
+_CLEARED_PAYLOAD = _cleared_payload()
+
+
+def _record_from_row(row: Mapping[str, Any]) -> ApprovalRecord:
+    return ApprovalRecord(
+        approval_id=row["approval_id"],
+        thread_id=row["thread_id"],
+        run_id=row["run_id"],
+        interrupt_id=row["interrupt_id"],
+        requester_hash=row["requester_hash"],
+        requester_context=_decode(row.get("requester_context")) or {},
+        api=row["api"],
+        method=row["method"],
+        path=row["path"],
+        operation_id=row.get("operation_id"),
+        call_hash=row["call_hash"],
+        tool_call_id=row.get("tool_call_id"),
+        message_id=row.get("message_id"),
+        approvers=list(_decode(row.get("approvers")) or []),
+        payload=dict(_decode(row.get("payload")) or {}),
+        status=row["status"],
+        decided_by=row.get("decided_by"),
+        decided_at=_as_datetime(row.get("decided_at")),
+        comment=row.get("comment"),
+        used_at=_as_datetime(row.get("used_at")),
+        created_at=_as_datetime(row.get("created_at")) or utcnow(),
+        expires_at=_as_datetime(row.get("expires_at")) or utcnow(),
+        requester_actor=row.get("requester_actor") or "",
+        decide_with=(
+            row["decide_with"] if row.get("decide_with") in DECIDE_WITH_VALUES else DECIDE_DIRECT
+        ),
+        relayers=[str(r) for r in _decode(row.get("relayers")) or []],
+        decided_via=row.get("decided_via"),
+        display_digest=row.get("display_digest"),
+    )
+
+
+def _row_of(record: ApprovalRecord) -> dict[str, Any]:
+    """A record as the approvals file keeps it (the table's columns, times in ISO form)."""
+    row = asdict(record)
+    for key in _DATETIME_FIELDS:
+        row[key] = _iso(row[key])
+    return row
+
+
+class ApprovalStore:
+    """The approvals table under postgres, an in-process dict otherwise.
+
+    Also the ledger `api_client` marks approvals used in (`consume`). Times
+    are this process's clock (`clock`), for the expiry and the decision alike.
+    Without a database, `path` (`dev_ledger_path`, under `langgraph dev`) is
+    the file the records are kept in: call `load` once before use.
+    """
+
+    def __init__(
+        self, db: Database, *, clock: Any = utcnow, path: str | Path | None = None
+    ) -> None:
+        self.db = db
+        self.table = db.approvals_table
+        self._clock = clock
+        self._memory: OrderedDict[str, ApprovalRecord] = OrderedDict()
+        self.path = Path(path) if path is not None and not db.is_postgres else None
+        # The records, which graph runs may reach from other threads.
+        self._lock = threading.Lock()
+        # One file write at a time; a write older than the file's is skipped.
+        self._file_lock = threading.Lock()
+        self._changes = 0  # changes numbered as they are written out
+        self._saved = 0  # the newest change the file holds
+        self._failed = 0  # the newest change whose write failed
+
+    def now(self) -> datetime:
+        return self._clock()
+
+    # -- the file (langgraph dev) ------------------------------------------------
+
+    async def load(self) -> int:
+        """Read the records the file keeps (none without a file); how many.
+
+        Raises `LedgerUnavailable` when the file exists but cannot be read:
+        the server must not start without the approvals that bind the tool
+        calls of its threads.
+        """
+        if self.path is None:
+            return 0
+        records = await asyncio.to_thread(self._read)
+        with self._lock:
+            self._memory = OrderedDict((r.approval_id, r) for r in records)
+        logger.info("approvals kept in %s: %d loaded", self.path, len(records))
+        return len(records)
+
+    def _read(self) -> list[ApprovalRecord]:
+        assert self.path is not None
+        try:
+            raw = self.path.read_bytes()
+        except FileNotFoundError:
+            return []
+        except OSError as exc:
+            raise self._unreadable(exc) from exc
+        try:
+            data = json.loads(raw)
+            if not isinstance(data, dict) or data.get("version") not in LEDGER_FILE_VERSIONS:
+                raise ValueError(f"not a version {LEDGER_FILE_VERSION} approvals file")
+            return [_record_from_row(row) for row in data["approvals"]]
+        except Exception as exc:
+            raise self._unreadable(exc) from exc
+
+    def _unreadable(self, exc: BaseException) -> LedgerUnavailable:
+        return LedgerUnavailable(
+            f"the approvals file {self.path} cannot be read ({type(exc).__name__}). It binds "
+            "the tool calls of this server's threads to their approvals: without it, calls "
+            "rejected, pending or sent already could be sent again. Restore it, or delete "
+            f"{self.path.parent if self.path else DEV_STATE_DIR}/ to reset the dev server's "
+            "threads and approvals together."
+        )
+
+    def _dump(self) -> bytes:
+        """The records as the file keeps them (call with `_lock` held)."""
+        rows = [_row_of(r) for r in self._memory.values()]
+        return json.dumps({"version": LEDGER_FILE_VERSION, "approvals": rows}, default=str).encode()
+
+    def _write(self, change: int, data: bytes) -> None:
+        """Replace the file with `data` (atomically, mode 0600), unless it holds a newer change."""
+        assert self.path is not None
+        with self._file_lock:
+            if change <= self._saved:
+                return
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            partial = self.path.with_name(f".{self.path.name}.{os.getpid()}.partial")
+            try:
+                fd = os.open(partial, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+                with os.fdopen(fd, "wb") as out:
+                    out.write(data)
+                    out.flush()
+                    os.fsync(out.fileno())
+                os.replace(partial, self.path)
+            except BaseException:
+                with contextlib.suppress(OSError):
+                    os.unlink(partial)
+                raise
+            self._saved = change
+
+    async def _save(self) -> None:
+        """Write the records out, after a change and before it takes effect (no file: nothing).
+
+        A failed write raises `LedgerUnavailable`, and the store answers
+        nothing until a later write succeeds (`_check_saved`).
+        """
+        if self.path is None:
+            return
+        with self._lock:
+            self._changes += 1
+            change = self._changes
+            data = self._dump()
+        try:
+            await asyncio.to_thread(self._write, change, data)
+        except Exception as exc:
+            self._failed = max(self._failed, change)
+            logger.error(
+                "the approvals file %s could not be written (%s): gated API calls and runs "
+                "on threads with approvals are refused until it is",
+                self.path,
+                type(exc).__name__,
+            )
+            raise LedgerUnavailable(
+                f"the approvals file could not be written ({type(exc).__name__})"
+            ) from exc
+
+    async def _check_saved(self) -> None:
+        """Before any use of the records: they are all in the file (a failed write is retried)."""
+        if self.path is not None and self._saved < self._failed:
+            await self._save()
+
+    # -- writes -----------------------------------------------------------------
+
+    async def add(self, record: ApprovalRecord) -> tuple[ApprovalRecord, bool, int]:
+        """Record a pending approval: `(record, created, superseded)`.
+
+        A tool asked again for the same interrupt (the run resumed for another
+        approval, so this tool call ran again) keeps the pending approval of the
+        same request instead of a second one (`created` False). A pending
+        approval of that interrupt for a different request, or past its expiry,
+        is marked expired (`superseded` counts them).
+        """
+        now = self.now()
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                superseded = 0
+                kept = None
+                for existing in list(self._memory.values()):
+                    if (
+                        existing.thread_id != record.thread_id
+                        or existing.interrupt_id != record.interrupt_id
+                        or existing.status != PENDING
+                    ):
+                        continue
+                    if existing.call_hash == record.call_hash and existing.expires_at > now:
+                        kept = existing
+                        break
+                    self._close(existing, EXPIRED, now)
+                    superseded += 1
+                if kept is None:
+                    self._memory[record.approval_id] = record
+                    self._evict()
+            if kept is not None and not superseded:
+                return kept, False, 0
+            await self._save()
+            return (kept, False, superseded) if kept is not None else (record, True, superseded)
+        rows = await self.db.fetchall(
+            f"""
+            UPDATE {self.table}
+               SET status = %s, decided_at = %s, payload = {_CLEARED_PAYLOAD}
+             WHERE thread_id = %s AND interrupt_id = %s AND status = %s
+               AND (call_hash <> %s OR expires_at <= %s)
+            RETURNING approval_id
+            """,
+            (
+                EXPIRED,
+                now,
+                capture_full(),
+                record.thread_id,
+                record.interrupt_id,
+                PENDING,
+                record.call_hash,
+                now,
+            ),
+        )
+        existing = await self.db.fetchone(
+            f"""
+            SELECT {_COLUMNS} FROM {self.table}
+             WHERE thread_id = %s AND interrupt_id = %s AND status = %s AND call_hash = %s
+               AND expires_at > %s
+             ORDER BY created_at DESC LIMIT 1
+            """,
+            (record.thread_id, record.interrupt_id, PENDING, record.call_hash, now),
+        )
+        if existing is not None:
+            return _record_from_row(existing), False, len(rows)
+        await self.db.execute(
+            f"""
+            INSERT INTO {self.table} ({_COLUMNS})
+            VALUES (%s, %s, %s, %s, %s, %s::jsonb, %s, %s, %s, %s, %s, %s, %s, %s::jsonb,
+                    %s::jsonb, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, %s, %s)
+            """,
+            (
+                record.approval_id,
+                record.thread_id,
+                record.run_id,
+                record.interrupt_id,
+                record.requester_hash,
+                _json(record.requester_context),
+                record.api,
+                record.method,
+                record.path,
+                record.operation_id,
+                record.call_hash,
+                record.tool_call_id,
+                record.message_id,
+                _json(record.approvers),
+                _json(record.payload),
+                record.status,
+                record.decided_by,
+                record.decided_at,
+                record.comment,
+                record.used_at,
+                record.created_at,
+                record.expires_at,
+                record.requester_actor,
+                record.decide_with,
+                _json(record.relayers),
+                record.decided_via,
+                record.display_digest,
+            ),
+        )
+        return record, True, len(rows)
+
+    async def decide(
+        self,
+        approval_id: str,
+        status: str,
+        decided_by: str,
+        comment: str | None,
+        decided_via: str | None = None,
+    ) -> ApprovalRecord | None:
+        """Decide a pending, unexpired approval (`approved` or `rejected`), atomically.
+
+        None when it is not pending any more (decided, expired, gone): of two
+        concurrent decisions exactly one gets the record. `decided_via` is the
+        agent that relayed the decision (None: decided directly).
+        """
+        if status not in (APPROVED, REJECTED):
+            raise ValueError(f"not a decision: {status!r}")
+        now = self.now()
+        comment = (comment or "").strip()[:COMMENT_MAX_CHARS] or None
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                record = self._memory.get(approval_id)
+                if record is None or not record.is_pending(now):
+                    return None
+                self._close(record, status, now, decided_by=decided_by, comment=comment)
+                record.decided_via = decided_via
+            await self._save()
+            return record
+        row = await self.db.fetchone(
+            f"""
+            UPDATE {self.table}
+               SET status = %s, decided_by = %s, decided_at = %s, comment = %s,
+                   decided_via = %s, payload = {_CLEARED_PAYLOAD}
+             WHERE approval_id = %s AND status = %s AND expires_at > %s
+            RETURNING {_COLUMNS}
+            """,
+            (
+                status,
+                decided_by,
+                now,
+                comment,
+                decided_via,
+                capture_full(),
+                approval_id,
+                PENDING,
+                now,
+            ),
+        )
+        return _record_from_row(row) if row is not None else None
+
+    async def consume(
+        self, approval_id: str, call_hash: str, thread_id: str | None = None
+    ) -> str | None:
+        """The ledger: mark an approved approval used, once. None when it may be sent now.
+
+        It must be approved, for exactly the request `call_hash`, on thread
+        `thread_id` (when given), and never used before; else the reason.
+        """
+        now = self.now()
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                record = self._memory.get(approval_id)
+                problem = self._unusable(record, call_hash, thread_id)
+                if problem is None and record is not None:
+                    record.used_at = now
+            if problem is None:
+                await self._save()  # before the call is sent
+            return problem
+        row = await self.db.fetchone(
+            f"""
+            UPDATE {self.table} SET used_at = %s
+             WHERE approval_id = %s AND status = %s AND used_at IS NULL AND call_hash = %s
+               AND (%s::text IS NULL OR thread_id = %s::text)
+            RETURNING approval_id
+            """,
+            (now, approval_id, APPROVED, call_hash, thread_id, thread_id),
+        )
+        if row is not None:
+            return None
+        return self._unusable(await self.get(approval_id), call_hash, thread_id) or (
+            "the approval is not usable"
+        )
+
+    @staticmethod
+    def _unusable(
+        record: ApprovalRecord | None, call_hash: str, thread_id: str | None
+    ) -> str | None:
+        if record is None:
+            return "no such approval"
+        if thread_id is not None and record.thread_id != thread_id:
+            return "the approval belongs to another thread"
+        if record.status != APPROVED:
+            return f"the approval is {record.effective_status()}, not approved"
+        if record.call_hash != call_hash:
+            return "the approval is for a different request"
+        if record.used_at is not None:
+            return "the approval was already used"
+        return None
+
+    async def expire(self, approval_id: str) -> ApprovalRecord | None:
+        """Mark one pending approval `expired` (its run no longer waits for it); None if not pending."""
+        now = self.now()
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                record = self._memory.get(approval_id)
+                if record is None or record.status != PENDING:
+                    return None
+                self._close(record, EXPIRED, now)
+            await self._save()
+            return record
+        row = await self.db.fetchone(
+            f"""
+            UPDATE {self.table}
+               SET status = %s, decided_at = %s, payload = {_CLEARED_PAYLOAD}
+             WHERE approval_id = %s AND status = %s
+            RETURNING {_COLUMNS}
+            """,
+            (EXPIRED, now, capture_full(), approval_id, PENDING),
+        )
+        return _record_from_row(row) if row is not None else None
+
+    async def expire_due(self) -> list[ApprovalRecord]:
+        """Mark every pending approval past its expiry `expired`; return them (the sweep).
+
+        Also retries a failed write of the approvals file.
+        """
+        now = self.now()
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                due = [
+                    r for r in self._memory.values() if r.status == PENDING and r.expires_at <= now
+                ]
+                for record in due:
+                    self._close(record, EXPIRED, now)
+            if due:
+                await self._save()
+            return due
+        rows = await self.db.fetchall(
+            f"""
+            UPDATE {self.table}
+               SET status = %s, decided_at = %s, payload = {_CLEARED_PAYLOAD}
+             WHERE status = %s AND expires_at <= %s
+            RETURNING {_COLUMNS}
+            """,
+            (EXPIRED, now, capture_full(), PENDING, now),
+        )
+        return [_record_from_row(r) for r in rows]
+
+    async def delete_for_thread(self, thread_id: str) -> int:
+        """Delete every approval of a thread (the thread was deleted); how many."""
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                gone = [k for k, r in self._memory.items() if r.thread_id == thread_id]
+                for key in gone:
+                    del self._memory[key]
+            if gone:
+                await self._save()
+            return len(gone)
+        rows = await self.db.fetchall(
+            f"DELETE FROM {self.table} WHERE thread_id = %s RETURNING approval_id", (thread_id,)
+        )
+        return len(rows)
+
+    # -- reads ------------------------------------------------------------------
+
+    async def _records(self) -> list[ApprovalRecord]:
+        """The records kept without a database, in the order they were added."""
+        await self._check_saved()
+        with self._lock:
+            return list(self._memory.values())
+
+    async def bound_approvals(
+        self, *, tool_call: tuple[str, str] | None = None, interrupt_id: str | None = None
+    ) -> list[BoundApproval]:
+        """The ledger's answer for a tool call that runs again without a decision.
+
+        Every approval asked by the tool call `(message id, tool call id)` or by
+        the interrupt `interrupt_id`, newest first, on any thread: a copy of a
+        thread keeps its messages, so a tool call there is the same tool call
+        (message ids are unique, so another thread's tool call never matches).
+        `api_client` refuses the call when one of them was asked for it.
+        """
+        now = self.now()
+        message_id, call_id = tool_call or (None, None)
+        if not self.db.is_postgres:
+            records = [
+                r
+                for r in await self._records()
+                if (message_id and r.message_id == message_id and r.tool_call_id == call_id)
+                or (interrupt_id and r.interrupt_id == interrupt_id)
+            ]
+        else:
+            rows = await self.db.fetchall(
+                f"""
+                SELECT {_COLUMNS} FROM {self.table}
+                 WHERE (message_id = %s::text AND tool_call_id = %s::text)
+                    OR interrupt_id = %s::text
+                """,
+                (message_id, call_id, interrupt_id),
+            )
+            records = [_record_from_row(r) for r in rows]
+        records.sort(key=lambda r: r.created_at, reverse=True)
+        return [
+            BoundApproval(
+                api=r.api,
+                method=r.method,
+                path=r.path,
+                status=r.effective_status(now),
+                used=r.used_at is not None,
+                rpc_method=r.rpc().get(RPC_METHOD_KEY),
+                a2a_operation=r.rpc().get(A2A_OPERATION_KEY),
+            )
+            for r in records
+        ]
+
+    async def get(self, approval_id: str) -> ApprovalRecord | None:
+        if not self.db.is_postgres:
+            await self._check_saved()
+            with self._lock:
+                return self._memory.get(approval_id)
+        row = await self.db.fetchone(
+            f"SELECT {_COLUMNS} FROM {self.table} WHERE approval_id = %s", (approval_id,)
+        )
+        return _record_from_row(row) if row is not None else None
+
+    async def for_thread(self, thread_id: str) -> list[ApprovalRecord]:
+        """Every approval of a thread, newest first."""
+        if not self.db.is_postgres:
+            return sorted(
+                (r for r in await self._records() if r.thread_id == thread_id),
+                key=lambda r: r.created_at,
+                reverse=True,
+            )
+        rows = await self.db.fetchall(
+            f"SELECT {_COLUMNS} FROM {self.table} WHERE thread_id = %s "
+            "ORDER BY created_at DESC, approval_id",
+            (thread_id,),
+        )
+        return [_record_from_row(r) for r in rows]
+
+    async def pending_for_thread(self, thread_id: str) -> list[ApprovalRecord]:
+        """The thread's pending approvals that have not expired, oldest first."""
+        now = self.now()
+        return sorted(
+            (r for r in await self.for_thread(thread_id) if r.is_pending(now)),
+            key=lambda r: r.created_at,
+        )
+
+    async def visible(
+        self,
+        principal: Principal,
+        *,
+        status: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ApprovalRecord]:
+        """Approvals the caller may see across threads, newest first (`GET /approvals`).
+
+        Their own (requested on their threads), the ones a role of theirs may
+        decide, and every one for a read-across role. A delegated principal
+        sees only the ones requested under its own subject and actor. `status`
+        filters (a pending approval past its expiry counts as `expired`).
+        """
+        now = self.now()
+        own = principal.hashed_id()
+        actor = principal.actor.id if principal.actor is not None else None
+        across = reads_across(principal)
+        # A delegated principal's roles never make it an approver.
+        roles = (
+            set() if actor is not None else {f"{ROLE_APPROVER_PREFIX}{r}" for r in principal.roles}
+        )
+
+        def mine(r: ApprovalRecord) -> bool:
+            return r.requester_hash == own and (actor is None or r.requester_actor == actor)
+
+        if not self.db.is_postgres:
+            rows = [
+                r
+                for r in sorted(await self._records(), key=lambda r: r.created_at, reverse=True)
+                if (across or mine(r) or roles & set(r.approvers))
+                and (status is None or r.effective_status(now) == status)
+            ]
+            return rows[offset : offset + limit]
+        conditions = [
+            "(%s OR (requester_hash = %s AND (%s::text IS NULL OR requester_actor = %s::text)) "
+            "OR approvers ?| %s::text[])"
+        ]
+        params: list[Any] = [across, own, actor, actor, sorted(roles)]
+        if status == PENDING:
+            conditions.append("status = %s AND expires_at > %s")
+            params += [PENDING, now]
+        elif status == EXPIRED:
+            conditions.append("(status = %s OR (status = %s AND expires_at <= %s))")
+            params += [EXPIRED, PENDING, now]
+        elif status is not None:
+            conditions.append("status = %s")
+            params.append(status)
+        rows = await self.db.fetchall(
+            f"SELECT {_COLUMNS} FROM {self.table} WHERE {' AND '.join(conditions)} "
+            "ORDER BY created_at DESC, approval_id LIMIT %s OFFSET %s",
+            (*params, limit, offset),
+        )
+        return [_record_from_row(r) for r in rows]
+
+    # -- memory -----------------------------------------------------------------
+
+    @staticmethod
+    def _close(
+        record: ApprovalRecord,
+        status: str,
+        now: datetime,
+        *,
+        decided_by: str | None = None,
+        comment: str | None = None,
+    ) -> None:
+        record.status = status
+        record.decided_at = now
+        if decided_by is not None:
+            record.decided_by = decided_by
+        if comment is not None:
+            record.comment = comment
+        record.payload = _without_call(record.payload)
+
+    def _evict(self) -> None:
+        while len(self._memory) > MEMORY_APPROVALS_CAP:
+            victim = next(
+                (k for k, r in self._memory.items() if r.status != PENDING),
+                next(iter(self._memory)),
+            )
+            del self._memory[victim]