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

package/src/cli/commands/pay.ts

@@ -1,4 +1,4 @@
-import type { X402PayerSigner } from "@absol-labs/sdk/x402";
+import type { X402PayerSigner, X402QuoteSummary } from "@absol-labs/sdk/x402";
 
 import {
   DEFAULT_SERVER_MANDATE_TTL_SECONDS,
@@ -24,7 +24,12 @@ import { assertTestnetRpc } from "../config.js";
 import { rpcTransport, type CliX402 } from "../deps.js";
 import { CliError, configError, usageError } from "../errors.js";
 import { usdcFundingHint } from "../../network.js";
-import { isPrivyWalletSource, resolveCliWallet } from "../wallet.js";
+import {
+  CDP_ENV_VARS,
+  PRIVATE_KEY_ENV,
+  isPrivyWalletSource,
+  resolveCliWallet,
+} from "../wallet.js";
 import { hasHeader, parseHeaders } from "./invoke.js";
 import type { X402PostSignatureError } from "../../x402-buyer/pay.js";
 import type { CommandContext, CommandSpec } from "../context.js";
@@ -39,7 +44,7 @@ export const payCommand: CommandSpec = {
   summary:
     "Pay an x402 endpoint into a recoverable escrow stream, under a spend mandate",
   usage:
-    'metrik pay <url> [--json \'{"text":"hi"}\' | --data <body>] [--method POST] [--header "K: V"] --max-amount <usdc> [--max-rate <usdc/s>] [--max-duration <seconds>] [--min-duration <seconds>] [--operator <address>] [--units atomic]',
+    'metrik pay <url> [--json \'{"text":"hi"}\' | --data <body>] [--method POST] [--header "K: V"] --max-amount <usdc> [--max-rate <usdc/s>] [--max-upfront <usdc>] [--max-duration <seconds>] [--min-duration <seconds>] [--operator <address>] [--units atomic]',
   flags: [
     "data",
     "json-body",
@@ -47,6 +52,7 @@ export const payCommand: CommandSpec = {
     "header",
     "max-amount",
     "max-rate",
+    "max-upfront",
     "max-duration",
     "min-duration",
     "operator",
@@ -57,6 +63,22 @@ export const payCommand: CommandSpec = {
   // settles into the escrow). The PAYER broadcasts nothing and needs no gas,
   // but it is a fund-moving command and is gated like one.
   signs: true,
+  // ...so the generic "Broadcasts a transaction" help would be false, and so
+  // would listing Privy: the command refuses a Privy wallet (its broker does
+  // not sign EIP-3009). Say what actually happens.
+  walletHelp: {
+    tag: "[signs a USDC payment]",
+    text:
+      "Broadcasts nothing and needs no gas: the payer signs an EIP-3009 USDC authorization (TransferWithAuthorization) " +
+      "that the seller's facilitator settles into an escrow stream. Requires a wallet holding USDC in the environment: " +
+      `${PRIVATE_KEY_ENV} or ${CDP_ENV_VARS.join(" + ")}. A Privy wallet cannot pay x402: its broker does not sign EIP-3009.`,
+  },
+  flagHelp: {
+    "max-upfront":
+      "--max-upfront <usdc> (cap on the NON-REFUNDABLE per-call part of an upfront-opener quote; default 0.10 USDC, 0 refuses any)",
+    data: "--data <body>",
+    "json-body": "--json <body> (alias: --json-body <body>)",
+  },
   async run(context: CommandContext): Promise<void> {
     const { args, config, env, out, deps } = context;
     const x402 = requireX402(deps.x402);
@@ -76,6 +98,11 @@ export const payCommand: CommandSpec = {
       maxRateRaw === undefined
         ? undefined
         : parseUsdcAmount(maxRateRaw, units, "max-rate");
+    const maxUpfrontRaw = stringFlag(args, "max-upfront");
+    const maxUpfront =
+      maxUpfrontRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxUpfrontRaw, units, "max-upfront");
     const maxDurationRaw = stringFlag(args, "max-duration");
     const maxDuration =
       maxDurationRaw === undefined
@@ -115,6 +142,7 @@ export const payCommand: CommandSpec = {
     });
 
     const wallet = await resolveCliWallet(env, {
+      purpose: "x402-payment",
       note: out.note,
       rpcUrl: config.rpcUrl,
     });
@@ -158,6 +186,12 @@ export const payCommand: CommandSpec = {
       ...(maxAmount === undefined ? {} : { maxAmount }),
       ...(maxRate === undefined ? {} : { maxRatePerSecond: maxRate }),
       ...(minDuration === undefined ? {} : { minDurationSeconds: minDuration }),
+      ...(maxUpfront === undefined ? {} : { maxUpfrontAmount: maxUpfront }),
+      // The split, stated BEFORE anything is signed (the mandate approved the
+      // quote; the SDK signs right after this).
+      onApproved: ({ quote }) => {
+        out.note(describeQuoteSplit(quote));
+      },
       sdkOptions: {
         transport: rpcTransport(config),
         // A LEGACY deployment's factory is refused by the SDK unless the
@@ -172,8 +206,15 @@ export const payCommand: CommandSpec = {
     const bodyText = await result.response.text();
     const opener = result.metrikStreamOpener;
     const quote = result.quote;
+    const settlementTx = settlementTransaction(result.paymentResponse);
     out.result({
       paid: result.paid,
+      // The facilitator's settlement transaction, from the PAYMENT-RESPONSE
+      // header the seller relayed: the facilitator's relayer broadcast it, not
+      // the payer. Reported as-is; null when the header carries none.
+      settlementTransaction: settlementTx,
+      settlementTransactionSource:
+        settlementTx === null ? null : "PAYMENT-RESPONSE",
       httpStatus: result.response.status,
       contentType: result.response.headers.get("content-type"),
       body: bodyText,
@@ -182,6 +223,16 @@ export const payCommand: CommandSpec = {
       refundUrl: opener?.refundUrl ?? null,
       escrow: opener?.escrow ?? null,
       deposit: opener?.deposit ?? null,
+      openerKind: quote?.openerKind ?? null,
+      price: quote?.amount ?? null,
+      // The NON-REFUNDABLE part (paid to the seller at settlement) and the
+      // metered, refundable part (the most any refund can return).
+      upfrontAmount: quote?.upfrontAmount ?? null,
+      refundableAmount: quote?.refundableAmount ?? null,
+      upfrontFee: opener?.upfrontFee ?? null,
+      upfrontOnly: opener?.upfrontOnly ?? quote?.upfrontOnly ?? null,
+      // True for an upfront-only payment: nothing was escrowed, nothing to refund.
+      final: opener?.upfrontOnly === true,
       ratePerSecond: opener?.ratePerSecond ?? null,
       expiresAt: opener?.expiresAt ?? null,
       operator: quote?.operator ?? null,
@@ -201,11 +252,33 @@ export const payCommand: CommandSpec = {
     out.print(`Paid. HTTP ${result.response.status}`);
     out.print(truncate(bodyText));
     out.print("");
-    if (opener !== null) {
+    if (opener !== null && opener.streamId === null) {
+      // Upfront-only: no stream exists, so there is no refund or reclaim to offer.
+      out.table([
+        ["opener", opener.opener],
+        ["payer", account.address],
+        ...splitRows(quote, opener.upfrontFee),
+        ...(settlementTx === null
+          ? []
+          : ([
+              [
+                "settlement tx",
+                `${settlementTx} (reported by the seller's facilitator in PAYMENT-RESPONSE; its relayer broadcast it)`,
+              ],
+            ] as const)),
+      ]);
+      out.print("");
+      out.print(
+        "This payment is FINAL: it was an upfront-only (minimum-charge) payment, the whole price was paid to the seller at settlement as a non-refundable per-call charge, and no escrow stream was opened. There is nothing to refund or reclaim.",
+      );
+      return;
+    }
+    if (opener !== null && opener.streamId !== null) {
       out.table([
         ["streamId", opener.streamId],
         ["opener", opener.opener],
         ["payer", account.address],
+        ...splitRows(quote, opener.upfrontFee),
         ...(opener.deposit === null
           ? []
           : ([["deposit", formatUsdc(opener.deposit)]] as const)),
@@ -229,6 +302,14 @@ export const payCommand: CommandSpec = {
               ["expires", new Date(opener.expiresAt * 1000).toISOString()],
             ] as const)),
         ["refund url", opener.refundUrl ?? "(the seller advertised no relay)"],
+        ...(settlementTx === null
+          ? []
+          : ([
+              [
+                "settlement tx",
+                `${settlementTx} (reported by the seller's facilitator in PAYMENT-RESPONSE; its relayer broadcast it)`,
+              ],
+            ] as const)),
       ]);
       out.print("");
       // A stream on another (e.g. legacy) registered escrow is reached by
@@ -239,7 +320,11 @@ export const payCommand: CommandSpec = {
           ? ` --escrow ${opener.escrow}`
           : "";
       out.print(
-        "Refunds are NOT automatic. The seller earns only for verified seconds; whatever is unearned stays in the escrow until someone reclaims it for you:",
+        quote?.openerKind === "upfront" &&
+          quote.upfrontAmount !== null &&
+          quote.upfrontAmount > 0n
+          ? `Refunds are NOT automatic. The ${formatUsdc(quote.upfrontAmount)} upfront charge is final; of the ${formatUsdc(quote.refundableAmount ?? 0n)} escrowed, the seller earns only verified seconds, and whatever is unearned stays in the escrow until someone reclaims it for you:`
+          : "Refunds are NOT automatic. The seller earns only for verified seconds; whatever is unearned stays in the escrow until someone reclaims it for you:",
       );
       out.print(
         opener.refundUrl === null
@@ -250,6 +335,54 @@ export const payCommand: CommandSpec = {
   },
 };
 
+/**
+ * One line stating what a quote commits the payer to, printed before signing:
+ * for an upfront-opener quote, the NON-REFUNDABLE per-call part and the
+ * metered, refundable part; for a stream quote, that all of it is metered.
+ */
+export function describeQuoteSplit(quote: X402QuoteSummary): string {
+  if (quote.openerKind === "upfront" && quote.upfrontAmount !== null) {
+    if (quote.upfrontOnly === true) {
+      return `quote: ${formatUsdc(quote.amount)}, ALL of it a NON-REFUNDABLE per-call charge (upfront-only: no stream is opened, nothing is metered, nothing can be refunded). Signing it.`;
+    }
+    return `quote: ${formatUsdc(quote.amount)} = ${formatUsdc(quote.upfrontAmount)} NON-REFUNDABLE per-call charge (paid to the seller at settlement) + ${formatUsdc(quote.refundableAmount ?? 0n)} metered and refundable (escrowed; the seller earns it only for verified seconds). Signing it.`;
+  }
+  return `quote: ${formatUsdc(quote.amount)}, all of it escrowed, metered and refundable (the seller earns it only for verified seconds). Signing it.`;
+}
+
+/** Table rows stating a paid quote's split (upfront quotes only). */
+function splitRows(
+  quote: X402QuoteSummary | null,
+  upfrontFee: bigint | null,
+): (readonly [string, string])[] {
+  if (quote === null || quote.openerKind !== "upfront") return [];
+  return [
+    ["price", formatUsdc(quote.amount)],
+    [
+      "non-refundable",
+      `${formatUsdc(quote.upfrontAmount ?? 0n)} (per-call charge, paid to the seller at settlement${upfrontFee === null ? "" : `; protocol fee ${formatUsdc(upfrontFee)} as the seller reports it`})`,
+    ],
+    [
+      "refundable",
+      `${formatUsdc(quote.refundableAmount ?? 0n)} (metered; the most any refund can return)`,
+    ],
+  ];
+}
+
+/**
+ * The settlement transaction hash from the facilitator's `PAYMENT-RESPONSE`,
+ * when it carries a well-formed one. Anything else (absent, empty, not a
+ * 32-byte hash) is `null`: a malformed value is never printed as a hash.
+ */
+export function settlementTransaction(
+  paymentResponse: { readonly transaction?: unknown } | null | undefined,
+): `0x${string}` | null {
+  const value = paymentResponse?.transaction;
+  return typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value)
+    ? (value as `0x${string}`)
+    : null;
+}
+
 const minBig = (a: bigint, b: bigint | undefined): bigint =>
   b !== undefined && b < a ? b : a;
 
@@ -410,15 +543,24 @@ export function explainPayFailure(error: unknown): unknown {
     case "X402PaymentRefusedError":
       return new CliError(error.message, {
         exitCode: 3,
-        hint: /exceeds maxAmount|exceeds maxRatePerSecond/.test(error.message)
-          ? "that ceiling is your spend mandate's (--max-amount / --max-rate or METRIK_AGENT_MANDATE_*), handed to the SDK as a second gate. Nothing was signed."
-          : "the quote failed one of the SDK's protections (wrong network or token, unknown factory, payTo != factory.predict(terms), not an opener payment, ...). Nothing was signed.",
+        hint: /maxUpfrontAmount/.test(error.message)
+          ? "the quote's NON-REFUNDABLE upfront (per-call) charge is above your cap (--max-upfront, default 0.10 USDC). Raise --max-upfront only if you accept losing that much per call whatever is delivered. Nothing was signed."
+          : /exceeds maxAmount|exceeds maxRatePerSecond/.test(error.message)
+            ? "that ceiling is your spend mandate's (--max-amount / --max-rate or METRIK_AGENT_MANDATE_*), handed to the SDK as a second gate. Nothing was signed."
+            : "the quote failed one of the SDK's protections (wrong network or token, unknown factory, payTo != factory.predict(terms), invalid upfront terms, not an opener payment, ...). Nothing was signed.",
         cause: error,
       });
     case "X402PostSignatureError": {
       // The signature was handed out: never say "nothing moved" unless the
       // chain proves the authorization can never be used.
       const post = error as X402PostSignatureError;
+      if (post.upfrontOnly && post.state === "used") {
+        return new CliError(error.message, {
+          exitCode: 4,
+          hint: "the money LEFT the payer as an upfront-only (minimum-charge) payment: the whole price was a non-refundable per-call charge and no stream was opened, so there is nothing to refund or reclaim. Keep this output as evidence if the response was not delivered (see docs/x402.md).",
+          cause: error,
+        });
+      }
       const recover =
         post.streamId === null
           ? ""

package/src/cli/commands/reclaim.ts

@@ -52,6 +52,8 @@ export const reclaimCommand: CommandSpec = {
   signs: true,
   async run(context: CommandContext): Promise<void> {
     const { args, config, env, out, deps } = context;
+    const setActivity = (activity: string | null): void =>
+      context.progress?.setActivity(activity);
     const [streamIdArg] = args.positionals;
     if (streamIdArg === undefined) {
       throw usageError("metrik reclaim requires a <streamId>");
@@ -136,7 +138,11 @@ export const reclaimCommand: CommandSpec = {
           out.note(
             `closed in ${closeResult.txHash} — waiting for it to land …`,
           );
+          setActivity(
+            `waiting for the RPC endpoint to show the close in ${closeResult.txHash}`,
+          );
           await awaitClosed(read, streamId, deps.sleep, closeResult.txHash);
+          setActivity(null);
           // A stream closed before any checkpoint covers its stop time is the
           // ORDINARY outcome of a short trial run, not an exotic one — and it
           // is the state `--close-first` leaves behind by construction. Say
@@ -175,10 +181,15 @@ export const reclaimCommand: CommandSpec = {
           ),
         explainFailure: async (error) =>
           await explainReclaimFailure(error, read, streamId, deps.nowSeconds()),
-        onRetry: (attempt, reason) =>
+        onRetry: (attempt, reason) => {
           out.note(
             `reclaim blocked: no checkpoint covers the stream's stop time yet (attempt ${attempt}/${attempts}) — ${reason}`,
-          ),
+          );
+          // The heartbeat must describe THIS wait, not guess at a slow RPC.
+          setActivity(
+            `waiting for the oracle's next checkpoint (attempt ${attempt}/${attempts} was blocked; retrying every ${interval}s)`,
+          );
+        },
         // "Retry later" is the wrong advice when the oracle is gone: every
         // attempt this command makes needs a proof FROM that oracle. So the
         // give-up message names the path that needs no proof, and says whether
@@ -196,11 +207,13 @@ export const reclaimCommand: CommandSpec = {
     // Read the settled figure back only once the node we are reading from has
     // actually applied the reclaim. The public RPC is load-balanced, so an
     // immediate read can land on a lagged node and report `settledCumulative: 0`
-    // for a stream that just settled a non-zero amount — printing "settled to
-    // operator 0 USDC" when it was not zero. Poll for `reclaimed` (which the
+    // for a stream that just settled a non-zero amount — printing an operator
+    // entitlement of 0 USDC when it was not zero. Poll for `reclaimed` (which the
     // transaction we just landed sets) so the number beside it is from the same
     // post-reclaim state. Bounded, and falls back to the last value read.
+    setActivity("waiting for the RPC endpoint to show the reclaim");
     const stream = await readSettledStream(read, streamId, deps.sleep);
+    setActivity(null);
     // The refund comes from the reclaim's own BuyerReclaimed event, never from
     // a post-reclaim read: reclaim overwrites `deposit` with the operator's
     // entitlement, so deposit − settled reads 0 after every reclaim.
@@ -239,7 +252,14 @@ export const reclaimCommand: CommandSpec = {
       ...(stream === null
         ? []
         : ([
-            ["settled to operator", formatUsdc(stream.settledCumulative)],
+            // No USDC moves to the operator at reclaim: reclaim fixes the
+            // operator's entitlement, the operator claims it later, and the
+            // protocol fee comes out at that claim. "Settled to operator"
+            // read as a payment that never happened.
+            [
+              "operator entitled",
+              `${formatUsdc(stream.settledCumulative)} (claims separately; fee taken at claim)`,
+            ],
             ...(refunded === null
               ? []
               : ([