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

package/docs/cli.md

@@ -46,7 +46,8 @@ consumer who installed the package could not run at all. `metrik mcp
 ## Testnet only
 
 The CLI signs with a raw private key and moves USDC, so the chain is an **allowlist**,
-not a default: only Base Sepolia (`84532`) is accepted. There is deliberately **no
+not a default: only networks the `@absol-labs/sdk` network registry knows **and marks as
+a testnet** are accepted (today: Base Sepolia, `84532`). There is deliberately **no
 override flag** — an escape hatch that re-enabled real funds would defeat the guarantee,
 and there is no mainnet deployment for it to reach anyway.
 
@@ -60,47 +61,194 @@ 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.
+
+**`metrik claim` does not work on a Privy wallet.** The broker's transaction allowlist
+carries the BUYER actions only (`openStream`, `close`, `reclaim`, `reclaimUnverified`), so
+an operator claim is refused server-side and the client cannot raise that ceiling. Claim
+with the operator's own `METRIK_AGENT_PRIVATE_KEY`. Every other command works. The CLI
+warns when you try it, and `metrik --help` / `metrik claim --help` say so up front.
+
+**`metrik mcp` does not carry a Privy wallet either.** The MCP server resolves its wallet
+with `parseAgentWalletEnv()`, which reads `METRIK_AGENT_PRIVATE_KEY` or the CDP variables
+and has no Privy branch — so `metrik mcp --print-config` prints a key placeholder and says
+why on stderr rather than emitting Privy variables the server would ignore.
+
+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
@@ -109,19 +257,21 @@ that needs no key at all — it builds and prints the intended call and says whi
 
 ## Commands
 
-| Command              | Needs a wallet?                | Broadcasts a tx? | What it does                                     |
-| -------------------- | ------------------------------ | ---------------- | ------------------------------------------------ |
-| `discover`           | no                             | no               | Lists verified registry listings                 |
-| `open`               | **yes** (not with `--dry-run`) | **yes**          | Escrows USDC into a metered stream               |
-| `status`             | no                             | no               | One stream's on-chain state + verified accrual   |
-| `streams`            | no (with `--address`)          | no               | Lists a wallet's streams from the escrow's logs  |
-| `watch`              | no                             | no               | Polls that until the stream closes               |
-| `invoke`             | **yes** (off-chain capability) | no               | Calls the paid service, authorized by the stream |
-| `close`              | **yes**                        | **yes**          | Stops the clock                                  |
-| `reclaim`            | **yes**                        | **yes**          | Takes back what was never earned                 |
-| `reclaim-unverified` | **yes**                        | **yes**          | Buyer escape hatch: reclaim with no proof        |
-| `claim`              | **yes** (the operator's)       | **yes**          | Operator: redeem what verified                   |
-| `mcp`                | no                             | no               | Prints the MCP client config for `metrik-mcp`    |
+| Command              | Needs a wallet?                | Broadcasts a tx?  | What it does                                     |
+| -------------------- | ------------------------------ | ----------------- | ------------------------------------------------ |
+| `discover`           | no                             | no                | Lists verified registry listings                 |
+| `open`               | **yes** (not with `--dry-run`) | **yes**           | Escrows USDC into a metered stream               |
+| `status`             | no                             | no                | One stream's on-chain state + verified accrual   |
+| `streams`            | no (with `--address`)          | no                | Lists a wallet's streams from the escrow's logs  |
+| `watch`              | no                             | no                | Polls that until the stream closes               |
+| `invoke`             | **yes** (off-chain capability) | no                | Calls the paid service, authorized by the stream |
+| `pay`                | **yes** (EIP-3009 signature)   | no (relayer does) | Pays an x402 endpoint into an escrow stream      |
+| `refund`             | only for `--close`             | no (relay does)   | Gasless close/reclaim of an x402 stream          |
+| `close`              | **yes**                        | **yes**           | Stops the clock                                  |
+| `reclaim`            | **yes**                        | **yes**           | Takes back what was never earned                 |
+| `reclaim-unverified` | **yes**                        | **yes**           | Buyer escape hatch: reclaim with no proof        |
+| `claim`              | **yes** (the operator's)       | **yes**           | Operator: redeem what verified                   |
+| `mcp`                | no                             | no                | Prints the MCP client config for `metrik-mcp`    |
 
 ### `metrik discover`
 
@@ -222,6 +372,21 @@ as `simulationPendingApproval: true`, with no `simulationError` — a script bra
 that field no longer sees the expected path as a failure. An allowance-shaped revert when
 the allowance IS already sufficient, and every other revert, are still surfaced as errors.
 
+**The operator-signed rate band.** Before anything is signed or broadcast — `--dry-run`
+included — `open` re-verifies the listing's operator-signed descriptor (the same check the
+seller's gateway runs) and refuses at exit `2` when `--rate` is outside its
+`minRatePerSecond`..`maxRatePerSecond` band, e.g. `the operator signed rates 100..10000
+atomic/s (0.0001..0.01 USDC/s); --rate 20000 (0.02 USDC/s) would be refused by the
+service's gateway`. The escrow accepts any non-zero rate, but the gateway answers every
+request on an out-of-band stream with `403 stream-rate-out-of-bounds`, so the deposit
+would sit in a stream that can never be served. Bounds are inclusive; a bound the operator
+did not sign is not enforced, and a legacy binding signs none. A descriptor that does not
+verify is a refusal (exit `4`), never "no band". Without `--operator`, an unreachable
+registry already fails `open` (exit `4`). With `--operator` — the existing escape hatch for
+a service the registry cannot vouch for — the band cannot be read, so the open proceeds
+with a warning saying the rate was **not** checked. There is no flag to override a band
+the CLI can read.
+
 **Amounts.** `--budget` and `--rate` are decimal USDC by default; `--units atomic`
 switches both to raw 6-decimal base units (what the escrow, the oracle and every
 `METRIK_E2E_*` fixture use). The unit is explicit rather than inferred from magnitude,
@@ -384,7 +549,10 @@ Configured mandate ceilings are carried through verbatim — they are policy, no
 and re-typing four caps from memory is where a wrong ceiling comes from. **Credentials are
 always placeholders.** This command never reads a key out of your environment and prints
 it back; the wallet block is simply shaped like the environment it ran in (the CDP
-variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise).
+variables if those are what you have set, `METRIK_AGENT_PRIVATE_KEY` otherwise). A Privy
+wallet is **not** an option here — `parseAgentWalletEnv()` has no Privy branch — so when
+the environment carries one the command says so on stderr and prints a key placeholder
+instead of a config the server could not start from.
 
 ### `metrik invoke`
 
@@ -414,6 +582,96 @@ listings ("consumer-attested T2 invocation is not supported for gated listings")
 live listings are gated — so a `metrik prove` would be a command that fails for almost
 everyone who ran it. It is left out until that constraint lifts.
 
+### `metrik pay` (x402)
+
+```bash
+metrik pay https://x402.example/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik pay <url> [--json <body> | --data <body>] [--method POST] [--header "K: V"] \
+  --max-amount <usdc> [--max-rate <usdc/s>] [--max-duration <s>] [--min-duration <s>] \
+  [--operator <address>] [--units atomic]
+```
+
+Pays any **x402 v2 `exact`** endpoint through `@absol-labs/sdk/x402`'s `payWithX402`,
+with every SDK protection intact (network and USDC from the registry, EIP-3009 only,
+registered opener factory, `payTo == factory.predict(terms)` read on-chain, bounded
+authorization lifetime, a plain transfer to the seller refused). A Metrik seller's
+payment opens an escrow stream with `deposit = price`; the seller earns
+`ratePerSecond x verified seconds`, capped at the deposit.
+
+The payer needs **USDC only, no gas** (the facilitator's relayer submits the
+authorization). A Privy wallet cannot pay: its broker does not sign EIP-3009.
+
+**How the spend mandate bounds an x402 payment.** No spend without a mandate: a
+payment IS a stream open, so its opener terms are checked by `checkMandate()` exactly
+like `metrik open`, inside the SDK's `onQuote` hook, after the SDK's own checks and
+**before anything is signed**:
+
+| Mandate cap            | Checked against                                |
+| ---------------------- | ---------------------------------------------- |
+| `maxPerStreamUsdc`     | the quote's `amount` (= the deposit)           |
+| `maxTotalUsdc`         | spent so far + `amount`                        |
+| `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn) |
+| `maxDurationSeconds`   | `maxDuration` (the stream window)              |
+| `allowedOperators`     | `operator` (who the stream pays)               |
+
+The caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`, so the price is
+enforced twice. A quote with no opener terms is refused. The mandate comes from
+`METRIK_AGENT_MANDATE_*` when set, otherwise it is sized to this command:
+`--max-amount` (required then) is the per-stream and total cap, `--max-rate` the rate cap
+(default: no tighter than the price), `--max-duration` the window cap (default 1 day),
+`--operator` the only allowed operator. With a standing mandate, every flag
+**intersects** it (the most restrictive value wins; an `--operator` outside
+`METRIK_AGENT_MANDATE_ALLOWED_OPERATORS` is refused): a flag can tighten the
+standing ceiling, never loosen or bypass it. Like every CLI mandate it covers one
+invocation.
+
+If anything fails after the authorization was handed to the seller, `metrik pay`
+establishes the outcome on-chain (USDC `authorizationState`, the opener's
+`StreamOpenedFor` log for that nonce), exits `4`, and says whether the money left
+the payer — with the `streamId` and the recovery command when the stream is found.
+It never reports "nothing moved" unless the authorization was unused and expired.
+
+A quote naming a **legacy** deployment's factory (for example a seller still on
+StreamEscrowV2 after the default moved to V3) is refused by the SDK unless you pass
+`--allow-legacy-factory`; that stream is then closed and reclaimed on the legacy
+escrow, and the printed recovery command carries `--escrow <legacy escrow>`.
+
+`--json <body>` is the request body (curl-style, sets `content-type: application/json`);
+a bare `--json` still selects JSON output, and both can be combined. The output is the
+response, the `streamId`, the opener, the deposit and rate, `minEarnSeconds` (after how
+many verified seconds nothing is left to reclaim) and the **refund URL**.
+**Refunds are not automatic** — see `metrik refund`.
+
+Exit codes: `2` usage (including no ceiling), `3` refused by the mandate or the SDK
+(nothing signed), `4` the settlement failed after signing (the error says whether the
+authorization was used and how to cancel it; see [x402.md](./x402.md)).
+
+### `metrik refund`
+
+```bash
+metrik refund <streamId> --refund-url <url> [--close] [--reclaim] [--attempts 5] [--max-wait 60]
+```
+
+Drives the seller's **gasless refund relay** through the SDK's `refundClient`, bound to
+the stream and to the opener read **from chain** (`factory.isOpener`), never from the
+relay. With no action flag it prints the status and the next step. `--close` signs the
+opener's EIP-712 `Close` as the payer (the relay pays the gas; authorized on the mandate
+owner's signature only, like `metrik close`). `--reclaim` sends the permissionless
+`opener.reclaim` (no wallet needed; the refund always goes to `payerOf(streamId)`) and
+retries a bounded number of times while the settlement window is open, honouring
+`Retry-After`; a longer wait exits `3` with the time to retry. Every relay "success" is
+checked against the transaction receipt on the configured chain. `--refund-url` accepts
+the full URL `metrik pay` printed, a `{streamId}` template or the relay's origin; it can
+also come from `METRIK_AGENT_REFUND_URL`.
+
+Nothing is refunded automatically, and the relay is a convenience: a payer can always
+recover on-chain without it (`metrik close` as the payer, with gas; `metrik reclaim` by
+anyone).
+
+`status`, `close` and `reclaim` understand opener-bought streams: they show the opener and the
+payer, `close` routes through the opener (payer only), and `reclaim` sends the
+permissionless opener reclaim and reports the refund to the payer.
+
 ### `metrik close` and `metrik reclaim`
 
 ```bash
@@ -427,12 +685,32 @@ returns the unspent budget, and the buyer sends it. `close` now points at
 `--close-first` for next time, rather than leaving the one-shot form visible only in
 `metrik reclaim --help`.
 
+**`reclaim` names the condition before it spends anything.** Three different on-chain
+states stop a reclaim, and they have three completely different answers: the stream was
+already reclaimed (you have the money), the stream is still running (close it first), or
+its stop time is not checkpointed yet (wait ~20 seconds). The CLI reads `getStream`,
+`latestCheckpointCheckedAt` and the chain clock up front and says which one it is, rather
+than sending a simulation and repeating whatever the endpoint's revert data decoded to —
+on the public Base Sepolia RPC all three came back as `Execution reverted for an unknown
+reason`. The pre-flight **fails open**: a read that does not answer never blocks the
+reclaim, because refusing to return a buyer's deposit over a dropped view call is worse
+than a wasted simulation.
+
 **`reclaim` waits, by design.** `reclaimWithProof` reverts with `SettlementWindowOpen`
 until a checkpoint whose `checkedAt` is at or after the stream's stop time has posted.
 That is the normal ordering of a checkpoint rail, not a fault — in practice the first
-attempt fails and one roughly 30 seconds later succeeds. The CLI retries **that one
-condition** on a bounded schedule and narrates the wait on stderr; every other failure is
-surfaced immediately and unretried.
+attempt fails and one roughly 30 seconds later succeeds. The CLI retries on a bounded
+schedule and narrates the wait on stderr; every other failure is surfaced immediately and
+unretried.
+
+The wait shows up in three shapes, and all three retry: the escrow's decoded
+`SettlementWindowOpen`; the **oracle** refusing a proof for a stream it has not
+checkpointed yet (the SDK fetches the proof before it simulates, so the escrow's revert
+never happens and the error is `StreamNotInCheckpointError` / `CheckpointNotReadyError`);
+and a reclaim revert the ABI could not decode, where the chain's state is read to decide.
+Only recognising the first of those is what made `--close-first` die on its first attempt
+against a stream closed before its first covering checkpoint — the ordinary result of a
+short trial run.
 
 If it is still blocked when the budget runs out, the message does **not** just say "retry
 later" — every attempt this command makes needs a proof from the oracle, so when the
@@ -448,8 +726,10 @@ lands on another that has not imported the block.) If the stream is **already**
 the close is skipped and the command goes straight to reclaim — so re-running it is always
 safe and never dead-ends on `StreamClosedAlready()`.
 
-`reclaim` on a stream that is still running reports that in words, with the command that
-fixes it, rather than surfacing the `StreamNotReclaimable()` selector.
+`--close-first` is also the one caller allowed past the still-running refusal, since
+clearing that state is the whole point of the flag. Once the close has landed it reports
+what the following retries are waiting for — the stop time, and how far the oracle has
+published — so the wait reads as the advertised wait rather than as a stalled command.
 
 Close and reclaim are buyer-recovery actions: `VerifiedStreamAgentClient` authorizes them
 on the mandate owner's signature alone, never on caps or expiry, so a lapsed mandate can
@@ -546,17 +826,26 @@ that wait legible.
 
 ## Settlement configuration
 
-Everything defaults to Metrik's live Base Sepolia deployment, and every value is
-overridable per command or through the environment:
-
-| Flag             | Env                         | Default                               |
-| ---------------- | --------------------------- | ------------------------------------- |
-| `--chain-id`     | `METRIK_AGENT_CHAIN_ID`     | `84532`                               |
-| `--rpc-url`      | `METRIK_AGENT_RPC_URL`      | Base Sepolia public RPC               |
-| `--escrow`       | `METRIK_AGENT_ESCROW`       | `BASE_SEPOLIA_ESCROW_V2`              |
-| `--usdc`         | `METRIK_AGENT_USDC`         | `BASE_SEPOLIA_USDC`                   |
-| `--oracle-url`   | `METRIK_AGENT_ORACLE_URL`   | `https://oracle.metrik.live`          |
-| `--registry-url` | `METRIK_AGENT_REGISTRY_URL` | the oracle's public listings endpoint |
+Everything defaults to the selected network's entry in the `@absol-labs/sdk` network
+registry (the default network is Base Sepolia), and every value is overridable per
+command or through the environment. Nothing chain-specific is hardcoded in the CLI.
+
+| Flag                  | Env                              | Default                                                                |
+| --------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| `--network`           | `METRIK_NETWORK`                 | the registry default (id, chain id or CAIP-2)                          |
+| `--chain-id`          | `METRIK_AGENT_CHAIN_ID`          | the network's chain id (must agree if both set)                        |
+| `--rpc-url`           | `METRIK_AGENT_RPC_URL`           | the network's first registered RPC                                     |
+| `--escrow`            | `METRIK_AGENT_ESCROW`            | the network's current escrow (V3); a `legacy` one (V2) for its streams |
+| `--escrow-generation` | `METRIK_AGENT_ESCROW_GENERATION` | the registry's; REQUIRED only for an unregistered escrow               |
+| `--usdc`              | `METRIK_AGENT_USDC`              | the network's registered USDC                                          |
+| `--oracle-url`        | `METRIK_AGENT_ORACLE_URL`        | the network's oracle                                                   |
+| `--registry-url`      | `METRIK_AGENT_REGISTRY_URL`      | the network's public listings endpoint                                 |
+
+The gas preflight names the network's gas token and faucet (from its gas-token
+metadata) instead of assuming ETH; on a network whose gas IS the settlement USDC it
+checks the one USDC balance and requires the deposit to leave room for gas. An
+`--escrow` the registry does not record has no log-scan anchor, so `metrik streams`
+needs `--from-block` for it.
 
 ## Embedding it
 

package/docs/langchain.md

@@ -12,6 +12,11 @@ Create them with [`createLangChainVerifiedStreamTools()`](../src/frameworks/lang
 ## Safety model
 
 - `hire_verified_service` checks the signed mandate before any stream open.
+- It then refuses a `ratePerSecondUsdc` outside the listing's operator-signed rate
+  band (the seller's gateway would refuse every request on that stream), and fails
+  closed when the registry cannot be read. An unlisted `serviceRef` has no signed
+  band and is not constrained. The same check runs in the ElizaOS and AgentKit
+  adapters.
 - `reclaim_unspent` passes the same signed-mandate context into the agent client,
   which re-checks authorization before the SDK can write.
 - `check_stream_status` is read-only and also returns `shouldStop` for a closed

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"}]'