@absol-labs/agent 0.12.0-rc.2 → 0.12.0-rc.4

package/docs/x402.md

@@ -145,9 +145,14 @@ instance, ever**:
   the mined outcome; it receives the one success only if none was delivered
   before.
 - The gateway enforces the same rule on its side: a `PAYMENT-SIGNATURE` whose
-  authorization is in flight or already settled gets `409
-x402-payment-already-used` **without** an upstream call; a retry after
-  `settlement_pending` is let through so it can reconcile.
+  authorization is in flight or already settled is refused **without** a
+  verify, an upstream call or a settlement. The refusal has the x402 v2 shape:
+  `402` with a fresh `PAYMENT-REQUIRED` whose `error` is
+  `x402-payment-already-used` (body `{"authorized": false, "reason":
+"x402-payment-already-used", …}`), so a stock client can sign a NEW payment
+  or report the reason. (It was a bare `409` before; the strictness is
+  unchanged.) A retry after `settlement_pending` is let through so it can
+  reconcile.
 - Relayer submissions (simulate + broadcast) are serialized, so concurrent
   payers never collide on the relayer's account nonce.
 
@@ -362,6 +367,56 @@ no proof that matches the escrow's on-chain latest root is available (with an
 shape), `wait` (with `retryAt` / `retryAfterSeconds`), `reclaim`,
 `reclaim-unverified` (with `typedData`), or `none`.
 
+How to read the fields:
+
+- `status` is the escrow's own on-chain status, verbatim (`active` / `closed`).
+  A stream past `expiresAt` that nobody closed is still `active` on-chain;
+  `state` says what it means now: `active` (running), `expired` (past
+  `expiresAt`, accrues nothing more, needs no close) or `closed`.
+  `onChainStatus` repeats the raw value.
+- `maxRefund` is a **ceiling**: the most this payment could ever refund (the
+  escrowed deposit), whatever was delivered. `reclaimable` is what a reclaim
+  returns **now**, given the latest verified delivery: `0` with `maxRefund:
+45000` means the verified delivery covers the whole deposit, not an error.
+  `maxRefundMeaning` and `reclaimableMeaning` say this in the response itself.
+
+**Right after paying.** Every answer is read at one block, and never below the
+block of a transaction the facilitator saw mined for that stream (its
+settlement, or a close/reclaim the relay sent), so a load-balanced RPC whose
+nodes lag each other cannot make a just-opened stream look unknown or a
+just-closed one look active. The relay waits, bounded (8 s by default), for the
+RPC to reach that block, then answers `503 chain-lagging` with `Retry-After`
+rather than a wrong answer. A miss for a stream it has no such block for
+(e.g. after a restart) is re-read once, a second later, before it is `404`. A
+client should still treat `404 not-found` and `503` right after paying as
+"retry shortly", and guard the body before reading `next`:
+
+```ts
+// `opened` is PAYMENT-RESPONSE extra.metrikStreamOpener.
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+async function relayStatus(refundUrl: string) {
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const res = await fetch(refundUrl);
+    const body = await res.json().catch(() => undefined);
+    if (res.ok && body?.next !== undefined) return body;
+    // Just settled: the relay's RPC may not have caught up yet.
+    if (res.status === 404 || res.status === 503 || res.status === 429) {
+      await sleep(Number(res.headers.get("retry-after") ?? "2") * 1000);
+      continue;
+    }
+    throw new Error(`refund relay ${res.status}: ${body?.error ?? "no body"}`);
+  }
+  throw new Error("refund relay did not serve the stream; retry later");
+}
+const status = await relayStatus(opened.refundUrl);
+if (status.next?.action === "close") {
+  // sign status.next.typedData (with your deadline) and POST it to `${refundUrl}/close`
+}
+```
+
+`@absol-labs/sdk`'s `refundClient` (≤ 0.10.0-rc.3) does not retry a status
+read; `metrik refund` re-reads it itself after acting (see `docs/cli.md`).
+
 A successful relayed transaction answers `200` only from its **mined** receipt:
 
 ```json
@@ -375,18 +430,19 @@ A successful relayed transaction answers `200` only from its **mined** receipt:
 `{"ok": false, "error": "<code>", "message": "…", …}`, with `Retry-After`
 where a retry makes sense:
 
-| Status | `error`                                                                                         | Meaning                                                                                     |
-| ------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                             |
-| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near   |
-| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory                     |
-| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                          |
-| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                         |
-| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome |
-| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent          |
-| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                               |
-| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                          |
-| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                 |
+| Status | `error`                                                                                         | Meaning                                                                                      |
+| ------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                              |
+| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near    |
+| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory (confirmed on-chain) |
+| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                           |
+| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                          |
+| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome  |
+| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent           |
+| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                                |
+| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                           |
+| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                  |
+| 503    | `chain-lagging`                                                                                 | The RPC is still below a block the stream changed in (`minBlock`); retry after `Retry-After` |
 
 ### Bounded against gas abuse
 
@@ -556,17 +612,18 @@ informational http(s) links on top of the terms, never uses them for
 settlement, and still refuses any other key. "Verified" here means verified
 delivery, not verified output.
 
-| Request carries                                            | Result                                                                                |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| nothing                                                    | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                    |
-| `PAYMENT-SIGNATURE`                                        | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE` |
-| `PAYMENT-SIGNATURE`, upstream `>= 400`                     | upstream response, nothing settled                                                    |
-| `PAYMENT-SIGNATURE`, settle fails                          | `402` + `PAYMENT-RESPONSE`, no upstream body                                          |
-| `x-metrik-capability`                                      | the capability path, unchanged                                                        |
-| capability **and** `PAYMENT-SIGNATURE`                     | `400 ambiguous-capability-and-payment`                                                |
-| probe capability **and** `PAYMENT-SIGNATURE`               | `400 ambiguous-probe-mode`                                                            |
-| any request while the facilitator marker cannot be proven  | `503 x402-facilitator-unavailable`                                                    |
-| a `PAYMENT-SIGNATURE` already in flight or already settled | `409 x402-payment-already-used`, no upstream call                                     |
+| Request carries                                                       | Result                                                                                                                                  |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| nothing                                                               | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                                                                      |
+| `PAYMENT-SIGNATURE`                                                   | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE`                                                   |
+| `PAYMENT-SIGNATURE`, upstream `>= 400`                                | upstream response, nothing settled                                                                                                      |
+| `PAYMENT-SIGNATURE`, verify refuses it (e.g. `validBefore` too short) | `402`, fresh `PAYMENT-REQUIRED` whose `error` is the reason; body `{"authorized": false, "reason": "x402-payment-invalid", "error": …}` |
+| `PAYMENT-SIGNATURE`, settle fails                                     | `402` + `PAYMENT-RESPONSE` (`success: false`, `errorReason`), no upstream body; body `{"reason": "x402-settlement-failed", "error": …}` |
+| `x-metrik-capability`                                                 | the capability path, unchanged                                                                                                          |
+| capability **and** `PAYMENT-SIGNATURE`                                | `400 ambiguous-capability-and-payment`                                                                                                  |
+| probe capability **and** `PAYMENT-SIGNATURE`                          | `400 ambiguous-probe-mode`                                                                                                              |
+| any request while the facilitator marker cannot be proven             | `503 x402-facilitator-unavailable`                                                                                                      |
+| a `PAYMENT-SIGNATURE` already in flight or already settled            | `402`, fresh `PAYMENT-REQUIRED` with `error: "x402-payment-already-used"`; no verify, upstream call or settle                           |
 
 With `METRIK_GATEWAY_X402V2_OPENER` unset the gateway is byte for byte the
 capability-only gateway (`test/gateway-http-baseline.test.ts`), and the
@@ -595,8 +652,9 @@ chain and before anything is signed — and the caps are also passed to the SDK
 (`X402MandateDeniedError` reason `not-an-opener-quote`).
 
 For an upfront quote the mandate counts the WHOLE price, upfront part included,
-as spend (`budgetUsdc = price`); that part is non-recoverable and nothing a
-refund returns is credited back. Its size is also capped separately before
+as spend (`budgetUsdc = price`); that part is non-recoverable, and a refund is
+credited back only in the one case below (an MCP `closeAfter` reclaim proven by
+its receipt). Its size is also capped separately before
 signing by `maxUpfrontAmount` (`metrik pay --max-upfront`, MCP
 `maxUpfrontAmountUsdc`; default 0.10 USDC, `0` refuses any upfront charge). The
 split is shown before signing and in the result. An upfront-only payment
@@ -608,13 +666,52 @@ non-stream charge that still counts against the mandate.
 ```bash
 metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' --max-amount 0.1
 metrik refund <streamId> --refund-url <url printed above> --close --reclaim
+
+# one-shot call: close and reclaim in the same run
+metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' \
+  --max-amount 0.1 --max-upfront 0.02 --close-after
 ```
 
 The MCP server offers the same as `x402_pay`, `refund_status` and `refund`
 (see [mcp-reference.md](./mcp-reference.md)); `x402_pay` shares the server
 mandate and cumulative spend with `hire_verified_service`. Refunds are still
 **requested, never pushed**: `metrik refund` / `refund` call the relay; nothing
-calls it for you.
+calls it for you unless you ask for it.
+
+### Closing right after the response (`--close-after`, `closeAfter`)
+
+The metered part of a payment pays per verified second of the seller's uptime,
+not per call. A one-shot caller that never closes lets the seller earn the whole
+metered part for a single response (testers measured never closing at 4x the
+cost of closing quickly); a caller that closes immediately gets back everything
+unearned. So the buyer can ask for the close up front:
+
+- `metrik pay … --close-after`
+- MCP `x402_pay` with `closeAfter: true`
+- `payX402WithMandate({ …, closeAfter: true | { verifyWith, maxAttempts, maxDelayMs } })`,
+  or `closeAfterPayment(…)` on an existing payment (`@absol-labs/agent/x402-buyer`)
+
+After a successful paid response, the buyer's own client runs exactly what
+`metrik refund --close --reclaim` runs (one shared implementation): the payer
+signs the opener's `Close`, the seller's refund relay sends it and pays the gas,
+the client waits — bounded, honouring the relay's `Retry-After` — for the
+checkpoint covering the close, then asks the relay for the permissionless
+reclaim, which the opener always pays to the payer. This is not an automatic
+refund: it is the buyer's client sending the buyer's close and reclaim, because
+the buyer asked; without the option nothing is sent. The payer still broadcasts
+nothing and needs no gas.
+
+What came back is reported from the verified receipt (`ReclaimForwarded` to the
+payer): the refund, what the seller earned, and what the payment finally cost
+(`price - refund` = the upfront part plus the earned seconds). An upfront-only
+payment has nothing to close (exit 0 / `nothing-to-close`); a request that never
+settled closes nothing. If the close or the reclaim does not finish, the payment
+and the response stand and nothing is lost — the unearned part stays escrowed for
+the payer: `metrik pay` exits `5` and prints the exact `metrik refund …` command
+that finishes it; the MCP tool still succeeds and names the `refund` call; the
+programmatic outcome is `incomplete` with the `stage`. In MCP, a verified reclaim
+is recorded as the stream's `reclaimedUsdc`, so only what the payment kept counts
+against the spend mandate.
 
 The facilitator's `PAYMENT-RESPONSE` `extra.metrikStreamOpener.expiresAt` is a
 JSON **number** (it was a decimal string before metrik-agent#121, which the SDK's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.12.0-rc.2",
+  "version": "0.12.0-rc.4",
   "description": "Metrik agent layer: verified-streaming USDC payments metered by delivery, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -85,7 +85,7 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "0.10.0-rc.3",
+    "@absol-labs/sdk": "0.10.0-rc.4",
     "@absol-labs/shared": "0.14.0-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",

package/src/cli/commands/claim.ts

@@ -63,47 +63,58 @@ export const claimCommand: CommandSpec = {
         `wallet ${account.address} is not the operator of this stream`,
         {
           exitCode: 3,
-          hint: `only ${stream.operator} can claim it — the escrow enforces this, so no other wallet can. Set ${PRIVATE_KEY_ENV} to the operator's key. (The buyer's side of this stream is \`metrik reclaim ${streamId}\`.)`,
+          hint: `only ${stream.operator} can claim it — the escrow enforces this, so no other wallet can. Set ${PRIVATE_KEY_ENV} to the operator's key. (The buyer's side of this stream is \`${buyerSideCommand(stream, streamId, deps.nowSeconds())}\`.)`,
         },
       );
     }
 
-    const plan = await planClaim(
-      read,
-      streamId,
-      stream,
-      escrowGenerationFor(config.chainId, config.escrow),
-    );
-    if (plan.kind === "nothing") throw plan.error;
-
     const write = deps.createWriteClient(
       config,
       account,
       writeClientOptions(wallet),
     );
-    const action = {
-      streamId,
-      // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
-      signedMandate: isPolicyEnforced(wallet)
-        ? null
-        : await signClaimMandate(account, config.chainId),
-      spentSoFarUsdc: 0n,
-      nowSeconds: deps.nowSeconds(),
-    };
+    const generation = escrowGenerationFor(config.chainId, config.escrow);
+    // The oracle can post (or the escrow retain) a newer checkpoint between
+    // this plan and the transaction, so a proof read moments ago can revert
+    // `InvalidProof`. Nothing was spent on a reverted simulation: re-plan from
+    // fresh chain and proof state and try again, a bounded number of times.
+    let plan: Extract<ClaimPlan, { kind: "claimWithProof" | "claimProven" }>;
     let result: { readonly txHash: `0x${string}` };
-    if (plan.kind === "claimWithProof") {
-      result = await write.claimStream(action);
-    } else {
-      if (write.claimProvenStream === undefined) {
-        throw new CliError(
-          "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
-          {
-            exitCode: 3,
-            hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
-          },
-        );
+    for (let attempt = 1; ; attempt += 1) {
+      const planned = await planClaim(read, streamId, stream, generation);
+      if (planned.kind === "nothing") throw planned.error;
+      plan = planned;
+      const action = {
+        streamId,
+        // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
+        signedMandate: isPolicyEnforced(wallet)
+          ? null
+          : await signClaimMandate(account, config.chainId),
+        spentSoFarUsdc: 0n,
+        nowSeconds: deps.nowSeconds(),
+      };
+      try {
+        if (plan.kind === "claimWithProof") {
+          result = await write.claimStream(action);
+        } else {
+          if (write.claimProvenStream === undefined) {
+            throw new CliError(
+              "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
+              {
+                exitCode: 3,
+                hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
+              },
+            );
+          }
+          result = await write.claimProvenStream(action);
+        }
+        break;
+      } catch (error) {
+        if (attempt >= CLAIM_REPLAN_ATTEMPTS || !isStaleProofError(error)) {
+          throw error;
+        }
+        await deps.sleep(CLAIM_REPLAN_DELAY_MS);
       }
-      result = await write.claimProvenStream(action);
     }
 
     out.result({
@@ -131,6 +142,21 @@ export const claimCommand: CommandSpec = {
   },
 };
 
+/** How many plan-then-send rounds `metrik claim` makes before giving up. */
+const CLAIM_REPLAN_ATTEMPTS = 3;
+/** Pause between rounds, so a just-posted checkpoint can settle on the RPC. */
+const CLAIM_REPLAN_DELAY_MS = 3_000;
+
+/**
+ * A claim reverted because its proof no longer matches a root the escrow
+ * accepts (a checkpoint rotated, or a lagging node served a not-yet-visible
+ * root). Re-planning reads a fresh proof, so it is worth one more round.
+ */
+export function isStaleProofError(error: unknown): boolean {
+  const text = describeError(error);
+  return /InvalidProof|fresh checkpoint proof/.test(text);
+}
+
 /**
  * Which claim, if any, `metrik claim` would send. Reads only, so it is
  * testable (and checkable against a live stream) without a key.
@@ -259,3 +285,19 @@ export async function planClaim(
     }),
   };
 }
+
+/**
+ * The buyer's recovery command for a stream. A reclaim needs the clock
+ * stopped (closed, or past expiresAt), so a still-running stream gets
+ * `--close-first`; the plain form only once it has stopped.
+ */
+export function buyerSideCommand(
+  stream: { readonly status: string; readonly expiresAt: number },
+  streamId: string,
+  nowSeconds: number,
+): string {
+  const stopped = stream.status === "closed" || nowSeconds >= stream.expiresAt;
+  return stopped
+    ? `metrik reclaim ${streamId}`
+    : `metrik reclaim ${streamId} --close-first`;
+}