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

package/dist/mcp/x402-tools.d.ts

@@ -0,0 +1,109 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import type { RefundClient, X402PayerSigner } from "@absol-labs/sdk/x402";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SignedSpendMandate } from "../mandates/mandate.js";
+import { type LookupFn } from "../x402-buyer/guarded-fetch.js";
+import type { PayX402WithMandateInput, PayX402WithMandateResult } 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 declare 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 declare 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 declare 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;
+    };
+}
+export declare function registerX402Tools(mcpServer: McpServer, ctx: McpX402Context): void;
+//# sourceMappingURL=x402-tools.d.ts.map

package/dist/mcp/x402-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/x402-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp/x402-tools.js

@@ -0,0 +1,554 @@
+import { z } from "zod";
+import { verifyMandateOwnerSignature, } from "../mandates/mandate.js";
+import { createPublicClient, http, keccak256, toHex, } from "viem";
+import { assertOutboundUrlAllowed, createGuardedFetch, OutboundRequestRefusedError, } from "../x402-buyer/guarded-fetch.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.";
+/** 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."),
+};
+const ZERO_STREAM_ID = `0x${"00".repeat(32)}`;
+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)."),
+};
+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."),
+};
+const PAYMENT_HEADERS = new Set(["payment-signature", "x-payment"]);
+export function registerX402Tools(mcpServer, ctx) {
+    const pay = ctx.x402.pay ??
+        (async (input) => {
+            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) => {
+            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 = {};
+        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;
+            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 = null;
+                const release = async () => {
+                    if (reservation !== null)
+                        await ctx.removeStream?.(reservation);
+                };
+                let result;
+                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)}`,
+                                budgetUsdc: request.budgetUsdc,
+                                ratePerSecondUsdc: request.ratePerSecondUsdc,
+                                maxDurationSeconds: request.maxDurationSeconds,
+                                openedAtSeconds: nowSeconds,
+                                mandateId: signedMandate.mandateId,
+                                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,
+                        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)}`,
+                        budgetUsdc: result.approved.budgetUsdc,
+                        ratePerSecondUsdc: result.approved.ratePerSecondUsdc,
+                        maxDurationSeconds: result.approved.maxDurationSeconds,
+                        openedAtSeconds: nowSeconds,
+                        mandateId: signedMandate.mandateId,
+                        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)}`,
+                        budgetUsdc: result.approved.budgetUsdc,
+                        ratePerSecondUsdc: result.approved.ratePerSecondUsdc,
+                        maxDurationSeconds: result.approved.maxDurationSeconds,
+                        openedAtSeconds: nowSeconds,
+                        mandateId: signedMandate.mandateId,
+                        ...(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) => {
+        const streamId = args.streamId.toLowerCase();
+        // 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 = 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 = 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, args) {
+    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, opener, result) {
+    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) {
+    return (options.sdkOptions?.publicClient ??
+        createPublicClient({
+            chain: options.network.chain,
+            transport: options.sdkOptions?.transport ?? http(options.network.rpcUrls[0]),
+        }));
+}
+function serializeStatus(status) {
+    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) {
+    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, error, state) {
+    if (error instanceof Error && error.name === "X402PostSignatureError") {
+        const post = error;
+        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)}`,
+                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)}`,
+                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, error) {
+    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, error) {
+    if (error instanceof Error) {
+        switch (error.name) {
+            case "RefundNotReadyError": {
+                const retryAt = error.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);
+}
+//# sourceMappingURL=x402-tools.js.map