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

package/src/mcp/x402-tools.ts

@@ -31,6 +31,10 @@ import type {
   PayX402WithMandateResult,
   X402PostSignatureError,
 } from "../x402-buyer/pay.js";
+import {
+  closeAfterPayment,
+  type CloseAfterOutcome,
+} from "../x402-buyer/refund-actions.js";
 
 /**
  * The MCP surface for x402 (metrik-agent#121 item 4): `x402_pay`,
@@ -45,7 +49,7 @@ import type {
  */
 
 export const X402_PAY_TOOL_DESCRIPTION =
-  "Pay an x402 endpoint (HTTP 402 Payment Required, x402 v2 'exact') and return its response. A Metrik x402 seller quotes a payment that opens an escrow STREAM; the seller earns ratePerSecond x VERIFIED seconds, capped at the deposit, and the unearned remainder stays recoverable by this server's wallet. An UPFRONT ('minimum charge') quote splits the price: upfrontAmount is a NON-REFUNDABLE per-call charge paid to the seller at settlement, and only price - upfrontAmount is escrowed and refundable; when upfrontAmount == price no stream opens at all (streamId null, nothing to refund). Subject to the agent's spend mandate (the WHOLE price vs per-stream and total caps, rate, duration, operator) and a cap on the non-refundable part (maxUpfrontAmountUsdc, default 0.10 USDC), checked BEFORE anything is signed. Refunds are NOT automatic: use refund_status and refund with the returned streamId.";
+  "Pay an x402 endpoint (HTTP 402 Payment Required, x402 v2 'exact') and return its response. A Metrik x402 seller quotes a payment that opens an escrow STREAM; the seller earns ratePerSecond x VERIFIED seconds, capped at the deposit, and the unearned remainder stays recoverable by this server's wallet. An UPFRONT ('minimum charge') quote splits the price: upfrontAmount is a NON-REFUNDABLE per-call charge paid to the seller at settlement, and only price - upfrontAmount is escrowed and refundable; when upfrontAmount == price no stream opens at all (streamId null, nothing to refund). Subject to the agent's spend mandate (the WHOLE price vs per-stream and total caps, rate, duration, operator) and a cap on the non-refundable part (maxUpfrontAmountUsdc, default 0.10 USDC), checked BEFORE anything is signed. Refunds are NOT automatic: pass closeAfter=true to have this server close the stream and reclaim the unearned part right after the response (recommended for one-shot calls), or use refund_status and refund with the returned streamId later.";
 export const REFUND_STATUS_TOOL_DESCRIPTION =
   "Read the refund state of a stream this server paid for over x402, from the seller's gasless refund relay: whether it is running, what is reclaimable, and the next step (close / wait / reclaim). An upfront-only payment (no stream) has nothing to refund. Moves no funds.";
 export const REFUND_TOOL_DESCRIPTION =
@@ -66,6 +70,8 @@ export interface McpX402Options {
     readonly opener?: `0x${string}`;
     /** The guarded fetch the relay client must use. */
     readonly fetch?: typeof fetch;
+    /** When the payment settled, unix ms (`x402_pay` with `closeAfter`). */
+    readonly settledAt?: number;
   }) => Promise<RefundClient>;
   /** Passed to the SDK payer (e.g. a transport for the on-chain checks). */
   readonly sdkOptions?: PayX402WithMandateInput["sdkOptions"];
@@ -76,6 +82,8 @@ export interface McpX402Options {
    * refund_status may contact (exact, or `*.domain`). Unset = any PUBLIC host.
    */
   readonly allowedHosts?: readonly string[];
+  /** Delay used while a close-after waits for the relay (tests). Default `setTimeout`. */
+  readonly sleep?: (ms: number) => Promise<void>;
   /** Base fetch under the outbound guard (tests). Default `globalThis.fetch`. */
   readonly fetch?: typeof fetch;
   /** DNS resolution for the outbound guard (tests). */
@@ -118,6 +126,8 @@ export interface McpX402Context {
     readonly x402Charge?: "upfront-only";
     /** The non-refundable part of the payment (the upfront charge), base units. */
     readonly nonRefundableUsdc?: bigint;
+    /** Base units this server's own verified reclaim returned to the payer. */
+    readonly reclaimedUsdc?: bigint;
   }) => Promise<void>;
   /** Drop a record (a released reservation). Absent = reservations are kept. */
   readonly removeStream?: (streamId: `0x${string}`) => Promise<void>;
@@ -185,6 +195,12 @@ const x402PaySchema = {
     .describe(
       "Cap on the NON-REFUNDABLE per-call part of an upfront-opener quote, base units. Default 100000 (0.10 USDC); 0 refuses any upfront charge.",
     ),
+  closeAfter: z
+    .boolean()
+    .optional()
+    .describe(
+      "true = right after a successful paid response, this server closes the stream on your behalf (it signs the payer's Close; the seller's refund relay sends it and pays the gas), waits for the checkpoint covering the close, and reclaims the unearned part to the payer. For one-shot calls: without it the stream keeps running and the seller can earn the whole metered part for one response. Your request, sent by this server; not an automatic refund. Only what the payment finally keeps counts against the spend mandate. The tool can take a minute or two longer.",
+    ),
 } as const;
 
 const ZERO_STREAM_ID = `0x${"00".repeat(32)}` as const;
@@ -245,12 +261,16 @@ export function registerX402Tools(
       streamId: `0x${string}`;
       opener?: `0x${string}`;
       fetch?: typeof fetch;
+      settledAt?: number;
     }) => {
       const { refundClient } = await import("@absol-labs/sdk/x402");
       return refundClient(target.refundUrl, {
         streamId: target.streamId,
         ...(target.opener === undefined ? {} : { opener: target.opener }),
         ...(target.fetch === undefined ? {} : { fetch: target.fetch }),
+        ...(target.settledAt === undefined
+          ? {}
+          : { settledAt: target.settledAt }),
         expectedChainId: ctx.x402.network.chain.id,
         // Chain access is what lets the SDK read the opener's KIND on-chain and
         // sign an upfront opener's Close under its own EIP-712 domain; without
@@ -292,7 +312,10 @@ export function registerX402Tools(
         await assertOutboundUrlAllowed(args.url, guard);
         const signedMandate = await ctx.resolveMandate();
         const owner = signedMandate.owner as `0x${string}`;
-        return await ctx.serialize(owner, async () => {
+        // A stream payment whose close-after runs OUTSIDE this owner's
+        // serialized queue (it can wait a minute or two for a checkpoint).
+        const pending: { close: PendingCloseAfter | null } = { close: null };
+        const answer = await ctx.serialize(owner, async () => {
           const spentSoFarUsdc = await ctx.getSpentSoFarUsdc(owner);
           const revokedMandateIds = await ctx.getRevokedMandateIds(owner);
           const nowSeconds = ctx.now();
@@ -372,6 +395,7 @@ export function registerX402Tools(
           }
           const opener = result.metrikStreamOpener;
           const upfrontAmount = result.quote?.upfrontAmount ?? null;
+          let streamRecord: StreamRecord | null = null;
           if (
             result.paid &&
             opener !== null &&
@@ -404,7 +428,7 @@ export function registerX402Tools(
             result.approved !== null
           ) {
             // Replace the reservation with the real stream (same amount).
-            await ctx.recordStream({
+            streamRecord = {
               streamId: opener.streamId,
               buyer: owner,
               operator: result.approved.operator,
@@ -422,7 +446,8 @@ export function registerX402Tools(
               ...(upfrontAmount === null || upfrontAmount === 0n
                 ? {}
                 : { nonRefundableUsdc: upfrontAmount }),
-            });
+            };
+            await ctx.recordStream(streamRecord);
             await release();
           } else if (!result.paid) {
             // No 402 was answered, so nothing was approved or signed.
@@ -461,19 +486,51 @@ export function registerX402Tools(
           };
           if (opener !== null && opener.streamId === null) {
             return ctx.ok(
-              `paid ${result.quote?.amount.toString() ?? "?"} USDC base units as an UPFRONT-ONLY charge; HTTP ${result.response.status}. The whole price was a non-refundable per-call charge paid to the seller at settlement: no stream was opened, the payment is final and there is nothing to refund.`,
-              structured,
+              `paid ${result.quote?.amount.toString() ?? "?"} USDC base units as an UPFRONT-ONLY charge; HTTP ${result.response.status}. The whole price was a non-refundable per-call charge paid to the seller at settlement: no stream was opened, the payment is final and there is nothing to refund.${args.closeAfter === true ? " closeAfter: nothing to close (no stream was opened); nothing was signed or sent." : ""}`,
+              args.closeAfter === true
+                ? {
+                    ...structured,
+                    closeAfter: {
+                      outcome: "nothing-to-close",
+                      refundIsAutomatic: false,
+                    },
+                  }
+                : structured,
             );
           }
           const split =
             upfrontAmount !== null && upfrontAmount > 0n
               ? ` Of the ${result.quote?.amount.toString() ?? "?"} paid, ${upfrontAmount.toString()} was a NON-REFUNDABLE per-call charge (final); only the ${opener?.deposit?.toString() ?? "?"} escrowed can come back.`
               : "";
+          const paidText = `paid ${opener?.deposit?.toString() ?? "?"} USDC base units into stream ${opener?.streamId ?? "?"}; HTTP ${result.response.status}.${split}`;
+          if (
+            args.closeAfter === true &&
+            opener !== null &&
+            opener.streamId !== null &&
+            streamRecord !== null
+          ) {
+            pending.close = {
+              opener: { ...opener, streamId: opener.streamId },
+              record: streamRecord,
+              paidText,
+              structured,
+            };
+            return null;
+          }
           return ctx.ok(
-            `paid ${opener?.deposit?.toString() ?? "?"} USDC base units into stream ${opener?.streamId ?? "?"}; HTTP ${result.response.status}.${split} The seller earns only for VERIFIED seconds; the unearned remainder is NOT refunded automatically — call refund (or refund_status) with this streamId.`,
+            `${paidText} The seller earns only for VERIFIED seconds; the unearned remainder is NOT refunded automatically — call refund (or refund_status) with this streamId.`,
             structured,
           );
         });
+        if (answer !== null || pending.close === null) {
+          return answer ?? ctx.unexpected(new Error("no x402_pay result"));
+        }
+        return await runCloseAfter(ctx, pending.close, {
+          owner,
+          guard,
+          guardedFetch,
+          openRefunds,
+        });
       } catch (error) {
         if (error instanceof OutboundRequestRefusedError) {
           return ctx.fail(error.message);
@@ -620,6 +677,164 @@ export function registerX402Tools(
   );
 }
 
+type StreamRecord = Parameters<McpX402Context["recordStream"]>[0];
+type ToolResult = ReturnType<McpX402Context["ok"]>;
+
+/** A paid stream whose close-after runs once the owner's queue is released. */
+interface PendingCloseAfter {
+  readonly opener: NonNullable<
+    PayX402WithMandateResult["metrikStreamOpener"]
+  > & {
+    readonly streamId: `0x${string}`;
+  };
+  readonly record: StreamRecord;
+  readonly paidText: string;
+  readonly structured: Record<string, unknown>;
+}
+
+/**
+ * `x402_pay` with `closeAfter`: right after the paid response, at the model's
+ * request, this server closes the stream (it signs the payer's Close, the
+ * seller's relay sends it) and reclaims the unearned part to the payer, with
+ * `metrik refund`'s run. The tool still SUCCEEDS when that does not finish —
+ * the payment and the response are good — and says exactly how to finish it.
+ *
+ * Spend accounting: only a reclaim whose mined receipt was VERIFIED
+ * (`ReclaimForwarded` to the payer) is credited back, as the record's
+ * `reclaimedUsdc`; the relay's unverified word never lowers counted spend.
+ */
+async function runCloseAfter(
+  ctx: McpX402Context,
+  pending: PendingCloseAfter,
+  wiring: {
+    readonly owner: `0x${string}`;
+    readonly guard: Parameters<typeof assertOutboundUrlAllowed>[1];
+    readonly guardedFetch: typeof fetch;
+    readonly openRefunds: (target: {
+      refundUrl: string;
+      streamId: `0x${string}`;
+      opener?: `0x${string}`;
+      fetch?: typeof fetch;
+      settledAt?: number;
+    }) => Promise<RefundClient>;
+  },
+): Promise<ToolResult> {
+  const { opener, record } = pending;
+  const outcome = await closeAfterPayment({
+    payment: opener,
+    payer: ctx.x402.signer.address as `0x${string}`,
+    openRefunds: async () => {
+      const refundUrl = opener.refundUrl as string;
+      await assertOutboundUrlAllowed(
+        refundUrl.replace("{streamId}", opener.streamId),
+        wiring.guard,
+      );
+      return await wiring.openRefunds({
+        refundUrl,
+        streamId: opener.streamId,
+        opener: opener.opener,
+        fetch: wiring.guardedFetch,
+        ...(typeof opener.settledAt === "number"
+          ? { settledAt: opener.settledAt }
+          : {}),
+      });
+    },
+    // Buyer recovery, authorized on the mandate owner's signature alone —
+    // the same rule as the refund tool.
+    closeSigner: async () => {
+      const signedMandate = await ctx.resolveMandate();
+      const decision = await verifyMandateOwnerSignature(signedMandate);
+      if (!decision.allowed) {
+        throw new Error(`mandate denied: ${decision.reason ?? "unknown"}`);
+      }
+      return ctx.x402.signer;
+    },
+    sleep:
+      ctx.x402.sleep ??
+      (async (ms) => {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+      }),
+  });
+
+  let counted = record.budgetUsdc;
+  const refunded = outcome.refundedUsdc;
+  if (refunded !== null && refunded > 0n && refunded <= record.budgetUsdc) {
+    // Only what the payment finally kept counts against the mandate.
+    await ctx.serialize(wiring.owner, async () => {
+      await ctx.recordStream({ ...record, reclaimedUsdc: refunded });
+    });
+    counted = record.budgetUsdc - refunded;
+  }
+  const closeAfter = {
+    outcome: outcome.outcome,
+    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,
+            amountUsdc: outcome.reclaim.amount?.toString() ?? null,
+            verified: outcome.reclaim.verified,
+          },
+    reclaimSkipped: outcome.reclaimSkipped,
+    refundedUsdc: refunded?.toString() ?? null,
+    finishedReason: outcome.finished,
+    incomplete:
+      outcome.incomplete === null
+        ? null
+        : {
+            stage: outcome.incomplete.stage,
+            closed: outcome.incomplete.closed,
+            reason: outcome.incomplete.reason,
+          },
+    sentBy: "buyer",
+    refundIsAutomatic: false,
+  };
+  const structured = {
+    ...pending.structured,
+    closeAfter,
+    countedSpendUsdc: counted.toString(),
+  };
+  return ctx.ok(
+    `${pending.paidText} ${describeCloseAfter(outcome, opener.streamId, counted)}`,
+    structured,
+  );
+}
+
+function describeCloseAfter(
+  outcome: CloseAfterOutcome,
+  streamId: `0x${string}`,
+  counted: bigint,
+): string {
+  const spend = `${counted.toString()} USDC base units count against the spend mandate.`;
+  if (outcome.outcome === "incomplete") {
+    const incomplete = outcome.incomplete;
+    if (incomplete?.stage === "no-relay") {
+      return `closeAfter did NOT finish: ${incomplete.reason}. ${spend}`;
+    }
+    return `closeAfter did NOT finish: the ${incomplete?.stage ?? "close"} did not complete (${incomplete?.reason ?? "unknown"}). Nothing is lost: the unearned part stays in the escrow for the payer. Finish it with refund (streamId ${streamId}${incomplete?.closed === true ? ", reclaim=true" : ", close=true, reclaim=true"}). ${spend}`;
+  }
+  const closed =
+    outcome.close === null
+      ? "the stream was already closed"
+      : `closed the stream (${outcome.close.transaction})`;
+  if (outcome.reclaim !== null) {
+    const amount = outcome.refundedUsdc ?? outcome.reclaim.amount;
+    return `closeAfter: at your request this server ${closed} and reclaimed ${amount?.toString() ?? "the unearned remainder"} USDC base units to the payer (${outcome.reclaim.transaction}${outcome.refundedUsdc !== null ? ", receipt verified on-chain" : ", relay-reported, not verified"}). ${spend}`;
+  }
+  if (outcome.finished === "reclaimed") {
+    return `closeAfter: ${closed}; it was already reclaimed to the payer. ${spend}`;
+  }
+  return `closeAfter: ${closed}; nothing to reclaim — the verified delivery covers the whole deposit. ${spend}`;
+}
+
 /** Upfront-only payments: a finished, successful answer — not an error. */
 function nothingToRefund(ctx: McpX402Context, args: { streamId: string }) {
   return ctx.ok(

package/src/x402-buyer/index.ts

@@ -7,3 +7,4 @@
  */
 export * from "./pay.js";
 export * from "./guarded-fetch.js";
+export * from "./refund-actions.js";

package/src/x402-buyer/pay.ts

@@ -1,7 +1,8 @@
-import type { MetrikNetwork } from "@absol-labs/sdk";
+import type { MetrikClient, MetrikNetwork } from "@absol-labs/sdk";
 import {
   findStreamForAuthorization,
   payWithX402,
+  refundClient,
   X402PaymentRefusedError,
   type PayWithX402Options,
   type PayWithX402Result,
@@ -19,6 +20,7 @@ import {
   type MandateDecision,
   type SignedSpendMandate,
 } from "../mandates/mandate.js";
+import { closeAfterPayment, type CloseAfterOutcome } from "./refund-actions.js";
 
 /**
  * Buyer-side x402 payments under a spend mandate (metrik-agent#121).
@@ -164,6 +166,35 @@ export interface PayX402WithMandateInput {
     PublicClient,
     "readContract" | "getLogs" | "getBlockNumber"
   >;
+  /**
+   * Close the stream and reclaim the unearned part right after a successful
+   * paid response, at the buyer's request: `signer` signs the payer's Close,
+   * the seller's refund relay sends it (and pays the gas), the client waits
+   * (bounded, honouring `Retry-After`) for the checkpoint covering the close,
+   * then asks the relay to reclaim to the payer. This is the buyer's own
+   * client acting for the buyer, not an automatic refund. Its outcome is
+   * {@link PayX402WithMandateResult.closeAfter}; a close/reclaim that does not
+   * finish never fails the payment. `true` uses the defaults below.
+   */
+  readonly closeAfter?: boolean | CloseAfterOptions;
+}
+
+/** Options of {@link PayX402WithMandateInput.closeAfter}. */
+export interface CloseAfterOptions {
+  /**
+   * Recommended: checks every relayed close/reclaim against its mined receipt,
+   * so `closeAfter.refundedUsdc` is the amount the receipt proves. Without it
+   * the relay's word is reported and `refundedUsdc` stays `null`.
+   */
+  readonly verifyWith?: MetrikClient;
+  /** Relay attempts while it says "not yet" (default the SDK's, 5). */
+  readonly maxAttempts?: number;
+  /** Longest single wait honoured, ms (default the SDK's, 60 000). */
+  readonly maxDelayMs?: number;
+  /** Injectable delay (tests). */
+  readonly sleep?: (ms: number) => Promise<void>;
+  /** Test seam: the refund client factory. Default the SDK's `refundClient`. */
+  readonly refundClientImpl?: typeof refundClient;
 }
 
 /** What is known about a payment whose signature was handed out but that did not complete cleanly. */
@@ -286,6 +317,13 @@ function authorizationFromHeader(
 export interface PayX402WithMandateResult extends PayWithX402Result {
   /** The stream-open request the mandate approved (null if nothing was paid). */
   readonly approved: HireRequest | null;
+  /**
+   * What `closeAfter` did: `null` when it was not requested or nothing was
+   * paid. What the payment finally cost is `approved.budgetUsdc -
+   * closeAfter.refundedUsdc` (when `refundedUsdc` is non-null): a caller that
+   * tracks cumulative spend counts only that.
+   */
+  readonly closeAfter: CloseAfterOutcome | null;
 }
 
 function smaller(a: bigint, b: bigint | undefined): bigint {
@@ -444,7 +482,66 @@ export async function payX402WithMandate(
       sentAuthorization,
     });
   }
-  return { ...result, approved: result.paid ? approved : null };
+  const closeAfter =
+    input.closeAfter === undefined ||
+    input.closeAfter === false ||
+    !result.paid ||
+    result.metrikStreamOpener === null
+      ? null
+      : await runCloseAfter(input, result.metrikStreamOpener);
+  return { ...result, approved: result.paid ? approved : null, closeAfter };
+}
+
+/** {@link PayX402WithMandateInput.closeAfter}, with the SDK's refund client. */
+async function runCloseAfter(
+  input: PayX402WithMandateInput,
+  payment: NonNullable<PayWithX402Result["metrikStreamOpener"]>,
+): Promise<CloseAfterOutcome> {
+  const options: CloseAfterOptions =
+    typeof input.closeAfter === "object" ? input.closeAfter : {};
+  const sleep =
+    options.sleep ??
+    (async (ms: number) => {
+      await new Promise((resolve) => setTimeout(resolve, ms));
+    });
+  const open = options.refundClientImpl ?? refundClient;
+  return await closeAfterPayment({
+    payment,
+    payer: getAddress(input.signer.address),
+    openRefunds: async () =>
+      open(payment, {
+        ...(options.verifyWith === undefined
+          ? {
+              // Chain access proves the opener's kind (the Close's EIP-712
+              // domain) when no MetrikClient is given.
+              publicClient:
+                input.sdkOptions?.publicClient ??
+                (createPublicClient({
+                  chain: input.network.chain,
+                  transport:
+                    input.sdkOptions?.transport ??
+                    http(input.network.rpcUrls[0]),
+                }) as PublicClient),
+              network: input.network,
+            }
+          : { verifyWith: options.verifyWith }),
+        expectedChainId: input.network.chain.id,
+        ...(input.sdkOptions?.fetch === undefined
+          ? {}
+          : { fetch: input.sdkOptions.fetch }),
+        ...(options.maxAttempts === undefined
+          ? {}
+          : { maxAttempts: options.maxAttempts }),
+        ...(options.maxDelayMs === undefined
+          ? {}
+          : { maxDelayMs: options.maxDelayMs }),
+        sleep,
+      }),
+    // The mandate's owner IS the payer (checked before paying): the buyer's
+    // own recovery needs nothing more.
+    closeSigner: async () => input.signer,
+    sleep,
+  });
 }
 
 /**