@absol-labs/agent 0.9.1 → 0.11.0

package/docs/cli.md

@@ -0,0 +1,705 @@
+# The `metrik` CLI
+
+`metrik` runs the whole Metrik loop from a terminal: find a verified service, escrow
+USDC into a metered stream, call the service, watch what it actually earned, stop the
+clock, and take back what was never delivered.
+
+**What you are buying: TIME, not calls.** A stream rents an endpoint that the oracle keeps
+probing, and the meter runs on availability that VERIFIED — not on the requests you send.
+One request and a thousand requests cost the same second, and the clock keeps running
+while you send none. A reviewer who made a single `invoke` call and paid for 302 seconds
+was billed exactly as designed. `metrik close <streamId>` stops the clock; nothing else
+does, and nothing pushes money back on its own.
+
+It is the **first surface that completes that loop**. The MCP tool set can discover,
+hire, check status and reclaim — but it cannot invoke the paid service and it cannot
+close a stream, so a reviewer or a new integrator had no single place to see the product
+end to end.
+
+The CLI is a thin shell over this package's existing exports (`discoverServices`,
+`VerifiedStreamAgentClient`, `invoke`, `MetrikClient`). It re-implements no protocol
+logic and defines no stream type of its own.
+
+## Install
+
+```bash
+npx --package @absol-labs/agent metrik --help   # no install
+pnpm add -g @absol-labs/agent && metrik --help  # installed
+pnpm cli --help                                 # inside this repository
+```
+
+The package publishes four executables. Each is declared in `bin`, shipped in the
+tarball, and — the part that matters — proved to resolve from a clean consumer's
+`node_modules/.bin` by `pnpm test:package`:
+
+| Bin               | What it starts                                                    |
+| ----------------- | ----------------------------------------------------------------- |
+| `metrik`          | this CLI                                                          |
+| `metrik-mcp`      | the stdio MCP server (`src/mcp/stdio.ts`)                         |
+| `metrik-mcp-http` | the hosted multi-tenant MCP server (`src/mcp/http-server.ts`)     |
+| `metrik-gateway`  | the reference caller-auth gateway (`src/gateway/server-entry.ts`) |
+
+The last two were documented as `node dist/…/x.js` against a checkout, which a
+consumer who installed the package could not run at all. `metrik mcp
+--print-config` prints the MCP client block that starts `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
+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.
+
+The rule is enforced twice:
+
+1. against the chain id you declare (`--chain-id`, or `METRIK_AGENT_CHAIN_ID`), and
+2. against the chain id the RPC endpoint **actually reports**, re-read before any
+   command that signs. A declared chain id is just a number someone typed; the endpoint
+   is the thing that settles. This is what stops
+   `--chain-id 84532 --rpc-url <a mainnet RPC>`.
+
+## Wallet
+
+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 |
+
+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.
+
+Misconfigurations are refused up front, at exit `3`, instead of failing somewhere deeper:
+
+- **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.
+- **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
+
+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
+that needs no key at all — it builds and prints the intended call and says which parts
+(allowance, simulation, mandate signature) it could not produce without one.
+
+## 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`    |
+
+### `metrik discover`
+
+```bash
+metrik discover                          # everything the registry serves
+metrik discover --min-tier 2 --limit 5   # verified-only, five strongest
+metrik discover --operator 0x…           # one operator's listings
+```
+
+`--category` filters the registry's unsigned `category` column. The public discovery
+endpoint serves **signed records only** and carries no category column, so that filter
+matches nothing there — it is for an authenticated PostgREST read.
+
+Each row prints what the operator's **signed descriptor** already carries: the callable
+endpoints (method + path + description), one worked example call, and the accepted
+`ratePerSecond` band in USDC **base units** — which is what `--rate … --units atomic`
+takes. Nothing unsigned is presented as fact.
+
+Listings are ordered **strongest declared verification first** (re-execution, then schema,
+then SLA, then canaries), ties broken on `serviceRef`, so the order is reproducible and
+`--limit 1` returns the best-attested listing rather than whatever the registry happened to
+serve first.
+
+Every row is schema-validated, its `serviceRef` re-derived from the signed record and the
+operator signature recovered — a compromised registry can neither invent an operator to
+pay nor redirect an invocation URL. Rows that fail are dropped and reported on stderr.
+
+An unreachable registry is an **error**, never an empty list. "The marketplace is empty"
+and "the registry was down" are different facts and are never rendered the same way.
+
+**Who attests is disclosed.** `discover` reads `getOracleSigners()` off the escrow and, when
+a listing's operator is ALSO one of those signers, says so on stderr and sets
+`operatorIsOracleSigner: true` in `--json`. On the current Base Sepolia deployment that
+overlap is real: the escrow has three oracle signers and one of them operates the live
+listings, so the party being paid is among the parties attesting that delivery happened.
+Verification there is not independent of the seller, and a tool that prints "tier 2" and
+"cryptographically verified" without saying so is letting a buyer assume otherwise. The
+CLI does not refuse such a listing and does not score it — it states the fact.
+
+If the signer set cannot be read, `operatorIsOracleSigner` is `null` and the warning says
+**UNKNOWN**. "We checked and there is no overlap" and "we could not check" are different
+facts; an escrow outage never renders as a clean bill of health.
+
+**SLA text is the operator's own claim.** Anything under `sla` comes from the operator's
+signed descriptor, and a signature proves only that the operator SAID it. Metrik verifies
+delivery, not promises made about it — one live listing claims that two consecutive failed
+intervals auto-pause the stream, and StreamEscrowV2 has no paused state at all, so that
+claim cannot be true. Every rendering of it is labelled unverified, in human output and in
+`--json` (`slaClaimVerified: false`).
+
+### `metrik open`
+
+```bash
+metrik open --service <serviceRef> --rate 0.000001 --budget 0.27 --duration 1h
+metrik open --service <serviceRef> --rate 1 --budget 270000 --duration 3600 --units atomic
+metrik open ... --dry-run
+```
+
+The operator is taken from the **verified listing** for that `serviceRef` (override with
+`--operator`, which then skips the registry lookup). `--dry-run` builds and simulates the
+transaction and broadcasts nothing — it prints the escrow calldata, the bounded USDC
+approval, and the `streamId` a real hire would produce.
+
+**`--dry-run` needs no wallet.** It is the look-before-you-leap path, and the person who
+most needs it is the one who has not funded a key yet. Without `METRIK_AGENT_PRIVATE_KEY`
+it prints the intended call and reports `buyer: null`, `mandateSigned: false`, and the
+SDK's own `no account configured — allowance and simulation skipped`, rather than
+inventing an address or a signature. With a key, the preview is a real simulation from a
+real address.
+
+**Two pre-flights, both before anything is signed.** Gas and the deposit are separate
+balances on separate tokens, so passing one says nothing about the other:
+
+1. Before a real open, close or reclaim, the CLI reads the wallet's **native** balance and
+   refuses at exit `3` if it is zero, naming the Base Sepolia faucet — instead of letting
+   the node answer with `gas required exceeds allowance (0)`, which reads like a USDC
+   approval problem and is not one.
+2. Before a real open, it reads the wallet's **USDC** balance and refuses at exit `3` if it
+   is below `--budget`, naming Circle's faucet. Without it the open path sends the USDC
+   approval first — which succeeds, because approving an amount you do not hold is legal —
+   and then reverts inside `transferFrom`, having already spent gas to learn something
+   that was one `balanceOf` away.
+
+The second check is deliberately **not** an allowance check: the CLI's own open path grants
+the bounded approval it needs (`approveTxHash` in the result), so a missing allowance is a
+step of the command, not a precondition for it. Gating on it would refuse a hire that was
+about to work. Balance is the fact the CLI cannot fix for you.
+
+`--dry-run` reports the USDC balance instead of enforcing it — it broadcasts nothing, so an
+underfunded wallet is information there, not a refusal.
+
+**A dry run does not predict failure on a first hire.** The simulation runs against current
+chain state, which does not include the bounded USDC approval a real open sends FIRST, so
+`openStream` reverts on the allowance every time that approval is not already in place.
+That is the command's own ordering, not a fault, and reporting it as `simulationError` made
+the one command meant to build confidence forecast failure on first use. It is now reported
+as `simulationPendingApproval: true`, with no `simulationError` — a script branching on
+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.
+
+**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,
+because guessing would be a silent 1,000,000x error on a fund-moving command.
+
+**Spend mandates.** Every fund-moving path in this package goes through `checkMandate()`,
+and the CLI is not exempt. The person typing the command is the mandate owner: the
+mandate is self-signed from the same wallet that funds the stream, exactly as the MCP
+server does. If `METRIK_AGENT_MANDATE_*` caps are set, they bind and an oversized hire is
+denied; with no caps configured, the mandate is sized to exactly this hire and scoped to
+exactly this operator. Neither path is an unbounded mandate.
+
+### `metrik status` / `metrik watch`
+
+```bash
+metrik status  <streamId>
+metrik watch   <streamId> --interval 15 --max-polls 40
+```
+
+`--max-polls` has **no default**: `watch` runs until the stream closes or you interrupt
+it. Both commands apply the same Base Sepolia allowlist as the signing paths — the V1 and
+V2 stream tuples diverge from index 5 onward, so a wrong-chain read does not revert, it
+silently decodes something else into fields with the right names.
+
+Accrual is read from the **oracle's checkpoint proof**, not from the stream tuple.
+`StreamEscrowV2.getStream` reports `claimedCumulative = 0` and `settledCumulative = 0`
+for a stream's entire active life (`settledCumulative` is written by `reclaim`), so a
+status built from stream fields would print "earned: 0" for a stream that had been
+delivering for an hour.
+
+Before the oracle's first covering checkpoint there is simply no proof, and the CLI says
+so rather than printing a zero that looks like a verdict. The protocol fee is read live
+off the escrow (`protocolFeeBps`), never hardcoded.
+
+**No settled figure is printed while the final checkpoint is missing.** Once a stream stops
+— closed, or past `expiresAt` — its accrual is final only after a checkpoint whose
+`checkedAt` reaches that stop time. Until then the latest checkpoint describes a SHORTER
+stream than the one that exists, so a reclaimable computed from it is too large and falls
+when the covering checkpoint lands. A live run read `reclaimable: 1400` straight after
+`close`, `0` two minutes later, and got `NothingToReclaim()` from the reclaim in between.
+
+So while that is pending, `buyer reclaimable` reads `pending final checkpoint` with the two
+timestamps that decide it, and `--json` sets `reclaimable: null` plus an explicit
+`settlement` object:
+
+```json
+{
+  "reclaimable": null,
+  "settlement": {
+    "pending": true,
+    "stopAt": 1789671000,
+    "coveredUpTo": 1789670980,
+    "provisionalReclaimable": "1400"
+  }
+}
+```
+
+The superseded number is kept under a name that cannot be mistaken for money. If the
+escrow will not say how far the oracle has published, that counts as pending — withholding
+a figure we cannot stand behind is the buyer-favouring error.
+
+`operator claimable` is treated differently on purpose: `claimWithProof` accepts any
+retained root, so the operator can act on it now and it can only grow. It is shown, marked
+`not final until the checkpoint covering the stop time lands`, rather than withheld.
+
+**The seller's side of the escape hatch.** When a stream has unclaimed earnings, `status`
+also prints an `operator deadline` row: `reclaimUnverified` pays the buyer the whole
+remaining deposit with no proof from `expiresAt + escapeGraceSeconds`, and on the live
+escrow that grace is 900 seconds and immutable. An operator who has earned but not claimed
+loses it at that moment, and the only defence is to `metrik claim` before it — which
+requires knowing the deadline exists.
+
+StreamEscrowV2 has exactly two states, `active` and `closed`. There is no paused state
+and the CLI never renders one.
+
+Two rows exist so that a buyer can diagnose a stuck reclaim from `status` alone. **oracle
+checkpoint** is how far the oracle has actually published; a value well behind the
+stream's stop time IS the reason a `reclaim` is blocked. **escape hatch** is when the
+no-proof path opens. Both are printed for every stream, not only broken ones — a buyer
+should learn the escape hatch exists before the day they need it.
+
+Every deadline on that screen is resolved against the **chain's** clock, not this
+machine's, because the escrow compares against `block.timestamp`. If the chain will not
+answer, the local clock is used and `clockSource` says so rather than hiding it.
+
+### `metrik streams`
+
+```bash
+metrik streams                                   # the configured wallet's streams
+metrik streams --address 0x… --role buyer        # anyone's, as buyer only
+metrik streams --limit 5 --json
+```
+
+Answers "which streams are mine?" from the escrow's own `StreamOpened` logs. `buyer` and
+`operator` are **indexed** on that event, so `--role` becomes an `eth_getLogs` topic
+filter the node evaluates: the response carries only that wallet's streams no matter how
+wide the window is.
+
+It signs nothing and broadcasts nothing, so `--address` is enough — no wallet needed.
+With no `--address`, the configured wallet is the subject.
+
+**The scan is anchored at the escrow's deploy block**, not at a fixed lookback. A
+lookback cannot describe coverage: a wallet whose stream predates the window is shown an
+empty list, indistinguishable from a wallet that never opened one, and telling someone
+their escrowed funds do not exist is the worst failure a payments tool has. The contract
+has no history before its deploy block, so whether the scan reached it is a fact the
+command can state. Pass `--from-block` for a non-default `--escrow`; without one, a
+different escrow is refused rather than scanned from a block that means nothing for it.
+
+**An empty result is only reported as "no streams" when it can be trusted.** Three things
+can make a scan partial, and each is named on stderr in both output modes, with
+`degraded: true` and a `degradedReasons` array in `--json`:
+
+- the window budget could not reach the anchor (4,000,000 blocks — the live escrow's whole
+  history is ~1.06M, so the default scan is complete);
+- a log query failed three times (one transient 429 is retried, not counted);
+- the RPC has **pruned its log index**. A pruning node answers a range it no longer
+  retains with a _successful empty result_, so the CLI probes the deploy block first —
+  measured on Base Sepolia, that block carries 6 escrow logs, and an endpoint that returns
+  none for it has pruned the history and its empty windows cannot be believed.
+  `https://base-sepolia-rpc.publicnode.com` fails this probe today; `https://sepolia.base.org`
+  passes it.
+
+The `--json` output carries `logRetentionProven` (`true` / `false` / `null` when no canary
+was possible). A row whose `getStream` read failed is kept and marked `status: "unread"` —
+never dropped, because a stream that vanishes from this list is exactly what the command
+exists to prevent.
+
+`originalDepositUsdc` comes from the **event**, not the stream: StreamEscrowV2 mutates
+`Stream.deposit` on reclaim, so the log is the only surviving record of what was escrowed.
+Earned-so-far is not listed here — that is a per-stream call to the oracle, and
+`metrik status <streamId>` is the command that makes it.
+
+### `metrik mcp --print-config`
+
+```bash
+metrik mcp                                 # same thing: a bare invocation prints it
+metrik mcp --print-config                  # the block to paste into an MCP client
+metrik mcp --print-config --name metrik-b  # a second server key, for a second wallet
+metrik mcp --print-config --json | jq .
+```
+
+Prints the `mcpServers` block for Claude Desktop (or any MCP client) that starts this
+package's stdio MCP server. A **bare `metrik mcp` prints it too** — it used to exit `2`
+demanding `--print-config` while the help said the command prints a config — and states on
+stderr that it printed a config rather than starting anything. The server itself is the
+separate `metrik-mcp` executable, which the host launches. It describes an **installed** package, not this repository:
+the command is `npx -y --package @absol-labs/agent@<this version> metrik-mcp`, pinned to
+the version that printed it — `latest` would drift under an MCP host that signs spend
+mandates.
+
+The block carries every variable the server fails closed without: `METRIK_AGENT_RPC_URL`,
+`METRIK_AGENT_ESCROW` and `METRIK_AGENT_USDC` (which have **no** defaults there, unlike in
+this CLI) filled from the settlement config the CLI is already pointed at, plus the four
+`METRIK_AGENT_MANDATE_*` caps without which the server refuses to sign a mandate at all.
+A printed config that omitted them would be a config that fails on first launch, which is
+the failure this command exists to prevent.
+
+Configured mandate ceilings are carried through verbatim — they are policy, not secrets,
+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).
+
+### `metrik invoke`
+
+```bash
+metrik invoke <streamId> --method POST --path /transform --body '{"text":"hi"}'
+metrik invoke <streamId> --path /v1/status --header "accept: application/json"
+metrik invoke <streamId> --path /health --ttl 120
+```
+
+`--path` defaults to `/`, `--method` to `GET`, and `--ttl` (the capability's lifetime in
+seconds) to `60`. `--header` may be repeated.
+
+Resolves the invocation origin from the operator's **signed** listing, signs an EIP-712
+`InvocationCapability` scoped to exactly this method and path, and sends it in the
+`x-metrik-capability` header. No out-of-band credential is involved: the stream is the
+credential.
+
+`--base-url` is an escape hatch for a local gateway. It bypasses verified listing
+routing, so the CLI warns when it is used.
+
+A non-2xx response is an error exit, so a script can branch on it. This command signs a
+capability but broadcasts no transaction — it still requires `METRIK_AGENT_PRIVATE_KEY`,
+because the capability is signed by the stream's buyer.
+
+**Not shipped: a `prove` command.** `invokeWithT2DeliveryProof` throws for gated
+listings ("consumer-attested T2 invocation is not supported for gated listings"), and the
+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 close` and `metrik reclaim`
+
+```bash
+metrik close   <streamId>
+metrik reclaim <streamId> --attempts 12 --interval 10
+metrik reclaim <streamId> --close-first
+```
+
+Nothing pushes money back. `close` stops the clock; `reclaim` is the transaction that
+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` 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.
+
+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
+oracle is gone, retrying forever never pays. The give-up message names
+`reclaim-unverified`, the path that needs no proof, and says whether its window is open
+yet and what taking it would cost.
+
+**`--close-first` is two transactions, sequenced by the CLI.** The reclaim only simulates
+against post-close state, so the close is sent, then confirmed through the same read path
+the reclaim will use, and only then is the reclaim attempted. (`sepolia.base.org` is
+load-balanced: the close receipt can come back from one node while the next simulation
+lands on another that has not imported the block.) If the stream is **already** closed,
+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 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
+never strand a buyer's own money.
+
+### `metrik claim`
+
+```bash
+metrik claim <streamId>
+```
+
+The seller's side of the loop, and the only redemption surface in this package — the MCP
+server has no claim tool either. `status` has always printed an `operator claimable` row;
+until now nothing in the CLI could act on it.
+
+`claimWithProof` is operator-gated on-chain, so the command reads the stream first and
+refuses a wallet that is not the operator **before** it broadcasts. An address mismatch is
+knowable with one read; letting it become a raw `NotOperator()` revert would charge gas to
+learn a fact that was already free. Same for a missing checkpoint: accrual lives in the
+oracle's proof, never in the stream tuple, so no proof means no claim is possible yet and
+the command says that instead of paying for `NothingToClaim()`.
+
+### `metrik reclaim-unverified`
+
+```bash
+metrik reclaim-unverified <streamId> --forfeit-unclaimed
+```
+
+**The escape hatch, for when the oracle cannot give you a proof.** Every other route this
+CLI has to a buyer's money goes through `reclaimWithProof`, so the whole ordinary path is
+only as available as the oracle is. `StreamEscrowV2.reclaimUnverified` is the one that is
+not: buyer-only, no proof, no signer quorum, no guardian.
+
+**What it costs.** The escrow sets the operator's entitlement to what they had _already
+claimed on-chain_, and their later claims then revert `NothingToClaim()` forever. So every
+voucher the operator verifiably earned but had not yet redeemed is **permanently forfeit,
+and paid to the buyer**. Nothing recovers it afterwards. That is why this is a separate
+command rather than a `metrik reclaim --unverified` flag one token away from the safe path,
+and why `--forfeit-unclaimed` has no default and no `--no-` form: the only way to reach the
+transaction is to type a phrase that says what it does. Where `metrik reclaim` works, use
+that instead — it settles the operator honestly and still pays you the rest.
+
+**When it opens.** The escrow gates it on
+
+```
+block.timestamp >= expiresAt + escapeGraceSeconds
+```
+
+— on **`expiresAt`, never on `closedAt`**. Closing a stream early does **not** bring the
+hatch forward: close a 24-hour stream after ten minutes and the hatch still opens roughly
+24 hours out, not `escapeGraceSeconds` later. Before then there is genuinely no no-proof
+route, and no CLI change can invent one. Readiness is fully computable before any gas is
+spent (`escapeGraceSeconds` is a public immutable), so the command refuses early rather
+than broadcasting into a guaranteed `EscapeHatchNotReady()`.
+
+Before broadcasting it prints what the operator stands to lose, read live. On this path
+that figure is usually **unknown** — the reason to be here at all is that the oracle is not
+answering, and the operator's redeemable balance is derived from the oracle's proof. It is
+reported as unknown, never as zero.
+
+> **Deployment note.** `escapeGraceSeconds` is **900 s** on the live Base Sepolia escrow,
+> while the contract's own comment says it should be "typically >= a day" — the point being
+> to give an operator time to redeem before forfeiture. Both values are immutable, so this
+> cannot change without a redeploy. The forfeiture above therefore bites far sooner than
+> the contract author intended.
+
+## Output
+
+Human-readable by default. `--json` puts one JSON document on stdout; warnings, progress
+and errors always go to **stderr**, so the stream stays parseable. `metrik watch --json`
+emits **JSON Lines** — one compact object per poll, each on its own line, so every line
+parses standalone:
+
+```bash
+metrik watch <streamId> --json | while read -r line; do
+  echo "$line" | jq -r '.verifiedAccrual.cumulativeAmount // "not checkpointed yet"'
+done
+```
+
+Exit codes: `0` success, `2` usage error, `3` refused configuration (wrong chain, no
+wallet, mandate denied), `4` the operation failed.
+
+**Nothing waits silently.** Every RPC call carries a 15s budget with two bounded retries,
+and the oracle fetch — an HTTP call the RPC transport does not cover — has its own 20s
+budget that names the endpoint when it expires. Any command still working after 8 seconds
+starts a heartbeat on stderr with the elapsed time, repeating every 10s, because with no
+output at all a slow endpoint and a wedged process are indistinguishable. The heartbeat is
+stderr in both modes, so `--json` stdout stays a single parseable document.
+
+Read paths time out; **broadcasts do not.** A transaction that has been sent may already be
+in the mempool, and a CLI that walked away from it on a timer would report a failure for
+something that in fact settled. Write paths keep waiting, and the heartbeat is what makes
+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 |
+
+## Embedding it
+
+The runner is exported, with every side-effecting dependency injected:
+
+```ts
+import { runCli } from "@absol-labs/agent/cli";
+
+const exitCode = await runCli({ argv: ["status", streamId, "--json"] });
+```