@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/docs/mcp-reference.md

@@ -0,0 +1,245 @@
+# MCP tool reference
+
+The canonical description of what `@absol-labs/agent`'s MCP server offers an
+agent, what each tool costs, and what it refuses to do. Both transports — stdio
+(`metrik-mcp`) and hosted Streamable HTTP (`metrik-mcp-http`, see
+[`mcp-hosted.md`](./mcp-hosted.md)) — serve exactly this set.
+
+The names and descriptions here are the ones in `METRIK_MCP_TOOLS`
+(`src/mcp/server.ts`); a clean-install check asserts the published `metrik-mcp`
+binary really offers them (`scripts/check-packed-package.mjs`).
+
+## What you are buying: TIME, not calls
+
+A stream rents an endpoint that the oracle keeps probing. **The meter runs on
+availability that VERIFIED, not on the requests you send.** Cost is
+`ratePerSecondUsdc x verified seconds`, capped at the escrowed budget. One
+request and a thousand requests cost the same second, and the clock keeps
+running while you send none.
+
+A reviewer who opened a stream, made a single `invoke_service` call and was
+billed for 302 seconds was billed exactly as designed. `reclaim_unspent` stops
+the clock; nothing else does, and **nothing pushes money back on its own**.
+
+The escrow proves _delivery_, not _correctness_. An endpoint that answers, on
+time, in the right shape, is what gets paid — whether its answer is any good is
+an economic question, not a cryptographic one.
+
+## The tools
+
+| Tool                    | Moves funds | What it does                                                                    |
+| ----------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `discover_services`     | no          | Lists marketplace services whose operator signature verifies.                   |
+| `hire_verified_service` | **yes**     | Escrows USDC and opens a per-second stream. **Starts the meter.**               |
+| `invoke_service`        | no          | Calls the service the stream is paying for. Adds no cost.                       |
+| `check_stream_status`   | no          | Reads live status, settled amount, claimable/reclaimable.                       |
+| `reclaim_unspent`       | **yes**     | Closes the stream (**stops the meter**) and returns unspent USDC to the buyer.  |
+| `list_streams`          | no          | Lists the streams this server opened.                                           |
+| `prove_https_response`  | no          | Buyer-side zkTLS proof of a response. Registered only with Reclaim credentials. |
+| `x402_pay`              | **yes**     | Pays an x402 endpoint (opener path, docs/x402.md) under the spend mandate.      |
+| `refund_status`         | no          | Refund state of an x402 stream, from the seller's gasless refund relay.         |
+| `refund`                | **yes**     | Gasless close (payer-signed) and reclaim of an opener stream via the relay.     |
+
+### `discover_services`
+
+`category?`, `limit?`. Returns `serviceRef`, `operator`, `publicUrl`, `access`,
+`accessUrl` per listing, plus `ratePerSecondBand` (`minRatePerSecondUsdc` /
+`maxRatePerSecondUsdc`, atomic units, `null` for an unsigned side) when the
+operator's signed descriptor carries one.
+
+The registry is an **untrusted transport**: every `serviceRef` is re-derived
+from the signed record and the operator's signature recovered, so a compromised
+registry can neither invent an operator to pay nor redirect an invocation. Rows
+that fail verification are dropped. An unreachable registry is an **error**, not
+an empty list — "zero services" and "could not reach the marketplace" must never
+read the same.
+
+### `hire_verified_service`
+
+`operator`, `serviceRef`, `budgetUsdc`, `ratePerSecondUsdc`, `durationSeconds?`.
+All USDC amounts are **atomic 6-decimal units** (`1 USDC = "1000000"`).
+
+Bounded by the server's own signed spend mandate (per-stream, cumulative, rate,
+duration, operator allowlist, expiry), configured through
+`METRIK_AGENT_MANDATE_*`. An MCP caller cannot produce an EIP-712 signature, so
+the mandate is never a tool argument — the server holds it and fails closed
+without one.
+
+`operator` is the wallet that gets paid, and it arrives as a separate argument
+from `serviceRef`. The pair is cross-checked against the verified registry, and
+the check **fails closed**: the hire proceeds only on a positive match.
+
+A contradicted pairing escrows a buyer's USDC to a stranger for someone else's
+service, and nothing downstream catches it — the escrow does not know who owns a
+`serviceRef`, and the oracle verifies the real endpoint while the money accrues
+elsewhere. A registry read that fails is no evidence the pairing is sound:
+settlement does not depend on that HTTP endpoint being reachable from the MCP
+host, so during an outage the bug would be fully live. An unlisted `serviceRef`
+is refused for the same reason — a hostile registry cannot forge a match, but it
+can suppress a row, which would otherwise downgrade a contradiction into a pass.
+
+Refusing strands nothing: no USDC has moved and the same call succeeds once the
+registry answers. If you must accept that risk,
+`METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR=true` downgrades "could not verify" to a
+warning on the result. It is operator-set input only — never a tool argument,
+because the caller being asked to relax a fund-safety check is the LLM the check
+exists to constrain — and it never overrides a positive contradiction.
+
+`ratePerSecondUsdc` must sit inside the listing's operator-signed rate band
+(inclusive). The descriptor is re-verified with the gateway's own check, and an
+out-of-band rate is refused before any approval or open is sent: the escrow
+accepts any non-zero rate, but the seller's gateway answers every request on
+such a stream with `403 stream-rate-out-of-bounds`. A descriptor that does not
+verify is a refusal. Under `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR=true` an
+unverifiable pairing has no listing to read a band from, and the result's
+warning says the rate was not checked; the override never widens a band the
+server can read.
+
+The result carries a `metering` block: the rate, the budget, the maximum this
+stream can ever spend, and what starts and stops the clock.
+
+### `invoke_service`
+
+`streamId`, `path?` (default `/`), `method?` (default `GET`), `headers?`,
+`body?`, `ttlSeconds?` (default 60, max 300).
+
+Signs a single-use EIP-712 `InvocationCapability` as the stream's buyer — scoped
+to exactly this method and path — and calls the service through the operator's
+caller-auth gateway.
+
+- **The origin is not a parameter.** It is resolved from the operator-signed
+  listing for the stream's own `serviceRef`. An LLM-chosen base URL is precisely
+  the injection this refuses; there is no override.
+- **The path cannot leave that origin.** The URL is resolved first and the
+  result is then proven to carry the signed origin and stay under the signed
+  base path — a prefix check on the raw path is not sufficient, because the URL
+  parser reads a backslash as a host separator for http(s). Backslashes and
+  control characters are rejected outright as well. Resolution happens **before**
+  the capability is signed, so a path that escapes never causes a buyer-signed
+  credential to exist.
+- **Fails closed before any network call** if the stream is not active, has
+  expired, or does not belong to this server's wallet — each with an error that
+  names the next step.
+- A gateway rejection is surfaced with its machine-readable reason
+  (`stream-not-funded`, `capability-expired`, `nonce-replayed`, …) and a next
+  step, rather than a bare `403`.
+- Responses are capped at 64 KiB with `bodyTruncated` reported explicitly.
+- It signs no transaction and moves no funds.
+
+### `check_stream_status`
+
+`streamId`. Returns the stream, `claimable`, `reclaimable`, and a `metering`
+block. A stream id that does not exist on the configured escrow is reported as
+such rather than as "closed" — an unset escrow slot decodes as an all-zero
+struct instead of reverting.
+
+### `reclaim_unspent`
+
+`streamId`, `closeFirst?`. Closing is what stops the meter.
+
+Authorized on the mandate owner's signature **alone** — never gated by mandate
+expiry, revocation, or caps, because those must never strand a buyer's own
+funds. It also works for a stream this server has no local record of (the
+escrow itself enforces buyer-only recovery), so losing in-memory state cannot
+stand between a buyer and their escrow.
+
+### `list_streams`
+
+No arguments. Every active stream listed is still accruing cost per verified
+second, whether or not it is being invoked.
+
+### `prove_https_response`
+
+Registered **only** when Reclaim credentials are configured
+(`RECLAIM_APP_ID` + `RECLAIM_APP_SECRET`). Generates a buyer-side zkTLS proof of an HTTPS response.
+
+**Public listings only.** The Reclaim attestor fetches the URL itself, from its
+own network position, and cannot carry this stream's single-use caller-auth
+capability — so against a gated listing the only thing it could prove is its own
+`403`. The tool says that instead of producing one. Use `invoke_service` for
+gated services; that delivery is covered by the oracle's own verification.
+
+The proof target is pinned to the stream's verified listing origin. A proof of
+some other origin, stamped with this stream's delivery binding, would be
+evidence of a delivery that did not happen here.
+
+This is an L2 signal to be cross-checked with oracle/L1 evidence — not a
+substitute for it.
+
+### `x402_pay`
+
+Arguments: `url` (https; http only for localhost), optional `method`, `headers`,
+`body`, `maxAmountUsdc`, `maxRatePerSecondUsdc` (base units; these can only TIGHTEN
+the server mandate) and `minDurationSeconds`. Pays through `@absol-labs/sdk/x402`'s
+`payWithX402` with every SDK protection intact, and is gated exactly like
+`hire_verified_service`: the same server mandate, the same cumulative spend, the
+same per-owner serialization. The payment's opener terms are checked by
+`checkMandate()` before anything is signed — `amount` (the deposit) against the
+per-stream and total caps, `ratePerSecond`, `maxDuration` and `operator` against
+theirs — and the stream it opens is recorded, so it counts against `maxTotalUsdc`.
+A caller-supplied `PAYMENT-SIGNATURE` / `X-PAYMENT` header is refused. The result
+carries the response (bounded), `streamId`, `opener`, `refundUrl`, the deposit and
+rate, and `refundIsAutomatic: false`.
+
+### `refund_status` / `refund`
+
+Arguments: `streamId`, optional `refundUrl` (not needed for a stream this server
+paid for — it was recorded); `refund` also takes `close` (stop the stream first;
+this wallet signs the opener's `Close`, authorized on the mandate owner's signature
+alone like `reclaim_unspent`) and `reclaim` (default `true`; the permissionless
+reclaim, the refund always goes to the payer). Every relay success is verified
+against the transaction receipt. A settlement window that is still open is reported
+with when to retry. Nothing is refunded automatically.
+
+The three x402 tools are **opt-in**: set `METRIK_AGENT_X402=1` to register them
+(any other value, or none, leaves them off).
+
+**Spend is reserved before anything is signed.** When the mandate approves a
+quote, `x402_pay` records a reservation for its amount in the stream registry
+— inside the same per-owner queue as `hire_verified_service` — before the SDK
+signs the EIP-3009 authorization. If anything fails after the signature has
+been handed out (a malformed or missing `PAYMENT-RESPONSE`, an unconfirmed
+settlement, a dropped connection), the outcome is established from the chain,
+never from the seller: USDC `authorizationState(from, nonce)` and the opener's
+`StreamOpenedFor(streamId, payer, authorizationNonce, …)` log. The reservation
+is released only if the authorization was never used AND has expired; a stream
+found on-chain replaces it under its real `streamId`; otherwise it stays
+counted, and the tool says the money may have moved — never "not settled".
+
+**Outbound requests are guarded.** The URLs the payment tool, `refund` and
+`refund_status` contact come from the model, so every request must be `https:`
+to a host whose every resolved address is public (loopback, private,
+link-local, unique-local, CGNAT, multicast and reserved ranges are refused),
+redirects are never followed, and `METRIK_AGENT_X402_ALLOWED_HOSTS`
+(comma-separated, exact or `*.domain`) restricts it further — list the seller
+AND its refund relay. A response that did not ask for payment is not returned
+(status only). The address is checked at lookup time; use the allowlist where
+DNS rebinding matters.
+
+## Configuration
+
+`metrik mcp --print-config` prints the `mcpServers` block to paste into an MCP
+client, already carrying every variable the server fails closed without. Secrets
+in it are placeholders by design.
+
+| Variable                                 | Required | Meaning                                                                                         |
+| ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `METRIK_AGENT_RPC_URL`                   | **yes**  | RPC of the selected network.                                                                    |
+| `METRIK_AGENT_ESCROW`                    | **yes**  | The network's registered **StreamEscrowV2**. Anything else is refused (see below).              |
+| `METRIK_AGENT_USDC`                      | **yes**  | Settlement token.                                                                               |
+| `METRIK_AGENT_ESCROW_GENERATION`         | no       | `v2` (default, and the only supported value). Declared, not probed.                             |
+| `METRIK_NETWORK`                         | no       | Registry id, chain id or CAIP-2 id; default the registry's default network. Testnets only.      |
+| `METRIK_AGENT_CHAIN_ID`                  | no       | Alternative selector; must agree with `METRIK_NETWORK` when both are set.                       |
+| `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW` | no       | `true` accepts an escrow the registry does not record (a deliberate private deployment).        |
+| `METRIK_AGENT_X402`                      | no       | `1` registers `x402_pay`, `refund_status`, `refund`. **Off by default.**                        |
+| `METRIK_AGENT_X402_ALLOWED_HOSTS`        | no       | Comma-separated hosts (`*.domain` allowed) the x402 tools may contact. Unset = any public host. |
+| `METRIK_AGENT_REGISTRY_URL`              | no       | Registry the invocation origin is verified against.                                             |
+| `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR` | no       | `true` downgrades an unverifiable operator pairing from a refusal to a warning. Off by default. |
+| `METRIK_AGENT_MCP_STATE_FILE`            | no       | Persists the stream registry across restarts.                                                   |
+| `METRIK_AGENT_MANDATE_*`                 | **yes**  | The four spend ceilings. No ceiling, no server.                                                 |
+| wallet vars                              | **yes**  | `METRIK_AGENT_PRIVATE_KEY`, or the CDP/Privy set.                                               |
+
+The escrow generation is a **declared fact, not an inference**: the server
+refuses any escrow that is not the network's registered `StreamEscrowV2` (the
+retired V1 escrow included) unless `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW=true`, because a wrong-generation read does not
+revert — it returns confident nonsense about someone's money.

package/docs/probe-capability.md

@@ -0,0 +1,191 @@
+# `ProbeCapability` — letting the verifier check a gated paid route
+
+> **What this changes for you as a seller:** if your listing is `gated`, the
+> Metrik oracle currently cannot call your paid route at all. It can only reach
+> your health route. Adopting `ProbeCapability` is what turns "the health
+> endpoint answered" into "the paid route delivered". It is **opt-in**, and a
+> gateway that does not adopt it is reported by the oracle as **unverifiable**
+> for the paid route — never as passing.
+
+## The problem
+
+A gated listing's paid route requires an `InvocationCapability` (see
+[`../src/capability/invocation-capability.ts`](../src/capability/invocation-capability.ts))
+signed by **the stream's buyer**: 60s TTL, single-use nonce, bound to one method
+and one path. The gateway recovers that signature and checks it against
+`stream.buyer` on-chain.
+
+The oracle is not a buyer. It holds no buyer key and has no stream. So for a
+gated listing there is no credential a regional probe worker could safely
+present, and the paid route goes unprobed by anybody — not remotely, and not
+even by the coordinator.
+
+That is a real gap in a claim the product makes. "The seller earns only for
+intervals that verified" must not quietly mean "the health endpoint answered".
+
+## The mechanism
+
+A second EIP-712 type, `ProbeCapability`, signed by an **oracle signer**:
+
+```
+ProbeCapability {
+  bytes32 serviceRef;   // the service being probed
+  address oracle;       // the minting signer; must equal the recovered signer
+  string  method;       // exactly one HTTP method
+  bytes32 pathHash;     // keccak256 of exactly one request path
+  bytes32 nonce;        // single-use
+  uint64  expiry;       // ~30s
+}
+```
+
+EIP-712 domain: `name = "Metrik Probe Capability"`, `version = "1"`, the
+gateway's `chainId`, and `verifyingContract` = the `StreamEscrowV2` the gateway
+already checks streams against. The domain name is deliberately **different**
+from `"Metrik Invocation Capability"`, so a buyer's invocation signature can
+never be replayed as a free probe and vice versa.
+
+Transport: base64url in the `x-metrik-probe-capability` request header.
+
+### Authority is public, not a shared secret
+
+The gateway authorizes the probe iff the recovered signer is in
+`StreamEscrowV2.getOracleSigners()` — a **public `view`** on the escrow. On the
+live Base Sepolia deployment (`0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`) that
+returns three addresses today.
+
+This is the whole reason the design beats "give the workers a credential":
+
+- **Nothing to distribute.** No API key, no registration, no onboarding call.
+  A third-party seller performs the identical on-chain read and reaches the
+  identical verdict, with no trust in the oracle's say-so.
+- **Nothing to leak.** The only secret is the oracle coordinator's signing key,
+  which never leaves it.
+- **Revocation is already solved.** Remove a signer on the escrow and it stops
+  being able to probe within one signer-cache TTL (60s by default).
+
+### No signing key leaves the coordinator
+
+The oracle coordinator mints **one fresh capability per probe, per vantage** and
+hands the encoded header to the worker alongside the nonce. Workers hold a
+bearer token for the coordinator and nothing else. Compromising every regional
+worker yields no ability to mint a capability, and no ability to probe anything
+the coordinator did not already ask for — the capability is bound to one
+service, one method, one path, one nonce and ~30 seconds.
+
+One capability **per vantage**, not one per probe, because the nonce is
+single-use: two vantages sharing a capability would see the second rejected as a
+replay.
+
+### A probe never consumes a buyer's budget
+
+Three independent reasons, all structural rather than conventional:
+
+1. A `ProbeCapability` carries **no `streamId` and no `buyer`**. There is no
+   stream identified for it to be billed against.
+2. Accrual is only ever produced by an **oracle checkpoint keyed to a stream**.
+   A gateway call produces none, ever — the gateway is an authorizer and proxy,
+   not a meter.
+3. In the reference gateway the probe branch is evaluated **first and returns
+   unconditionally**, so it can never fall through into the stream branch. An
+   authorized probe decision carries only the probe — no `stream`, no
+   capability, nothing billable. A test asserts the stream reader is never even
+   called.
+
+The gateway additionally sets `x-metrik-probe: 1` on the **upstream** request so
+your own metering and analytics can exclude verification traffic. It is
+gateway-asserted: any inbound copy from a client is stripped first, so a paying
+caller cannot mark its own billable request as a probe.
+
+### Rate limiting: why 60/minute
+
+Without a bound, an oracle-signed capability is a licence to consume your
+service indefinitely for free.
+
+The oracle checkpoints every ~15–22 seconds, so **one** vantage probes a given
+service at most ~4 times a minute. T1 multi-vantage fans that out across at most
+9 vantages (the coordinator plus the oracle's 8-worker cap), giving a worst-case
+honest load of **~36 probes/minute**. The default budget is **60 per minute**:
+comfortable headroom for a re-execution sample and clock jitter, while capping
+the free-service surface at one request per second — far below anything
+economically interesting as a way to get the service for nothing.
+
+Tune it with `METRIK_GATEWAY_PROBE_MAX_PER_MINUTE`. A useful side effect: since
+every capability is single-use and ~30s-lived, the rate limit is also what
+bounds the replay cache — at most `maxPerMinute × ttl/60` probe nonces live at
+once.
+
+### Replay protection reuses the existing cache
+
+The probe path calls the **same** `NonceReplayCache` the buyer path uses, so a
+nonce can never be spent once as a probe and once as an invocation. The nonce is
+consumed _before_ the rate-limit check, so a captured capability replayed at
+volume is rejected as a replay rather than eating the honest probe budget, and
+_before_ the on-chain signer read, so a flood cannot amplify into RPC load.
+
+## Enabling it
+
+```bash
+METRIK_GATEWAY_PROBE_CAPABILITY=true          # off by default
+METRIK_GATEWAY_PROBE_MAX_PER_MINUTE=60        # optional
+METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS=60  # optional
+```
+
+There is **no credential to configure**. The signer set is read from the
+`METRIK_GATEWAY_RPC_URL` and escrow the gateway already uses.
+
+Not using the reference gateway? Implement the verification in this exact order
+— cheapest and most local first, so an unsigned or replayed flood cannot amplify
+into RPC load:
+
+1. Decode the `x-metrik-probe-capability` header; malformed → `403`.
+2. `now >= expiry` → `403`.
+3. Recover the EIP-712 signer; it must equal `capability.oracle` → else `403`.
+4. `capability.method` must equal the request method → else `403`.
+5. `keccak256(path)` must equal `capability.pathHash` (path only — no query, no
+   fragment, no trailing slash except root) → else `403`.
+6. `capability.serviceRef` must be one you front → else `403`.
+7. Consume `capability.nonce` single-use → replay is `403`.
+8. Rate-limit → `429`.
+9. `capability.oracle` must be in `getOracleSigners()` → else `403`. If you
+   cannot read the set, **deny** (`403`); do not serve on a stale set.
+
+Then proxy upstream and **do not meter, bill or settle the call**.
+
+## Failure modes, and what each one means to the oracle
+
+Every denial is a distinct machine-readable `reason` in the JSON body:
+
+| Reason                                          | Status | What it means                                                                                            |
+| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| `probe-not-enabled`                             | 403    | This gateway has not adopted `ProbeCapability`. The oracle reports the paid route **unverifiable**.      |
+| `malformed-probe-capability`                    | 403    | Header was not a decodable signed capability.                                                            |
+| `probe-capability-expired`                      | 403    | Past `expiry`.                                                                                           |
+| `probe-invalid-signature`                       | 403    | Signature does not recover to the claimed `oracle`.                                                      |
+| `probe-method-mismatch` / `probe-path-mismatch` | 403    | Capability was not minted for this route.                                                                |
+| `probe-service-ref-mismatch`                    | 403    | Minted for another service.                                                                              |
+| `probe-nonce-replayed`                          | 403    | Nonce already spent.                                                                                     |
+| `probe-rate-limited`                            | 429    | Free-probe budget for this window is spent.                                                              |
+| `probe-signer-not-authorized`                   | 403    | Signer is not in `getOracleSigners()`.                                                                   |
+| `probe-signer-set-unavailable`                  | 403    | The set could not be read fresh enough. Fail closed.                                                     |
+| `ambiguous-probe-mode`                          | 400    | Request carried a probe capability _and_ a buyer capability or `X-PAYMENT`. Refused rather than guessed. |
+
+## Honest limitations
+
+- **This is an adoption ask.** We ship the reference implementation because we
+  run the reference gateway, but a third-party seller has to adopt it. Until
+  they do, their gated paid route stays health-route-only and the oracle says so
+  out loud rather than implying coverage it does not have.
+- **A gated seller can stay unverifiable on purpose.** A hostile gateway can
+  simply answer `403` to every probe and remain in the "unverifiable" bucket.
+  That gains it nothing it does not already have today — under the oracle's
+  `strict` enforcement an unverifiable paid route accrues nothing, and under
+  `eligible` it is exactly today's health-route-only behaviour, counted and
+  surfaced. What it can never do is be counted as _passing_.
+- **Delivery, not correctness.** A passing probe is evidence the paid route
+  produced a fresh, spec-conforming response for _this_ challenge. It is not a
+  proof the output is correct. See
+  [`../../streamproof-protocol/docs/verification-model.md`](https://github.com/Absol-Labs/metrik-protocol/blob/main/docs/verification-model.md).
+- **The signer set is federated today.** All three addresses in
+  `getOracleSigners()` are keys held by one process, and one of them operates
+  the live listings. `ProbeCapability` inherits that posture exactly — it makes
+  the _paid route_ checkable, not the verifier independent.

package/docs/quickstart.md

@@ -16,9 +16,15 @@ Base Sepolia constants used throughout (chainId **84532**):
 
 | Thing  | Address                                      |
 | ------ | -------------------------------------------- |
-| Escrow | `0x21948a5E6AE8d9A3D1050791AB6138657Fb54286` |
+| Escrow | `0x0f09f36Ccc05A7c9882F438721C08De314dFd46C` |
 | USDC   | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
+The escrow above is **StreamEscrowV2**, the checkpoint-settled contract the
+oracle and the dApp actually settle against. The retired V1 metered escrow
+(`0x21948a5E…`) is not a valid target: its stream tuple diverges from V2's at
+index 5, so a V2 read of it does not revert — it decodes other fields into
+correctly-named ones and reports a confident wrong answer.
+
 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.
@@ -209,7 +215,10 @@ const sdkConfig: StreamProofClientConfig = {
   chain: baseSepolia,
   transport: http("https://sepolia.base.org"),
   account,
-  escrow: "0x21948a5E6AE8d9A3D1050791AB6138657Fb54286",
+  escrow: "0x0f09f36Ccc05A7c9882F438721C08De314dFd46C",
+  // Selects the checkpoint decoder. Without it the SDK reads through the legacy
+  // V1 ABI, and `claimable()`/`reclaimable()` revert against StreamEscrowV2.
+  escrowV2: "0x0f09f36Ccc05A7c9882F438721C08De314dFd46C",
   usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
 };
 
@@ -284,6 +293,40 @@ const { reclaimResult } = await agent.reclaimStream({
 escape-window rules, and `claimed + fees + reclaimed == deposit` conserves the escrowed
 funds exactly.
 
+### 7b. Or pay a seller over x402 (no gas needed)
+
+A Metrik x402 seller (an HTTP `402` with an x402 v2 `exact` quote) can be paid in one
+call. The payment opens the same kind of stream — `deposit = price`, earned per verified
+second — and the same spend mandate bounds it before anything is signed:
+
+```ts
+import { defaultNetwork } from "@absol-labs/agent";
+import { payX402WithMandate } from "@absol-labs/agent/x402-buyer";
+
+const paid = await payX402WithMandate({
+  url: "https://x402.137.23.50.249.sslip.io/transform",
+  init: {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: '{"text":"# hi"}',
+  },
+  signer: account, // USDC only, no ETH
+  network: defaultNetwork(),
+  signedMandate,
+  spentSoFarUsdc: 0n,
+  nowSeconds: Math.floor(Date.now() / 1000),
+});
+console.log(paid.metrikStreamOpener); // streamId, opener, refundUrl, deposit, rate
+```
+
+Getting the unearned part back is not automatic: close, then reclaim, through the seller's
+gasless relay (the `metrik refund` command below, or the SDK's `refundClient`).
+
+Full details, including the mandate mapping: [the buyer section](./x402.md).
+
+From a terminal: `metrik pay <url> --json '{"text":"# hi"}' --max-amount 0.1`, then
+`metrik refund <streamId> --refund-url <url> --close --reclaim`.
+
 ---
 
 ## 8. Five ways to integrate
@@ -336,8 +379,13 @@ pnpm mcp:stdio   # same server, from inside this repository (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
+Tools: `discover_services`, `hire_verified_service`, `invoke_service`,
+`check_stream_status`, `reclaim_unspent`, `list_streams` (+ `prove_https_response` when
+Reclaim creds are set) — full reference in [`docs/mcp-reference.md`](./mcp-reference.md).
+`invoke_service` is the "use" half: it signs a stream-scoped capability and calls the
+operator-signed origin, so an agent never needs an out-of-band credential. Note the meter
+runs on verified SECONDS, not on calls — invoking more often is free, and invoking never
+costs the same. 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).
@@ -380,4 +428,5 @@ Metrik proves **verified delivery** (responded, correctly-shaped, within SLA to
 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.
+e2e:cdp`) — the working reference for everything above; its x402 leg is
+[`scripts/e2e-x402.ts`](../scripts/e2e-x402.ts) (`pnpm e2e:x402`).

package/docs/threat-model.md

@@ -20,7 +20,11 @@ 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)
+- Metrik `402` verified-stream opens in [`src/x402/facilitator.ts`](../src/x402/facilitator.ts)
+  (a Metrik-native challenge flow, not the x402 protocol — see [docs/x402.md](./x402.md))
+- the x402 v2 opener facilitator in [`src/x402-opener/`](../src/x402-opener/) and the
+  gateway's x402 v2 mode in [`src/gateway/x402-opener-mode.ts`](../src/gateway/x402-opener-mode.ts)
+  (both off by default — see [docs/x402.md](./x402.md))
 - 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)
@@ -38,10 +42,27 @@ Out of scope:
 | 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."                                        |
+| 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, challenge 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.                                                   |
 
+## x402 v2 opener threats
+
+The opener path moves a buyer's USDC only under that buyer's own EIP-3009
+signature, so no agent-held key spends and no spend mandate applies; the
+threats are about where the signed payment can end up.
+
+| Threat                                                                                                                                            | Mitigation                                                                                                                                                                                                                                                                                                                                                            | Code / tests                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| A stock x402 facilitator (or anyone holding the signed payload) submits `transferWithAuthorization` to the opener directly, stranding the payment | Only `MetrikOpenerExactScheme` settles, via `deployAndSettle`; its stock verifier gets a signer that cannot broadcast. The gateway refuses to start, and fails closed (503) later, unless the facilitator's `/supported` marker names its exact factory/escrow/token/chain. `PAYMENT-SIGNATURE` is never forwarded upstream. No discovery extension is ever declared. | `src/x402-opener/scheme.ts`, `src/gateway/x402-opener-mode.ts`; `test/x402-opener-gateway.test.ts`, `test/x402-opener.fork.int.test.ts` |
+| A forged or tampered `payTo`, terms or listing redirects funds                                                                                    | `payTo` must equal `factory.predict(terms)` read on-chain (never code/codehash); `(operator, serviceRef)` must resolve to exactly one operator-signed listing via discovery signature verification; amount bounded by `rate × maxDuration`                                                                                                                            | `test/x402-opener-scheme.test.ts`, `test/x402-opener-config.test.ts`                                                                    |
+| Success reported without a stream                                                                                                                 | `settle` returns `success: true` only from a mined receipt carrying the escrow `StreamOpened` (buyer = opener) and the opener `StreamOpenedFor` for this payer/nonce/amount                                                                                                                                                                                           | `test/x402-opener-scheme.test.ts`                                                                                                       |
+| One payment buys several served responses (a replayed `PAYMENT-SIGNATURE`)                                                                        | At most one successful settle per authorization (chain + asset + payer + nonce) per facilitator instance; the gateway refuses an in-flight or settled authorization with `409` before the upstream runs. In-memory, per instance: run one instance                                                                                                                    | `test/x402-opener-scheme.test.ts`, `test/x402-opener-gateway.test.ts`, `test/x402-opener-regressions.fork.int.test.ts`                  |
+| Concurrent payers fail on the relayer nonce after being served                                                                                    | Relayer submissions are serialized                                                                                                                                                                                                                                                                                                                                    | same                                                                                                                                    |
+| Dust payments drain relayer gas; unauthenticated `/verify` amplifies RPC load                                                                     | Minimum amount (default 0.01 USDC, advertised; the gateway refuses a lower price), `/settle` rate limit per token, `/verify` requires the token by default                                                                                                                                                                                                            | `test/x402-opener-config.test.ts`, fork regressions                                                                                     |
+| A failed upstream still charges the buyer                                                                                                         | The gateway settles only when the upstream status is `< 400`, and a failed settle sends no body                                                                                                                                                                                                                                                                       | `test/x402-opener-gateway.test.ts`, fork E2E                                                                                            |
+| Relayer key or facilitator token leaks                                                                                                            | Env only, never logged or echoed in errors; `/settle` requires the bearer token (constant-time compared)                                                                                                                                                                                                                                                              | `src/x402-opener/facilitator-server.ts`; `test/x402-opener-config.test.ts`                                                              |
+
 ## Fund-Moving Paths
 
 These are the autonomous fund-moving paths in the current agent layer:
@@ -52,7 +73,7 @@ These are the autonomous fund-moving paths in the current agent layer:
 4. `VerifiedStreamAgentClient.reclaimStream()`
 5. MCP `hire_verified_service`
 6. MCP `reclaim_unspent`
-7. x402 `open()` via `VerifiedStreamX402Facilitator`
+7. Metrik `402` `open()` via `VerifiedStreamFacilitator`
 
 All of them now pass a signed mandate check before the SDK can send a write.