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

package/src/mcp/x402-tools.ts

@@ -0,0 +1,785 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import type {
+  RefundClient,
+  RefundRelayResult,
+  RefundStatus,
+  X402PayerSigner,
+} from "@absol-labs/sdk/x402";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import {
+  verifyMandateOwnerSignature,
+  type SignedSpendMandate,
+} from "../mandates/mandate.js";
+import {
+  createPublicClient,
+  http,
+  keccak256,
+  toHex,
+  type PublicClient,
+} from "viem";
+
+import {
+  assertOutboundUrlAllowed,
+  createGuardedFetch,
+  OutboundRequestRefusedError,
+  type LookupFn,
+} from "../x402-buyer/guarded-fetch.js";
+import type {
+  PayX402WithMandateInput,
+  PayX402WithMandateResult,
+  X402PostSignatureError,
+} from "../x402-buyer/pay.js";
+
+/**
+ * The MCP surface for x402 (metrik-agent#121 item 4): `x402_pay`,
+ * `refund_status`, `refund`. Registered only when the server is given an
+ * {@link McpX402Options}; every existing tool is unchanged.
+ *
+ * `x402_pay` is gated exactly like `hire_verified_service`: the SAME server
+ * mandate, the SAME per-owner serialization, the SAME cumulative spend
+ * (`getSpentSoFarUsdc`, which counts the stream this payment opens once it is
+ * recorded), and `checkMandate()` on the payment's opener terms before the SDK
+ * signs anything (see `../x402-buyer/pay.ts`).
+ */
+
+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.";
+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 =
+  "Recover the unearned part of an x402 payment through the seller's gasless refund relay: close=true stops the stream (this wallet signs the opener's Close; the relay pays the gas), reclaim=true sends the permissionless reclaim (the refund always goes to the payer). Only the escrowed part can come back: an upfront charge is final, and an upfront-only payment has nothing to refund. Nothing is refunded automatically; reclaim waits for the settlement window and may say when to retry.";
+
+export interface McpX402Options {
+  /** The payer: this server's own wallet (must own the server mandate). */
+  readonly signer: X402PayerSigner;
+  readonly network: MetrikNetwork;
+  /** Mandate-gated payer. Default: `payX402WithMandate` (lazily loaded). */
+  readonly pay?: (
+    input: PayX402WithMandateInput,
+  ) => Promise<PayX402WithMandateResult>;
+  /** Refund relay client factory. Default: the SDK's `refundClient`. */
+  readonly refundClient?: (target: {
+    readonly refundUrl: string;
+    readonly streamId: `0x${string}`;
+    readonly opener?: `0x${string}`;
+    /** The guarded fetch the relay client must use. */
+    readonly fetch?: typeof fetch;
+  }) => Promise<RefundClient>;
+  /** Passed to the SDK payer (e.g. a transport for the on-chain checks). */
+  readonly sdkOptions?: PayX402WithMandateInput["sdkOptions"];
+  /** Chain reads after a post-signature failure (see `payX402WithMandate`). */
+  readonly chainReader?: PayX402WithMandateInput["chainReader"];
+  /**
+   * `METRIK_AGENT_X402_ALLOWED_HOSTS`: the only hosts x402_pay / refund /
+   * refund_status may contact (exact, or `*.domain`). Unset = any PUBLIC host.
+   */
+  readonly allowedHosts?: readonly string[];
+  /** Base fetch under the outbound guard (tests). Default `globalThis.fetch`. */
+  readonly fetch?: typeof fetch;
+  /** DNS resolution for the outbound guard (tests). */
+  readonly lookup?: LookupFn;
+  /**
+   * Local development / fork tests ONLY: let the outbound guard reach
+   * loopback and private addresses (and plain http). Never set from env.
+   */
+  readonly allowPrivateNetworks?: boolean;
+}
+
+/** What the server shares with these tools (its mandate state and registry). */
+export interface McpX402Context {
+  readonly x402: McpX402Options;
+  readonly resolveMandate: () =>
+    | SignedSpendMandate
+    | Promise<SignedSpendMandate>;
+  readonly getSpentSoFarUsdc: (owner: `0x${string}`) => Promise<bigint>;
+  readonly getRevokedMandateIds: (
+    owner: `0x${string}`,
+  ) => Promise<readonly `0x${string}`[]>;
+  readonly serialize: <T>(
+    owner: `0x${string}`,
+    task: () => Promise<T>,
+  ) => Promise<T>;
+  readonly recordStream: (record: {
+    readonly streamId: `0x${string}`;
+    readonly buyer: `0x${string}`;
+    readonly operator: `0x${string}`;
+    readonly serviceRef: `0x${string}`;
+    readonly budgetUsdc: bigint;
+    readonly ratePerSecondUsdc: bigint;
+    readonly maxDurationSeconds: number;
+    readonly openedAtSeconds: number;
+    readonly mandateId: `0x${string}`;
+    readonly refundUrl?: string;
+    readonly opener?: `0x${string}`;
+    readonly x402Reservation?: boolean;
+    /** Not a stream: a settled upfront-only charge (counted spend, nothing to refund). */
+    readonly x402Charge?: "upfront-only";
+    /** The non-refundable part of the payment (the upfront charge), base units. */
+    readonly nonRefundableUsdc?: bigint;
+  }) => Promise<void>;
+  /** Drop a record (a released reservation). Absent = reservations are kept. */
+  readonly removeStream?: (streamId: `0x${string}`) => Promise<void>;
+  readonly findStream: (streamId: `0x${string}`) => Promise<{
+    readonly refundUrl?: string;
+    readonly opener?: `0x${string}`;
+    readonly x402Charge?: "upfront-only";
+  } | null>;
+  readonly now: () => number;
+  readonly ok: (
+    text: string,
+    structured?: Record<string, unknown>,
+  ) => { content: { type: "text"; text: string }[] };
+  readonly fail: (text: string) => {
+    content: { type: "text"; text: string }[];
+    isError: boolean;
+  };
+  readonly unexpected: (error: unknown) => {
+    content: { type: "text"; text: string }[];
+    isError: boolean;
+  };
+}
+
+/** Longest response body returned to the model. */
+const MAX_BODY_CHARS = 32 * 1024;
+
+const atomicSchema = z
+  .string()
+  .regex(/^[1-9]\d*$/, "a positive integer of USDC base units (6 decimals)");
+const bytes32Schema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{64}$/, "a 0x-prefixed 32-byte hex value");
+
+const x402PaySchema = {
+  url: z
+    .string()
+    .url()
+    .describe("The x402 endpoint. https only (http only for localhost)."),
+  method: z
+    .enum(["GET", "POST", "PUT", "PATCH", "DELETE"])
+    .optional()
+    .describe("HTTP method. Default POST with a body, otherwise GET."),
+  headers: z.record(z.string()).optional(),
+  body: z.string().max(1_000_000).optional().describe("Request body."),
+  maxAmountUsdc: atomicSchema
+    .optional()
+    .describe(
+      "Optional price ceiling, base units. Can only TIGHTEN the server mandate's per-stream cap.",
+    ),
+  maxRatePerSecondUsdc: atomicSchema
+    .optional()
+    .describe("Optional rate ceiling, base units/second. Tightens only."),
+  minDurationSeconds: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Refuse a quote the seller can fully earn in fewer verified seconds.",
+    ),
+  maxUpfrontAmountUsdc: z
+    .string()
+    .regex(/^(0|[1-9]\d*)$/, "a non-negative integer of USDC base units")
+    .optional()
+    .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.",
+    ),
+} as const;
+
+const ZERO_STREAM_ID = `0x${"00".repeat(32)}` as const;
+
+const refundSchema = {
+  streamId: bytes32Schema,
+  refundUrl: z
+    .string()
+    .url()
+    .optional()
+    .describe(
+      "The seller's refund relay URL. Optional for a stream this server paid for (it was recorded).",
+    ),
+} as const;
+
+const refundActionSchema = {
+  ...refundSchema,
+  close: z
+    .boolean()
+    .optional()
+    .describe("Stop the stream first (this wallet signs Close)."),
+  reclaim: z
+    .boolean()
+    .optional()
+    .describe("Send the permissionless reclaim. Default true."),
+} as const;
+
+const PAYMENT_HEADERS = new Set(["payment-signature", "x-payment"]);
+
+export function registerX402Tools(
+  mcpServer: McpServer,
+  ctx: McpX402Context,
+): void {
+  const pay =
+    ctx.x402.pay ??
+    (async (input: PayX402WithMandateInput) => {
+      const { payX402WithMandate } = await import("../x402-buyer/pay.js");
+      return await payX402WithMandate(input);
+    });
+  // Every outbound request these tools make — the seller, and the refund
+  // relay — goes through the guard: https only, public addresses only, the
+  // optional host allowlist, and never a redirect.
+  const guard = {
+    ...(ctx.x402.allowedHosts === undefined
+      ? {}
+      : { allowedHosts: ctx.x402.allowedHosts }),
+    ...(ctx.x402.allowPrivateNetworks === true
+      ? { allowPrivateNetworks: true }
+      : {}),
+    ...(ctx.x402.fetch === undefined ? {} : { fetch: ctx.x402.fetch }),
+    ...(ctx.x402.lookup === undefined ? {} : { lookup: ctx.x402.lookup }),
+  };
+  const guardedFetch = createGuardedFetch(guard);
+  const openRefunds =
+    ctx.x402.refundClient ??
+    (async (target: {
+      refundUrl: string;
+      streamId: `0x${string}`;
+      opener?: `0x${string}`;
+      fetch?: typeof fetch;
+    }) => {
+      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 }),
+        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
+        // it, such a Close is refused.
+        publicClient: refundReader(ctx.x402),
+        network: ctx.x402.network,
+      });
+    });
+
+  mcpServer.registerTool(
+    "x402_pay",
+    {
+      description: X402_PAY_TOOL_DESCRIPTION,
+      inputSchema: x402PaySchema,
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+        readOnlyHint: false,
+        title: "Pay x402 Endpoint",
+      },
+    },
+    async (args) => {
+      const headers: Record<string, string> = {};
+      for (const [name, value] of Object.entries(args.headers ?? {})) {
+        if (PAYMENT_HEADERS.has(name.toLowerCase())) {
+          return ctx.fail(
+            `do not set the ${name} header: this server signs the payment itself, after the quote passes the spend mandate.`,
+          );
+        }
+        headers[name.toLowerCase()] = value;
+      }
+      if (args.body !== undefined && headers["content-type"] === undefined) {
+        headers["content-type"] = "application/json";
+      }
+      try {
+        // Refuse a forbidden target before the mandate, the registry or the
+        // seller is touched.
+        await assertOutboundUrlAllowed(args.url, guard);
+        const signedMandate = await ctx.resolveMandate();
+        const owner = signedMandate.owner as `0x${string}`;
+        return await ctx.serialize(owner, async () => {
+          const spentSoFarUsdc = await ctx.getSpentSoFarUsdc(owner);
+          const revokedMandateIds = await ctx.getRevokedMandateIds(owner);
+          const nowSeconds = ctx.now();
+          // The reservation: written BEFORE the SDK signs (onApproved), inside
+          // this owner's serialized queue, under a key of its own. It is
+          // released only when the authorization provably never moved money,
+          // and replaced by the real stream record once the stream is known.
+          let reservation: `0x${string}` | null = null;
+          const release = async () => {
+            if (reservation !== null) await ctx.removeStream?.(reservation);
+          };
+          let result: PayX402WithMandateResult;
+          try {
+            result = await pay({
+              url: args.url,
+              init: {
+                method:
+                  args.method ?? (args.body === undefined ? "GET" : "POST"),
+                headers,
+                ...(args.body === undefined ? {} : { body: args.body }),
+              },
+              signer: ctx.x402.signer,
+              network: ctx.x402.network,
+              signedMandate,
+              spentSoFarUsdc,
+              nowSeconds,
+              revokedMandateIds,
+              ...(args.maxAmountUsdc === undefined
+                ? {}
+                : { maxAmount: BigInt(args.maxAmountUsdc) }),
+              ...(args.maxRatePerSecondUsdc === undefined
+                ? {}
+                : { maxRatePerSecond: BigInt(args.maxRatePerSecondUsdc) }),
+              ...(args.minDurationSeconds === undefined
+                ? {}
+                : { minDurationSeconds: args.minDurationSeconds }),
+              ...(args.maxUpfrontAmountUsdc === undefined
+                ? {}
+                : { maxUpfrontAmount: BigInt(args.maxUpfrontAmountUsdc) }),
+              sdkOptions: { ...ctx.x402.sdkOptions, fetch: guardedFetch },
+              ...(ctx.x402.chainReader === undefined
+                ? {}
+                : { chainReader: ctx.x402.chainReader }),
+              onApproved: async ({ request, quote }) => {
+                reservation = keccak256(
+                  toHex(
+                    `x402-reservation:${owner}:${quote.payTo}:${nowSeconds}:${crypto.randomUUID()}`,
+                  ),
+                );
+                await ctx.recordStream({
+                  streamId: reservation,
+                  buyer: owner,
+                  operator: request.operator,
+                  serviceRef:
+                    quote.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+                  budgetUsdc: request.budgetUsdc,
+                  ratePerSecondUsdc: request.ratePerSecondUsdc,
+                  maxDurationSeconds: request.maxDurationSeconds,
+                  openedAtSeconds: nowSeconds,
+                  mandateId: signedMandate.mandateId as `0x${string}`,
+                  opener: quote.payTo,
+                  x402Reservation: true,
+                  ...(quote.upfrontAmount === null || quote.upfrontAmount === 0n
+                    ? {}
+                    : { nonRefundableUsdc: quote.upfrontAmount }),
+                });
+              },
+            });
+          } catch (error) {
+            return await settleFailure(ctx, error, {
+              release,
+              reservation,
+              owner,
+              mandateId: signedMandate.mandateId as `0x${string}`,
+              nowSeconds,
+            });
+          }
+          const opener = result.metrikStreamOpener;
+          const upfrontAmount = result.quote?.upfrontAmount ?? null;
+          if (
+            result.paid &&
+            opener !== null &&
+            opener.streamId === null &&
+            result.approved !== null
+          ) {
+            // Upfront-only: there is NO stream to record or refund. The spend
+            // still counts against the mandate (the whole price is gone), so
+            // the reservation is replaced by a permanent, non-stream charge.
+            await ctx.recordStream({
+              streamId: chargeKey(owner, opener.opener, result),
+              buyer: owner,
+              operator: result.approved.operator,
+              serviceRef:
+                result.quote?.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+              budgetUsdc: result.approved.budgetUsdc,
+              ratePerSecondUsdc: result.approved.ratePerSecondUsdc,
+              maxDurationSeconds: result.approved.maxDurationSeconds,
+              openedAtSeconds: nowSeconds,
+              mandateId: signedMandate.mandateId as `0x${string}`,
+              opener: opener.opener,
+              x402Charge: "upfront-only",
+              nonRefundableUsdc: result.approved.budgetUsdc,
+            });
+            await release();
+          } else if (
+            result.paid &&
+            opener !== null &&
+            opener.streamId !== null &&
+            result.approved !== null
+          ) {
+            // Replace the reservation with the real stream (same amount).
+            await ctx.recordStream({
+              streamId: opener.streamId,
+              buyer: owner,
+              operator: result.approved.operator,
+              serviceRef:
+                result.quote?.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+              budgetUsdc: result.approved.budgetUsdc,
+              ratePerSecondUsdc: result.approved.ratePerSecondUsdc,
+              maxDurationSeconds: result.approved.maxDurationSeconds,
+              openedAtSeconds: nowSeconds,
+              mandateId: signedMandate.mandateId as `0x${string}`,
+              ...(opener.refundUrl === null
+                ? {}
+                : { refundUrl: opener.refundUrl }),
+              opener: opener.opener,
+              ...(upfrontAmount === null || upfrontAmount === 0n
+                ? {}
+                : { nonRefundableUsdc: upfrontAmount }),
+            });
+            await release();
+          } else if (!result.paid) {
+            // No 402 was answered, so nothing was approved or signed.
+            await release();
+          }
+          if (!result.paid) {
+            // Not a payment: do not relay a body this server fetched on the
+            // model's behalf (it would make the tool a general-purpose
+            // fetcher of whatever the URL serves).
+            return ctx.fail(
+              `the endpoint answered HTTP ${result.response.status} without asking for an x402 payment; nothing was signed or paid, and its body is not returned.`,
+            );
+          }
+          const body = await result.response.text();
+          const truncated = body.length > MAX_BODY_CHARS;
+          const structured = {
+            paid: result.paid,
+            httpStatus: result.response.status,
+            contentType: result.response.headers.get("content-type"),
+            body: truncated ? body.slice(0, MAX_BODY_CHARS) : body,
+            bodyTruncated: truncated,
+            streamId: opener?.streamId ?? null,
+            opener: opener?.opener ?? null,
+            refundUrl: opener?.refundUrl ?? null,
+            depositUsdc: opener?.deposit?.toString() ?? null,
+            ratePerSecondUsdc: opener?.ratePerSecond?.toString() ?? null,
+            expiresAt: opener?.expiresAt ?? null,
+            minEarnSeconds: result.quote?.minEarnSeconds?.toString() ?? null,
+            openerKind: result.quote?.openerKind ?? null,
+            priceUsdc: result.quote?.amount.toString() ?? null,
+            nonRefundableUsdc: upfrontAmount?.toString() ?? null,
+            refundableUsdc: result.quote?.refundableAmount?.toString() ?? null,
+            upfrontFeeUsdc: opener?.upfrontFee?.toString() ?? null,
+            upfrontOnly: opener?.upfrontOnly ?? false,
+            refundIsAutomatic: false,
+          };
+          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,
+            );
+          }
+          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.`
+              : "";
+          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.`,
+            structured,
+          );
+        });
+      } catch (error) {
+        if (error instanceof OutboundRequestRefusedError) {
+          return ctx.fail(error.message);
+        }
+        return ctx.unexpected(error);
+      }
+    },
+  );
+
+  const bind = async (args: {
+    streamId: string;
+    refundUrl?: string | undefined;
+  }): Promise<
+    | RefundClient
+    | { readonly error: string }
+    | { readonly nothingToRefund: string }
+  > => {
+    const streamId = args.streamId.toLowerCase() as `0x${string}`;
+    // Stream id 0 is an upfront-only payment: nothing was escrowed. Never
+    // contact a relay or sign anything for it.
+    if (streamId === ZERO_STREAM_ID) {
+      return { nothingToRefund: streamId };
+    }
+    const record = await ctx.findStream(streamId);
+    if (record?.x402Charge === "upfront-only") {
+      return { nothingToRefund: streamId };
+    }
+    const refundUrl = args.refundUrl ?? record?.refundUrl;
+    if (refundUrl === undefined) {
+      return {
+        error: `no refund relay is known for stream ${streamId}: pass refundUrl (x402_pay returned it).`,
+      };
+    }
+    try {
+      await assertOutboundUrlAllowed(
+        refundUrl.replace("{streamId}", streamId),
+        guard,
+      );
+    } catch (error) {
+      if (error instanceof OutboundRequestRefusedError) {
+        return { error: error.message };
+      }
+      throw error;
+    }
+    return await openRefunds({
+      refundUrl,
+      streamId,
+      ...(record?.opener === undefined ? {} : { opener: record.opener }),
+      fetch: guardedFetch,
+    });
+  };
+
+  mcpServer.registerTool(
+    "refund_status",
+    {
+      description: REFUND_STATUS_TOOL_DESCRIPTION,
+      inputSchema: refundSchema,
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true,
+        title: "x402 Refund Status",
+      },
+    },
+    async (args) => {
+      try {
+        const refunds = await bind(args);
+        if ("error" in refunds) return ctx.fail(refunds.error);
+        if ("nothingToRefund" in refunds) return nothingToRefund(ctx, args);
+        const status = await refunds.status();
+        return ctx.ok(describeStatus(status), serializeStatus(status));
+      } catch (error) {
+        if (error instanceof Error && error.name === "NothingToRefundError") {
+          return nothingToRefund(ctx, args);
+        }
+        return explainRefundError(ctx, error);
+      }
+    },
+  );
+
+  mcpServer.registerTool(
+    "refund",
+    {
+      description: REFUND_TOOL_DESCRIPTION,
+      inputSchema: refundActionSchema,
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+        readOnlyHint: false,
+        title: "x402 Refund",
+      },
+    },
+    async (args) => {
+      try {
+        const refunds = await bind(args);
+        if ("error" in refunds) return ctx.fail(refunds.error);
+        if ("nothingToRefund" in refunds) return nothingToRefund(ctx, args);
+        let closeResult: RefundRelayResult | null = null;
+        if (args.close === true) {
+          // Buyer recovery, authorized on the mandate owner's signature alone
+          // (never on caps or expiry, so a lapsed mandate cannot strand the
+          // payer's own money) — the same rule as reclaim_unspent.
+          const signedMandate = await ctx.resolveMandate();
+          const decision = await verifyMandateOwnerSignature(signedMandate);
+          if (!decision.allowed) {
+            return ctx.fail(`mandate denied: ${decision.reason ?? "unknown"}`);
+          }
+          closeResult = await refunds.close({ signer: ctx.x402.signer });
+        }
+        let reclaimResult: RefundRelayResult | null = null;
+        if (args.reclaim !== false) {
+          reclaimResult = await refunds.reclaim();
+        }
+        const status = await refunds.status();
+        return ctx.ok(
+          `${closeResult === null ? "" : `closed (${closeResult.transaction}). `}${reclaimResult === null ? "" : `reclaimed ${reclaimResult.amount?.toString() ?? "?"} USDC base units to the payer (${reclaimResult.transaction}). `}${describeStatus(status)}`,
+          {
+            ...serializeStatus(status),
+            close:
+              closeResult === null
+                ? null
+                : {
+                    transaction: closeResult.transaction,
+                    verified: closeResult.verified,
+                  },
+            reclaim:
+              reclaimResult === null
+                ? null
+                : {
+                    transaction: reclaimResult.transaction,
+                    amountUsdc: reclaimResult.amount?.toString() ?? null,
+                    verified: reclaimResult.verified,
+                  },
+          },
+        );
+      } catch (error) {
+        if (error instanceof Error && error.name === "NothingToRefundError") {
+          return nothingToRefund(ctx, args);
+        }
+        return explainRefundError(ctx, error);
+      }
+    },
+  );
+}
+
+/** Upfront-only payments: a finished, successful answer — not an error. */
+function nothingToRefund(ctx: McpX402Context, args: { streamId: string }) {
+  return ctx.ok(
+    "nothing to refund: this was an upfront-only payment — the whole price was a non-refundable per-call charge paid to the seller at settlement, no stream was opened and nothing was escrowed. Nothing was requested, signed or sent.",
+    {
+      streamId: args.streamId.toLowerCase(),
+      nothingToRefund: true,
+      upfrontOnly: true,
+      refundIsAutomatic: false,
+    },
+  );
+}
+
+/** Registry key of a settled upfront-only charge (not an escrow stream id). */
+function chargeKey(
+  owner: `0x${string}`,
+  opener: `0x${string}`,
+  result: PayX402WithMandateResult,
+): `0x${string}` {
+  return keccak256(
+    toHex(
+      `x402-upfront-charge:${owner}:${opener}:${result.authorization?.nonce ?? crypto.randomUUID()}`,
+    ),
+  );
+}
+
+/** Read-only chain access for the SDK refund client's opener-kind check. */
+function refundReader(options: McpX402Options): PublicClient {
+  return (
+    options.sdkOptions?.publicClient ??
+    (createPublicClient({
+      chain: options.network.chain,
+      transport:
+        options.sdkOptions?.transport ?? http(options.network.rpcUrls[0]),
+    }) as PublicClient)
+  );
+}
+
+function serializeStatus(status: RefundStatus): Record<string, unknown> {
+  return {
+    streamId: status.streamId,
+    opener: status.opener,
+    payer: status.payer,
+    status: status.status,
+    reclaimed: status.reclaimed,
+    reclaimableUsdc: status.reclaimable?.toString() ?? null,
+    next: status.next,
+    refundIsAutomatic: false,
+  };
+}
+
+function describeStatus(status: RefundStatus): string {
+  if (status.reclaimed) {
+    return `stream ${status.streamId} is reclaimed: the unearned remainder went back to ${status.payer}.`;
+  }
+  return `stream ${status.streamId} is ${status.status}; next step: ${status.next.action}${status.next.retryAt === undefined ? "" : ` (from ${status.next.retryAt})`}. Nothing is refunded automatically.`;
+}
+
+/**
+ * A failed x402_pay. Before the signature was handed out (mandate or SDK
+ * refusal) the reservation is released. After it, the reservation is KEPT
+ * unless the authorization provably can never move funds, the real stream is
+ * recorded when it can be identified on-chain, and the model is never told
+ * "not settled" when the money may have moved.
+ */
+async function settleFailure(
+  ctx: McpX402Context,
+  error: unknown,
+  state: {
+    readonly release: () => Promise<void>;
+    readonly reservation: `0x${string}` | null;
+    readonly owner: `0x${string}`;
+    readonly mandateId: `0x${string}`;
+    readonly nowSeconds: number;
+  },
+) {
+  if (error instanceof Error && error.name === "X402PostSignatureError") {
+    const post = error as X402PostSignatureError;
+    if (post.releasable) {
+      await state.release();
+    } else if (post.upfrontOnly && post.state === "used") {
+      // Settled as an upfront-only charge: no stream to record, but the spend
+      // is real and stays counted — as a non-stream charge.
+      await ctx.recordStream({
+        streamId: keccak256(
+          toHex(
+            `x402-upfront-charge:${state.owner}:${post.opener}:${post.authorization?.nonce ?? crypto.randomUUID()}`,
+          ),
+        ),
+        buyer: state.owner,
+        operator: post.approved.operator,
+        serviceRef: post.quote.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+        budgetUsdc: post.approved.budgetUsdc,
+        ratePerSecondUsdc: post.approved.ratePerSecondUsdc,
+        maxDurationSeconds: post.approved.maxDurationSeconds,
+        openedAtSeconds: state.nowSeconds,
+        mandateId: state.mandateId,
+        opener: post.opener,
+        x402Charge: "upfront-only",
+        nonRefundableUsdc: post.approved.budgetUsdc,
+      });
+      await state.release();
+    } else if (post.streamId !== null) {
+      await ctx.recordStream({
+        streamId: post.streamId,
+        buyer: state.owner,
+        operator: post.approved.operator,
+        serviceRef: post.quote.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+        budgetUsdc: post.approved.budgetUsdc,
+        ratePerSecondUsdc: post.approved.ratePerSecondUsdc,
+        maxDurationSeconds: post.approved.maxDurationSeconds,
+        openedAtSeconds: state.nowSeconds,
+        mandateId: state.mandateId,
+        opener: post.opener,
+        ...(post.quote.upfrontAmount === null || post.quote.upfrontAmount === 0n
+          ? {}
+          : { nonRefundableUsdc: post.quote.upfrontAmount }),
+      });
+      await state.release();
+    }
+    return ctx.fail(
+      `${post.message} ${post.releasable ? "The spend reservation was released." : `The ${post.approved.budgetUsdc.toString()} USDC base units stay COUNTED against the spend mandate.`}${post.streamId === null ? "" : ` streamId: ${post.streamId} (opener ${post.opener}); recover the unearned part with refund / refund_status.`} Do not retry this payment blindly.`,
+    );
+  }
+  // Anything else was raised before a signature existed: nothing moved.
+  await state.release();
+  if (error instanceof OutboundRequestRefusedError)
+    return ctx.fail(error.message);
+  return explainPayError(ctx, error);
+}
+
+function explainPayError(ctx: McpX402Context, error: unknown) {
+  if (error instanceof Error) {
+    switch (error.name) {
+      case "X402MandateDeniedError":
+        return ctx.fail(
+          `${error.message} Raise the server's METRIK_AGENT_MANDATE_* caps only if that payment is intended.`,
+        );
+      case "X402PaymentRefusedError":
+        return ctx.fail(error.message);
+    }
+  }
+  return ctx.unexpected(error);
+}
+
+function explainRefundError(ctx: McpX402Context, error: unknown) {
+  if (error instanceof Error) {
+    switch (error.name) {
+      case "RefundNotReadyError": {
+        const retryAt = (error as { retryAt?: number | null }).retryAt;
+        return ctx.fail(
+          `${error.message}${retryAt === null || retryAt === undefined ? "" : ` Retry at ${retryAt} (unix seconds).`} Nothing is refunded automatically.`,
+        );
+      }
+      case "OutboundRequestRefusedError":
+      case "RefundRelayError":
+      case "NotStreamPayerError":
+      case "InvalidInputError":
+        return ctx.fail(error.message);
+    }
+  }
+  return ctx.unexpected(error);
+}