@atrib/agent 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or a Contribution
+      incorporated within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, modify, or distribute
+      those modifications in accordance with this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. Also, an optional
+      "Statement of Purpose" appears after the copyright notice.
+
+   Copyright 2025-2026 Atrib 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
+
+       http://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.

package/README.md

@@ -0,0 +1,333 @@
+# `@atrib/agent`
+
+**Verifiable agent actions, client side. Every outbound MCP tool call gets signed at the moment of dispatch, carries provable context to the receiver, and chains into the next action. Works with every major MCP framework. Sits above every major agent payment protocol so commerce-closing settlement is bundled in.**
+
+`@atrib/agent` is the client-side half of the [atrib protocol](https://github.com/creatornader/atrib/blob/main/atrib-spec.md). Each outbound MCP tool call becomes a signed, chainable record so anyone (the agent itself, downstream auditors, merchants closing a transaction, future agents picking up the work) can verify what happened without trusting any intermediary.
+
+You set up one `atrib()` interceptor, plug it into your framework's adapter, and every outbound `tools/call` from that point on carries W3C trace context, an atrib chain token, and the full atrib session lifecycle. When a payment completes (through any of the supported commerce protocols), a transaction record closes the chain and the substrate produces a signed settlement document anyone can recompute. When commerce never closes the chain, the substrate still serves recall, audit, and cross-agent provenance.
+
+Two coverage surfaces define what you get:
+
+## Coverage Matrix 1: MCP Framework Adapters
+
+| Framework                                  | Package                          | Adapter helper                                                                                                                                                    | Integration shape                                                                                 | Status      |
+| ------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------- |
+| **Raw `@modelcontextprotocol/sdk` Client** | `@modelcontextprotocol/sdk`      | `wrapMcpClient(client, interceptor, { serverUrl? })`                                                                                                              | Proxy-based wrapper, returns new client                                                           | ✅ Shipped  |
+| **Claude Agent SDK**                       | `@anthropic-ai/claude-agent-sdk` | **Case A (in-process tools):** zero code. the SDK's `createSdkMcpServer` returns a real `McpServer` that `@atrib/mcp` wraps directly                             | Reuses `@atrib/mcp`'s `atrib()` middleware on the server side                                     | ✅ Shipped  |
+|                                            |                                  | **Case B (third-party servers):** `createAtribProxy({ upstream, interceptor })` from `@atrib/mcp`. in-process surrogate `McpServer` that forwards to an upstream | Proxy McpServer between SDK and upstream transport                                                | ✅ Shipped  |
+| **Cloudflare Agents**                      | `agents`                         | `attributeCloudflareAgentMcp(agent, { interceptor, serverUrls })`                                                                                                 | Walks `agent.mcp.mcpConnections`, replaces `.client` via `wrapMcpClient`                          | ✅ Shipped  |
+| **Vercel AI SDK MCP**                      | `@ai-sdk/mcp`                    | `attributeVercelAiSdkMcp(mcpClient, { interceptor, serverUrl })`                                                                                                  | Monkey-patches `mcpClient.request()` (custom JSON-RPC, not SDK Client)                            | ✅ Shipped  |
+| **LangChain JS MCP adapters**              | `@langchain/mcp-adapters`        | **High-level:** `attributeLangchainMcp(multiClient, { interceptor, serverUrls })`                                                                                 | Walks `multiClient.config.mcpServers`, monkey-patches `callTool` + `fork` on each internal Client | ✅ Shipped  |
+|                                            |                                  | **Low-level:** `wrapMcpClient(rawClient, interceptor)` passed to `loadMcpTools(name, wrapped)`                                                                    | Reuses raw-SDK wrapper path                                                                       | ✅ Shipped  |
+| **OpenAI Agents SDK**                      | `@openai/agents`                 | _(planned. custom transport architecture, not `@modelcontextprotocol/sdk`)_                                                                                      | Planned: subclass `MCPServerSSE` / `MCPServerStdio` / `MCPServerStreamableHttp`                   | ⏳ Planned  |
+| **Mastra**                                 | `@mastra/mcp`                    | _(planned. smaller footprint, needs source verification)_                                                                                                        |;                                                                                                 | ⏳ Planned  |
+
+**The pattern across every row is identical:** one `atrib()` interceptor object, one adapter helper call, zero changes to your existing tool invocation code. The name of the helper varies because each host framework exposes a structurally different integration surface, but the `ToolCallInterceptor` type, the options shape, and the observable behavior are uniform.
+
+## Coverage Matrix 2: Agent Payment Protocols
+
+`@atrib/agent` sits **above** every major agent payment protocol. It does not implement payments, move money, or enforce transactions; it detects transaction events in the response flow of whichever payment protocol your agent is using, and writes a signed transaction record that closes the attribution chain. **You do not choose a payment protocol at install time**; the detection logic for all six (ACP, UCP, x402, MPP, AP2, a2a-x402) runs simultaneously and fires on whichever one your tool responses happen to carry. Transaction records emitted by `@atrib/agent` carry the `signers` array per spec [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records); the counterparty signature is collected via the payment protocol's settlement response.
+
+All detection logic lives in `packages/agent/src/transaction.ts` and runs against unit tests for each protocol's published spec.
+
+| Protocol                              | Sponsor / origin                                            | Detection signal                                                                                                              | Spec reference                       |
+| ------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| **ACP**. Agentic Commerce Protocol   | Stripe / OpenAI; `github.com/agentic-commerce-protocol`    | `status === "completed"` + embedded `order` on `/checkout_sessions/{id}/complete`, or `order_create` / `order_update` webhook | [§1.7.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#171-acp-agentic-commerce-protocol)                               |
+| **UCP**. Universal Commerce Protocol | `github.com/universal-commerce-protocol/ucp`                | Same shape as ACP + top-level `ucp.version` envelope                                                                          | [§1.7.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#172-ucp-universal-commerce-protocol)                               |
+| **x402**                              | Coinbase. `github.com/coinbase/x402`                       | HTTP `PAYMENT-RESPONSE` header (v2) or legacy `X-PAYMENT-RESPONSE` (v1) on the 200 response                                   | [§1.7.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#173-x402)                               |
+| **MPP**. Machine Payments Protocol   | Tempo Labs / Stripe; IETF `draft-ryan-httpauth-payment-01` | HTTP `Payment-Receipt` header on 200 success response                                                                         | [§1.7.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#174-mpp-machine-payments-protocol)                               |
+| **AP2**. Agent Payments Protocol     | Google; `github.com/google-agentic-commerce/ap2`           | A2A Message with DataPart containing `ap2.mandates.PaymentMandate`                                                            | [§1.7.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#175-ap2-and-a2a-x402)                               |
+| **a2a-x402**                          | Google. `github.com/google-agentic-commerce/a2a-x402`      | A2A task `status.message.metadata["x402.payment.status"] === "payment-completed"` + `receipts[].success === true`             | [§1.7.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#175-ap2-and-a2a-x402) (reported as AP2 crypto path) |
+
+**The linking mechanism is the same across all six:** the session `context_id` (16-byte anchor, equal to the W3C OTel trace-id by default) travels with the outbound payment request; via `X-atrib-Context` HTTP header for protocols that don't expose a free-form metadata field, or via `params._meta.atrib` for any payment protocol running over MCP transport. When the merchant's side sees the payment-completed signal, atrib writes a transaction record with that `context_id`, and the attribution graph can reconstruct the full chain from contributing tool calls → transaction → settlement.
+
+**You do not install a separate package for each protocol.** ACP, UCP, x402, MPP, AP2 and a2a-x402 detection all ship in `@atrib/agent` and `@atrib/mcp` by default. Adding a new payment protocol happens by adding a detector in `transaction.ts`, not by asking users to install anything.
+
+### What each detector actually looks for on the wire
+
+These are the exact shapes the production `detectTransaction()` function in [`packages/agent/src/transaction.ts`](src/transaction.ts) matches against. Every shape below is covered by a unit test against a real spec fixture in [`packages/agent/test/fixtures/`](test/fixtures/), the customer-facing question "what does atrib actually detect" has a one-paragraph answer per protocol.
+
+#### ACP: Stripe / OpenAI Agentic Commerce Protocol
+
+Detected on the success response of `POST /checkout_sessions/{id}/complete`. Required fields: top-level `status: "completed"` plus an `order` object with a string `id`. The optional `order.permalink_url` becomes the `checkoutUrl` for Path 2 `content_id` derivation per spec [§5.4.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#545-transaction-detection).
+
+```json
+{
+  "id": "checkout_session_abc123",
+  "status": "completed",
+  "order": {
+    "id": "ord_xyz789",
+    "permalink_url": "https://merchant.example.com/orders/ord_xyz789"
+  }
+}
+```
+
+The `order_create` and `order_update` webhook event shapes are also detected (`type: "order_create"` plus a `data` object containing the order fields).
+
+#### UCP: Universal Commerce Protocol
+
+Identical to ACP **plus** a top-level `ucp` envelope with a `version` string. The envelope is the only structural distinguisher between ACP and UCP, without it the same shape is reported as ACP.
+
+```json
+{
+  "ucp": { "version": "1.0", "capabilities": [] },
+  "id": "checkout_session_abc123",
+  "status": "completed",
+  "order": { "id": "ord_xyz789", "permalink_url": "https://..." }
+}
+```
+
+#### x402: Coinbase
+
+Detected entirely from an HTTP **response header**, not the body. The v2 header is `PAYMENT-RESPONSE` (per [github.com/coinbase/x402](https://github.com/coinbase/x402)); the v1 legacy header `X-PAYMENT-RESPONSE` is also accepted. Header name lookup is case-insensitive per RFC 7230.
+
+```http
+HTTP/1.1 200 OK
+PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlfQ==
+```
+
+The header value is base64-encoded JSON `{success, transaction, network, payer, requirements}` but `detectTransaction()` only checks for the header's _presence_; the surrounding `wrapMcpClient` / framework adapter is responsible for capturing response headers and passing them to the detector.
+
+#### MPP: IETF draft `draft-ryan-httpauth-payment-01`
+
+Also header-based, but a **different** header from x402 (the two were conflated in earlier drafts of this code; see [`DECISIONS.md` D016](https://github.com/creatornader/atrib/blob/main/DECISIONS.md)). MPP uses `Payment-Receipt` per [§5.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#53-atribmcp-mcp-server-middleware) of the IETF draft. Both headers may not co-exist on a real response, but if they do, x402 wins (deterministic precedence documented in the test suite).
+
+```http
+HTTP/1.1 200 OK
+Payment-Receipt: eyJzdGF0dXMiOiJzdWNjZXNzIn0
+```
+
+#### AP2: Google Agent Payments Protocol (v0.1)
+
+Detected from an A2A `Message` containing a `DataPart` whose `data` object has the literal key `"ap2.mandates.PaymentMandate"`. AP2 v0.1 does **not** use W3C Verifiable Credentials despite earlier drafts assuming it would (a legacy VC fallback is kept for research forks).
+
+```json
+{
+  "messageId": "b5951b1a-8d5b-4ad3-a06f-92bf74e76589",
+  "contextId": "sample-payment-context",
+  "role": "user",
+  "parts": [
+    {
+      "kind": "data",
+      "data": {
+        "ap2.mandates.PaymentMandate": {
+          "payment_details": { "payment_request_id": "order_shoes_123", "...": "..." }
+        }
+      }
+    }
+  ]
+}
+```
+
+`IntentMandate` and `CartMandate` are **not** detected; they are upstream funnel events, not transaction events. Only `PaymentMandate` closes the chain.
+
+#### a2a-x402: Google AP2 crypto path
+
+Detected from an A2A `task` whose `status.message.metadata` contains `"x402.payment.status": "payment-completed"` **and** at least one entry in `"x402.payment.receipts"` with `success: true`. A `payment-completed` status with no successful receipt does NOT detect (a failed receipt is not a transaction). Reported as `protocol: 'AP2'` because a2a-x402 is the AP2 crypto path, not a separate protocol.
+
+```json
+{
+  "kind": "task",
+  "status": {
+    "message": {
+      "metadata": {
+        "x402.payment.status": "payment-completed",
+        "x402.payment.receipts": [{ "success": true, "transaction": "0xabc...", "network": "base" }]
+      }
+    }
+  }
+}
+```
+
+#### Heuristic fallback (last resort)
+
+If none of the above match, the detector falls back to checking the **tool name** against a set of common keywords: `create_order`, `complete_checkout`, `process_payment`, `place_order`, `purchase`, `checkout`. A match returns `protocol: 'heuristic'` and is included in the chain, but it's a weaker signal than any of the protocol-specific detectors above. Use this only when no payment protocol is in play and you want the chain to still close on a domain-specific tool name.
+
+---
+
+## Quick start: one interceptor, any framework
+
+Every adapter wiring looks the same:
+
+```ts
+import { atrib } from '@atrib/agent'
+
+const interceptor = atrib({
+  // 32-byte Ed25519 seed in base64url. Generate with:
+  //   node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))'
+  creatorKey: process.env.ATRIB_PRIVATE_KEY!,
+
+  // Your merchant identity (used for Path 1 transaction detection per §5.4.5).
+  merchantDomain: 'https://merchant.example.com',
+
+  // Canonical URLs of MCP servers this agent will call (drives policy negotiation).
+  serverUrls: ['https://search.example.com', 'https://shop.example.com'],
+
+  // Optional: where to submit signed records. Omit in development.
+  logEndpoint: process.env.ATRIB_LOG_ENDPOINT,
+})
+```
+
+That's the interceptor. Now plug it into whichever framework you use:
+
+### Raw `@modelcontextprotocol/sdk`
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { wrapMcpClient } from '@atrib/agent'
+
+const raw = new Client({ name: 'my-agent', version: '1.0.0' }, { capabilities: {} })
+await raw.connect(transport)
+const client = wrapMcpClient(raw, interceptor, {
+  serverUrl: 'https://my-tool.example.com',
+})
+// Use `client` anywhere the raw Client would have been used.
+```
+
+### Claude Agent SDK: Case A (in-process tools, zero atrib code on this side)
+
+```ts
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
+import { atrib as wrapServer } from '@atrib/mcp'  // note: server-side package
+
+const sdkServer = createSdkMcpServer({
+  name: 'my-tools',
+  tools: [tool('search', 'Search the web', { q: z.string() }, async ({ q }) => ({ ... }))],
+})
+wrapServer(sdkServer.instance, { creatorKey: process.env.ATRIB_PRIVATE_KEY! })
+
+// Pass sdkServer to the Claude Agent SDK as a normal `{ type: 'sdk', ... }` config.
+// Attribution flows at the server side; the interceptor on this side is not needed.
+```
+
+### Claude Agent SDK: Case B (third-party MCP servers via proxy)
+
+```ts
+import { createAtribProxy } from '@atrib/mcp'
+
+const proxy = await createAtribProxy({
+  upstream: { type: 'http', url: 'https://my-tool.example.com/mcp' },
+  interceptor,
+})
+
+// Pass `proxy.mcpServer` to the Claude Agent SDK as `{ type: 'sdk', instance: proxy.mcpServer, ... }`.
+```
+
+### Cloudflare Agents
+
+```ts
+import { Agent } from 'agents'
+import { attributeCloudflareAgentMcp } from '@atrib/agent'
+
+class MyAgent extends Agent {
+  async onRequest() {
+    await this.mcp.addMcpServer('search', 'https://search.example.com/mcp')
+    attributeCloudflareAgentMcp(this, {
+      interceptor,
+      serverUrls: { search: 'https://search.example.com' },
+    })
+    // ... call MCP tools as normal
+  }
+}
+```
+
+### Vercel AI SDK
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp'
+import { streamText } from 'ai'
+import { attributeVercelAiSdkMcp } from '@atrib/agent'
+
+const mcpClient = await createMCPClient({
+  transport: { type: 'http', url: 'https://my-tool.example.com/mcp' },
+})
+attributeVercelAiSdkMcp(mcpClient, {
+  interceptor,
+  serverUrl: 'https://my-tool.example.com',
+})
+
+const tools = await mcpClient.tools()
+const result = await streamText({ model: 'openai/gpt-5.4', tools, prompt: '...' })
+```
+
+### LangChain JS
+
+```ts
+import { MultiServerMCPClient } from '@langchain/mcp-adapters'
+import { attributeLangchainMcp } from '@atrib/agent'
+
+const multi = new MultiServerMCPClient({
+  mcpServers: { search: { transport: 'http', url: 'https://search.example.com/mcp' } },
+})
+await multi.initializeConnections()
+await attributeLangchainMcp(multi, {
+  interceptor,
+  serverUrls: { search: 'https://search.example.com' },
+})
+
+const tools = await multi.getTools()
+// ... pass `tools` to your LangChain agent as normal
+```
+
+**In every case:** same interceptor, one adapter call, identical behavior. The differences between adapters are forced by differences between host frameworks; not invented by atrib.
+
+---
+
+## What you get
+
+Once the adapter is wired in, every successful `tools/call` from your agent:
+
+1. **Carries W3C trace context** (`traceparent`, `tracestate`, `baggage`) in `params._meta`, so downstream servers can correlate calls with your OTel traces.
+2. **Carries an attribution chain token** in `params._meta.atrib`, a ~87-char base64url token identifying the prior call in the chain ([§1.5.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#152-http-transport-tracestate)).
+3. **Emits a signed attribution record** to the submission queue asynchronously, zero blocking on the hot path ([§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission)).
+4. **Updates session state** with the response's own `_meta.atrib` token, so the next call chains correctly from the current response.
+5. **Detects transaction events** in the response via the `transaction.ts` detector, across all six payment protocols in coverage matrix 2. When a transaction is detected, a transaction record is emitted linking the session `context_id` to the transaction.
+6. **Fails silent**: if any internal atrib step (signing, submission, interceptor logic) throws, the error is caught, logged with the `atrib:` prefix, and the tool call proceeds normally per spec [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract).
+
+---
+
+## Runnable examples
+
+- [`claude-agent-sdk/`](https://github.com/creatornader/atrib/tree/main/packages/integration/examples/claude-agent-sdk). Case A (in-process tools) and Case B (proxy) side-by-side
+- [`cloudflare-agents/`](https://github.com/creatornader/atrib/tree/main/packages/integration/examples/cloudflare-agents); `McpAgent` server-side and `Agent` client-side surfaces
+- [`vercel-ai-sdk/`](https://github.com/creatornader/atrib/tree/main/packages/integration/examples/vercel-ai-sdk); `createMCPClient` with AI Gateway model routing
+- [`langchain-js/`](https://github.com/creatornader/atrib/tree/main/packages/integration/examples/langchain-js); `MultiServerMCPClient` and the low-level `loadMcpTools` path
+
+Each example directory contains a `README.md` with framework-specific rationale and a runnable `integration.ts` snippet.
+
+---
+
+## Failure model (spec §5.8)
+
+The entire atrib integration is wrapped in defensive error handling at every adapter boundary. If any of the following fails, the original tool call continues normally and an `atrib:`-prefixed warning is logged:
+
+- `onBeforeToolCall` throws → forward the request with original `_meta` (no injection)
+- `onAfterToolResponse` throws → return the result to the caller anyway
+- Signing throws → skip the record for that call
+- Submission network error → the submission queue retries with exponential backoff; final failure drops the record silently
+- `creatorKey` missing → pass-through mode with one console warning per process
+
+**atrib failures never affect the primary tool call or agent response.** This is invariant #1 in `CLAUDE.md` and is enforced by unit tests in each adapter's test file.
+
+---
+
+## Spec references
+
+| Spec section | What it defines                                              |
+| ------------ | ------------------------------------------------------------ |
+| [§1.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#13-canonical-serialization)         | JCS canonical serialization of records                       |
+| [§1.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#14-signing-and-verification)         | Ed25519 signing and verification                             |
+| [§1.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#15-context-propagation)         | Context propagation via `params._meta` and W3C trace context |
+| [§1.7](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#17-transaction-event-hooks)         | Transaction event hooks for all 6 payment protocols          |
+| [§2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2-merkle-log-protocol)           | Merkle log protocol (Tessera-backed, tlog-tiles spec)        |
+| [§3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#3-graph-query-interface)           | Graph query interface (fact layer only)                      |
+| [§4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#4-attribution-policy-format)           | Policy format (merchant-side value distribution)             |
+| [§5.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#53-atribmcp-mcp-server-middleware)         | Agent-side middleware behavior                               |
+| [§5.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#54-atribagent-agent-middleware)         | Path 1 / Path 2 transaction detection                        |
+| [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract)         | Degradation contract; silent failure never breaks the host  |
+
+The full protocol spec is at [`atrib-spec.md`](https://github.com/creatornader/atrib/blob/main/atrib-spec.md).
+
+---
+
+> **A note on documentation links.** The atrib protocol repository is currently private (in-progress public preparation). Links in this README to the spec and sister packages (`atrib-spec.md`, `packages/agent/README.md`, etc.) point at `github.com/creatornader/atrib/blob/main/...` URLs that will resolve once the repository goes public. Until then, see [`atrib.dev`](https://atrib.dev) for the protocol overview.

package/dist/adapters/cloudflare-agent.d.ts

@@ -0,0 +1,46 @@
+import type { ToolCallInterceptor } from '../middleware.js';
+/**
+ * Minimal structural type for a Cloudflare `Agent` we can attribute. Mirrors
+ * the public surface of `agents`'s `Agent` class without importing from
+ * `agents` (we don't want a hard dependency on the Cloudflare package).
+ *
+ * `client` is typed as `unknown` here rather than `MinimalMcpClient` so the
+ * real Cloudflare `MCPClientConnection.client: Client` from
+ * `@modelcontextprotocol/sdk` is structurally assignable without forcing
+ * users to cast at the call site. The helper performs a runtime check on
+ * each connection's `client` shape before wrapping.
+ */
+export interface CloudflareAgentLike {
+    mcp: {
+        mcpConnections: Record<string, {
+            client: unknown;
+            url?: URL | string;
+        }>;
+    };
+}
+/** Options for `attributeCloudflareAgentMcp`. */
+export interface AttributeCloudflareAgentMcpOptions {
+    /** The atrib interceptor that should observe tool calls on this agent. */
+    interceptor: ToolCallInterceptor;
+    /**
+     * Optional override map of server name → canonical serverUrl. If a server
+     * name appears here, the helper passes that URL as the `serverUrl` option
+     * to `wrapMcpClient`. If a server name is missing from this map, the helper
+     * derives serverUrl from the connection's own `url.origin`.
+     *
+     * Override when the upstream URL the agent connects to is not the canonical
+     * URL you want to record in attribution records (e.g. you're hitting a
+     * reverse proxy or staging endpoint but want production identity).
+     */
+    serverUrls?: Record<string, string>;
+}
+/**
+ * Wrap every currently-connected MCP client on a Cloudflare Agent with atrib
+ * attribution. Returns the number of connections wrapped (excluding ones that
+ * were already wrapped). Idempotent. safe to call multiple times.
+ *
+ * Call this in `onStart()` after your `addMcpServer()` calls. If you add more
+ * MCP servers later (in a message handler, after OAuth, etc.), call again.
+ */
+export declare function attributeCloudflareAgentMcp(agent: CloudflareAgentLike, options: AttributeCloudflareAgentMcpOptions): number;
+//# sourceMappingURL=cloudflare-agent.d.ts.map

package/dist/adapters/cloudflare-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-agent.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare-agent.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAkB3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE;QACH,cAAc,EAAE,MAAM,CACpB,MAAM,EACN;YACE,MAAM,EAAE,OAAO,CAAA;YACf,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,CAAA;SACnB,CACF,CAAA;KACF,CAAA;CACF;AAED,iDAAiD;AACjD,MAAM,WAAW,kCAAkC;IACjD,0EAA0E;IAC1E,WAAW,EAAE,mBAAmB,CAAA;IAEhC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,kCAAkC,GAC1C,MAAM,CA4DR"}