@absol-labs/agent 0.3.2 → 0.5.0

package/README.md

@@ -1,183 +1,386 @@
 # @absol-labs/agent
 
-The **Metrik agent layer** — how AI agents hire and pay for verified services through
-Metrik, safely. This is the **go-to-market wedge** and the investor headline:
-_verified, per-second, conditional payments for autonomous agents, built on x402._
-The layer is operator/infra-agnostic by design: _"x402 proves the payment, Metrik
-proves the delivery."_
+The Metrik agent layer: everything an autonomous agent needs to **hire and pay for
+third-party services safely**, where money is released only for delivery that is
+independently verified. Metrik is an infra-agnostic verified-service marketplace and
+payment rail for AI agents, settling in USDC on Base. The tagline is the design
+contract: **x402 proves the payment, Metrik proves the delivery** — and delivery,
+honestly scoped, is what this package makes an agent able to enforce, never
+"proven-correct output."
+
+It builds on [`@absol-labs/sdk`](https://github.com/Absol-Labs/metrik-sdk), which speaks
+to the on-chain metered escrow. This layer wraps that client in the guardrails and
+integration surfaces an agent actually needs: owner-signed spend mandates that gate every
+fund move, an x402 facilitator that turns a `402` into a verified stream, an MCP server
+that exposes hire/monitor/reclaim as agent tools, adapters for the major agent frameworks,
+Reclaim consumer zkTLS for buyer-side delivery proofs, and non-custodial Coinbase CDP
+wallets so Metrik never holds a key.
+
+Live on Base Sepolia (chainId `84532`), testnet only. App: [app.metrik.live](https://app.metrik.live).
+Docs: [metrik.live](https://metrik.live). Frontdoor: [github.com/Absol-Labs](https://github.com/Absol-Labs).
+
+## Install
 
-Built on [`@absol-labs/sdk`](https://github.com/Absol-Labs/streamproof-sdk); it turns
-the protocol into something an agent can actually use.
-
-> **New here?** [`docs/quickstart.md`](./docs/quickstart.md) — hire a verified,
-> auto-refunding service in under 10 minutes (install → wallet → mandate → hire →
-> monitor → settle), with copy-pasteable examples for all four integration surfaces.
-
-> **Why agents are the wedge** + the full agent journey:
-> [`product-strategy.md`](https://github.com/Absol-Labs/streamproof-protocol/blob/main/docs/product-strategy.md)
-> and [`production-flow.md`](https://github.com/Absol-Labs/streamproof-protocol/blob/main/docs/production-flow.md)
-> (Journey 2 — Atlas). The agent's own zkTLS delivery proof is **L2** (consumer zkTLS) in
-> [`verification-model.md`](https://github.com/Absol-Labs/streamproof-protocol/blob/main/docs/verification-model.md).
-> The explicit agent-layer security review lives in
-> [docs/threat-model.md](./docs/threat-model.md).
+```bash
+pnpm add @absol-labs/agent
+```
 
-## What's here
+The package is **ESM-only** (`"type": "module"`) and targets **Node `>=20 <21`**. It ships
+`@absol-labs/sdk`, `@absol-labs/shared`, `viem`, `zod`, the Reclaim zkTLS SDKs, the
+Coinbase CDP SDK, and the MCP SDK as dependencies. The agent-framework packages
+(`@coinbase/agentkit`, `@elizaos/core`, `@langchain/core`) are **optional peer
+dependencies** — install only the one you use.
+
+## What it does
+
+**Spend mandates** are the "an agent can't run away with the wallet" guarantee. The wallet
+owner signs an EIP-712 `SpendMandate` carrying per-stream, total, rate, and duration caps
+plus an operator allowlist and expiry. Every buyer-side fund move checks the mandate first
+and hard-stops on denial; `MandateDecision` returns a machine-readable reason. Buyer-recovery
+actions (close, reclaim) verify only the signature — never expiry or caps — so a lapsed
+mandate can never strand the buyer's own funds in escrow.
+
+**The x402 facilitator** (`VerifiedStreamX402Facilitator`) turns an HTTP `402` challenge
+into a real on-chain stream open instead of a one-shot payment. The agent receives a
+verified-streaming requirement, signs a payload bound to its mandate, and the facilitator
+opens the escrowed stream through the SDK.
+
+**The MCP server** exposes `discover_services`, `hire_verified_service`,
+`check_stream_status`, `reclaim_unspent`, `list_streams`, and — when Reclaim credentials are
+configured — `prove_https_response`, so any MCP-native agent transacts directly. It reads
+settlement config from the environment and never accepts a raw key as a tool argument.
+
+**Framework adapters** put the same mandate-gated client behind AgentKit, ElizaOS,
+LangChain, and CrewAI, each importable from its own subpath.
+
+**Consumer zkTLS** (`ReclaimConsumerProofService`) lets the buyer prove the exact HTTPS
+response it received, bound to its stream context. This is the L2 delivery signal in
+Metrik's verification stack — dispute evidence that complements, and never replaces, the
+oracle's L1 observations.
+
+**Non-custodial wallets**: `resolveAgentWallet()` accepts either an injected viem signer or
+a provisioned Coinbase CDP Server Wallet v2 account. CDP mode uses Coinbase-managed remote
+signing, so no private key is ever read or exported.
+
+## Usage
+
+### Sign and check a spend mandate
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  spendMandateSchema,
+  signedSpendMandateSchema,
+  createSpendMandateTypedData,
+  checkMandate,
+} from "@absol-labs/agent";
+
+const owner = privateKeyToAccount(
+  process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}`,
+);
+
+const mandate = spendMandateSchema.parse({
+  maxPerStreamUsdc: 5_000_000n, // 5 USDC (6 decimals)
+  maxTotalUsdc: 50_000_000n,
+  maxRatePerSecondUsdc: 1_000n,
+  maxDurationSeconds: 86_400,
+  allowedOperators: ["0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814"],
+  expiresAt: 2_000_000_000,
+});
+
+const unsigned = {
+  mandateId: `0x${"77".repeat(32)}` as const,
+  owner: owner.address,
+  chainId: 84532,
+  issuedAt: Math.floor(Date.now() / 1000),
+  mandate,
+};
+
+const signature = await owner.signTypedData(
+  createSpendMandateTypedData(unsigned),
+);
+const signedMandate = signedSpendMandateSchema.parse({
+  ...unsigned,
+  signature,
+});
+
+// Every fund-moving action gates on this. Fail-closed on any denial.
+const decision = await checkMandate(
+  signedMandate,
+  {
+    operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
+    budgetUsdc: 2_000_000n,
+    ratePerSecondUsdc: 500n,
+    maxDurationSeconds: 3_600,
+  },
+  0n, // spentSoFarUsdc under this mandate
+  { nowSeconds: Math.floor(Date.now() / 1000) },
+);
+
+if (!decision.allowed) throw new Error(`mandate denied: ${decision.reason}`);
+```
 
+### Agent wallet lifecycle: create/restore → fund → sign
+
+An agent gets a usable wallet entirely through this package — no out-of-band key. `resolveAgentWallet()`
+accepts an injected viem private key OR a Coinbase CDP config; the CDP path is **create-or-restore**:
+the same `ownerName` always resolves to the same CDP-managed address, so re-running with the same env
+restores the identical wallet instead of minting a new one.
+
+```ts
+import {
+  resolveAgentWallet,
+  parseAgentWalletEnv,
+  getWalletBalances,
+  faucetHint,
+  requestCdpFaucet,
+} from "@absol-labs/agent";
+import { MetrikClient } from "@absol-labs/sdk";
+import { CdpClient } from "@coinbase/cdp-sdk";
+
+// 1) Create or restore, from env (CDP_API_KEY_ID/CDP_API_KEY_SECRET/CDP_WALLET_SECRET +
+//    METRIK_AGENT_CDP_OWNER_NAME, or METRIK_AGENT_PRIVATE_KEY for an injected key).
+const wallet = await resolveAgentWallet(parseAgentWalletEnv());
+console.log("address:", wallet.account.address);
+
+// 2) Read balance.
+const metrik = MetrikClient.baseSepolia({ account: wallet.account });
+const balances = await getWalletBalances({
+  publicClient: metrik.publicClient,
+  address: wallet.account.address,
+  usdc: metrik.config.usdc,
+});
+
+// 3) Fund (testnet only) — a faucet hint, or request funds programmatically for a CDP wallet.
+console.log(faucetHint(84532)); // { cdpFaucetUrl, usdcFaucetUrl, ... }
+if (wallet.source === "cdp" && balances.nativeWei === 0n) {
+  const cdp = new CdpClient({
+    /* same CDP_* creds */
+  });
+  await requestCdpFaucet({
+    cdp,
+    address: wallet.account.address,
+    token: "eth",
+  });
+}
+
+// 4) Sign — `wallet.account` is a plain viem `Account`; no extra wrapper needed.
+const signature = await wallet.account.signTypedData?.(/* ... */);
 ```
-src/
-  mandates/   spend mandates — per-stream/total/rate/duration caps + operator
-              allowlists. The "agents can't run away with the wallet" guarantee.
-  sdk/        mandate-gated wrapper over @absol-labs/sdk for open/status/claim/reclaim.
-  x402/       Metrik as an x402 verified-streaming payment scheme / facilitator.
-  mcp/        an MCP server exposing hire/monitor/reclaim as agent tools.
-docs/
-  quickstart.md    zero → hired verified service in <10 min (start here).
-  agent-layer.md   the product design + investor narrative.
-  crewai.md        CrewAI's official MCP integration path for Metrik tools.
-  eliza.md         ElizaOS plugin/actions for hire/status/reclaim.
-  threat-model.md  the explicit autonomous-spend / key-custody review.
-  langchain.md     the LangChain tool adapter and example loop.
+
+`getWalletBalances` and `faucetHint`/`requestCdpFaucet` are deliberately thin: they don't introduce a
+second wallet system, they just fill in the "read balance" and "get testnet funds" gaps around the
+existing `resolveAgentWallet()` / `createWalletBackedAgentClient()` surface. `faucetHint` and
+`requestCdpFaucet` only support Base Sepolia (`84532`) — Metrik is testnet-only, single-chain.
+
+See [`scripts/e2e-hire.ts`](./scripts/e2e-hire.ts) for the full journey (create/restore wallet → fund →
+hire → invoke → settle) run against real Base Sepolia infrastructure: `pnpm e2e:hire` (needs real CDP
+creds — see `.env.example`).
+
+### Hire via x402: `402` challenge → signed payload → open stream
+
+```ts
+import {
+  VerifiedStreamX402Facilitator,
+  encodeX402PayloadHeader,
+} from "@absol-labs/agent";
+
+const facilitator = new VerifiedStreamX402Facilitator({
+  sdkConfig, // @absol-labs/sdk StreamProofClientConfig (chain, transport, account, escrow, usdc)
+});
+
+const challenge = facilitator.challenge({
+  operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
+  serviceRef: `0x${"ab".repeat(32)}`,
+  chainId: 84532,
+  escrow: sdkConfig.escrow,
+  ratePerSecondUsdc: 500n,
+  maxDurationSeconds: 3_600,
+  maxBudgetUsdc: 2_000_000n,
+});
+
+const header = encodeX402PayloadHeader({ challenge, signedMandate });
+const { streamId } = await facilitator.open(header); // mandate-gated, opens on-chain
 ```
 
-## The four pieces
-
-1. **x402 integration** — an agent hits a `402`, gets back a _verified-streaming_
-   payment requirement, and opens a stream instead of a one-shot payment. Reuses
-   the `402` negotiation surface and opens the on-chain stream through the SDK.
-2. **MCP server** — exposes "hire verified compute / get status / reclaim" as MCP
-   tools so any MCP agent (Claude, etc.) transacts natively. When Reclaim creds are
-   configured, it also exposes `prove_https_response` for public-response zkTLS proofs
-   tied to a tracked stream.
-3. **Framework tools** — LangChain, ElizaOS, and CrewAI now sit on top of the same
-   mandate-gated client. CrewAI consumes the existing MCP lane via its official MCP
-   integration; ElizaOS gets a direct plugin/action surface.
-4. **Spend mandates** — owner-signed EIP-712 budget/intent guardrails (AP2-style):
-   caps and allowlists enforced before any fund-moving action, with expiry and
-   local revocation checks.
-5. **zkTLS delivery proofs (L2, consumer zkTLS)** — the agent can now produce a Reclaim-backed proof
-   of the exact HTTPS response it consumed, bound to buyer/stream context and intended
-   to complement, not replace, oracle L1 evidence.
-
-Current real chain surface:
-
-- `VerifiedStreamAgentClient` wraps `@absol-labs/sdk` for `open`, `status`, `claim`,
-  `close`, and `reclaim`.
-- All autonomous fund-moving helpers (`openVerifiedStream()`, `claimStream()`,
-  `closeStream()`, `reclaimStream()`) enforce signed-mandate verification first and
-  hard-stop on denial.
-- `VerifiedStreamX402Facilitator` turns an HTTP `402` challenge into a real verified
-  stream open on Base Sepolia.
-- `createVerifiedStreamMcpServer()` exposes real MCP tools for `hire_verified_service`,
-  `check_stream_status`, `reclaim_unspent`, and `list_streams`.
-- `ReclaimConsumerProofService` generates a verifiable zkTLS proof of a consumed HTTPS
-  response, hashing the exact request/match/redaction policy before local verification.
-- `VerifiedStreamX402Facilitator.proveConsumedHttpsResponse()` binds that proof to the
-  same buyer/mandate context that opened the stream.
-- If Reclaim env vars are configured, `createVerifiedStreamMcpServer()` also exposes
-  `prove_https_response` for tracked streams. The MCP tool intentionally excludes secret
-  headers/cookies so credentials do not pass through model-visible tool arguments.
-- `createLangChainVerifiedStreamTools()` exposes the same hire/status/reclaim flow as
-  LangChain tools, including a `shouldStop` status signal for paused streams.
-- `createMetrikElizaPlugin()` (alias `metrikElizaPlugin`) exposes the hire/status/reclaim/close
-  flow as an ElizaOS plugin — canonical `HIRE_VERIFIED_SERVICE`, `CHECK_STREAM_STATUS`,
-  `RECLAIM_UNSPENT`, and `CLOSE_STREAM` actions with structured results and fail-closed
-  payload parsing. See [`examples/metrik-character.ts`](examples/metrik-character.ts).
-- `createCrewAiVerifiedStreamMcpConfig()` emits a CrewAI `MCPServerStdio` config for
-  the existing mandate-gated MCP server, with a tool filter limited to verified-stream
-  operations.
-- `resolveAgentWallet()` accepts either an injected viem signer or a provisioned
-  Coinbase CDP Server Wallet v2 account, then feeds that signer into the existing
-  agent/SDK path without ever exporting a private key.
-- Model A is infra-agnostic: a stream targets a seller payout wallet + `serviceRef`
-  only (no service-network field). Settlement is single-chain on Base Sepolia.
-
-## Wallet modes
-
-The agent layer now supports two wallet sources:
-
-- injected viem account via `METRIK_AGENT_PRIVATE_KEY`
-- Coinbase CDP Server Wallet v2 via `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`,
-  `CDP_WALLET_SECRET`, and `METRIK_AGENT_CDP_OWNER_NAME`
-
-CDP mode uses Coinbase-managed remote signing. Metrik never reads or exports the
-wallet private key. If `METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT=true`, the agent also
-provisions a per-agent ERC-4337 smart account owned by that CDP wallet for the later
-gas-abstraction path.
-
-## MCP server
-
-The MCP server runs over stdio and reads its settlement config from env. It never
+The scheme name is exported as `X402_SCHEME`; `parseX402ChallengeJson`,
+`parseX402PayloadHeader`, and `encodeX402PayloadHeader` handle the wire format on both sides.
+
+### Run the MCP server
+
+The server runs over stdio and reads its settlement config from the environment; it never
 asks for a raw key in a tool argument.
 
 ```bash
-cp .env.example .env
-pnpm mcp:stdio
+pnpm mcp:stdio   # or: pnpm mcp:http
+```
+
+Programmatically:
+
+```ts
+import {
+  METRIK_MCP_TOOLS,
+  startVerifiedStreamMcpServerStdio,
+  createVerifiedStreamMcpServerFromEnv,
+} from "@absol-labs/agent";
+
+console.log(METRIK_MCP_TOOLS.map((t) => t.name));
+// discover_services, hire_verified_service, check_stream_status,
+// reclaim_unspent, list_streams, prove_https_response
+
+await startVerifiedStreamMcpServerStdio(); // reads process.env, connects stdio
+// or, for custom transport wiring:
+// const runtime = await createVerifiedStreamMcpServerFromEnv();
+```
+
+Core env surface: `METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW`, `METRIK_AGENT_USDC`,
+`METRIK_AGENT_CHAIN_ID` (`84532`), and one wallet source — either
+`METRIK_AGENT_PRIVATE_KEY` (injected signer) or the CDP set (`CDP_API_KEY_ID`,
+`CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`, `METRIK_AGENT_CDP_OWNER_NAME`). Set
+`RECLAIM_APP_ID` / `RECLAIM_APP_SECRET` to enable the `prove_https_response` zkTLS tool.
+See [`docs/quickstart.md`](./docs/quickstart.md) for the full list.
+
+## Closed loop: `hire → invoke → (prove) → settle`
+
+Opening and funding a stream only pays for a service - it does not, on its own,
+authorize the buyer to _call_ it. The caller-auth gateway (metrik-protocol#62/#63/#64)
+closes that gap: a seller runs a small reverse-proxy gateway in front of its real
+service, and a buyer's SDK calls it directly with a short-lived, single-use,
+stream-bound `InvocationCapability` - no separate credential, no manual API key.
+
+**Seller side** - front any HTTP service with the reference gateway:
+
+```ts
+import {
+  CallerAuthGateway,
+  createCallerAuthGatewayServer,
+} from "@absol-labs/agent";
+
+const gateway = new CallerAuthGateway({
+  escrowAddress: "0x...", // the StreamEscrowV2 this service's streams settle on
+  rpcUrl: process.env.METRIK_GATEWAY_RPC_URL!,
+  serviceRef: "0x...", // this gateway's serviceRef - must match the listing
+});
+
+const server = createCallerAuthGatewayServer({
+  gateway,
+  upstreamUrl: "https://my-real-service.example.com",
+});
+await server.listen(8787);
 ```
 
-Env surface:
-
-- `METRIK_AGENT_RPC_URL`
-- `METRIK_AGENT_ESCROW`
-- `METRIK_AGENT_USDC`
-- `METRIK_AGENT_PRIVATE_KEY` (optional injected signer mode)
-- `CDP_API_KEY_ID`
-- `CDP_API_KEY_SECRET`
-- `CDP_WALLET_SECRET`
-- `METRIK_AGENT_CDP_OWNER_NAME`
-- `METRIK_AGENT_CDP_SMART_ACCOUNT_NAME`
-- `METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT`
-- `METRIK_AGENT_CHAIN_ID` (`84532` in Phase 2)
-- `METRIK_AGENT_CHAIN_NAME`
-- `METRIK_AGENT_MCP_STATE_FILE` (optional JSON registry for `list_streams`)
-- `RECLAIM_APP_ID` (optional, enables zkTLS proof generation)
-- `RECLAIM_APP_SECRET` (optional, enables zkTLS proof generation)
-- `METRIK_AGENT_RECLAIM_LOGS` (optional, defaults to `false`)
-
-## zkTLS / Reclaim (L2, consumer zkTLS)
-
-Use the programmatic proof service or the x402 facilitator when the consumed request
-needs private headers/cookies. Use the MCP tool only for public request inputs; it
-looks up stream context locally and avoids sending secrets through the model/tool layer.
-
-Every proof is verified locally against the exact URL/method/body/match/redaction
-policy the agent declared. This is an **L2 delivery signal** (consumer zkTLS) only: the verifier should
-cross-check it with L1/oracle observations before any settlement decision.
-
-## End-to-end journey (hire -> stream -> settle)
-
-The whole loop is proven end to end against a local node in
-[`test/e2e.int.test.ts`](test/e2e.int.test.ts) and scripted for integrators in
-[`examples/hire-stream-settle.ts`](examples/hire-stream-settle.ts):
-
-1. **Wallet** — a non-custodial injected-key viem account (credential-free; swap
-   in a Coinbase CDP wallet via `createWalletBackedAgentClient({ cdp: ... })`).
-2. **Mandate** — the owner signs an EIP-712 spend mandate (caps + operator
-   allowlist); every buyer-side fund move is mandate-gated and fail-closed.
-3. **Hire** — the x402 facilitator turns a `402` challenge into an escrowed
-   `openStream` on the hardened `StreamEscrow`.
-4. **Verify** — an M-of-N oracle quorum submits real EIP-712 `Delivered`
-   attestations; USDC accrues only for verified seconds (`checkedAt <=
-block.timestamp` is enforced on-chain).
-5. **Settle** — the operator claims its earned USDC net of the protocol fee, the
-   buyer closes and reclaims the unspent balance, a terminal `SlaReceiptIssued`
-   event is emitted, and every cent conserves exactly.
-
-The test also covers the **failure branch**: two failed checks auto-pause the
-stream, the buyer reclaims, and the operator can still claim only what it earned
-before the outage — buyer-favouring by construction.
-
-Run the example (needs Foundry `anvil`):
+Or run the ready-made standalone server from env (`METRIK_GATEWAY_ESCROW_ADDRESS`,
+`METRIK_GATEWAY_RPC_URL`, `METRIK_GATEWAY_SERVICE_REF`, `METRIK_GATEWAY_UPSTREAM_URL`,
+optional `METRIK_GATEWAY_CHAIN_ID` / `METRIK_GATEWAY_PORT` / `METRIK_GATEWAY_HOST`):
 
 ```bash
-anvil --silent &
-pnpm tsx examples/hire-stream-settle.ts
+pnpm gateway
 ```
 
-> The SLA receipt carries the raw material for on-chain reputation
-> (`verifiedSeconds`, `accrued`, `finalStatus`, `consecutiveFailures`). Feeding it
-> into `@absol-labs/shared`'s `slaReceiptRecordFromEvent` + `aggregateReputation`
-> (protocol#38) is a one-liner once the installed `@absol-labs/shared` is bumped to
-> the version that exports them (the pinned `0.3.0` does not yet).
+Every request must carry a valid capability; every failure mode (missing header, bad
+signature, wrong buyer, closed/expired/underfunded stream, replayed nonce, wrong
+method/path, wrong `serviceRef`) is rejected with a distinct machine-readable `reason`
+and a `402`/`403` - the real upstream is never touched on a rejection. Access is revoked
+automatically: once a stream is closed, expired, or reclaimed, the next on-chain read
+fails closed with no extra bookkeeping.
+
+**Buyer side** - after `hireVerifiedService`/`open()`, call the purchased service
+directly:
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import { createSdkInvokeStreamReader, invoke } from "@absol-labs/agent";
+
+const buyer = privateKeyToAccount(
+  process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}`,
+);
+const streamReader = createSdkInvokeStreamReader({
+  escrowAddress: "0x...",
+  rpcUrl: process.env.METRIK_AGENT_RPC_URL!,
+});
+
+const { response } = await invoke(
+  streamId, // from hireVerifiedService()
+  {
+    method: "POST",
+    path: "/v1/infer",
+    body: JSON.stringify({ prompt: "..." }),
+  },
+  {
+    streamReader,
+    buyer,
+    domain: { chainId: 84532, verifyingContract: "0x..." }, // same escrow as above
+    serviceBaseUrl: "https://gateway.example.com", // the seller's gateway, not the real upstream
+  },
+);
+
+console.log(await response.json());
+```
+
+`invoke()` loads the stream, fails closed BEFORE any network call if it is not active,
+is expired, or does not belong to the signing account, then builds and signs a
+capability scoped to exactly that one `method`+`path` (short expiry, single-use nonce)
+and attaches it as the `x-metrik-capability` header. Use `capabilityFor()` directly if
+you only need the signed capability without the SDK also performing the `fetch`.
+
+For a T2 (consumer-zkTLS) service, `invokeWithT2DeliveryProof()` attaches the SAME
+capability to the exact request the buyer's Reclaim attestor proves, so the
+capability-authorized call IS the delivery evidence - usage and proof become one action:
+
+```ts
+import { invokeWithT2DeliveryProof } from "@absol-labs/agent";
+
+const { t2 } = await invokeWithT2DeliveryProof(streamId, {
+  streamReader,
+  buyer,
+  domain: { chainId: 84532, verifyingContract: "0x..." },
+  request: {
+    url: "https://gateway.example.com/v1/infer",
+    method: "POST",
+    responseMatches: [{ type: "regex", value: '"result":"(?<result>.*)"' }],
+    nonceInjection: { in: "query", name: "nonce" },
+  },
+  intervalIndex: 0n,
+  nonce: deliveryNonce, // from GET /delivery/nonce
+});
+
+// t2.body is the exact POST /delivery/proof request payload.
+```
+
+## Consumer zkTLS (delivery proofs)
+
+`ReclaimConsumerProofService` (and `createReclaimConsumerProofServiceFromEnv`) generate a
+Reclaim-backed proof of the exact HTTPS response the agent consumed, verified locally
+against the declared URL, method, body, match, and redaction policy before it is trusted.
+`VerifiedStreamX402Facilitator.proveConsumedHttpsResponse()` binds that proof to the same
+buyer/mandate context that opened the stream. When credentials require private headers or
+cookies, use the programmatic service or the facilitator directly rather than the MCP tool,
+so secrets never pass through model-visible tool arguments. Treat the result as an L2
+signal: the verifier cross-checks it with L1/oracle evidence before any settlement decision.
+
+## Framework adapters
+
+Framework adapters are intentionally not re-exported from the top-level barrel — some pull
+heavy optional dependency graphs — so import each from its own subpath:
+
+```ts
+import { metrikActionProvider } from "@absol-labs/agent/agentkit";
+import { metrikElizaPlugin } from "@absol-labs/agent/eliza";
+import { createLangChainVerifiedStreamTools } from "@absol-labs/agent/langchain";
+import { createCrewAiVerifiedStreamMcpConfig } from "@absol-labs/agent/crewai";
+```
+
+Per-framework guides: [`docs/langchain.md`](./docs/langchain.md),
+[`docs/eliza.md`](./docs/eliza.md), [`docs/crewai.md`](./docs/crewai.md).
+
+## Requirements
+
+- Node **`>=20 <21`**, package manager `pnpm@9.15.x`.
+- **ESM only** — this package has no CommonJS build; consume it from an ESM context.
+- Framework adapters need their matching optional peer dependency installed. Known caveat:
+  the AgentKit adapter pulls a heavy graph (`@coinbase/agentkit` / ZeroDev) that can break a
+  flat `npm install`; prefer `pnpm` and import the adapter only from its `@absol-labs/agent/agentkit`
+  subpath.
 
 ## Develop
 
@@ -189,8 +392,15 @@ pnpm test
 pnpm build
 ```
 
-> The x402 facilitator, zkTLS proof path, signed-mandate engine, MCP server, and
-> framework adapters are all real and tested in-repo. The `*.int.test.ts`
-> integration suites deploy the hardened `StreamEscrow` on a throwaway `anvil`
-> node and self-skip cleanly when `anvil` is not on `PATH`, so default CI stays
-> green.
+The x402 facilitator, zkTLS proof path, signed-mandate engine, MCP server, and framework
+adapters are all real and tested in-repo. The `*.int.test.ts` integration suites deploy the
+hardened `StreamEscrow` on a throwaway `anvil` node and self-skip when `anvil` is not on
+`PATH`, so default CI stays green. A full hire → stream → settle walkthrough lives in
+[`examples/hire-stream-settle.ts`](examples/hire-stream-settle.ts).
+
+## Links
+
+- Frontdoor: [github.com/Absol-Labs](https://github.com/Absol-Labs)
+- Docs: [metrik.live](https://metrik.live) · App: [app.metrik.live](https://app.metrik.live)
+- SDK: [`@absol-labs/sdk`](https://github.com/Absol-Labs/metrik-sdk)
+- Quickstart: [`docs/quickstart.md`](./docs/quickstart.md) · Design + narrative: [`docs/agent-layer.md`](./docs/agent-layer.md) · Security review: [`docs/threat-model.md`](./docs/threat-model.md)