attestlayer 0.1.0__py3-none-any.whl

attest/README.md

@@ -0,0 +1,230 @@
+# attest (Python SDK)
+
+Decide → Gate → Verify → Attest, for any function that makes an agent act.
+
+```bash
+pip install -e ".[dev]"      # from the repo root
+pytest -q
+ATTEST_AUTO_APPROVE=1 python examples/unknown_app.py
+```
+
+## Quickstart
+
+```python
+import attest
+
+@attest.action(system="gmail", verb="send", target="to")
+def send_email(to, subject, body):
+    return gmail.users().messages().send(userId="me", body=...).execute()
+
+send_email("arun@newco.com", "Follow-up", "…")
+```
+
+What happens on that call:
+
+1. **Decide** — the call becomes an Action Descriptor (`gmail.send` → `arun@newco.com`). Built-in rules
+   classify the recipient as external and the default policy says `ask`.
+2. **Gate** — the console prompts `y / n / e`. `ATTEST_AUTO_APPROVE=1` approves in CI; a non-interactive
+   stdin rejects. Slack and web inbox arrive in P1.3.
+3. **Execute** — your function runs. Attest never calls the vendor to write.
+4. **Verify** — the response carried an id ⇒ `acknowledged` (L1). Pass `verify=` for your own check (L2).
+   Read-back recipes (L3) arrive in P1.2.
+5. **Attest** — one hash-chained row in `.attest/ledger.sqlite` (or `$ATTEST_LEDGER`), with params and result
+   stored as hashes plus an allow-listed preview.
+
+Nothing about how you built the agent changed.
+
+## Detection without labels
+
+```python
+@attest.action                                                   # send_email ⇒ unknown / send
+def send_email(to, body): ...
+
+@attest.action(method="POST", url="https://api.someweirdcrm.io/v2/leads")   # ⇒ someweirdcrm / create
+def create_lead(name, email): ...
+
+@attest.action(tool_name="hubspot_update_deal")                  # ⇒ hubspot / update
+def update_deal(deal_id, **props): ...
+
+attest.register("acme_internal_tool", system="acme", verb="pay") # your own override
+```
+
+## Policy (YAML)
+
+`$ATTEST_POLICY` or `./attest.yaml`; first match wins; built-in rules R0–R4 run first.
+
+```yaml
+policies:
+  - match: { verb: [send, share], target: external }
+    decision: ask
+  - match: { verb: [delete, pay] }
+    decision: ask
+    approvers: [finance-leads]
+  - match: { system: hubspot, verb: update }
+    decision: act
+  - match: { target_domain: [competitor.com] }
+    decision: refuse
+```
+
+Match keys: `system`, `verb`, `target` (internal | known | external | none), `target_domain`, `actor`, `agent`,
+`risk`, `action` (`gmail.send`, globs allowed). Decisions: `act`, `ask`, `refuse`.
+
+## Read-back (L3) with your own credentials
+
+Give Attest the client or token the agent already holds; it reads the system of record in-process and
+compares intent with what is there. Nothing leaves your process.
+
+```python
+at = Attest(readers={"gmail": gmail_service,          # googleapiclient resource, or an OAuth token string
+                     "slack": slack_web_client,       # slack_sdk WebClient, or an xoxb token
+                     "hubspot": hubspot_client},      # hubspot Client, or a private-app token
+            http_get=lambda url, params=None: session.get(url, params=params).json())   # any REST API
+```
+
+| system | write | read-back | compares |
+| --- | --- | --- | --- |
+| gmail | send / reply | `messages.get` | SENT label, every intended recipient in To/Cc, subject, reply thread |
+| gmail | create draft | `drafts.get` | exists, recipients, subject |
+| gmail | update labels | `messages.get` | added ⊂ labels, removed ∩ labels = ∅ |
+| slack | send | `conversations.history` (or `.replies`) | ts, text, thread_ts |
+| slack | create channel | `conversations.info` | exists, name, is_private |
+| hubspot | create / update any object | `GET crm/v3/objects/{type}/{id}` | id, every intended property |
+| calendar | create / update event | `events.get` | confirmed, summary, start / end, attendees |
+| drive | create / upload / update file | `files.get` | name, mimeType, parents, not trashed |
+| drive | share | `permissions.list` | every intended email present, role |
+| docs | create / append | `documents.get` | title, appended text present |
+| sheets | create / write values | `spreadsheets.get` / `values.get` | title, every written row present |
+| notion | create / update page | `pages.retrieve` | title, status, select, text, number… properties, parent |
+| notion | create database | `databases.retrieve` | exists, title |
+| linear | create / update issue, project, comment | GraphQL `issue` / `project` / `comment` | title, priority, state, assignee, team, body |
+| outlook | send / reply | sent-items search | found, every recipient, subject |
+| outlook | create / update event | `me/events/{id}` | subject, start / end, attendees, not cancelled |
+| teams | send | channel / chat message | text |
+| *anything REST* | create / update | convention: `GET <url>/<returned id>` | id, every intended field the record carries |
+| *anything with an OpenAPI spec* | create / update | `OpenApiDriver(spec, http_get)` — spec-derived GET path, nested collections, never guesses | id, every intended field |
+
+Per action: `@at.action(..., reader=gmail_service)` or `http_get=…`. A read-back that finds the record but
+nothing to compare is `acknowledged` with `exists: true`, not `verified`.
+
+## LangGraph / LangChain
+
+```python
+from attest.adapters import langgraph as attest_lg
+
+mapping = {"send_email": {"system": "gmail", "verb": "send", "target": "to"},
+           "update_deal": {"system": "hubspot", "verb": "update", "target": "deal_id"}}
+tools = attest_lg.wrap_tools([send_email, update_deal], at, mapping=mapping)   # before building the graph
+attest_lg.wrap(graph, at, mapping=mapping)                                     # or patch an existing graph's ToolNode
+create_agent(model, tools, middleware=[attest_lg.AttestMiddleware(at, mapping=mapping)])   # langchain ≥ 1
+```
+
+Refusals and rejections come back to the model as an error ToolMessage; the ledger records them either way.
+Unmapped tools are inferred from their name. `pip install "attestlayer[langgraph]"`.
+
+## Gate modes: Slack, web inbox, webhook, LangGraph interrupt, MCP pending
+
+One contract, several ways to pause (doc 03 §6):
+
+```python
+from attest import Attest, StoreGate, PendingStore
+from attest.gate.slack import SlackNotifier
+from attest.gate.webhook import WebhookNotifier
+
+store = PendingStore(".attest/ledger.sqlite")
+at = Attest(gate=StoreGate(store, wait=True, timeout_s=900, notifiers=[
+    SlackNotifier("xoxb-…", "#agent-approvals", inbox_url="http://localhost:8321"),   # card with Approve / Reject
+    WebhookNotifier("https://your.app/attest", secret="…", confirm_url="http://localhost:8321"),
+]))
+```
+
+| mode | gate | what happens on `ask` |
+| --- | --- | --- |
+| sync-block | `ConsoleGate()` | terminal prompt `y / n / e` |
+| sync-block | `StoreGate(wait=True, notifiers=…)` | request persisted, Slack card / webhook / inbox notified, call blocks until a human decides (or `timeout_s` ⇒ expired ⇒ rejected) |
+| pending | `StoreGate(wait=False)` | raises `ActionPending(resume_token)`; later `fn.resume(token)` / `at.resume(token)` executes once approved |
+| async-interrupt | `InterruptGate()` | LangGraph `interrupt()` with the request as payload; `Command(resume={"status": "approved"})` continues |
+
+Decisions can come from anywhere that reaches the store: the Slack buttons (`POST /slack/interact` on the inbox
+server, signature-verified), the web inbox, `POST /confirm/{id}`, or `attest confirm <id> approve --edits '{…}'`.
+Every decision records the approver's identity and channel in the ledger. Edits at confirm time change what
+runs. Cross-process resume passes `execute=`; the same process remembers it.
+
+### Web inbox + API
+
+```bash
+attest serve --port 8321      # http://127.0.0.1:8321 — approve / reject / edit pending requests
+```
+
+`GET /api/pending` · `GET /api/requests/{id}` · `POST /confirm/{id}` `{"status","approver","edits","note"}` ·
+`GET /api/ledger` · `GET /api/ledger/verify` · `POST /slack/interact`. Set `ATTEST_SERVER_TOKEN` to require a
+bearer token.
+
+### CLI
+
+```bash
+attest ledger [--limit 20] [--run RUN] [--json]     attest verify        attest export --format csv
+attest pending                                      attest confirm <id|token> approve|reject [--edits '{…}']
+```
+
+## MCP proxy (zero code)
+
+```json
+{ "mcpServers": { "gmail": { "command": "attest-mcp",
+    "args": ["--upstream", "npx -y @modelcontextprotocol/server-gmail", "--server", "gmail", "--mode", "block"] } } }
+```
+
+Every `tools/call` is normalized by tool name, decided, gated, forwarded, verified and recorded; `tools/list`
+gains `attest_resume`. Read-back uses MCP tool pairs (`create_issue` ⇒ `get_issue`) and compares fields.
+`--mode block` waits for a decision in the inbox / Slack (`--timeout`); `--mode pending` returns
+`{"status": "pending_confirmation", "resume_token"}` and the agent calls `attest_resume` after approval;
+`--mode auto` approves everything (dev). Slack / webhook via `--slack-token --slack-channel` / `--webhook`.
+
+## OpenAI Agents SDK
+
+```python
+from attest.adapters import openai_agents as attest_oa
+tools = attest_oa.wrap_tools([send_email, update_deal], at, mapping=mapping)
+agent = Agent(name="followup", tools=tools)
+```
+
+Same behaviour as LangGraph: refusals / rejections return as tool errors; with a pending gate the tool returns a
+resume token and `await attest_oa.resume(at, token)` executes after approval. `pip install "attestlayer[openai]"`.
+
+## Verification levels
+
+| level | meaning |
+| --- | --- |
+| `verified` | read-back matched: a reviewed recipe or the REST convention driver compared intent with the record |
+| `verified-custom` | your `verify=` returned true |
+| `acknowledged` | response carried an id / success — the API said yes, nothing was read back |
+| `attested-only` | recorded; nothing checkable |
+| `unverified` | a check ran and **contradicted** the claimed result |
+
+A check that could not run (exception, missing id) degrades to `acknowledged` / `attested-only` with the
+error in evidence. Only a contradiction is `unverified`.
+
+## Ledger
+
+```python
+from attest import SqliteLedger
+L = SqliteLedger(".attest/ledger.sqlite")
+L.entries(run_id="…")      # LedgerEntry objects
+L.verify_chain()           # ChainReport(ok, checked, broken_at)
+L.export("json") / L.export("csv")
+```
+
+## API-only (entry point 5)
+
+```python
+attest.attest(system="n8n", verb="send", target="x@ext.com", result={"id": "m1"})            # ⇒ acknowledged
+attest.attest(system="n8n", verb="send", verified=True, evidence={"message_id": "m1"})       # ⇒ verified-custom
+```
+
+## Environment
+
+| var | effect |
+| --- | --- |
+| `ATTEST_LEDGER` | ledger path (default `.attest/ledger.sqlite`) |
+| `ATTEST_POLICY` | policy YAML path |
+| `ATTEST_AUTO_APPROVE` | `1` approve all, `0` reject all (skips the console gate) |
+| `ATTEST_AGENT`, `ATTEST_ACTOR` | defaults for the descriptor |

attest/__init__.py

@@ -0,0 +1,61 @@
+"""Attest — proof layer for AI agents. Decide → Gate → Verify → Attest.
+
+    import attest
+
+    @attest.action(system="gmail", verb="send", target="to")
+    def send_email(to, subject, body): ...
+
+Module-level `action`, `attest`, `run` use a lazily created default client (ledger at
+`.attest/ledger.sqlite` or `$ATTEST_LEDGER`, policy from `$ATTEST_POLICY` / `./attest.yaml`, console gate).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from attest.core import ActionReceipt, Attest
+from attest.descriptor import ActionDescriptor
+from attest.exceptions import ActionPending, ActionRefused, ActionRejected, AttestError
+from attest.gate import AutoGate, ConfirmDecision, ConfirmRequest, StoreGate
+from attest.gate.console import ConsoleGate
+from attest.gate.store import PendingStore
+from attest.ledger import LedgerEntry, SqliteLedger
+from attest.policy import PolicyContext, PolicyEngine, PolicyResult
+from attest.registry import Detection, detect, register
+from attest.verify import Level, ReadBackDriver
+
+__version__ = "0.1.0"
+_default: Attest | None = None
+
+
+def default() -> Attest:
+    global _default
+    if _default is None:
+        _default = Attest()
+    return _default
+
+
+def configure(**kw: Any) -> Attest:
+    """Replace the default client (e.g. `attest.configure(agent="x", gate=AutoGate())`)."""
+    global _default
+    _default = Attest(**kw)
+    return _default
+
+
+def action(fn=None, **kw):
+    return default().action(fn, **kw)
+
+
+def attest(**kw):  # noqa: A001 - module-level verb by design
+    return default().attest(**kw)
+
+
+def run(run_id: str | None = None, **kw):
+    return default().run(run_id, **kw)
+
+
+__all__ = ["Attest", "ActionReceipt", "ActionDescriptor", "ActionRefused", "ActionRejected", "ActionPending",
+           "AttestError", "AutoGate", "ConsoleGate", "StoreGate", "PendingStore", "ConfirmDecision", "ConfirmRequest",
+           "LedgerEntry", "SqliteLedger",
+           "PolicyContext", "PolicyEngine", "PolicyResult", "Detection", "detect", "register", "Level",
+           "ReadBackDriver",
+           "action", "attest", "run", "default", "configure", "__version__"]

attest/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Framework adapters (doc 03 §2, entry point 2). Each wraps every tool of a framework with Attest so
+one line covers the whole agent. Import the framework you use: `from attest.adapters import langgraph`."""

attest/adapters/claude_agent_sdk.py

@@ -0,0 +1,131 @@
+"""Claude Agent SDK adapter — Attest as PreToolUse / PostToolUse hooks.
+
+    from claude_agent_sdk import ClaudeAgentOptions, HookMatcher
+    from attest.adapters import claude_agent_sdk as attest_cl
+
+    mapping = {"mcp__gmail__send_message": {"system": "gmail", "verb": "send", "target": "to"}}
+    pre, post = attest_cl.hooks(at, mapping=mapping)
+    options = ClaudeAgentOptions(hooks={"PreToolUse": [HookMatcher(hooks=[pre])],
+                                        "PostToolUse": [HookMatcher(hooks=[post])]})
+
+PreToolUse decides + gates: refuse / rejected ⇒ `permissionDecision: "deny"` with the reason; approved ⇒ "allow"
+(with `updatedInput` when the human edited params). PostToolUse verifies the tool response and writes the
+ledger row. The pending row is written at PreToolUse so a denied or crashed call still leaves a record.
+Hook inputs are plain dicts (`tool_name`, `tool_input`, `tool_response`, `session_id`, `tool_use_id`), so the
+adapter has no import of the SDK and can be driven by tests.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from attest.adapters.langgraph import Mapping, descriptor_for
+from attest.core import Attest, entry_decision
+from attest.descriptor import ActionDescriptor, short_hash
+from attest.exceptions import ActionPending, ActionRefused, ActionRejected
+from attest.ledger import ConfirmRecord, ExecutionRecord, LedgerEntry
+from attest.ledger.models import VerificationRecord, preview
+from attest.verify import verify
+
+
+class _Parked:
+    def __init__(self, d: ActionDescriptor, entry: LedgerEntry, spec: dict[str, Any]):
+        self.d, self.entry, self.spec = d, entry, spec
+
+
+def hooks(client: Attest | None = None, *, mapping: Mapping | None = None, server: str | None = None
+          ) -> tuple[Callable[..., Any], Callable[..., Any]]:
+    """→ (pre_tool_use, post_tool_use) async hook callables with the SDK's `(input, tool_use_id, context)` shape."""
+    at = client or __import__("attest").default()
+    parked: dict[str, _Parked] = {}
+
+    async def pre_tool_use(input_data: dict[str, Any], tool_use_id: str | None = None,
+                           context: Any = None) -> dict[str, Any]:
+        name = str(input_data.get("tool_name") or "")
+        args = dict(input_data.get("tool_input") or {})
+        srv = server or (name.split("__")[1] if name.startswith("mcp__") and name.count("__") >= 2 else None)
+        d, recognised, spec = descriptor_for(at, name, args, mapping, server=srv)
+        d.extra["framework"] = "claude-agent-sdk"
+        d.run_id = d.run_id or input_data.get("session_id")
+        pol = at.policy.evaluate(d, recognised=recognised)
+        d.target_class = pol.target_class  # type: ignore[assignment]
+        entry = at._entry(d, pol)
+        key = tool_use_id or d.id
+        if pol.decision == "refuse":
+            at.ledger.append(entry)
+            return _deny(f"attest refused: {'; '.join(pol.reasons)}")
+        updated: dict[str, Any] | None = None
+        if pol.decision == "ask":
+            request = at._request(d, pol)
+            decision = at.gate.confirm(request)
+            if decision.pending:
+                try:
+                    at._park(d, entry, request, decision, lambda p: None, spec.get("verify"), spec.get("readers"),
+                             spec.get("http_get"))
+                except ActionPending as e:
+                    return _deny(f"attest: pending human confirmation (resume_token={e.resume_token}); retry later")
+            try:
+                d, entry = at._after_confirm(d, entry, decision)
+            except ActionRejected as e:
+                return _deny("attest: a human rejected this action" + (f" ({e.note})" if e.note else ""))
+            if decision.edits:
+                updated = {**args, **{k: v for k, v in d.params.items() if k in args}}
+        parked[key] = _Parked(d, entry, spec)
+        reason = "attest: " + ("; ".join(pol.reasons) or pol.decision)
+        out: dict[str, Any] = {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow",
+                                                      "permissionDecisionReason": reason}}
+        if updated is not None:
+            out["hookSpecificOutput"]["updatedInput"] = updated
+        return out
+
+    async def post_tool_use(input_data: dict[str, Any], tool_use_id: str | None = None,
+                            context: Any = None) -> dict[str, Any]:
+        name = str(input_data.get("tool_name") or "")
+        key = tool_use_id or ""
+        parked_item = parked.pop(key, None)
+        if parked_item is None:  # PostToolUse without our PreToolUse (hook not matched) — record what we can
+            args = dict(input_data.get("tool_input") or {})
+            d, recognised, spec = descriptor_for(at, name, args, mapping, server=server)
+            pol = at.policy.evaluate(d, recognised=recognised)
+            entry = at._entry(d, pol)
+            entry.confirm = ConfirmRecord(status="not_required")
+        else:
+            d, entry, spec = parked_item.d, parked_item.entry, parked_item.spec
+        response = input_data.get("tool_response")
+        result = _unwrap(response)
+        failed = isinstance(response, dict) and (response.get("is_error") or response.get("isError"))
+        entry.execution = ExecutionRecord(status="failed" if failed else "done",
+                                          result_hash=None if result is None else short_hash(result),
+                                          result_preview=preview(result), error=str(result)[:400] if failed else None)
+        if failed:
+            entry.verification = VerificationRecord(level="attested-only", method="none",
+                                                    evidence={"detail": "tool error"})
+        else:
+            entry.verification = verify(d.with_result(result), result, custom=spec.get("verify"),
+                                        drivers=at._drivers(spec.get("readers"), spec.get("http_get")))
+        at.ledger.append(entry)
+        return {}
+
+    return pre_tool_use, post_tool_use
+
+
+def _deny(reason: str) -> dict[str, Any]:
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny",
+                                   "permissionDecisionReason": reason}}
+
+
+def _unwrap(response: Any) -> Any:
+    """Tool responses arrive as MCP-style content lists or plain values; pull out something the ladder can judge."""
+    if isinstance(response, dict) and isinstance(response.get("content"), list):
+        import json
+        texts = [c.get("text", "") for c in response["content"] if isinstance(c, dict) and c.get("type") == "text"]
+        joined = "\n".join(texts).strip()
+        try:
+            return json.loads(joined) if joined else response
+        except json.JSONDecodeError:
+            return joined or response
+    return response
+
+
+__all__ = ["hooks"]
+_ = (ActionRefused, entry_decision)

attest/adapters/crewai.py

@@ -0,0 +1,100 @@
+"""CrewAI adapter — wraps `crewai.tools.BaseTool` instances (or anything with `name`, `description`, `_run`).
+
+    from attest.adapters import crewai as attest_crew
+    tools = attest_crew.wrap_tools([send_email_tool, update_deal_tool], at, mapping={...})
+    agent = Agent(role="…", tools=tools)
+
+Returns a subclass instance of the original tool whose `_run` (and `_arun` when present) goes through
+decide → gate → execute → verify → attest. Refusals / rejections return an error string to the agent.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from attest.adapters.langgraph import Mapping, _error_text, _only_known, descriptor_for
+from attest.core import Attest
+from attest.exceptions import ActionPending, ActionRefused, ActionRejected
+
+
+def wrap_tool(tool: Any, client: Attest | None = None, *, mapping: Mapping | None = None,
+              raise_on_block: bool = False) -> Any:
+    at = client or __import__("attest").default()
+    name = getattr(tool, "name", type(tool).__name__)
+    spec = dict((mapping or {}).get(name) or {})
+    orig_run = tool._run
+    orig_arun = getattr(tool, "_arun", None)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        params, by_name = _params(orig_run, args, kwargs)
+        d, recognised, sp = descriptor_for(at, name, params, mapping)
+        d.extra["framework"] = "crewai"
+        call = (lambda p: orig_run(**{**params, **_only_known(params, p)})) if by_name else \
+            (lambda p: orig_run(*args, **{**kwargs, **_only_known(kwargs, p)}))
+        try:
+            receipt = at.run_action(d, call, recognised=recognised, verify_fn=sp.get("verify"),
+                                    readers=sp.get("readers"), http_get=sp.get("http_get"))
+        except ActionPending as e:
+            if raise_on_block:
+                raise
+            return f"attest: pending human confirmation (resume_token={e.resume_token})"
+        except (ActionRefused, ActionRejected) as e:
+            if raise_on_block:
+                raise
+            return _error_text(e)
+        return receipt.result
+
+    async def _arun(self, *args: Any, **kwargs: Any) -> Any:
+        target = orig_arun or orig_run
+        params, by_name = _params(target, args, kwargs)
+        d, recognised, sp = descriptor_for(at, name, params, mapping)
+        d.extra["framework"] = "crewai"
+        call = (lambda p: target(**{**params, **_only_known(params, p)})) if by_name else \
+            (lambda p: target(*args, **{**kwargs, **_only_known(kwargs, p)}))
+        try:
+            receipt = await at.arun_action(d, call, recognised=recognised, verify_fn=sp.get("verify"),
+                                           readers=sp.get("readers"), http_get=sp.get("http_get"))
+        except ActionPending as e:
+            if raise_on_block:
+                raise
+            return f"attest: pending human confirmation (resume_token={e.resume_token})"
+        except (ActionRefused, ActionRejected) as e:
+            if raise_on_block:
+                raise
+            return _error_text(e)
+        return receipt.result
+
+    cls = type(tool)
+    wrapped_cls = type(f"Attested{cls.__name__}", (cls,), {"_run": _run, "_arun": _arun, "_attest_wrapped": True})
+    try:  # pydantic models (crewai BaseTool) — copy fields
+        wrapped = wrapped_cls.model_validate(tool.model_dump()) if hasattr(tool, "model_dump") else None
+    except Exception:
+        wrapped = None
+    if wrapped is None:
+        import copy
+        wrapped = copy.copy(tool)
+        wrapped.__class__ = wrapped_cls
+    _ = spec
+    return wrapped
+
+
+def _params(fn: Any, args: tuple, kwargs: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+    """→ (params, by_name): positional args mapped onto the function's parameter names when possible."""
+    if not args:
+        return dict(kwargs), True
+    import inspect
+    try:
+        names = [p for p in inspect.signature(fn).parameters if p not in ("self", "args", "kwargs")]
+    except (TypeError, ValueError):
+        names = []
+    by_name = len(names) >= len(args)
+    out = {names[i] if i < len(names) else f"arg{i}": a for i, a in enumerate(args)}
+    out.update(kwargs)
+    return out, by_name
+
+
+def wrap_tools(tools: list[Any], client: Attest | None = None, *, mapping: Mapping | None = None,
+               raise_on_block: bool = False) -> list[Any]:
+    return [wrap_tool(t, client, mapping=mapping, raise_on_block=raise_on_block) for t in tools]
+
+
+__all__ = ["wrap_tool", "wrap_tools"]

attest/adapters/deerflow.py

@@ -0,0 +1,15 @@
+"""DeerFlow adapter. DeerFlow agents are LangChain (≥1) agents with a middleware chain; Attest plugs in as a
+middleware — placed **outermost**, per DeerFlow's own ordering rule for ToolReceiptMiddleware, so nothing
+downstream can short-circuit the record.
+
+    from attest.adapters.deerflow import AttestMiddleware
+    middlewares = [AttestMiddleware(at, mapping=…), *deerflow_middlewares]
+
+DeerFlow's tool receipts (args/output hashes cited by the model) and Attest's ledger complement each other:
+receipts prove a call happened inside the run; Attest proves the world changed and who approved it.
+"""
+from __future__ import annotations
+
+from attest.adapters.langgraph import AttestMiddleware, wrap_tool, wrap_tools
+
+__all__ = ["AttestMiddleware", "wrap_tool", "wrap_tools"]