effect-ledger 0.1.0__py3-none-any.whl

effect_ledger/__init__.py

@@ -0,0 +1,9 @@
+"""Server-owned effect recovery, with optional LangChain, LangGraph and MCP adapters."""
+
+from .operations import EffectExecutor, Operation, OperationConflict
+from .recovery import RecoveryDecision, RecoveryPolicy
+from .sqlite import SQLiteOperationStore
+from .store import Claim, OperationStore
+
+__all__ = ["EffectExecutor", "Operation", "OperationConflict", "Claim",
+           "OperationStore", "SQLiteOperationStore", "RecoveryDecision", "RecoveryPolicy"]

effect_ledger/_graph_boundary.py

@@ -0,0 +1,53 @@
+"""Shared identity and suspension rules for LangGraph effect adapters."""
+import hashlib
+from collections.abc import Callable
+from typing import Any
+
+from langchain.tools import ToolRuntime
+from langchain_core.messages import AIMessage
+from langchain_core.runnables import RunnableLambda
+from langgraph.types import interrupt
+
+from .operations import _json, _text
+
+
+def tool_identity(runtime: ToolRuntime, workflow_id: str | None,
+                  operation_id: Callable[[ToolRuntime], str] | None) -> str:
+    if operation_id is not None:
+        return _text(operation_id(runtime), "operation_id")
+    thread_id = runtime.config.get("configurable", {}).get("thread_id")
+    _text(thread_id, "thread_id")
+    _text(runtime.tool_call_id, "tool_call_id")
+    # Tool call IDs can be reused on later model turns. Bind to the durable
+    # parent message too, so a new intentional action is not silently dropped.
+    parent = next((message for message in reversed(runtime.state["messages"])
+                   if isinstance(message, AIMessage) and any(
+                       call["id"] == runtime.tool_call_id for call in message.tool_calls)), None)
+    if parent is None:
+        raise ValueError("Tool call has no checkpointed parent AIMessage")
+    _text(parent.id, "parent message ID")
+    binding = _json([workflow_id, thread_id, parent.id, runtime.tool_call_id])
+    return "lg-" + hashlib.sha256(binding.encode()).hexdigest()
+
+
+def pause(status: dict[str, Any], effect: str, config: dict | None = None) -> Any:
+    def wait(_: Any) -> Any:
+        # Historical resume answers only wake the graph; no retry permission or I/O.
+        while True:
+            interrupt({**status, "kind": "effect_recovery", "effect": effect})
+    if config is None:
+        return wait(None)
+    # Python 3.10 async middleware tracing may lose the implicit runnable context.
+    # A native synchronous Runnable restores the explicitly supplied graph config
+    # for interrupt without relying on private ContextVars or spawning another task.
+    return RunnableLambda(wait).invoke(None, config=config)
+
+
+def checked_identity(runtime: ToolRuntime, workflow_id: str | None,
+                     operation_id: Callable[[ToolRuntime], str] | None, effect: str) -> str:
+    try:
+        return tool_identity(runtime, workflow_id, operation_id)
+    except Exception as exc:
+        status = {"operation_id": None, "state": "identity_error", "unresolved": True,
+                  "error": type(exc).__name__, "version": None}
+    return pause(status, effect, runtime.config)

effect_ledger/_sql.py

@@ -0,0 +1,208 @@
+"""Shared SQL state transitions; backend transactions provide serialization."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from .models import _MISSING, Operation, OperationConflict, _json, _text
+from .store import Claim
+
+# Named explicitly rather than selected with *, so a ledger widened by a newer
+# release still reads here instead of failing to build an Operation.
+_COLUMNS = ("scope", "operation_id", "effect", "request", "provider_key", "state",
+            "attempt", "version", "result", "error", "created_at")
+_FIELDS = ", ".join(_COLUMNS)
+
+# Append-only; the index of a step is the version it produces. Step 0 is the
+# original shape, so a ledger written before versioning replays it as a no-op
+# and reaches the same place as a fresh file by the same single path.
+_MIGRATIONS: tuple[tuple[str, ...], ...] = (
+    (
+        """CREATE TABLE IF NOT EXISTS operations (
+            scope TEXT NOT NULL, operation_id TEXT NOT NULL,
+            effect TEXT NOT NULL, request TEXT NOT NULL,
+            provider_key TEXT NOT NULL, state TEXT NOT NULL,
+            attempt INTEGER NOT NULL, version INTEGER NOT NULL,
+            result TEXT, error TEXT,
+            PRIMARY KEY (scope, operation_id)
+        )""",
+        """CREATE TABLE IF NOT EXISTS decisions (
+            scope TEXT NOT NULL, decision_id TEXT NOT NULL,
+            payload TEXT NOT NULL, decided_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (scope, decision_id)
+        )""",
+    ),
+    # Text, written by the host, so both backends return the same sortable value.
+    # Rows that predate the column keep NULL rather than a fabricated time.
+    ("ALTER TABLE operations ADD COLUMN created_at TEXT",),
+)
+SCHEMA_VERSION = len(_MIGRATIONS)
+
+
+class SQLStore:
+    def _transaction(self, scope: str):
+        raise NotImplementedError
+
+    def _initialize(self):
+        """Bring the ledger to SCHEMA_VERSION, or refuse to read a newer one.
+
+        Reading a ledger a later release widened is the failure this stamp exists
+        to name: without it the mismatch surfaces as a TypeError on every read,
+        including the operator's own triage commands."""
+        with self._transaction("__schema__") as db:
+            db.execute("""CREATE TABLE IF NOT EXISTS schema_version (
+                id INTEGER PRIMARY KEY, version INTEGER NOT NULL
+            )""")
+            row = db.execute("SELECT version FROM schema_version WHERE id=1").fetchone()
+            current = 0 if row is None else row["version"]
+            if current > SCHEMA_VERSION:
+                raise ValueError(
+                    f"Ledger schema is v{current}; this build of effect-ledger "
+                    f"understands v{SCHEMA_VERSION}. Upgrade the code rather than "
+                    "reading the ledger with an older release.")
+            for step in _MIGRATIONS[current:]:
+                for statement in step:
+                    db.execute(statement)
+            if row is None:
+                db.execute("INSERT INTO schema_version(id, version) VALUES (1, ?)",
+                           (SCHEMA_VERSION,))
+            elif current < SCHEMA_VERSION:
+                db.execute("UPDATE schema_version SET version=? WHERE id=1", (SCHEMA_VERSION,))
+
+    @staticmethod
+    def _operation(row: Any) -> Operation:
+        data = dict(row)
+        data["request"] = json.loads(data["request"])
+        data["result"] = json.loads(data["result"]) if data["result"] is not None else None
+        return Operation(**data)
+
+    def _get(self, db: Any, scope: str, operation_id: str) -> Operation | None:
+        row = db.execute(
+            f"SELECT {_FIELDS} FROM operations WHERE scope=? AND operation_id=?",
+            (scope, operation_id),
+        ).fetchone()
+        return None if row is None else self._operation(row)
+
+    def get(self, scope: str, operation_id: str) -> Operation | None:
+        _text(operation_id, "operation_id")
+        with self._transaction(scope) as db:
+            return self._get(db, scope, operation_id)
+
+    def unresolved(self, scope: str, *, limit: int) -> list[Operation]:
+        """List operations awaiting a decision, oldest first. Read-only; grants nothing.
+
+        Age orders the queue but settles nothing: the oldest row is the one to
+        look at first, never the one a timer may retry. Rows written before
+        created_at existed carry no time and sort ahead of every dated row."""
+        _text(scope, "scope")
+        if type(limit) is not int or limit < 1:
+            raise ValueError("limit must be a positive integer")
+        with self._transaction(scope) as db:
+            rows = db.execute(
+                f"SELECT {_FIELDS} FROM operations WHERE scope=? AND state IN ('in_flight', "
+                "'indeterminate') ORDER BY COALESCE(created_at, ''), operation_id LIMIT ?",
+                (scope, limit),
+            ).fetchall()
+        return [self._operation(row) for row in rows]
+
+    def claim(self, scope: str, operation_id: str, effect: str, request: dict[str, Any]) -> Claim:
+        """Atomically bind and durably acquire one attempt, or return its status."""
+        _text(scope, "scope")
+        _text(operation_id, "operation_id")
+        _text(effect, "effect")
+        if type(request) is not dict:
+            raise ValueError("request must be a JSON object")
+        payload = _json(request)
+        with self._transaction(scope) as db:
+            record = self._get(db, scope, operation_id)
+            if record is None:
+                db.execute(
+                    f"INSERT INTO operations({_FIELDS}) "
+                    "VALUES (?, ?, ?, ?, ?, 'in_flight', 1, 1, NULL, NULL, ?)",
+                    (scope, operation_id, effect, payload, str(uuid4()),
+                     # Always fractional, so a burst inside one second still
+                     # sorts by arrival rather than collapsing to ID order.
+                     datetime.now(timezone.utc).isoformat(timespec="microseconds")),
+                )
+            else:
+                if record.effect != effect or _json(record.request) != payload:
+                    raise OperationConflict("Operation ID is bound to a different effect or request")
+                if record.state != "ready":
+                    return Claim(record, False)
+                db.execute(
+                    "UPDATE operations SET state='in_flight', attempt=attempt+1, "
+                    "version=version+1, error=NULL WHERE scope=? AND operation_id=?",
+                    (scope, operation_id),
+                )
+            record = self._get(db, scope, operation_id)
+            assert record is not None
+        return Claim(record, True)
+
+    def finish(self, owned: Operation, state: str, result: str | None, error: str | None) -> Operation:
+        scope = owned.scope
+        with self._transaction(scope) as db:
+            changed = db.execute(
+                "UPDATE operations SET state=?, result=?, error=?, version=version+1 "
+                "WHERE scope=? AND operation_id=? AND version=? AND state='in_flight'",
+                (state, result, error, scope, owned.operation_id, owned.version),
+            ).rowcount
+            if changed != 1:
+                raise OperationConflict("Attempt no longer owns this operation")
+            record = self._get(db, scope, owned.operation_id)
+            assert record is not None
+            return record
+
+    def resolve(
+        self, scope: str, operation_id: str, *, expected_version: int, decision_id: str,
+        action: str, reason: str, workers_stopped: bool, result: Any = _MISSING,
+    ) -> Operation:
+        """Atomically apply a trusted decision or replay its current state.
+
+        Requires stopped workers and reconciled provider requests. Completion
+        requires an explicit result; identical decisions cannot grant another retry."""
+        _text(operation_id, "operation_id")
+        _text(decision_id, "decision_id")
+        _text(reason, "reason")
+        if workers_stopped is not True:
+            raise ValueError("Confirm old workers cannot continue before resolving")
+        if type(expected_version) is not int or expected_version < 1:
+            raise ValueError("expected_version must be a positive integer")
+        if action not in ("retry", "complete"):
+            raise ValueError("action must be retry or complete")
+        if action == "complete" and result is _MISSING:
+            raise ValueError("Confirmed completion requires a result")
+        if action == "retry" and result is not _MISSING:
+            raise ValueError("Retry decisions cannot supply a completed result")
+        encoded = _json(result) if action == "complete" else None
+        payload = _json({
+            "operation_id": operation_id, "expected_version": expected_version,
+            "action": action, "reason": reason, "result": encoded,
+        })
+        with self._transaction(scope) as db:
+            record = self._get(db, scope, operation_id)
+            if record is None:
+                raise OperationConflict("Unknown operation")
+            decision = db.execute(
+                "SELECT payload FROM decisions WHERE scope=? AND decision_id=?",
+                (scope, decision_id),
+            ).fetchone()
+            if decision is not None:
+                if decision["payload"] != payload:
+                    raise OperationConflict("Decision ID already used with different parameters")
+                return record
+            if record.version != expected_version or record.state not in ("in_flight", "indeterminate"):
+                raise OperationConflict("Stale version or operation is not unresolved")
+            db.execute(
+                "UPDATE operations SET state=?, result=?, error=NULL, version=version+1 "
+                "WHERE scope=? AND operation_id=?",
+                ("ready" if action == "retry" else "completed", encoded, scope, operation_id),
+            )
+            db.execute(
+                "INSERT INTO decisions(scope, decision_id, payload) VALUES (?, ?, ?)",
+                (scope, decision_id, payload),
+            )
+            record = self._get(db, scope, operation_id)
+            assert record is not None
+            return record

effect_ledger/cli.py

@@ -0,0 +1,149 @@
+"""Operator console for unresolved effects. Never expose this as a model tool.
+
+Reading is safe. Deciding is not: `resolve` is the only path that grants another
+attempt or declares an effect complete, and it trusts what the operator asserts.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .models import Operation, OperationConflict
+from .operations import EffectExecutor
+
+
+def _executor(database: str, scope: str) -> EffectExecutor:
+    if database.startswith(("postgresql://", "postgres://")):
+        from .postgres import PostgresOperationStore
+        return EffectExecutor(store=PostgresOperationStore(database), scope=scope)
+    return EffectExecutor(database, scope=scope)
+
+
+def _summary(record: Operation) -> dict[str, Any]:
+    return {"operation_id": record.operation_id, "effect": record.effect,
+            "state": record.state, "attempt": record.attempt, "version": record.version,
+            "error": record.error, "created_at": record.created_at}
+
+
+def _list(executor: EffectExecutor, args: argparse.Namespace) -> int:
+    records = executor.unresolved(limit=args.limit)
+    if args.json:
+        print(json.dumps([_summary(r) for r in records], indent=2))
+    elif not records:
+        print("No unresolved operations.")
+    else:
+        print(f"{'STATE':<14} {'VER':>3} {'ATT':>3}  {'EFFECT':<24} OPERATION ID")
+        for r in records:
+            print(f"{r.state:<14} {r.version:>3} {r.attempt:>3}  {r.effect:<24} {r.operation_id}")
+        print(f"\n{len(records)} unresolved. `show <id>` prints the request; "
+              "settle one with `resolve`.")
+    return 0
+
+
+def _show(executor: EffectExecutor, args: argparse.Namespace) -> int:
+    record = executor.get(args.operation_id)
+    if record is None:
+        print(f"Unknown operation: {args.operation_id}", file=sys.stderr)
+        return 2
+    print(json.dumps({**_summary(record), "request": record.request,
+                      "result": record.result}, indent=2, sort_keys=True))
+    if record.state in ("in_flight", "indeterminate"):
+        # The version is the interlock, so name the one the operator just read.
+        print(f"\nUnresolved. Confirm the provider's own records against the request "
+              f"above, stop the workers, then pass --expected-version {record.version}.",
+              file=sys.stderr)
+    return 0
+
+
+def _resolve(executor: EffectExecutor, args: argparse.Namespace) -> int:
+    if not args.workers_stopped:
+        print("Refusing: pass --workers-stopped only after confirming that no worker "
+              "can still be running this operation.", file=sys.stderr)
+        return 2
+    if args.action == "complete":
+        try:
+            result = json.loads(args.result_json)
+        except json.JSONDecodeError as exc:
+            print(f"--result-json is not valid JSON: {exc}", file=sys.stderr)
+            return 2
+        extra = {"result": result}
+    else:
+        extra = {}
+    try:
+        record = executor.resolve(
+            args.operation_id, expected_version=args.expected_version,
+            decision_id=args.decision_id, action=args.action, reason=args.reason,
+            workers_stopped=True, **extra)
+    except OperationConflict as exc:
+        current = executor.get(args.operation_id)
+        print(f"Rejected: {exc}", file=sys.stderr)
+        if current is not None:
+            print(f"The operation is now state={current.state!r} version={current.version}. "
+                  "Look at it again before deciding; the version you passed described a "
+                  "state that no longer exists.", file=sys.stderr)
+        return 3
+    print(json.dumps(record.response(), indent=2, sort_keys=True))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="effect-ledger", description=__doc__.splitlines()[0])
+    parser.add_argument("--db", required=True, metavar="PATH_OR_DSN",
+                        help="SQLite file, or a postgresql:// DSN")
+    parser.add_argument("--scope", required=True, help="account or tenant scope")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    listing = commands.add_parser("list", help="unresolved operations in this scope")
+    listing.add_argument("--limit", type=int, default=50)
+    listing.add_argument("--json", action="store_true")
+    listing.set_defaults(run=_list)
+
+    show = commands.add_parser("show", help="one operation with its stored request")
+    show.add_argument("operation_id")
+    show.set_defaults(run=_show)
+
+    resolve = commands.add_parser(
+        "resolve", help="settle one operation (trusted operators only)",
+        description="Records a decision you already made by checking the provider. "
+                    "This command performs no external call and verifies nothing "
+                    "about the provider on your behalf.")
+    resolve.add_argument("operation_id")
+    action = resolve.add_mutually_exclusive_group(required=True)
+    action.add_argument("--complete", dest="action", action="store_const", const="complete",
+                        help="the effect is confirmed done; requires --result-json")
+    action.add_argument("--retry", dest="action", action="store_const", const="retry",
+                        help="permit exactly one more attempt")
+    # Deliberately not auto-filled from the store: this version is what makes the
+    # decision refer to the state the operator actually looked at.
+    resolve.add_argument("--expected-version", type=int, required=True,
+                         help="version from `show`, as observed when you decided")
+    resolve.add_argument("--decision-id", required=True,
+                         help="stable ID; replaying it cannot grant a second attempt")
+    resolve.add_argument("--reason", required=True, help="what you checked, and where")
+    resolve.add_argument("--result-json", help="stored result for --complete")
+    resolve.add_argument("--workers-stopped", action="store_true",
+                         help="assert no worker can still be running this operation")
+    resolve.set_defaults(run=_resolve)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "resolve":
+        if args.action == "complete" and args.result_json is None:
+            parser.error("--complete requires --result-json")
+        if args.action == "retry" and args.result_json is not None:
+            parser.error("--retry cannot carry a result")
+    try:
+        return args.run(_executor(args.db, args.scope), args)
+    except (ValueError, LookupError) as exc:
+        print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

effect_ledger/langchain.py

@@ -0,0 +1,191 @@
+"""LangChain effect boundary. Install last among tool middleware; see docs/langchain-boundary.md."""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from contextvars import ContextVar
+from enum import Enum
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain.agents.middleware.types import ToolCallRequest
+from langchain.tools import ToolRuntime
+from langchain_core.messages import ToolMessage
+from langgraph.errors import GraphBubbleUp
+
+from ._graph_boundary import checked_identity, pause
+from .operations import EffectExecutor, Operation, OperationConflict, _json, _text
+
+_CURRENT: ContextVar[Operation | None] = ContextVar('effect_operation', default=None)
+
+
+class ToolPolicy(Enum):
+    READ_ONLY = 'read_only'
+    CONTROL = 'control'
+
+
+READ_ONLY = ToolPolicy.READ_ONLY
+CONTROL = ToolPolicy.CONTROL
+
+
+class UnsupportedToolResult(ValueError):
+    """A durable tool returned a value that cannot be safely replayed."""
+
+
+class _ControlFlow(BaseException):
+    """Carry graph control flow through the framework-free handler error boundary."""
+
+    def __init__(self, signal: GraphBubbleUp):
+        self.signal = signal
+
+
+def current_operation() -> Operation:
+    """Return the task-local protected attempt, or raise LookupError outside a tool."""
+    operation = _CURRENT.get()
+    if operation is None:
+        raise LookupError('No protected effect is executing')
+    return operation
+
+
+class ExecutionBoundary(AgentMiddleware):
+    """Protect every tool by default and commit results before outer processing.
+
+    READ_ONLY and CONTROL tools bypass the ledger. Requires durable checkpoints and
+    serialized threads. Do not combine with durable_tool on the same effect."""
+
+    def __init__(self, executor: EffectExecutor, *,
+                 tools: Mapping[str, str | ToolPolicy] | None = None,
+                 workflow_id: str | None = None,
+                 operation_id: Callable[[ToolRuntime], str] | None = None) -> None:
+        if operation_id is None:
+            _text(workflow_id, 'workflow_id')
+        self.executor = executor
+        self.tool_policies: dict[str, str | ToolPolicy] = {}
+        for name, policy in (tools or {}).items():
+            name = _text(name, 'tool name')
+            if isinstance(policy, str):
+                policy = _text(policy, 'effect')
+            elif policy not in (READ_ONLY, CONTROL):
+                raise ValueError('tool policy must be READ_ONLY, CONTROL, or an effect name')
+            self.tool_policies[name] = policy
+        self.workflow_id = workflow_id
+        self.operation_id = operation_id
+
+    def _policy(self, name: str) -> str | ToolPolicy:
+        return self.tool_policies.get(name, f'langchain.tool:{name}')
+
+    @staticmethod
+    def result(content: str | list, *, artifact: Any = None) -> dict[str, Any]:
+        """Create the result envelope for a trusted operator's complete decision."""
+        return ExecutionBoundary._encode(ToolMessage(
+            content=content, artifact=artifact, tool_call_id='stored'))
+
+    @staticmethod
+    def _encode(message: Any) -> dict[str, Any]:
+        if not isinstance(message, ToolMessage):
+            raise UnsupportedToolResult(
+                'Protected tools must return ToolMessage; mark no-effect control tools CONTROL')
+        if message.status != 'success':
+            raise ValueError('Protected tools must return a successful ToolMessage')
+        data = message.model_dump(mode='python', exclude={'id', 'tool_call_id', 'name'})
+        envelope = {'format': 'langchain-tool-result:v1', 'message': data}
+        try:
+            _json(envelope)  # Reject coercion of non-JSON artifacts.
+        except ValueError as exc:
+            raise UnsupportedToolResult(
+                'Protected tool results and artifacts must contain only JSON values') from exc
+        return envelope
+
+    @staticmethod
+    def _reply(status: dict[str, Any], request: ToolCallRequest, effect: str) -> ToolMessage:
+        if status['state'] != 'completed':
+            if status.get('error') == 'UnsupportedToolResult':
+                status = {**status, 'configuration_hint':
+                    'Mark no-effect Command tools CONTROL; effect results and artifacts must be JSON.'}
+            return pause(status, effect, request.runtime.config)
+        try:
+            envelope = status['result']
+            if envelope['format'] != 'langchain-tool-result:v1':
+                raise ValueError('Unknown result envelope')
+            message = ToolMessage.model_validate({**envelope['message'],
+                'tool_call_id': request.tool_call['id'], 'name': request.tool_call['name'],
+                'id': None})
+            if message.status != 'success':
+                raise ValueError('Completion cannot contain an error ToolMessage')
+            return message
+        except Exception as exc:
+            invalid = {**status, 'state': 'result_error', 'unresolved': True,
+                       'error': type(exc).__name__}
+        return pause(invalid, effect, request.runtime.config)
+
+    def _failure(self, operation_id: str, effect: str, tool_name: str,
+                 exc: Exception) -> dict[str, Any]:
+        status = {'operation_id': operation_id, 'state': 'transport_error',
+                  'unresolved': True, 'error': type(exc).__name__, 'version': None}
+        if isinstance(exc, OperationConflict):
+            try:
+                existing = self.executor.get(operation_id)
+            except Exception:
+                existing = None
+            if existing is not None and existing.effect != effect:
+                identity = "workflow_id" if self.operation_id is None else "operation_id"
+                status['configuration_hint'] = (
+                    f"Operation is bound to {existing.effect!r}, but {tool_name!r} resolved "
+                    f"to {effect!r}. Configure tools={{{tool_name!r}: "
+                    f"{existing.effect!r}}} to preserve the effect name and replay the "
+                    f"recorded outcome. A new {identity} dispatches this effect again even "
+                    f"though the bound operation is already {existing.state}; choose it only "
+                    f"to perform a deliberately new action.")
+        return status
+
+    def wrap_tool_call(self, request: ToolCallRequest, handler: Callable) -> Any:
+        effect = self._policy(request.tool_call['name'])
+        if effect in (READ_ONLY, CONTROL):
+            return handler(request)
+        assert isinstance(effect, str)
+        identity = checked_identity(request.runtime, self.workflow_id, self.operation_id, effect)
+
+        def execute(owned: Operation):
+            token = _CURRENT.set(owned)
+            try:
+                frozen = request.override(tool_call={**request.tool_call, 'args': owned.request})
+                return self._encode(handler(frozen))
+            except GraphBubbleUp as signal:
+                raise _ControlFlow(signal) from signal
+            finally:
+                _CURRENT.reset(token)
+
+        try:
+            status = self.executor.execute(identity, effect, request.tool_call['args'], execute).response()
+        except _ControlFlow as flow:
+            # _ControlFlow only carried this signal out; it did not cause it.
+            raise flow.signal from None
+        except Exception as exc:
+            status = self._failure(identity, effect, request.tool_call['name'], exc)
+        return self._reply(status, request, effect)
+
+    async def awrap_tool_call(self, request: ToolCallRequest, handler: Callable) -> Any:
+        effect = self._policy(request.tool_call['name'])
+        if effect in (READ_ONLY, CONTROL):
+            return await handler(request)
+        assert isinstance(effect, str)
+        identity = checked_identity(request.runtime, self.workflow_id, self.operation_id, effect)
+
+        async def execute(owned: Operation):
+            token = _CURRENT.set(owned)
+            try:
+                frozen = request.override(tool_call={**request.tool_call, 'args': owned.request})
+                return self._encode(await handler(frozen))
+            except GraphBubbleUp as signal:
+                raise _ControlFlow(signal) from signal
+            finally:
+                _CURRENT.reset(token)
+
+        try:
+            status = (await self.executor.aexecute(
+                identity, effect, request.tool_call['args'], execute)).response()
+        except _ControlFlow as flow:
+            # _ControlFlow only carried this signal out; it did not cause it.
+            raise flow.signal from None
+        except Exception as exc:
+            status = self._failure(identity, effect, request.tool_call['name'], exc)
+        return self._reply(status, request, effect)