@absol-labs/agent 0.8.0 → 0.9.0

package/docs/mcp-hosted.md

@@ -0,0 +1,137 @@
+# Hosted MCP over Streamable HTTP
+
+The agent lane ships two MCP transports over the **same** tool set
+(`hire_verified_service`, `check_stream_status`, `reclaim_unspent`, `list_streams`,
+and the optional `prove_https_response`):
+
+- **stdio** (`src/mcp/stdio.ts`, `pnpm mcp:stdio`) — local dev, one process per
+  caller. Unchanged.
+- **Streamable HTTP** (`src/mcp/http.ts` + `src/mcp/http-server.ts`,
+  `pnpm mcp:http`) — a hosted, **multi-tenant**, per-caller-authenticated
+  endpoint suitable for deployment. This document covers the HTTP transport.
+
+The HTTP transport uses the MCP SDK's `StreamableHTTPServerTransport` (the
+current remote transport; the deprecated HTTP+SSE transport is not used). It
+speaks the standard Streamable HTTP session contract: `POST /mcp` for JSON-RPC
+requests (an `initialize` opens a session and the server returns an
+`Mcp-Session-Id` header), `GET /mcp` for the server→client SSE stream, and
+`DELETE /mcp` to end a session — all carrying the `Mcp-Session-Id` header once a
+session exists.
+
+## Security model (fail-closed)
+
+- **Per-caller auth before anything runs.** Every request must carry
+  `Authorization: Bearer <token>`. A missing or invalid token is rejected with
+  `401` **before** any MCP session is created or any tool executes — so an
+  unauthenticated request can never move funds or read another caller's state.
+- **Constant-time token comparison.** Tokens are compared via SHA-256 +
+  `crypto.timingSafeEqual` across all configured tenants with no early exit;
+  tokens are never logged.
+- **Tenant isolation.** Each valid token maps to its **own** tenant context —
+  its own wallet-backed agent client and its own stream registry. One caller
+  can never drive another caller's funds or observe another caller's streams.
+  MCP sessions are bound to the tenant that opened them: presenting another
+  tenant's `Mcp-Session-Id` is rejected with `403`; an unknown session id is
+  `404`.
+- **Refuses to run open.** If no tenants/tokens are configured, the server
+  throws before binding — it will never serve an unauthenticated endpoint.
+- **No stack traces leak.** Errors are returned as generic JSON-RPC error
+  envelopes; internal detail stays server-side.
+- **CORS** is off by default (same-origin / non-browser clients). Set
+  `METRIK_MCP_ALLOWED_ORIGINS` to opt specific browser origins in.
+
+## Environment contract
+
+| Variable                     | Required | Default   | Meaning                                                                |
+| ---------------------------- | -------- | --------- | ---------------------------------------------------------------------- |
+| `METRIK_MCP_TENANTS`         | **yes**  | —         | JSON array of tenant configs (below). Empty/missing ⇒ refuse to start. |
+| `PORT` / `METRIK_MCP_PORT`   | no       | `8080`    | Listen port.                                                           |
+| `METRIK_MCP_HOST`            | no       | `0.0.0.0` | Bind host.                                                             |
+| `METRIK_MCP_PATH`            | no       | `/mcp`    | MCP endpoint path.                                                     |
+| `METRIK_MCP_ALLOWED_ORIGINS` | no       | _(none)_  | Comma-separated CORS origins, or `*`.                                  |
+
+Each entry in `METRIK_MCP_TENANTS` is:
+
+```jsonc
+{
+  "id": "acme", // stable tenant id (routing/logging only)
+  "token": "<secret-bearer>", // the caller's bearer token — never logged
+  "env": {
+    // optional: layered over the process env to
+    "METRIK_AGENT_CDP_OWNER_NAME": "acme-agent", // build THIS tenant's wallet
+  },
+}
+```
+
+A tenant's `env` is merged over the process environment and used to build that
+tenant's isolated, wallet-backed agent client via the same
+`METRIK_AGENT_*` / wallet / Reclaim variables the stdio server uses
+(`METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW`, `METRIK_AGENT_USDC`,
+`METRIK_AGENT_PRIVATE_KEY` **or** the `CDP_*` wallet vars, etc. — see
+`src/mcp/server.ts` and `src/wallet/provider.ts`). Tenants that share the same
+network but need distinct wallets override only the wallet vars in their `env`.
+
+> Provide tokens and wallet secrets through your host's secret manager / env UI.
+> Never commit them, and never bake them into the image.
+
+## Run it
+
+```bash
+export METRIK_AGENT_RPC_URL="https://base-sepolia.example/rpc"
+export METRIK_AGENT_ESCROW="0x21948a5E6AE8d9A3D1050791AB6138657Fb54286"
+export METRIK_AGENT_USDC="0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+# ... wallet vars (private key or CDP) ...
+export METRIK_MCP_TENANTS='[{"id":"acme","token":"REPLACE_WITH_SECRET"}]'
+export PORT=8080
+
+pnpm mcp:http          # dev (tsx)
+# or, from a build:
+node dist/mcp/http-server.js
+```
+
+The process binds `0.0.0.0:$PORT` and logs only its address (never secrets).
+`SIGINT`/`SIGTERM` trigger a graceful shutdown of all live sessions.
+
+## Connect an MCP client
+
+Point any Streamable HTTP MCP client at `http(s)://<host>:<port>/mcp` with the
+tenant's bearer token. With the TypeScript SDK:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(
+  new URL("https://mcp.example.com/mcp"),
+  {
+    requestInit: {
+      headers: { Authorization: `Bearer ${process.env.METRIK_MCP_TOKEN}` },
+    },
+  },
+);
+const client = new Client({ name: "my-agent", version: "1.0.0" });
+await client.connect(transport);
+await client.listTools();
+await client.callTool({ name: "list_streams", arguments: {} });
+```
+
+Claude Desktop / other config-driven clients: add a remote MCP server pointing
+at the `/mcp` URL and set the `Authorization: Bearer <token>` header. The
+transport handles the session id, POST/GET/DELETE lifecycle automatically.
+
+## Programmatic embedding
+
+The transport is also exported from the package root for hosting inside another
+service:
+
+- `createHostedMcpHttpServer({ resolver, path?, allowedOrigins? })` — build a
+  Node `http.Server` around a `TenantResolver`; `listen(port, host)` /
+  `close()`.
+- `StaticTenantResolver` — constant-time, in-memory resolver over a list of
+  `HostedMcpTenant`s.
+- `parseHostedMcpServerConfig(env)` / `createHostedMcpTenants(config)` /
+  `startHostedMcpHttpServerFromEnv(env)` — the env-driven wiring used by
+  `pnpm mcp:http`.
+
+Supply your own `TenantResolver` to source tokens/tenants from a database or a
+secrets service instead of env.

package/docs/privy-embedded-wallet.md

@@ -0,0 +1,102 @@
+# Privy embedded-wallet integration
+
+`@absol-labs/agent` provides a small, provider-neutral adapter for a
+user-owned Privy embedded **EOA**. The site or host application must first
+authenticate the user with Privy's client SDK and obtain that user's EIP-1193
+wallet provider. The agent package does not authenticate users, create wallets
+from an app id alone, receive an app secret, or persist key material.
+
+```ts
+import { http } from "viem";
+import { baseSepolia } from "viem/chains";
+import {
+  createWalletBackedAgentClient,
+  type PrivyEip1193Provider,
+} from "@absol-labs/agent";
+
+// The authenticated Privy wallet/session is created by the host application.
+const provider: PrivyEip1193Provider =
+  await host.getAuthenticatedPrivyProvider();
+const address = await host.getAuthenticatedPrivyAddress();
+
+const { wallet, agentClient } = await createWalletBackedAgentClient(
+  {
+    chain: baseSepolia,
+    // The Privy mode replaces this transport with the authenticated provider
+    // so writes use eth_sendTransaction. It remains the default for other modes.
+    transport: http(process.env.BASE_SEPOLIA_RPC_URL!),
+    escrow: "0x…",
+    usdc: "0x…",
+  },
+  {
+    privy: {
+      appId: "your-public-privy-app-id",
+      address,
+      provider,
+      chainId: 84532,
+    },
+  },
+);
+
+// `wallet.account` is a viem-compatible JSON-RPC EOA. Every autonomous write
+// still goes through the signed Metrik spend-mandate checks in agentClient.
+await wallet.account.signMessage({ message: "user-approved test" });
+```
+
+The adapter verifies Base Sepolia (`chainId: 84532`) and the configured address
+against `eth_chainId` and `eth_accounts` before construction and before every
+`personal_sign` or `eth_signTypedData_v4` request. Contract writes are sent
+through the same authenticated provider with `eth_sendTransaction`; the adapter
+does not claim access to raw transaction signatures. A network or account switch
+fails closed with `PrivyEmbeddedWalletError`.
+
+## Headless external-agent session
+
+The Metrik dApp can attach a Privy additional signer under a non-empty Privy policy,
+collect an owner-signed Metrik spend mandate, and exchange those approvals for a
+short-lived broker token. An external agent adapts the copied session JSON without any
+Privy app secret or wallet key:
+
+```ts
+import {
+  createPrivySessionProvider,
+  createWalletBackedAgentClient,
+} from "@absol-labs/agent";
+
+const session = JSON.parse(process.env.METRIK_AGENT_SESSION_JSON!);
+const provider = createPrivySessionProvider({
+  brokerUrl: session.brokerUrl,
+  sessionToken: session.sessionToken,
+  address: session.address,
+});
+
+const { agentClient } = await createWalletBackedAgentClient(sdkConfig, {
+  privy: {
+    appId: session.appId,
+    address: session.address,
+    provider,
+    chainId: session.chainId,
+  },
+});
+```
+
+The broker permits only bounded USDC approval, V2 stream open/close/reclaim, and
+short-lived invocation-capability signatures for an active buyer stream. It stores a
+hash—not the plaintext—of the session token. Revoked or expired sessions fail closed.
+It asks Privy to sponsor only the first successful write in the session.
+
+## Boundary and limitations
+
+- The adapter supports a user-owned Privy EOA only.
+- It does not claim ERC-4337, EIP-1271, or smart-account support.
+- The browser adapter alone does not provide headless access. Headless operation requires
+  the deployed broker, a real Privy additional-signer policy, and user approval in the dApp.
+- The provider must implement the standard `eth_sendTransaction` EIP-1193 path.
+  In Privy mode, `createWalletBackedAgentClient` replaces the SDK transport with
+  that authenticated provider so a separate public RPC cannot bypass the wallet.
+- The host must keep the Privy app secret and any authorization material
+  server-side. Only the public app id belongs in browser configuration.
+
+Do not use an unauthenticated or arbitrary EIP-1193 provider as a substitute
+for Privy's authenticated user wallet. Do not put a Privy app secret in
+`PrivyEmbeddedWalletConfig`.

package/docs/quickstart.md

@@ -0,0 +1,370 @@
+# Quickstart — hire a verified service in <10 minutes
+
+Get an AI agent from zero to a **hired, oracle-verified, buyer-recoverable** service stream
+on Base Sepolia. Every code block below uses the real, current exports of
+`@absol-labs/agent` — no pseudocode.
+
+> _x402 proves the payment, Metrik proves the delivery._
+
+**What you get:** an owner-signed spend mandate caps how much/how fast/how long/with whom
+your agent can spend; the agent escrows USDC and pays a seller **only for the delivery an
+independent oracle proves**. In V2, failed or unproven intervals do not advance cumulative
+entitlement. The stream remains active until the buyer closes it or it expires, and reclaim
+follows the checkpoint finalization or escape-window rules.
+
+Base Sepolia constants used throughout (chainId **84532**):
+
+| Thing  | Address                                      |
+| ------ | -------------------------------------------- |
+| Escrow | `0x21948a5E6AE8d9A3D1050791AB6138657Fb54286` |
+| USDC   | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
+
+A complete, runnable version of this journey lives in
+[`scripts/e2e-cdp.ts`](../scripts/e2e-cdp.ts) (the live CI E2E, metrik-agent#32) — treat
+it as the working reference.
+
+---
+
+## 1. Install
+
+```bash
+pnpm add @absol-labs/agent
+```
+
+`@absol-labs/agent` and its `@absol-labs/*` dependencies are published to the **public
+npm registry** — no `.npmrc`, scope registry, or auth token is required to install.
+
+**Runtime:** Node **20.x** (the package pins `engines.node` to `>=20 <21`; 20.19+
+recommended). The Coinbase AgentKit action reads decorator metadata via
+`reflect-metadata`, which only exists in the **built** output (`tsc` emits decorator
+metadata; `tsx`/esbuild does not) — so `import "reflect-metadata"` **before** importing
+the package, and for the AgentKit path import from the built package, not raw `.ts`.
+
+---
+
+## 2. Provision a wallet
+
+Two supported wallet sources, both resolved through `resolveAgentWallet` /
+`parseAgentWalletEnv`. Metrik never reads or exports a private key in CDP mode.
+
+**Injected key (fastest for testnet):**
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import { resolveAgentWallet } from "@absol-labs/agent";
+
+const account = privateKeyToAccount(
+  process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}`,
+);
+const wallet = await resolveAgentWallet({ injectedAccount: account });
+// wallet.source === "injected"; wallet.account is a viem Account
+```
+
+**Coinbase CDP Server Wallet v2 (production, remote signing):**
+
+```ts
+import { CdpClient } from "@coinbase/cdp-sdk";
+import { resolveAgentWallet, type CdpClientLike } from "@absol-labs/agent";
+
+const cdp = new CdpClient({
+  apiKeyId: process.env.CDP_API_KEY_ID,
+  apiKeySecret: process.env.CDP_API_KEY_SECRET,
+  walletSecret: process.env.CDP_WALLET_SECRET,
+});
+const wallet = await resolveAgentWallet(
+  { cdp: { ownerName: process.env.METRIK_AGENT_CDP_OWNER_NAME! } },
+  { createCdpClient: () => cdp as unknown as CdpClientLike },
+);
+// under the hood: cdp.evm.getOrCreateAccount({ name: ownerName })
+```
+
+CDP env: `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`,
+`METRIK_AGENT_CDP_OWNER_NAME` (+ optional `METRIK_AGENT_CDP_SMART_ACCOUNT_NAME`,
+`METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT`). Or set `METRIK_AGENT_PRIVATE_KEY` and let
+`parseAgentWalletEnv(process.env)` pick the injected path automatically.
+
+---
+
+## 3. Sign a spend mandate
+
+The mandate is the guardrail: caps + allowlists checked **before any transaction**,
+fail-closed. Build the EIP-712 payload with `createSpendMandateTypedData`, sign it with
+the wallet, then validate the shape with `signedSpendMandateSchema`.
+
+```ts
+import {
+  spendMandateSchema,
+  createSpendMandateTypedData,
+  signedSpendMandateSchema,
+} from "@absol-labs/agent";
+import { generatePrivateKey } from "viem/accounts"; // handy for a random bytes32 mandateId
+
+const nowSeconds = Math.floor(Date.now() / 1000);
+const account = wallet.account;
+
+const mandate = spendMandateSchema.parse({
+  maxPerStreamUsdc: 100_000n, // 0.1 USDC (6 decimals) — max deposit per stream
+  maxTotalUsdc: 100_000n, // cumulative cap across all streams
+  maxRatePerSecondUsdc: 1n, // max accrual rate the agent may agree to
+  maxDurationSeconds: 3600, // max stream lifetime
+  allowedOperators: [account.address as `0x${string}`], // omit/empty ⇒ any operator
+  expiresAt: nowSeconds + 365 * 24 * 60 * 60,
+});
+
+const unsigned = {
+  mandateId: generatePrivateKey(), // any 32-byte hex
+  owner: account.address as `0x${string}`,
+  chainId: 84532,
+  issuedAt: nowSeconds,
+  mandate,
+};
+
+const signature = await account.signTypedData!(
+  createSpendMandateTypedData(unsigned),
+);
+const signedMandate = signedSpendMandateSchema.parse({
+  ...unsigned,
+  signature,
+});
+```
+
+Denials are machine-readable (`MandateDecision.reason`): `exceeds-per-stream-cap`,
+`exceeds-total-cap`, `exceeds-rate-cap`, `exceeds-duration-cap`, `operator-not-allowed`,
+`mandate-expired`, `mandate-revoked`, `invalid-signature`.
+
+---
+
+## 4. Discover a service
+
+Before you can hire, you need a seller. `discoverServices` reads the Metrik listings
+registry and returns typed, **verified** services — it recovers each row's operator
+signature and drops any listing whose signature does not match its operator or whose
+`serviceRef` is not the one derived from its signed record. It never returns an
+unverifiable listing.
+
+**Zero configuration**: the default read source is
+`https://oracle.metrik.live/listings`, the oracle's public, credential-free,
+CORS-enabled endpoint. You need no API key and no setup.
+
+**It fails loudly.** An unreachable, erroring, or non-200 registry throws
+`RegistryUnavailableError` rather than returning `[]`. "The marketplace was never
+reached" and "the marketplace is empty" are different facts, and a caller that reads
+`[]` and gives up has been misled. Catch it only if your code can genuinely handle
+not having reached the marketplace at all.
+
+```ts
+import { discoverServices, RegistryUnavailableError } from "@absol-labs/agent";
+
+let services;
+try {
+  services = await discoverServices({ limit: 10 });
+} catch (error) {
+  if (error instanceof RegistryUnavailableError) {
+    // The registry was never read — do NOT treat this as "no services".
+    throw error;
+  }
+  throw error;
+}
+
+for (const s of services) {
+  console.log(`${s.serviceRef} → ${s.operator} @ ${s.accessUrl} [${s.access}]`);
+}
+
+const target = services[0]; // pick one to hire
+```
+
+Each `ServiceListing` is
+`{ serviceRef, operator, publicUrl, access, accessUrl, signed, category }`, with
+`serviceRef`/`operator`/`publicUrl`/`accessUrl` taken from the **signed** record, never
+from the unsigned envelope columns. Invoke against `accessUrl` — for a `gated` listing
+that is the operator-signed gateway origin, and a gated listing with no signed access
+URL is dropped rather than invoked against an unsigned one.
+
+Need the registry's full answer — `registryAvailable`, `source`, tier and verification
+summaries, and a note explaining when a non-empty source filtered to nothing? Call
+`discoverServicesDetailed` instead; it returns the SDK result verbatim.
+
+> The `category` filter matches only on an authenticated PostgREST read; the public
+> endpoint serves signed records and carries no category column. Supplying `apiKey`
+> also requires an explicit `registryUrl` (a Supabase project URL) — the public
+> default is not a PostgREST base, so that combination is rejected rather than
+> silently 404ing.
+
+---
+
+## 5. Hire a verified service
+
+`VerifiedStreamAgentClient.openVerifiedStream` runs the mandate guard, then escrows USDC
+and opens the metered stream through `@absol-labs/sdk`. It throws `MandateDeniedError`
+before any transaction if the hire breaches the mandate. Feed it the `operator` +
+`serviceRef` from a discovered service.
+
+```ts
+import { VerifiedStreamAgentClient } from "@absol-labs/agent";
+import type { StreamProofClientConfig } from "@absol-labs/sdk";
+import { baseSepolia } from "viem/chains";
+import { http } from "viem";
+
+const sdkConfig: StreamProofClientConfig = {
+  chain: baseSepolia,
+  transport: http("https://sepolia.base.org"),
+  account,
+  escrow: "0x21948a5E6AE8d9A3D1050791AB6138657Fb54286",
+  usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+};
+
+const agent = new VerifiedStreamAgentClient(sdkConfig);
+
+const hire = await agent.openVerifiedStream({
+  operator: target.operator, // seller payout wallet from discovery
+  serviceRef: target.serviceRef, // bytes32 the oracle verifies delivery against
+  budgetUsdc: 100_000n,
+  ratePerSecondUsdc: 1n,
+  maxDurationSeconds: 3600,
+  signedMandate,
+  spentSoFarUsdc: 0n,
+  nowSeconds: Math.floor(Date.now() / 1000),
+});
+
+console.log(`stream ${hire.streamId} opened, tx=${hire.txHash}`);
+```
+
+Metrik is infra-agnostic (Model A): a stream targets a seller's payout wallet +
+`serviceRef` only — there is no service-network field. Settlement is single-chain
+on Base Sepolia.
+
+---
+
+## 6. Monitor
+
+`getStreamStatus` returns the on-chain stream plus derived `claimable`/`reclaimable`:
+
+```ts
+const { stream, claimable, reclaimable } = await agent.getStreamStatus(
+  hire.streamId,
+);
+
+console.log(stream.status); // "active" | "closed" in StreamEscrowV2
+console.log(stream.accrued); // USDC accrued for oracle-verified delivery
+console.log(stream.deposit); // total escrowed
+console.log(claimable); // claimable by the seller now
+console.log(reclaimable); // reclaimable by the buyer now
+```
+
+Payment only ever accrues for verified seconds. In StreamEscrowV2, a checkpoint advances
+the operator's cumulative entitlement; a failed or unproven interval does not. Failure does
+not change the stream from active to paused: the stream stays active until buyer close or
+expiry. The buyer reclaims after checkpoint finalization, or through the escape-window path
+when checkpoints are unavailable.
+
+---
+
+## 7. Settle
+
+**Seller** claims earned USDC (net of protocol fee); **buyer** closes and reclaims the
+unspent balance. All three are mandate-gated.
+
+```ts
+const now = () => Math.floor(Date.now() / 1000);
+const auth = { streamId: hire.streamId, signedMandate, spentSoFarUsdc: 0n };
+
+// Seller side — claim what delivery earned:
+await agent.claimStream({ ...auth, nowSeconds: now() });
+
+// Buyer side — close, then reclaim every unspent cent:
+await agent.closeStream({ ...auth, nowSeconds: now() });
+const { reclaimResult } = await agent.reclaimStream({
+  ...auth,
+  nowSeconds: now(),
+});
+// or in one call: agent.reclaimStream({ ...auth, nowSeconds: now(), closeFirst: true })
+```
+
+**Buyer-protection guarantee:** the buyer can recover unspent USDC under the checkpoint /
+escape-window rules, and `claimed + fees + reclaimed == deposit` conserves the escrowed
+funds exactly.
+
+---
+
+## 8. Four ways to integrate
+
+Pick the surface that matches your stack — all four sit on the **same** mandate-gated
+client and business logic.
+
+**(a) SDK client directly** — the path used above:
+
+```ts
+import { VerifiedStreamAgentClient } from "@absol-labs/agent";
+const agent = new VerifiedStreamAgentClient(sdkConfig);
+await agent.openVerifiedStream({
+  /* ... */
+});
+```
+
+**(b) Coinbase AgentKit** — exposes `discover_services`, `hire_verified_service`,
+`check_stream_status`, `reclaim_unspent`, `close_stream` as native actions:
+
+```ts
+import "reflect-metadata";
+import { createMetrikAgentKit } from "@absol-labs/agent/agentkit";
+
+const agentKit = await createMetrikAgentKit({
+  walletProvider, // a CdpEvmWalletProvider / CdpSmartWalletProvider
+  metrik: { signedMandate, sdkConfig }, // chainId defaults to 84532
+});
+// then agentKit.getVercelAITools() or getLangChainTools() — or LangChain directly:
+// import { createLangChainVerifiedStreamTools } from "@absol-labs/agent/langchain";
+```
+
+**(c) MCP** — local stdio for dev, hosted HTTP for deployment:
+
+```bash
+pnpm mcp:stdio   # local: one process per caller (src/mcp/stdio.ts)
+pnpm mcp:http    # hosted: multi-tenant Streamable HTTP, per-caller bearer auth
+```
+
+Tools: `discover_services`, `hire_verified_service`, `check_stream_status`, `reclaim_unspent`,
+`list_streams` (+ `prove_https_response` when Reclaim creds are set). Env is read via
+`parseMetrikAgentEnv` (`METRIK_AGENT_RPC_URL` / `_ESCROW` / `_USDC` + wallet vars). The
+hosted endpoint requires `Authorization: Bearer <token>` before anything runs — see
+[`docs/mcp-hosted.md`](./mcp-hosted.md).
+
+**Spend mandate (required).** An MCP caller (an LLM) cannot produce an EIP-712 signature,
+so the mandate is **not** a tool argument — the server holds it, self-signed from its own
+funding wallet and bounded by env caps you set. A fund-moving MCP server **refuses to
+start** without an explicit spend ceiling:
+
+```bash
+METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC=100000000     # 100 USDC (atomic, 6dp) per stream
+METRIK_AGENT_MANDATE_MAX_TOTAL_USDC=1000000000         # 1000 USDC cumulative across streams
+METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC=1000000  # 1 USDC/sec ceiling
+METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS=86400        # max stream lifetime
+METRIK_AGENT_MANDATE_ALLOWED_OPERATORS=0xabc...,0xdef... # optional CSV allowlist; omit = any
+METRIK_AGENT_MANDATE_TTL_SECONDS=86400                 # optional mandate lifetime (default 24h)
+```
+
+The `hire_verified_service` tool then takes only the hire terms (`operator`, `serviceRef`,
+`budgetUsdc`, `ratePerSecondUsdc`, optional `durationSeconds`), all USDC in **atomic
+6-decimal units**. The cumulative cap (`maxTotalUsdc`) is enforced by default; mandate
+revocation requires wiring a revocation resolver (the server warns once on stderr if none
+is set).
+
+**(d) ElizaOS** — a plugin with `DISCOVER_SERVICES`, `HIRE_VERIFIED_SERVICE`,
+`CHECK_STREAM_STATUS`, `RECLAIM_UNSPENT`, `CLOSE_STREAM` actions:
+
+```ts
+import { metrikElizaPlugin } from "@absol-labs/agent/eliza"; // === createMetrikElizaPlugin
+
+const plugin = metrikElizaPlugin({ agentClient: agent }); // agent = VerifiedStreamAgentClient
+// register `plugin` on your Eliza character — see docs/eliza.md + examples/metrik-character.ts
+```
+
+---
+
+## Honesty note
+
+Metrik proves **verified delivery** (responded, correctly-shaped, within SLA to real
+traffic) — **not output correctness** (that the model's answer is right). Pitch and treat
+it accordingly. The full journey, run live against the real deployed escrow on Base
+Sepolia, is [`scripts/e2e-cdp.ts`](../scripts/e2e-cdp.ts) (`pnpm build:e2e && pnpm
+e2e:cdp`) — the working reference for everything above.