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

package/src/cli/commands/pay.ts

@@ -32,6 +32,17 @@ import {
 } from "../wallet.js";
 import { hasHeader, parseHeaders } from "./invoke.js";
 import type { X402PostSignatureError } from "../../x402-buyer/pay.js";
+import {
+  closeAfterPayment,
+  type CloseAfterOutcome,
+} from "../../x402-buyer/refund-actions.js";
+import {
+  authorizeCloseSigner,
+  DEFAULT_ATTEMPTS,
+  DEFAULT_MAX_WAIT_SECONDS,
+  explainRefundFailure,
+  reclaimActivity,
+} from "./refund.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
 /** Default stream window a request-sized mandate allows (one day). */
@@ -44,7 +55,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-upfront <usdc>] [--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>] [--close-after] [--units atomic]',
   flags: [
     "data",
     "json-body",
@@ -56,6 +67,7 @@ export const payCommand: CommandSpec = {
     "max-duration",
     "min-duration",
     "operator",
+    "close-after",
     "units",
     "allow-legacy-factory",
   ],
@@ -78,6 +90,8 @@ export const payCommand: CommandSpec = {
       "--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>)",
+    "close-after":
+      "--close-after (after a successful paid response, this client closes the stream for you and reclaims the unearned part: it signs the payer's Close, the seller's refund relay sends it and pays the gas, then it waits for the covering checkpoint and asks the relay to reclaim to the payer. Your request, sent by your client; not an automatic refund. Exit 5 if it does not finish, with the command that finishes it)",
   },
   async run(context: CommandContext): Promise<void> {
     const { args, config, env, out, deps } = context;
@@ -207,7 +221,16 @@ export const payCommand: CommandSpec = {
     const opener = result.metrikStreamOpener;
     const quote = result.quote;
     const settlementTx = settlementTransaction(result.paymentResponse);
-    out.result({
+    const closeAfter = booleanFlag(args, "close-after");
+    // A stream on another (e.g. legacy) registered escrow is reached by
+    // naming that escrow; the CLI defaults to the network's current one.
+    const escrowFlag =
+      opener?.escrow !== null &&
+      opener?.escrow !== undefined &&
+      opener.escrow.toLowerCase() !== config.escrow.toLowerCase()
+        ? ` --escrow ${opener.escrow}`
+        : "";
+    const payResult = {
       paid: result.paid,
       // The facilitator's settlement transaction, from the PAYMENT-RESPONSE
       // header the seller relayed: the facilitator's relayer broadcast it, not
@@ -240,19 +263,41 @@ export const payCommand: CommandSpec = {
       minEarnSeconds: quote?.minEarnSeconds ?? null,
       mandateSource: envCaps === null ? "request" : "env",
       refundIsAutomatic: false,
-    });
+    };
 
     if (!result.paid) {
+      // Nothing settled (the endpoint answered without a payment, or the paid
+      // request failed and was never settled): there is nothing to close.
+      out.result({
+        ...payResult,
+        ...(closeAfter ? { closeAfter: { outcome: "not-paid" } } : {}),
+      });
       out.print(
         `The endpoint answered ${result.response.status} without asking for payment; nothing was signed or paid.`,
       );
       out.print(truncate(bodyText));
+      if (closeAfter) {
+        out.print(
+          "--close-after: nothing was paid, so there is nothing to close.",
+        );
+      }
       return;
     }
     out.print(`Paid. HTTP ${result.response.status}`);
     out.print(truncate(bodyText));
     out.print("");
     if (opener !== null && opener.streamId === null) {
+      out.result({
+        ...payResult,
+        ...(closeAfter
+          ? {
+              closeAfter: {
+                outcome: "nothing-to-close",
+                refundIsAutomatic: false,
+              },
+            }
+          : {}),
+      });
       // Upfront-only: no stream exists, so there is no refund or reclaim to offer.
       out.table([
         ["opener", opener.opener],
@@ -271,54 +316,62 @@ export const payCommand: CommandSpec = {
       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.",
       );
+      if (closeAfter) {
+        out.print(
+          "--close-after: nothing to close — no stream was opened. Nothing was signed or sent.",
+        );
+      }
       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)),
-        ...(opener.ratePerSecond === null
-          ? []
-          : ([
-              ["rate", `${formatUsdc(opener.ratePerSecond)} / verified second`],
-            ] as const)),
-        ...(quote?.minEarnSeconds === null ||
-        quote?.minEarnSeconds === undefined
-          ? []
-          : ([
-              [
-                "fully earned after",
-                `${formatDuration(Number(quote.minEarnSeconds))} of verified delivery`,
-              ],
-            ] as const)),
-        ...(opener.expiresAt === null
-          ? []
-          : ([
-              ["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
-      // naming that escrow; the CLI defaults to the network's current one.
-      const escrowFlag =
-        opener.escrow !== null &&
-        opener.escrow.toLowerCase() !== config.escrow.toLowerCase()
-          ? ` --escrow ${opener.escrow}`
-          : "";
+    if (opener === null || opener.streamId === null) {
+      out.result(payResult);
+      return;
+    }
+    const streamId = opener.streamId;
+    out.table([
+      ["streamId", streamId],
+      ["opener", opener.opener],
+      ["payer", account.address],
+      ...splitRows(quote, opener.upfrontFee),
+      ...(opener.deposit === null
+        ? []
+        : ([["deposit", formatUsdc(opener.deposit)]] as const)),
+      ...(opener.ratePerSecond === null
+        ? []
+        : ([
+            ["rate", `${formatUsdc(opener.ratePerSecond)} / verified second`],
+          ] as const)),
+      ...(quote?.minEarnSeconds === null || quote?.minEarnSeconds === undefined
+        ? []
+        : ([
+            [
+              "fully earned after",
+              `${formatDuration(Number(quote.minEarnSeconds))} of verified delivery`,
+            ],
+          ] as const)),
+      ...(opener.expiresAt === null
+        ? []
+        : ([
+            ["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("");
+    const refundCommand = (flags: string): string =>
+      opener.refundUrl === null
+        ? `metrik reclaim ${streamId}${escrowFlag}`
+        : `metrik refund ${streamId} --refund-url ${opener.refundUrl}${escrowFlag} ${flags}`;
+
+    if (!closeAfter) {
+      out.result(payResult);
       out.print(
         quote?.openerKind === "upfront" &&
           quote.upfrontAmount !== null &&
@@ -328,13 +381,208 @@ export const payCommand: CommandSpec = {
       );
       out.print(
         opener.refundUrl === null
-          ? `  metrik reclaim ${opener.streamId}${escrowFlag}      (anyone may send it; the refund always goes to the payer)`
-          : `  metrik refund ${opener.streamId} --refund-url ${opener.refundUrl}${escrowFlag} --close --reclaim`,
+          ? `  ${refundCommand("")}      (anyone may send it; the refund always goes to the payer)`
+          : `  ${refundCommand("--close --reclaim")}`,
       );
+      return;
     }
+
+    // --close-after: the buyer asked for it, so THIS client now sends the
+    // buyer's own close and reclaim. Not an automatic refund.
+    out.note(
+      "--close-after: closing the stream now, as you asked. This client signs the payer's Close and the seller's refund relay sends it (the relay pays the gas); then it waits for the checkpoint covering the close and asks the relay to reclaim the unearned part to the payer.",
+    );
+    const outcome = await closeAfterPayment({
+      payment: opener,
+      payer: account.address,
+      openRefunds: async () =>
+        await x402.refundClient(config, {
+          refundUrl: opener.refundUrl as string,
+          streamId,
+          opener: opener.opener,
+          maxAttempts: DEFAULT_ATTEMPTS,
+          maxDelayMs: DEFAULT_MAX_WAIT_SECONDS * 1_000,
+          ...(typeof opener.settledAt === "number"
+            ? { settledAt: opener.settledAt }
+            : {}),
+        }),
+      closeSigner: async () =>
+        await authorizeCloseSigner(account, config.chainId),
+      sleep: deps.sleep,
+      note: out.note,
+      ...(context.progress === undefined
+        ? {}
+        : {
+            setActivity: (activity: string | null) =>
+              context.progress?.setActivity(activity),
+          }),
+      reclaimActivity: reclaimActivity(
+        DEFAULT_ATTEMPTS,
+        DEFAULT_MAX_WAIT_SECONDS,
+      ),
+    });
+    const finishCommand =
+      outcome.outcome === "incomplete"
+        ? refundCommand(
+            outcome.incomplete?.closed === true
+              ? "--reclaim"
+              : "--close --reclaim",
+          )
+        : null;
+    out.result({
+      ...payResult,
+      closeAfter: describeCloseAfter(outcome, {
+        price: quote?.amount ?? null,
+        deposit: opener.deposit,
+        finishCommand,
+      }),
+    });
+    out.table(closeAfterRows(outcome, quote, opener.deposit));
+    out.print("");
+    if (outcome.outcome === "incomplete") {
+      const incomplete = outcome.incomplete;
+      const why =
+        incomplete?.error instanceof Error
+          ? explainRefundFailure(incomplete.error)
+          : null;
+      throw new CliError(
+        `paid (HTTP ${result.response.status}), but the close-after did not finish: ${incomplete?.stage === "no-relay" ? "" : `the ${incomplete?.stage ?? "close"} did not finish — `}${incomplete?.reason ?? "unknown"}`,
+        {
+          exitCode: 5,
+          hint: `the payment and the response are fine, and nothing is lost: ${incomplete?.closed === true ? "the stream is closed and " : ""}the unearned part stays in the escrow for the payer. Finish it with:\n    ${finishCommand ?? refundCommand("--close --reclaim")}${
+            why instanceof CliError && why.hint !== undefined
+              ? `\n  (${why.hint})`
+              : ""
+          }`,
+          cause: incomplete?.error ?? undefined,
+        },
+      );
+    }
+    out.print(describeCloseAfterDone(outcome));
   },
 };
 
+/**
+ * The `closeAfter` part of `metrik pay --close-after --json`: what this
+ * client's close + reclaim did, with the amounts from the verified receipt.
+ */
+export function describeCloseAfter(
+  outcome: CloseAfterOutcome,
+  context: {
+    readonly price: bigint | null;
+    readonly deposit: bigint | null;
+    readonly finishCommand: string | null;
+  },
+): Record<string, unknown> {
+  const refunded = outcome.refundedUsdc;
+  return {
+    outcome: outcome.outcome,
+    streamId: outcome.streamId,
+    close:
+      outcome.close === null
+        ? null
+        : {
+            transaction: outcome.close.transaction,
+            verified: outcome.close.verified,
+          },
+    closeSkipped: outcome.closeSkipped,
+    reclaim:
+      outcome.reclaim === null
+        ? null
+        : {
+            transaction: outcome.reclaim.transaction,
+            amount: outcome.reclaim.amount,
+            verified: outcome.reclaim.verified,
+          },
+    reclaimSkipped: outcome.reclaimSkipped,
+    // Base units returned to the payer, from the receipt's ReclaimForwarded
+    // (null unless the receipt was verified).
+    refunded,
+    // What the payment finally cost: price - refunded (upfront + earned).
+    kept:
+      refunded === null || context.price === null
+        ? null
+        : context.price - refunded,
+    // What the seller earned from the escrow: deposit - refunded.
+    earned:
+      refunded === null || context.deposit === null
+        ? null
+        : context.deposit - refunded,
+    finishedReason: outcome.finished,
+    status: outcome.status?.status ?? null,
+    reclaimed: outcome.status?.reclaimed ?? null,
+    incomplete:
+      outcome.incomplete === null
+        ? null
+        : {
+            stage: outcome.incomplete.stage,
+            closed: outcome.incomplete.closed,
+            reason: outcome.incomplete.reason,
+          },
+    finishCommand: context.finishCommand,
+    // The buyer's own client sent these, at the buyer's request.
+    sentBy: "buyer",
+    refundIsAutomatic: false,
+  };
+}
+
+/** Human rows for a close-after run. */
+function closeAfterRows(
+  outcome: CloseAfterOutcome,
+  quote: X402QuoteSummary | null,
+  deposit: bigint | null,
+): (readonly [string, string])[] {
+  const rows: (readonly [string, string])[] = [];
+  if (outcome.close !== null) {
+    rows.push([
+      "close tx",
+      `${outcome.close.transaction}${outcome.close.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+  } else if (outcome.closeSkipped !== null) {
+    rows.push(["close", "skipped — already closed"]);
+  }
+  if (outcome.reclaim !== null) {
+    rows.push([
+      "reclaim tx",
+      `${outcome.reclaim.transaction}${outcome.reclaim.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+    const amount = outcome.refundedUsdc ?? outcome.reclaim.amount;
+    if (amount !== null) {
+      rows.push([
+        "refunded to payer",
+        `${formatUsdc(amount)}${outcome.refundedUsdc === null ? " (relay-reported; the receipt was NOT verified)" : " (from the verified receipt)"}`,
+      ]);
+      if (deposit !== null) {
+        rows.push([
+          "seller earned",
+          `${formatUsdc(deposit - amount)} (verified seconds)`,
+        ]);
+      }
+      if (quote !== null) {
+        rows.push([
+          "payment cost",
+          `${formatUsdc(quote.amount - amount)} of the ${formatUsdc(quote.amount)} paid`,
+        ]);
+      }
+    }
+  }
+  return rows;
+}
+
+function describeCloseAfterDone(outcome: CloseAfterOutcome): string {
+  if (outcome.reclaim !== null) {
+    const amount = outcome.refundedUsdc ?? outcome.reclaim.amount;
+    return `Closed and reclaimed at your request: ${amount === null ? "the unearned remainder" : formatUsdc(amount)} went back to the payer${outcome.refundedUsdc !== null ? " (receipt verified on-chain)" : ""}. Nothing further to do for this stream.`;
+  }
+  if (outcome.finished === "reclaimed") {
+    return "Already finished: the stream is closed and was already reclaimed to the payer. Nothing further to do.";
+  }
+  if (outcome.finished === "nothing-to-reclaim") {
+    return "Closed at your request. Nothing to reclaim: the verified delivery covers the whole deposit, so none of it is unearned.";
+  }
+  return "Closed at your request.";
+}
+
 /**
  * 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