@absol-labs/agent 0.9.0 → 0.10.0

package/docs/cli.md

@@ -0,0 +1,569 @@
+# 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
+
+Two 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 |
+
+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.
+
+Three 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 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.
+
+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.
+
+`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"] });
+```

package/docs/crewai.md

@@ -33,9 +33,13 @@ from crewai import Agent, Crew, Task
 from crewai.mcp import MCPServerStdio
 from crewai.mcp.filters import create_static_tool_filter
 
+# `metrik-mcp` is the executable this package publishes. It resolves anywhere
+# `@absol-labs/agent` is installed (npm/pnpm link it into node_modules/.bin) and
+# via `npx --package @absol-labs/agent metrik-mcp`. The old default was
+# `pnpm mcp:stdio`, which only ever resolved inside the agent repository.
 metrik_mcp = MCPServerStdio(
-    command="pnpm",
-    args=["mcp:stdio"],
+    command="metrik-mcp",
+    args=[],
     env={
         "METRIK_AGENT_RPC_URL": "https://base-sepolia.example.invalid",
         "METRIK_AGENT_ESCROW": "0x0000000000000000000000000000000000000000",

package/docs/eliza.md

@@ -50,6 +50,7 @@ runnable-shaped example lives in
 
 ```ts
 import { http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
 import { baseSepolia } from "viem/chains";
 import { createMetrikElizaPlugin } from "@absol-labs/agent/eliza";
 import { createWalletBackedAgentClient } from "@absol-labs/agent";
@@ -65,7 +66,11 @@ const { agentClient } = await createWalletBackedAgentClient(
       escrow: process.env.METRIK_AGENT_ESCROW! as `0x${string}`,
     },
   },
-  { privateKey: process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}` },
+  {
+    injectedAccount: privateKeyToAccount(
+      process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}`,
+    ),
+  },
 );
 
 const metrikPlugin = createMetrikElizaPlugin({ agentClient });

package/docs/mcp-hosted.md

@@ -4,8 +4,9 @@ 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`):
 
-- **stdio** (`src/mcp/stdio.ts`, `pnpm mcp:stdio`) — local dev, one process per
-  caller. Unchanged.
+- **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`),
+  or `pnpm mcp:stdio` inside this repository.
 - **Streamable HTTP** (`src/mcp/http.ts` + `src/mcp/http-server.ts`,
   `pnpm mcp:http`) — a hosted, **multi-tenant**, per-caller-authenticated
   endpoint suitable for deployment. This document covers the HTTP transport.

package/docs/quickstart.md

@@ -34,8 +34,8 @@ pnpm add @absol-labs/agent
 `@absol-labs/agent` and its `@absol-labs/*` dependencies are published to the **public
 npm registry** — no `.npmrc`, scope registry, or auth token is required to install.
 
-**Runtime:** Node **20.x** (the package pins `engines.node` to `>=20 <21`; 20.19+
-recommended). The Coinbase AgentKit action reads decorator metadata via
+**Runtime:** Node **20.19+, 22 LTS or 24** (the package pins `engines.node` to
+`>=20.19 <25`). The Coinbase AgentKit action reads decorator metadata via
 `reflect-metadata`, which only exists in the **built** output (`tsc` emits decorator
 metadata; `tsx`/esbuild does not) — so `import "reflect-metadata"` **before** importing
 the package, and for the AgentKit path import from the built package, not raw `.ts`.
@@ -286,11 +286,23 @@ funds exactly.
 
 ---
 
-## 8. Four ways to integrate
+## 8. Five ways to integrate
 
-Pick the surface that matches your stack — all four sit on the **same** mandate-gated
+Pick the surface that matches your stack — all five sit on the **same** mandate-gated
 client and business logic.
 
+**(a0) The `metrik` CLI** — no code at all, and the only surface that runs the whole
+loop (`discover -> open -> invoke -> watch -> close -> reclaim`):
+
+```bash
+npx --package @absol-labs/agent metrik discover --min-tier 2
+npx --package @absol-labs/agent metrik open --service <serviceRef> \
+  --rate 0.000001 --budget 0.27 --duration 1h --dry-run
+```
+
+Testnet-only, key read from `METRIK_AGENT_PRIVATE_KEY`, `--json` for scripting. Full
+reference: [`docs/cli.md`](./cli.md).
+
 **(a) SDK client directly** — the path used above:
 
 ```ts
@@ -319,7 +331,8 @@ const agentKit = await createMetrikAgentKit({
 **(c) MCP** — local stdio for dev, hosted HTTP for deployment:
 
 ```bash
-pnpm mcp:stdio   # local: one process per caller (src/mcp/stdio.ts)
+metrik-mcp       # local: one process per caller — the published executable
+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
 ```