@agent-custody/receipts 0.1.1 → 0.1.2

package/README.md

@@ -9,7 +9,7 @@ Two producers, one receipt format, one verifier.
 
 Anyone holding the public keys can verify a receipt offline. The agent is not trusted. The layer around it is, and the receipt says exactly how far that trust extends, starting with who issued it.
 
-- [Tutorials](docs/tutorials.md): fourteen runnable examples, one per aspect of the code, all executed by the test suite
+- [Tutorials](docs/tutorials.md): fifteen runnable examples, one per aspect of the code, all executed by the test suite
 - [Usage guide](docs/usage.md): gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop
 - [The interceptor SDK](docs/sdk.md): Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK and LangChain, and wrapping tool functions in anything else
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
@@ -103,6 +103,9 @@ Every receipt names its issuer, and the verifier prints what that issuer kind is
 | Vercel AI SDK | SDK | `wrapTools` | | a real `generateText` loop over the SDK's mock model |
 | LangChain / LangGraph (JS) | SDK | `tool(issuer.wrap(fn))` | `ReceiptCallbackHandler` | real `StructuredTool` invocations |
 | anything else | SDK | `issuer.wrap(name, fn)` | `issuer.record` | plain functions |
+| Python: LangChain, OpenAI Agents SDK, Claude Agent SDK | sidecar + [Python package](../python/README.md) | `wrap_tools`, `claude_hook` PreToolUse deny, `client.wrap` | `ReceiptCallbackHandler` | the real Python packages, receipts checked by this verifier |
+| Go, Java, Rust, any language with HTTP | sidecar | decide then record | record | [examples/languages](examples/languages), each run against a live sidecar |
+| any MCP host in any language: Claude Agent SDK Python, OpenAI Agents Python | gateway | yes | | the gateway is an MCP server; [usage.md](docs/usage.md#python-hosts) |
 
 The framework packages are optional peer dependencies. Each adapter imports only from its own package.
 
@@ -167,7 +170,7 @@ Every field carries a provenance label. This is the design decision that matters
 bun install                              # from the repository root, once for the workspace
 cd packages/receipts
 node scripts/demo.ts                     # gateway: keys, grant, policy, four tool calls, verification, a tampering attempt; then the SDK wrapping the same tool
-node examples/01-keys-and-signing.ts     # first of fourteen step-by-step examples, see docs/tutorials.md
+node examples/01-keys-and-signing.ts     # first of fifteen step-by-step examples, see docs/tutorials.md
 bun run test                             # this package; `bun run test` at the root runs every package
 ```
 
@@ -227,12 +230,13 @@ src/gateway.ts     the MCP proxy: scope check, facts, policy, forward, receipt
 src/sdk/index.ts   the interceptor: policy decision, record, wrap(tool fn)
 src/sdk/claude.ts  Claude Code command hook and Claude Agent SDK in-process hooks
 src/sdk/openai-agents.ts, vercel-ai.ts, langchain.ts   framework adapters, tested against the real packages
+src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other languages
 src/verify.ts      offline verification, the human-readable report, and the audit that a later log extends an earlier one
-src/cli.ts         keygen, grant, gateway, hook, log, verify, audit
+src/cli.ts         keygen, grant, gateway, hook, serve, log, verify, audit
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
 scripts/           fake Stripe upstream, fixture builders for gateway and SDK, demo
-examples/          fourteen runnable tutorials, one per aspect; each is run by the test suite
+examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
 docs/              tutorials, usage (gateway), sdk, policies, verification
@@ -249,6 +253,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - SDK core: policy decision, record, and a generic `wrap(tool, fn)` for any framework whose tools are functions.
 - Claude Code command hook for PreToolUse, PostToolUse, and PostToolUseFailure, with blocking on deny.
 - Claude Agent SDK in-process hooks over the same handler.
+- Sidecar: the SDK issuer behind a local HTTP API (`serve`), with a Python package on PyPI-ready footing and Go, Java, and Rust clients, so agents in any language get the same receipts from one signing implementation.
 - Consistency proofs between tree heads (RFC 9162), served by the log and checked by the `audit` command, so an auditor holding an old tree head can prove nothing before it was rewritten.
 - Remote log: the issuer can append to a log run by someone else over HTTP, whose key then signs the tree heads, so a verifier learns the receipt was in a log the operator could not rewrite. Includes the reference log server, bearer-token auth, and a root endpoint for auditors.
 - Framework adapters, each tested against the real package with a scripted model and no network: OpenAI Agents SDK (`wrapTools` enforces, `observeRunner` records from lifecycle events), Vercel AI SDK (`wrapTools` over a real `generateText` loop), LangChain (`ReceiptCallbackHandler` records, `issuer.wrap` enforces).

package/dist/cli.js

@@ -6,6 +6,7 @@ import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
 import { serveLog } from "./log-sink.js";
+import { serveSidecar } from "./sidecar.js";
 import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
 import { handleHookEvent } from "./sdk/claude.js";
@@ -16,6 +17,7 @@ const USAGE = `agent-custody <command>
   grant   --key <principal.key> --principal <id> --agent <id> --scopes <a,b> [--ttl-hours 24] --out <file>
   gateway --config <gateway.json>
   hook    [--config <sdk.json>]        Claude Code hook command; reads the event on stdin (or AGENT_CUSTODY_CONFIG)
+  serve   --config <sdk.json> [--port 8788] [--host 127.0.0.1]   the SDK as a local HTTP API for agents in other languages
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
   verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log <log.jsonl>] [--json]
   audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
@@ -80,6 +82,17 @@ async function main(argv) {
             console.log(JSON.stringify(out));
             return 0;
         }
+        case "serve": {
+            const { values } = parseArgs({ args: rest, options: { config: { type: "string" }, port: { type: "string", default: "8788" }, host: { type: "string", default: "127.0.0.1" } } });
+            if (!values.config)
+                throw new Error("serve needs --config");
+            const issuer = createSdkIssuer(loadSdkConfig(values.config));
+            const running = await serveSidecar(issuer, { port: Number(values.port), host: values.host });
+            console.error(`agent-custody serve: ${running.url} agent=${issuer.agentId} keyid=${issuer.keyid} log=${issuer.log.kind}:${issuer.log.where}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            return 0;
+        }
         case "log": {
             const { values } = parseArgs({
                 args: rest,

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from "./policy.ts";
 export * from "./receipt.ts";
 export * from "./verify.ts";
 export * from "./sdk/index.ts";
+export * from "./sidecar.ts";

package/dist/index.js

@@ -10,3 +10,4 @@ export * from "./policy.js";
 export * from "./receipt.js";
 export * from "./verify.js";
 export * from "./sdk/index.js";
+export * from "./sidecar.js";

package/dist/sidecar.d.ts

@@ -0,0 +1,12 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { SdkIssuer } from "./sdk/index.ts";
+export declare function sidecarHandler(issuer: SdkIssuer): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningSidecar {
+    url: string;
+    close(): Promise<void>;
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export declare function serveSidecar(issuer: SdkIssuer, opts: {
+    port: number;
+    host?: string;
+}): Promise<RunningSidecar>;

package/dist/sidecar.js

@@ -0,0 +1,93 @@
+// The sidecar: the SDK issuer behind a local HTTP API, so agents written in any language can decide and record.
+// Same config file, same receipts, same key. Everything it records is claimed, exactly as with the in-process SDK:
+// the sidecar trusts what the agent's process tells it. Bind it to localhost; it is a per-host companion, not a service.
+//   GET  /health                      -> { agentId, keyid, log: { kind, where } }
+//   POST /decide  ToolEvent           -> PolicyDecision | null
+//   POST /record  { event, outcome, policy? } -> ReceiptBundle, or 4xx/5xx with { error }
+import { createServer } from "node:http";
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function parseEvent(v) {
+    if (!isRecord(v) || typeof v.tool !== "string" || v.tool.length === 0)
+        throw new Error("event needs a non-empty string tool");
+    const args = isRecord(v.args) ? v.args : v.args === undefined ? {} : { input: v.args };
+    const ev = { tool: v.tool, args };
+    if (typeof v.model === "string")
+        ev.model = v.model;
+    if (isRecord(v.session))
+        ev.session = { id: typeof v.session.id === "string" ? v.session.id : null, toolUseId: typeof v.session.toolUseId === "string" ? v.session.toolUseId : null };
+    return ev;
+}
+function parseOutcome(v) {
+    if (!isRecord(v) || typeof v.status !== "string")
+        throw new Error("outcome needs a status");
+    switch (v.status) {
+        case "executed":
+        case "failed":
+            return { status: v.status, result: v.result ?? null };
+        case "denied":
+            return { status: "denied", reason: typeof v.reason === "string" ? v.reason : "denied" };
+        case "error":
+            return { status: "error", error: typeof v.error === "string" ? v.error : "error" };
+        default:
+            throw new Error(`unknown outcome status ${v.status}`);
+    }
+}
+function parsePolicy(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (!isRecord(v) || (v.decision !== "allow" && v.decision !== "deny") || !Array.isArray(v.reasons) || !Array.isArray(v.errors) || typeof v.policyDigest !== "string")
+        throw new Error("policy must be a PolicyDecision from /decide");
+    return { decision: v.decision, reasons: v.reasons.map(String), errors: v.errors.map(String), policyDigest: v.policyDigest };
+}
+export function sidecarHandler(issuer) {
+    return async (req, res) => {
+        const json = (status, body) => {
+            res.writeHead(status, { "content-type": "application/json" });
+            res.end(JSON.stringify(body));
+        };
+        const url = new URL(req.url ?? "/", "http://localhost");
+        try {
+            if (req.method === "GET" && url.pathname === "/health")
+                return json(200, { agentId: issuer.agentId, keyid: issuer.keyid, log: { kind: issuer.log.kind, where: issuer.log.where } });
+            if (req.method !== "POST")
+                return json(404, { error: "not found" });
+            let raw = "";
+            for await (const chunk of req)
+                raw += chunk;
+            let body;
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                return json(400, { error: "body must be JSON" });
+            }
+            if (url.pathname === "/decide")
+                return json(200, issuer.decide(parseEvent(body)));
+            if (url.pathname === "/record") {
+                if (!isRecord(body))
+                    return json(400, { error: "body must be {event, outcome, policy?}" });
+                const bundle = await issuer.record(parseEvent(body.event), parseOutcome(body.outcome), parsePolicy(body.policy));
+                return json(200, bundle);
+            }
+            return json(404, { error: "not found" });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return json(/needs|must|unknown outcome/.test(msg) ? 400 : 502, { error: msg });
+        }
+    };
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export function serveSidecar(issuer, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = sidecarHandler(issuer);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/`, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}

package/docs/sdk.md

@@ -177,3 +177,26 @@ The three framework packages are optional peer dependencies. Each adapter import
 ## What an SDK receipt is worth
 
 A verified SDK receipt establishes that a process holding the application key reported this call, at this time, with these arguments and this result, and that the record has not changed since. It does not establish that the process reported every call, that the arguments are what the tool really received, or that anyone outside the process checked anything. The verifier prints exactly that sentence under `ISSUER`. Keep it in the dashboard too.
+
+## Other languages: the sidecar
+
+The interceptor above is TypeScript. Agents in any other language get the same receipts through the sidecar: the SDK issuer behind a local HTTP API, started from the same config file.
+
+```bash
+agent-custody serve --config sdk.json          # 127.0.0.1:8788 by default; --port and --host to change
+```
+
+| | |
+| --- | --- |
+| `GET /health` | `{ agentId, keyid, log: { kind, where } }` |
+| `POST /decide` with a `ToolEvent` `{ tool, args, model?, session? }` | the `PolicyDecision`, or `null` when no policy is configured |
+| `POST /record` with `{ event, outcome, policy? }` | the `ReceiptBundle`; `outcome` is `{ status: "executed" \| "failed", result }`, `{ status: "denied", reason }`, or `{ status: "error", error }` |
+
+The client's loop is decide, run the tool, record. A malformed body gets a 400 and nothing is written; a log that refuses the leaf gets a 502 and nothing is written. Bind the sidecar to loopback: it is a per-host companion holding the signing key, not a shared service, and everything it records is `claimed` exactly as with the in-process SDK, because it trusts what the client reports.
+
+**Python** has a real package, [packages/python](../../python/README.md): `pip install agent-custody`, a standard-library client with `decide`, `record`, and `wrap`, and adapters for LangChain callbacks, OpenAI Agents function tools, and Claude Agent SDK hooks, each tested against the real package with receipts checked by this verifier.
+
+**Go, Java, Rust, and Python without the package** each have a complete client in [examples/languages](../examples/languages): one file, standard library where the language has an HTTP client, decide then record. The test suite runs every one of them against a live sidecar. Any language with an HTTP client is the same forty lines.
+
+The gateway needs none of this. It is an MCP server, so a Python or Go agent host that speaks MCP puts it in front of its tools with a config change; [usage.md](usage.md) shows the Python hosts.
+

package/docs/tutorials.md

@@ -24,6 +24,7 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 12 | inside a receipt | [12-read-a-receipt.ts](../examples/12-read-a-receipt.ts) | the bundle's three parts, the in-toto statement, every predicate field with its provenance, the tree head | `src/receipt.ts` |
 | 13 | a log run by someone else | [13-remote-log.ts](../examples/13-remote-log.ts) | the reference log server on a free port, an SDK config that logs to it, a tree head signed by the log's key, verification failing without that key and passing with it, the root endpoint, a refused token | `src/log-sink.ts` |
 | 14 | proving history was not rewritten | [14-audit-history.ts](../examples/14-audit-history.ts) | three receipts and a kept tree head, a consistency proof that passes, the operator rewriting one leaf and appending a fourth call, the audit failing while the fourth receipt still verifies alone | `src/log.ts`, `src/verify.ts` |
+| 15 | agents in other languages | [15-sidecar.ts](../examples/15-sidecar.ts) | the sidecar on a free port, a client written as a Python or Go program would write it: decide, run, record; a denial recorded without running the tool; both receipts verified | `src/sidecar.ts` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -124,6 +124,31 @@ Claude sees only the tools inside the grant's scopes. Every call it makes produc
 claude mcp add stripe -- node /abs/path/agent-custody/packages/receipts/src/cli.ts gateway --config /abs/path/gateway.json
 ```
 
+### Python hosts
+
+The gateway is language-neutral: any host that can launch a stdio MCP server can use it. Claude Agent SDK for Python:
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, query
+
+options = ClaudeAgentOptions(mcp_servers={"stripe": {"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}})
+async for message in query(prompt="Refund customer cust_123 by 50 dollars", options=options):
+    ...
+```
+
+OpenAI Agents SDK for Python:
+
+```python
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio
+
+async with MCPServerStdio(params={"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}) as stripe:
+    agent = Agent(name="support", instructions="...", mcp_servers=[stripe])
+    result = await Runner.run(agent, "Refund customer cust_123 by 50 dollars")
+```
+
+With the npm package installed globally, `"command": "agent-custody", "args": ["gateway", "--config", ...]` replaces the node invocation. Every tool the agent sees comes through the gateway; denied calls never reach Stripe and still produce a receipt. For receipts from tools that are plain Python functions rather than MCP servers, use the sidecar and the Python package, in [sdk.md](sdk.md).
+
 ### Your own agent loop (TypeScript)
 
 This is what [scripts/demo.ts](../scripts/demo.ts) does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {