@absol-labs/agent 0.10.0 → 0.11.0

package/docs/cli.md

@@ -60,47 +60,183 @@ The rule is enforced twice:
 
 ## Wallet
 
-Two wallet sources, resolved in a **fixed order** — first match wins:
+Three wallet sources, resolved in a **fixed order** — first match wins:
 
 | Order | Variables                                                                                  | Wallet                                  |
 | ----- | ------------------------------------------------------------------------------------------ | --------------------------------------- |
 | 1     | `METRIK_AGENT_PRIVATE_KEY`                                                                 | a raw Base Sepolia test key             |
 | 2     | `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`, `METRIK_AGENT_CDP_OWNER_NAME` | a Coinbase CDP Server Wallet v2 account |
+| 3     | `METRIK_AGENT_PRIVY_*` (below)                                                             | a Privy wallet reached through a broker |
 
-This is the same order `parseAgentWalletEnv()` uses, so one environment configures the
-CLI, the MCP server and the framework adapters identically. The order is **fixed**
-rather than "whichever is configured": an environment carrying both is ambiguous about
-which address funds the stream, and that ambiguity is a fund-moving one. When both are
-present the private key wins and the CLI says so on stderr rather than choosing quietly.
+The first two are the same order `parseAgentWalletEnv()` uses, so one environment
+configures the CLI, the MCP server and the framework adapters identically. The order is
+**fixed** rather than "whichever is configured": an environment carrying two is ambiguous
+about which address funds the stream, and that ambiguity is a fund-moving one. When more
+than one is present the earlier entry wins and the CLI says so on stderr rather than
+choosing quietly.
 
-Three misconfigurations are refused up front, at exit `3`, instead of failing somewhere
-deeper:
+Misconfigurations are refused up front, at exit `3`, instead of failing somewhere deeper:
 
-- **A half-configured CDP wallet** ("you set three of the four variables") is reported as
-  exactly that. Rendering it as "no wallet is configured" would send the reader looking
-  in the wrong place.
+- **A half-configured wallet** ("you set three of the four CDP variables", "you set the
+  Privy session token but not the address") is reported as exactly that, naming the
+  missing variables. Rendering it as "no wallet is configured" would send the reader
+  looking in the wrong place.
 - **A CDP _smart_ account** (`METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT` /
   `METRIK_AGENT_CDP_SMART_ACCOUNT_NAME`) is refused. It is an ERC-4337 account at a
   different address from its owner, reached through a bundler; this CLI broadcasts
   through `--rpc-url`, so it would sign and spend from the **owner** while you funded the
   smart account.
-- **A non-local signer** is refused with the reason, rather than accepted and failed
-  later inside viem.
+- **An account that cannot sign** is refused with the reason, rather than accepted and
+  failed later inside viem. The check is about capability, not locality: every wallet must
+  be able to sign EIP-712 typed data, and only the paths that broadcast through
+  `--rpc-url` additionally need a local signer.
 
 There is no `--private-key` flag, and there will not be one — nor a flag for any other
 credential: a secret on the command line lands in shell history, in `ps` output, and in
 any CI log that echoes the command. Commands print the derived **address**; the
 credential is never echoed, including by `metrik mcp --print-config`.
 
-**Privy is not wired into the CLI, and this is not an oversight.** Both Privy adapters in
-`src/wallet/` produce a JSON-RPC account with no `signTransaction`: they sign and
-broadcast by sending `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so
-they need the wallet client's **transport** to be that provider rather than a plain RPC.
-That is not three more environment variables — it changes the transport for every
-fund-moving command, and `metrik invoke` additionally requires a local signer
-(`InvokeOptions.buyer: LocalAccount`). CDP has neither problem (its account signs
-locally) and is the only wallet path in this package with live CI evidence, which is why
-it is the one that is wired.
+### Privy
+
+A Privy wallet differs from the other two in one structural way: its account has no local
+`signTransaction`. It signs and broadcasts by sending `eth_sendTransaction` /
+`eth_signTypedData_v4` to a provider, so for a Privy wallet the **provider is the wallet
+client's transport** instead of the plain `http(--rpc-url)` a local signer uses. That is
+the whole of the wiring. Private-key and CDP runs are unchanged, byte for byte.
+
+There are two shapes. Set one; setting both uses the agent-owned wallet and says so.
+
+**Agent-owned (`privy-autonomous`)** — headless, no browser, no user login:
+
+| Variable                        | Required | What it is                                                               |
+| ------------------------------- | -------- | ------------------------------------------------------------------------ |
+| `METRIK_AGENT_PRIVY_WALLET_KEY` | yes      | the credential-store key of a wallet you already provisioned             |
+| `METRIK_AGENT_PRIVY_BROKER_URL` | no       | overrides the broker the wallet was provisioned against                  |
+| `METRIK_WALLET_ENCRYPTION_KEY`  | no       | selects the encrypted-file store (the durable option on a headless host) |
+
+**The CLI never provisions a wallet for you.** A fund-moving command is the wrong place to
+mint one, so if nothing is stored under that key the CLI says so and stops. Provision once,
+deliberately — see [autonomous-privy-wallet.md](./autonomous-privy-wallet.md):
+
+```ts
+import { provisionMetrikAutonomousWallet } from "@absol-labs/agent";
+
+const wallet = await provisionMetrikAutonomousWallet({
+  storeKey: "my-agent/base-sepolia",
+});
+console.log(wallet.address); // fund this with test USDC and Base Sepolia ETH
+```
+
+```bash
+export METRIK_AGENT_PRIVY_WALLET_KEY=my-agent/base-sepolia
+metrik invoke 0x… --path /health
+```
+
+Read the credential-store durability section of that document before funding anything: on
+a headless Linux host the OS store is **not** durable and provisioning is refused, which
+is why `METRIK_WALLET_ENCRYPTION_KEY` exists. The CLI selects the same store the same way
+— set that variable and it reads the encrypted file, unset and it reads the OS store — so
+a mismatch between provisioning and use simply finds no wallet and says so.
+
+**User-owned broker session (`privy-session`)** — a scoped session minted from a Privy
+login (today that means the dApp, which holds the user's Privy access token):
+
+| Variable                           | Required | What it is                                                         |
+| ---------------------------------- | -------- | ------------------------------------------------------------------ |
+| `METRIK_AGENT_PRIVY_BROKER_URL`    | yes      | the broker that minted the token; a token is valid nowhere else    |
+| `METRIK_AGENT_PRIVY_SESSION_TOKEN` | yes      | the token from the broker's `POST /v1/sessions`                    |
+| `METRIK_AGENT_PRIVY_ADDRESS`       | yes      | the embedded wallet address the session is bound to                |
+| `METRIK_AGENT_PRIVY_APP_ID`        | yes      | the **public** Privy app id — the broker serves it at `/v1/config` |
+
+#### Which broker the CLI talks to
+
+The agent-owned path defaults to the broker URL the wallet was provisioned against, which
+for `provisionMetrikAutonomousWallet()` is the Metrik broker at
+`https://wallet.137.23.50.249.sslip.io`. Its `GET /health` and `GET /v1/config` answer
+publicly; `/v1/config` carries only the public app id, the public policy id and the fixed
+policy ceilings, and nothing there is a secret. The Privy **authorization key** stays on
+the broker and is never served.
+
+If you would rather not trust that deployment, run your own: it is
+`metrik-privy-broker` from this package (`src/wallet/privy-broker-server.ts`), it needs
+your own `PRIVY_APP_ID` / `PRIVY_APP_SECRET` / authorization key / policy id, and you then
+point `METRIK_AGENT_PRIVY_BROKER_URL` at it. A wallet provisioned against one broker
+cannot be authorized by another — only the broker holding that wallet's Privy
+authorization key can sign for it — so switching brokers means provisioning a new wallet.
+
+#### The spend mandate, and why a Privy wallet does not sign one
+
+Every fund-moving command in this package normally self-signs an EIP-712
+`SpendMandate` first. Read why, from `src/cli/mandate.ts`: _"the person typing
+the command IS the mandate owner: they hold the key and they just stated the
+exact spend on the command line."_ The mandate exists because, for a key-holding
+wallet, the client is the last line of defence — so the agent is made to state
+its own ceiling and is held to it.
+
+**For a Privy wallet that premise is false.** The user does not hold the key: it
+lives at Privy and is exercised by the broker, which caps every `openStream`
+against a policy the client cannot reach and cannot raise. A self-signed mandate
+on top of that is an agent attesting to its own limits when a stronger limit is
+already enforced somewhere the agent cannot touch.
+
+So for a policy-enforced wallet the CLI **does not sign a mandate**, and
+**substitutes the real ceiling instead of dropping the check**: it reads the
+broker's public `GET /v1/config` and refuses an over-ceiling hire locally, in the
+same shape as the gas and USDC preflights — fail early with an actionable
+message rather than paying gas to learn a knowable fact. `open --dry-run`
+reports the ceiling and whether the hire fits; a real `open` refuses.
+
+```
+mandate       not signed — this wallet's ceiling is enforced by its broker, which is stronger
+spend policy  1 USDC (1000000 atomic) total, 1000 atomic/second, 1h max — enforced by https://wallet.137.23.50.249.sslip.io
+fits policy   yes
+```
+
+Two things this deliberately does NOT do:
+
+- **It does not widen the broker.** Both brokers restrict `eth_signTypedData_v4`
+  to `primaryType: "InvocationCapability"`. Teaching them to sign a
+  `SpendMandate` would weaken the exact property that makes the wallet
+  non-custodial, to reinstate a check that is the weaker of the two.
+- **It does not retire `METRIK_AGENT_MANDATE_*`.** Those caps are a standing
+  ceiling the operator deliberately chose, and can be TIGHTER than the broker
+  policy. They still apply, enforced locally, because no mandate is signed to
+  carry them.
+
+Do not "restore" the mandate for consistency. It would both weaken the guarantee
+and break every fund-moving command against the broker as deployed.
+
+#### What works, and what does not
+
+`open`, `close`, `reclaim`, `reclaim-unverified` and `invoke` all work with a
+Privy wallet.
+
+`metrik claim` does not, and that is not a Privy defect: `claim` is the
+**operator's** side, and a broker policy allowlists the **buyer** actions only
+(`openStream`, `close`, `reclaim`, `reclaimUnverified`, and a bounded USDC
+approval to the escrow). An operator claims with the operator's own key. The CLI
+says this before it runs rather than letting you discover it at the broker.
+
+Privy support is Base Sepolia (84532) only, EOA only. No ERC-4337, no EIP-1271,
+no gas sponsorship claim.
+
+#### Trust model, honestly
+
+A raw `METRIK_AGENT_PRIVATE_KEY` is the simplest thing that can possibly work and the CLI
+holds the whole key: anything that reads your environment can move every token in that
+wallet, forever.
+
+Privy is not "no custody" — it is **different** custody. The signing key lives at Privy and
+is exercised by the broker, so the parties who can move funds are Privy and whoever runs
+the broker, together. What the CLI holds is a P-256 authorization key (agent-owned) or a
+short-lived session token (session) — credentials that authorize a **policy-bounded**
+request, not credentials that can drain the wallet. Leaking one is bounded by the broker's
+policy: Base Sepolia only, the escrow and USDC contracts only, zero native value, and the
+installed ceilings (`/v1/config`). Losing the agent-owned P-256 key is the mirror risk: the
+wallet can never be authorized again and anything it holds is unspendable.
+
+Pick a raw key if you are the only party and you want no third party in the path. Pick
+Privy if you want a policy boundary between the machine running the agent and the money.
 
 `invoke` needs the key too, even though it broadcasts nothing: it signs an **off-chain
 EIP-712 invocation capability** as the stream's buyer. `open --dry-run` is the one path

package/docs/mcp-hosted.md

@@ -1,8 +1,9 @@
 # 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`):
+(`discover_services`, `hire_verified_service`, `invoke_service`,
+`check_stream_status`, `reclaim_unspent`, `list_streams`, and the optional
+`prove_https_response` — see [`mcp-reference.md`](./mcp-reference.md)):
 
 - **stdio** (`src/mcp/stdio.ts`) — local dev, one process per caller. Started with
   the published `metrik-mcp` executable (`npx --package @absol-labs/agent metrik-mcp`),
@@ -79,7 +80,7 @@ network but need distinct wallets override only the wallet vars in their `env`.
 
 ```bash
 export METRIK_AGENT_RPC_URL="https://base-sepolia.example/rpc"
-export METRIK_AGENT_ESCROW="0x21948a5E6AE8d9A3D1050791AB6138657Fb54286"
+export METRIK_AGENT_ESCROW="0x0f09f36Ccc05A7c9882F438721C08De314dFd46C"   # StreamEscrowV2 — NOT the retired V1 escrow
 export METRIK_AGENT_USDC="0x036CbD53842c5426634e7929541eC2318f3dCF7e"
 # ... wallet vars (private key or CDP) ...
 export METRIK_MCP_TENANTS='[{"id":"acme","token":"REPLACE_WITH_SECRET"}]'

package/docs/mcp-reference.md

@@ -0,0 +1,175 @@
+# 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. |
+
+### `discover_services`
+
+`category?`, `limit?`. Returns `serviceRef`, `operator`, `publicUrl`, `access`,
+`accessUrl` per listing.
+
+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.
+
+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.
+
+## 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**  | Base Sepolia RPC.                                                                               |
+| `METRIK_AGENT_ESCROW`                    | **yes**  | The **StreamEscrowV2** address. The retired V1 escrow is refused.                               |
+| `METRIK_AGENT_USDC`                      | **yes**  | Settlement token.                                                                               |
+| `METRIK_AGENT_ESCROW_GENERATION`         | no       | `v2` (default, and the only supported value). Declared, not probed.                             |
+| `METRIK_AGENT_CHAIN_ID`                  | no       | Defaults to `84532`; nothing else is accepted.                                                  |
+| `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 the retired V1 address by name, because a wrong-generation read does not
+revert — it returns confident nonsense about someone's money.

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",
 };
 
@@ -336,8 +345,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).

package/docs/threat-model.md

@@ -20,7 +20,8 @@ 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))
 - 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,7 +39,7 @@ 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.                                                   |
 
@@ -52,7 +53,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.