agent-custody 0.1.2__py3-none-any.whl

agent_custody/__init__.py

@@ -0,0 +1,95 @@
+"""Receipts for tool calls, from Python.
+
+The signing key, the policy, and the log live in the agent-custody sidecar, `agent-custody serve --config sdk.json`,
+a local process. This client talks to it over HTTP with nothing but the standard library. Everything recorded is
+claimed, exactly as with the in-process TypeScript SDK: the sidecar trusts what this process reports.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+__all__ = ["Client", "PolicyDeniedError", "SidecarError", "receipt_id_of"]
+
+DEFAULT_URL = "http://127.0.0.1:8788/"
+
+
+class SidecarError(RuntimeError):
+    """The sidecar refused or could not complete a request. No receipt was written."""
+
+
+class PolicyDeniedError(PermissionError):
+    def __init__(self, tool: str, reason: str, receipt_id: str):
+        super().__init__(f"Denied by policy: {reason} (receipt {receipt_id})")
+        self.tool = tool
+        self.reason = reason
+        self.receipt_id = receipt_id
+
+
+def receipt_id_of(bundle: Dict[str, Any]) -> str:
+    payload = json.loads(base64.b64decode(bundle["envelope"]["payload"]))
+    return payload["predicate"]["receiptId"]
+
+
+def _event(tool: str, args: Optional[Dict[str, Any]], model: Optional[str], session: Optional[Dict[str, Optional[str]]]) -> Dict[str, Any]:
+    ev: Dict[str, Any] = {"tool": tool, "args": args or {}}
+    if model is not None:
+        ev["model"] = model
+    if session is not None:
+        ev["session"] = session
+    return ev
+
+
+class Client:
+    def __init__(self, url: str = DEFAULT_URL, timeout: float = 10.0):
+        self.url = url if url.endswith("/") else url + "/"
+        self.timeout = timeout
+
+    def _post(self, path: str, body: Any) -> Any:
+        req = urllib.request.Request(self.url + path, data=json.dumps(body).encode(), headers={"content-type": "application/json"}, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return json.loads(res.read())
+        except urllib.error.HTTPError as e:
+            try:
+                detail = json.loads(e.read()).get("error", "")
+            except Exception:
+                detail = ""
+            raise SidecarError(f"sidecar {path}: {e.code} {detail}".strip()) from None
+        except urllib.error.URLError as e:
+            raise SidecarError(f"sidecar unreachable at {self.url}: {e.reason}") from None
+
+    def health(self) -> Dict[str, Any]:
+        with urllib.request.urlopen(self.url + "health", timeout=self.timeout) as res:
+            return json.loads(res.read())
+
+    def decide(self, tool: str, args: Optional[Dict[str, Any]] = None, *, model: Optional[str] = None, session: Optional[Dict[str, Optional[str]]] = None) -> Optional[Dict[str, Any]]:
+        """The configured policy's decision for this call, or None when the sidecar has no policy."""
+        return self._post("decide", _event(tool, args, model, session))
+
+    def record(self, tool: str, args: Optional[Dict[str, Any]], outcome: Dict[str, Any], policy: Optional[Dict[str, Any]] = None, *, model: Optional[str] = None, session: Optional[Dict[str, Optional[str]]] = None) -> Dict[str, Any]:
+        """Issues one receipt. `outcome` is {"status": "executed"|"failed", "result": ...}, {"status": "denied", "reason": ...}, or {"status": "error", "error": ...}."""
+        return self._post("record", {"event": _event(tool, args, model, session), "outcome": outcome, "policy": policy})
+
+    def wrap(self, tool: str, fn: Callable[[Dict[str, Any]], Any], *, model: Optional[str] = None) -> Callable[[Dict[str, Any]], Any]:
+        """decide, run, record. Raises PolicyDeniedError on deny, after recording the denial."""
+
+        def wrapped(args: Dict[str, Any]) -> Any:
+            policy = self.decide(tool, args, model=model)
+            if policy and policy["decision"] == "deny":
+                reason = "; ".join(policy["reasons"] + policy["errors"]) or "no permit policy matched"
+                bundle = self.record(tool, args, {"status": "denied", "reason": reason}, policy, model=model)
+                raise PolicyDeniedError(tool, reason, receipt_id_of(bundle))
+            try:
+                result = fn(args)
+            except Exception as e:
+                self.record(tool, args, {"status": "error", "error": str(e)}, policy, model=model)
+                raise
+            self.record(tool, args, {"status": "executed", "result": result}, policy, model=model)
+            return result
+
+        wrapped.__name__ = getattr(fn, "__name__", tool)
+        return wrapped

agent_custody/claude_agent_sdk.py

@@ -0,0 +1,47 @@
+"""Claude Agent SDK (Python) hooks. Same contract as the TypeScript adapter and the Claude Code command hook.
+
+PreToolUse: evaluate policy; on deny, record a denial receipt and block. On allow or no policy return no decision,
+so the host's own permission flow still applies. This never auto-approves. PostToolUse / PostToolUseFailure record.
+
+    from claude_agent_sdk import HookMatcher
+    hooks = {event: [HookMatcher(hooks=[claude_hook(client)])] for event in ("PreToolUse", "PostToolUse", "PostToolUseFailure")}
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from . import Client, receipt_id_of
+
+
+def _event(input_data: Dict[str, Any]) -> Dict[str, Any]:
+    raw = input_data.get("tool_input")
+    args = raw if isinstance(raw, dict) else {"input": raw}
+    return {"tool": input_data["tool_name"], "args": args, "session": {"id": input_data.get("session_id"), "toolUseId": input_data.get("tool_use_id")}}
+
+
+def handle_hook_event(client: Client, input_data: Dict[str, Any]) -> Dict[str, Any]:
+    ev = _event(input_data)
+    name = input_data.get("hook_event_name")
+    if name == "PreToolUse":
+        policy = client.decide(ev["tool"], ev["args"], session=ev["session"])
+        if policy and policy["decision"] == "deny":
+            reason = "; ".join(policy["reasons"] + policy["errors"]) or "no permit policy matched"
+            bundle = client.record(ev["tool"], ev["args"], {"status": "denied", "reason": reason}, policy, session=ev["session"])
+            return {"continue": True, "hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": f"agent-custody: {reason} (receipt {receipt_id_of(bundle)})"}}
+        return {}
+    if name == "PostToolUse":
+        client.record(ev["tool"], ev["args"], {"status": "executed", "result": input_data.get("tool_response")}, client.decide(ev["tool"], ev["args"]), session=ev["session"])
+        return {}
+    if name == "PostToolUseFailure":
+        client.record(ev["tool"], ev["args"], {"status": "failed", "result": input_data.get("error", input_data.get("tool_response"))}, client.decide(ev["tool"], ev["args"]), session=ev["session"])
+        return {}
+    return {}
+
+
+def claude_hook(client: Client) -> Callable[[Dict[str, Any], Optional[str], Any], Any]:
+    """A hook callable in the shape the Claude Agent SDK expects: (input_data, tool_use_id, context) -> dict."""
+
+    async def hook(input_data: Dict[str, Any], tool_use_id: Optional[str], context: Any) -> Dict[str, Any]:
+        return handle_hook_event(client, input_data)
+
+    return hook

agent_custody/langchain.py

@@ -0,0 +1,61 @@
+"""LangChain / LangGraph adapter: a callback handler that records a receipt for every tool run it sees.
+
+Observe-only. Callbacks cannot block a tool, so this evaluates no policy. For enforcement wrap the function before
+turning it into a tool: `tool(client.wrap("name", fn))`. Do not combine both on one tool, or it is recorded twice.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from . import Client
+
+
+def _parse_args(input_str: str, inputs: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    if isinstance(inputs, dict):
+        return inputs
+    try:
+        v = json.loads(input_str)
+        return v if isinstance(v, dict) else {"input": v}
+    except (TypeError, ValueError):
+        return {"input": input_str}
+
+
+def _unwrap(output: Any) -> Any:
+    content = getattr(output, "content", None) if hasattr(output, "tool_call_id") else None
+    if content is None:
+        return output
+    if isinstance(content, str):
+        try:
+            return json.loads(content)
+        except ValueError:
+            return content
+    return content
+
+
+class ReceiptCallbackHandler(BaseCallbackHandler):
+    name = "agent-custody"
+
+    def __init__(self, client: Client):
+        super().__init__()
+        self.client = client
+        self._pending: Dict[UUID, Dict[str, Any]] = {}
+
+    def on_tool_start(self, serialized: Dict[str, Any], input_str: str, *, run_id: UUID, parent_run_id: Optional[UUID] = None, tags=None, metadata=None, inputs: Optional[Dict[str, Any]] = None, **kwargs: Any) -> None:
+        name = kwargs.get("name") or (serialized or {}).get("name") or "unknown"
+        self._pending[run_id] = {"tool": name, "args": _parse_args(input_str, inputs), "session": {"id": None, "toolUseId": kwargs.get("tool_call_id")}}
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        ev = self._pending.pop(run_id, None)
+        if ev is None:
+            return
+        self.client.record(ev["tool"], ev["args"], {"status": "executed", "result": _unwrap(output)}, None, session=ev["session"])
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        ev = self._pending.pop(run_id, None)
+        if ev is None:
+            return
+        self.client.record(ev["tool"], ev["args"], {"status": "error", "error": str(error)}, None, session=ev["session"])

agent_custody/openai_agents.py

@@ -0,0 +1,54 @@
+"""OpenAI Agents SDK (Python) adapter: wraps each FunctionTool's on_invoke_tool. Decides, runs, records.
+
+A denied call never runs; the model receives the denial text as the tool result and the run continues.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any, Dict, List
+
+from agents import FunctionTool
+
+from . import Client, receipt_id_of
+
+
+def _parse(input_json: str) -> Dict[str, Any]:
+    try:
+        v = json.loads(input_json) if input_json else {}
+        return v if isinstance(v, dict) else {"input": v}
+    except ValueError:
+        return {"input": input_json}
+
+
+def _result(v: Any) -> Any:
+    if not isinstance(v, str):
+        return v
+    try:
+        return json.loads(v)
+    except ValueError:
+        return v
+
+
+def wrap_tools(client: Client, tools: List[FunctionTool]) -> List[FunctionTool]:
+    out: List[FunctionTool] = []
+    for t in tools:
+        original = t.on_invoke_tool
+
+        async def invoke(ctx: Any, input_json: str, _t: FunctionTool = t, _orig=original) -> Any:
+            args = _parse(input_json)
+            policy = client.decide(_t.name, args)
+            if policy and policy["decision"] == "deny":
+                reason = "; ".join(policy["reasons"] + policy["errors"]) or "no permit policy matched"
+                bundle = client.record(_t.name, args, {"status": "denied", "reason": reason}, policy)
+                return f"Denied by policy: {reason} (receipt {receipt_id_of(bundle)})"
+            try:
+                result = await _orig(ctx, input_json)
+            except Exception as e:
+                client.record(_t.name, args, {"status": "error", "error": str(e)}, policy)
+                raise
+            client.record(_t.name, args, {"status": "executed", "result": _result(result)}, policy)
+            return result
+
+        out.append(dataclasses.replace(t, on_invoke_tool=invoke))
+    return out

agent_custody-0.1.2.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: agent-custody
+Version: 0.1.2
+Summary: Signed, verifiable receipts for AI agent tool calls, from Python, through the agent-custody sidecar
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Provides-Extra: test
+Requires-Dist: langchain-core>=0.3; extra == 'test'
+Requires-Dist: openai-agents>=0.1; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# agent-custody (Python)
+
+Signed, verifiable receipts for AI agent tool calls, from Python. The key, the Cedar policy, and the Merkle log live in the agent-custody sidecar, a local process from the npm package; this client talks to it over HTTP with the standard library only.
+
+```bash
+npm install -g @agent-custody/receipts && agent-custody keygen --dir keys --name app
+agent-custody serve --config sdk.json          # loopback, port 8788
+pip install agent-custody
+```
+
+```python
+from agent_custody import Client, PolicyDeniedError
+
+client = Client()                                # http://127.0.0.1:8788/
+refund = client.wrap("stripe.refund", lambda args: stripe.refund(**args))
+refund({"amount": 5000})                         # decide, run, record; raises PolicyDeniedError on deny
+```
+
+Adapters, each tested against the real package: `agent_custody.langchain.ReceiptCallbackHandler` (record-only), `agent_custody.openai_agents.wrap_tools` (enforce and record), `agent_custody.claude_agent_sdk.claude_hook` (PreToolUse deny, PostToolUse record). Receipts are verified by the TypeScript verifier; the tests do exactly that.
+
+Everything recorded is `claimed`: the sidecar trusts what this process reports, the same as the in-process TypeScript SDK. For enforcement the agent cannot skip, put the gateway in front of the tools instead; it is an MCP server and needs nothing from this package.
+
+```bash
+uv run --extra test pytest        # from packages/python; starts a sidecar with node from ../receipts
+```

agent_custody-0.1.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_custody/__init__.py,sha256=XQU2PRLXtEOzWsxeLwmVEkBcKjFcldS4gAm6o04JnWE,4617
+agent_custody/claude_agent_sdk.py,sha256=v2CAl1AGzLm5s6c7qXuV3JcAEqpjKnYawWwRwglgNnA,2605
+agent_custody/langchain.py,sha256=IbkQVcvvOXdkKD2hsYGP61CNh_1p06VzhMCd4agHz4w,2459
+agent_custody/openai_agents.py,sha256=i6CruYcPJdD4cko2RFiuYEiBG62l6rLGBojkDYYP-3E,1908
+agent_custody-0.1.2.dist-info/METADATA,sha256=Z4RkprXTZNffY47ytSkmuR8lZrSFWxedMOB37_L35pw,2110
+agent_custody-0.1.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agent_custody-0.1.2.dist-info/RECORD,,

agent_custody-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any