@absol-labs/agent 0.7.3 → 0.9.0

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.

package/docs/threat-model.md

@@ -0,0 +1,160 @@
+# Agent Threat Model
+
+This document is the agent-layer security review for Phase 2. It covers the
+autonomous spend surface in `streamproof-agent` and maps each threat to the
+current mitigation, code path, and test coverage.
+
+It complements the cross-repo rules in
+[`Absol-Labs/.github/CONTRIBUTING.md`](../../streamproof-dotgithub/CONTRIBUTING.md)
+and the per-repo security pass in [`AGENTS.md`](../AGENTS.md). The same
+non-negotiables apply here:
+
+- no fake green paths
+- no secrets in git or logs
+- fail-closed autonomous spend
+- explicit signing only through the configured account or wallet
+
+## Scope
+
+In scope:
+
+- signed spend mandates in [`src/mandates/mandate.ts`](../src/mandates/mandate.ts)
+- the mandate-gated SDK wrapper in [`src/sdk/client.ts`](../src/sdk/client.ts)
+- x402 verified-stream opens in [`src/x402/facilitator.ts`](../src/x402/facilitator.ts)
+- MCP fund-moving tools in [`src/mcp/server.ts`](../src/mcp/server.ts)
+- zkTLS consumer delivery proofs in [`src/zktls/reclaim.ts`](../src/zktls/reclaim.ts)
+- wallet custody in [`src/wallet/provider.ts`](../src/wallet/provider.ts)
+
+Out of scope:
+
+- oracle correctness
+- escrow correctness
+- decentralized verifier / slashing / dispute work
+
+## Threat Map
+
+| Threat                          | Why it matters                                                                                                                 | Current mitigation                                                                                                                                                                                                                                                                                                      | Test / evidence                                                                                                                                                                                                                                                                                    | Residual risk                                                                                                                                                                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Runaway spend                   | A prompt or tool call opens streams beyond the owner's intent.                                                                 | Every autonomous fund-moving path calls `checkMandate()` before the SDK can write: `openVerifiedStream()`, `claimStream()`, `closeStream()`, `reclaimStream()`, MCP `hire_verified_service`, and MCP `reclaim_unspent`. Mandates cap per-stream, cumulative spend, rate, duration, and operator. Denial is a hard stop. | [`test/mandate.test.ts`](../test/mandate.test.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts), [`test/x402.int.test.ts`](../test/x402.int.test.ts)                                                                                         | `spentSoFarUsdc` and revocation data are resolver inputs. If an integrator provides stale values, the agent still fails closed on signature/expiry/operator checks, but cumulative-cap freshness depends on the integrator's state source. |
+| Mandate bypass                  | A caller skips the mandate layer and reaches the SDK write path directly from the agent layer.                                 | The agent wrapper no longer exposes ungated autonomous write helpers. Existing-stream actions re-read the stream and authorize against the actual operator before `claim`, `close`, or `reclaim`. MCP also prechecks before dispatch.                                                                                   | [`src/sdk/client.ts`](../src/sdk/client.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts)                                                                                                                                                    | A caller can still use `@absol-labs/sdk` directly outside this repo. That is expected; this document only claims the agent layer itself is mandate-gated.                                                                                  |
+| Key exposure                    | The agent leaks a private key through logs, env parsing, tool args, or local persistence.                                      | No MCP tool accepts a raw key. Wallet selection is explicit: injected viem account, CDP Server Wallet v2, or an authenticated Privy embedded EOA provider. CDP/Privy paths remote-sign and never export private keys into Metrik code. `.env.example` contains names only.                                              | [`src/wallet/provider.ts`](../src/wallet/provider.ts), [`test/wallet.test.ts`](../test/wallet.test.ts), [`test/privy-wallet.test.ts`](../test/privy-wallet.test.ts), [`README.md`](../README.md)                                                                                                   | Injected-key mode is still as safe as the caller's own host. Privy authentication/session revocation remains the host/provider's responsibility.                                                                                           |
+| Prompt-injection-driven spend   | A hostile response or tool output tries to coerce the agent into paying a different operator or budget.                        | Structured inputs are validated, x402 settlement targets must match the configured chain/escrow, and any spend still must satisfy the owner's signed mandate.                                                                                                                                                           | [`src/x402/facilitator.ts`](../src/x402/facilitator.ts), [`test/x402.test.ts`](../test/x402.test.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts)                                                                                                                                      | Prompt injection can still trigger tool invocation attempts. The safety claim is not "the prompt cannot be attacked"; it is "the attack cannot exceed the mandate or redirect settlement silently."                                        |
+| Mandate replay                  | A previously valid signed mandate is replayed after revocation or outside the intended lifetime.                               | Mandates are EIP-712 signed over `mandateId`, `owner`, `chainId`, `issuedAt`, expiry, and policy hashes. `checkMandate()` verifies signature, revocation, expiry, then policy. Integrators can revoke by `mandateId` and track cumulative spend.                                                                        | [`src/mandates/mandate.ts`](../src/mandates/mandate.ts), [`test/mandate.test.ts`](../test/mandate.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts)                                                                                                                                              | Replay protection is only as strong as revocation and cumulative-spend state freshness. The signed payload itself is bound to one chain and one owner, but revocation is local state today.                                                |
+| False or weak delivery evidence | A consumer submits a proof that is validly signed by the zkTLS system but not bound to the intended request or stream context. | The Reclaim adapter re-verifies every proof locally against the exact URL/method/body/match/redaction spec supplied by the caller, and binds the proof context to buyer/stream metadata before returning it. MCP only exposes the public-request subset so secrets do not leak through tool arguments.                  | [`src/zktls/reclaim.ts`](../src/zktls/reclaim.ts), [`src/x402/facilitator.ts`](../src/x402/facilitator.ts), [`src/mcp/server.ts`](../src/mcp/server.ts), [`test/reclaim.test.ts`](../test/reclaim.test.ts), [`test/x402.test.ts`](../test/x402.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts) | L2 is still consumer-supplied evidence. A malicious consumer can withhold proofs, and settlement must still treat L1/oracle evidence as authoritative on failure, ambiguity, and expiry.                                                   |
+
+## Fund-Moving Paths
+
+These are the autonomous fund-moving paths in the current agent layer:
+
+1. `VerifiedStreamAgentClient.openVerifiedStream()`
+2. `VerifiedStreamAgentClient.claimStream()`
+3. `VerifiedStreamAgentClient.closeStream()`
+4. `VerifiedStreamAgentClient.reclaimStream()`
+5. MCP `hire_verified_service`
+6. MCP `reclaim_unspent`
+7. x402 `open()` via `VerifiedStreamX402Facilitator`
+
+All of them now pass a signed mandate check before the SDK can send a write.
+
+Read-only paths are not mandate-gated:
+
+- `getStreamStatus()`
+- MCP `check_stream_status`
+- MCP `list_streams`
+- MCP `prove_https_response`
+
+## Key Custody Options
+
+### Injected caller account
+
+- Source: `METRIK_AGENT_PRIVATE_KEY`
+- Trust model: the caller hosts the signer locally.
+- Safety properties:
+  - the agent layer does not request the key through tool args
+  - the key is not logged or written to disk by agent code
+  - every autonomous write still needs a valid signed mandate
+
+### Coinbase CDP Server Wallet v2
+
+- Source: `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`
+- Trust model: Coinbase holds signing material inside its remote signing boundary.
+- Safety properties:
+  - Metrik only receives a signing-capable account object
+  - the private key is never exported into this repo
+  - the same mandate checks apply before any autonomous write
+
+### Privy embedded user-owned EOA
+
+- Source: an authenticated Privy EIP-1193 wallet provider supplied by the host application
+- Trust model: the user owns/authenticates the embedded EOA through Privy; the agent package
+  sees only the provider and public wallet address
+- Safety properties:
+  - no Privy app secret or wallet key is accepted by the adapter
+  - chain and account identity are checked before construction and before each signature
+  - every autonomous write still requires the signed Metrik spend mandate
+- Headless boundary:
+  - the user attaches a Privy additional signer under a non-empty provider policy
+  - the broker stores only a hash of the short-lived agent token and rechecks a signed
+    Metrik mandate, decoded calldata, stream ownership/state, expiry, and revocation
+  - the first successful write requests provider gas sponsorship; later writes do not
+- Limitations: ERC-4337/EIP-1271 smart accounts are not supported
+
+### Autonomous agent-owned Privy EOA
+
+- Source: a P-256 key generated by the agent process and persisted only through
+  an injected secure store or the host OS credential manager
+- Trust model: the agent owns the authorization key; the broker owns only the
+  Privy app credentials and wallet identifier
+- Safety properties:
+  - provisioning sends the broker a public SPKI key and proof-of-possession,
+    never the PKCS8 private key
+  - a fixed approved Metrik policy is required when the broker creates the EOA
+  - provisioning fails closed on a credential store that does not survive a host
+    reboot (process memory, or the Linux kernel keyring the OS keyring silently
+    falls back to when no Secret Service provider answers), because losing the
+    owner key makes any funds the wallet holds permanently unspendable
+  - every write uses prepare → local P-256 signature → one-time execute; the
+    broker verifies the exact canonical Privy request before forwarding it
+  - nonce/public-key binding, short proof/request expiry, strict P-256 parsing,
+    idempotency, and restricted Metrik calldata prevent replay and arbitrary RPC
+- Limitations: the broker must provide persistent idempotency/replay storage and
+  a real Privy integration. This path does not claim smart-account/EIP-1271 or
+  gas sponsorship support. A failed secure store is a hard stop; plaintext
+  persistence is intentionally unsupported.
+
+### CDP-owned smart account + paymaster limits
+
+- Source: optional smart-account provisioning in the wallet layer plus SDK
+  `gasAbstraction`
+- Trust model: the owner signer controls a smart account, and the bundler/paymaster
+  can impose additional sponsorship policy.
+- Safety properties:
+  - approvals remain bounded to the requested stream budget
+  - the SDK exposes a policy hook for session/per-merchant limits
+  - paymaster allowlists can restrict sponsored targets such as the escrow and
+    EntryPoint
+
+### Session keys
+
+`PrivySessionBroker` issues a random, short-lived bearer credential after verifying the
+user's Privy access token, embedded-wallet ownership, and owner-signed Metrik mandate.
+The credential never contains a wallet key. `createPrivySessionProvider` turns it into a
+restricted EIP-1193 boundary for an external agent; revocation and expiry fail closed.
+
+## Security Pass Alignment
+
+The current implementation satisfies the agent-layer security pass this way:
+
+- Every autonomous fund-moving path calls `checkMandate()` before the SDK write.
+- No private key is silently held, logged, or embedded; signing is explicit via
+  the configured injected signer or CDP signer.
+- Budget, rate, duration, and operator limits are enforced in code, not
+  merely documented.
+- Secrets stay in env / repo-secret surfaces; `.env.example` is names only.
+
+## Residual Risks
+
+- Revocation and cumulative-spend state are still local/integrator-provided.
+- CDP and paymaster trust are external dependencies.
+- zkTLS proofs depend on Reclaim as an external attestation system.
+- L2 remains supplemental evidence; it must not override L1 failure or ambiguity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -47,6 +47,7 @@
   "sideEffects": false,
   "files": [
     "dist",
+    "docs",
     "src"
   ],
   "repository": {
@@ -66,38 +67,50 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.7.0",
+    "@absol-labs/sdk": "^0.9.0",
     "@absol-labs/shared": "^0.12.1",
-    "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",
     "@privy-io/node": "0.33.0",
-    "@reclaimprotocol/js-sdk": "^5.6.0",
-    "@reclaimprotocol/zk-fetch": "^1.0.0",
     "reflect-metadata": "^0.2.2",
     "viem": "^2.21.0",
     "zod": "^3.24.0"
   },
   "peerDependencies": {
     "@coinbase/agentkit": "^0.10.4",
+    "@coinbase/cdp-sdk": "^1.51.2",
     "@elizaos/core": "^1.7.2",
-    "@langchain/core": "^1.2.0"
+    "@langchain/core": "^1.2.0",
+    "@reclaimprotocol/js-sdk": "^5.6.0",
+    "@reclaimprotocol/zk-fetch": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@coinbase/agentkit": {
       "optional": true
     },
+    "@coinbase/cdp-sdk": {
+      "optional": true
+    },
     "@elizaos/core": {
       "optional": true
     },
     "@langchain/core": {
       "optional": true
+    },
+    "@reclaimprotocol/js-sdk": {
+      "optional": true
+    },
+    "@reclaimprotocol/zk-fetch": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@coinbase/agentkit": "^0.10.4",
+    "@coinbase/cdp-sdk": "^1.51.2",
     "@elizaos/core": "^1.7.2",
     "@langchain/core": "^1.2.0",
+    "@reclaimprotocol/js-sdk": "^5.6.0",
+    "@reclaimprotocol/zk-fetch": "^1.0.0",
     "@swc/core": "^1.10.0",
     "@types/node": "^20.17.0",
     "prettier": "^3.4.0",