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

package/dist/mcp/server.js

@@ -3,14 +3,19 @@ import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { http, isAddress, isHex } from "viem";
-import { baseSepolia } from "viem/chains";
 import { z } from "zod";
 import { discoverServices as defaultDiscoverServices, } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate } from "../mandates/mandate.js";
 import { parseServerMandateCapsEnv, signServerMandate, ServerMandateConfigError, } from "../mandates/env.js";
 import { isCheckpointStream, } from "../sdk/client.js";
 import { createWalletBackedAgentClient, parseAgentWalletEnv, } from "../wallet/provider.js";
 import { createReclaimConsumerProofServiceFromEnv, } from "../zktls/reclaim.js";
+import { CAPABILITY_HEADER_NAME, httpMethodSchema, } from "../capability/invocation-capability.js";
+import { createSdkInvokeStreamReader, InvokeAccessUrlError, InvokeBuyerMismatchError, InvokePathError, InvokeServiceRefMismatchError, InvokeStreamExpiredError, InvokeStreamNotActiveError, } from "../sdk/invoke.js";
+import { createServiceInvoker, RegistryUnavailableError, ServiceListingNotFoundError, } from "./service-invoker.js";
+import { defaultNetwork, readOnlyMetrikClient, registeredDeployment, resolveAgentNetwork, } from "../network.js";
+import { REFUND_STATUS_TOOL_DESCRIPTION, REFUND_TOOL_DESCRIPTION, X402_PAY_TOOL_DESCRIPTION, registerX402Tools, } from "./x402-tools.js";
 /**
  * MCP server for the agent lane.
  *
@@ -42,6 +47,41 @@ const hireVerifiedServiceSchema = {
         .optional()
         .describe("Optional max stream lifetime in seconds. Defaults to the server mandate's max duration."),
 };
+/**
+ * Ceiling on a capability's lifetime.
+ *
+ * A signed capability is a bearer credential for one method+path on one stream:
+ * anything holding it can make that call until it expires. The signer's own
+ * default is 60s; this bounds what an LLM may ask for so a single tool argument
+ * cannot mint a long-lived credential. It is a cap, not the default.
+ */
+const MAX_CAPABILITY_TTL_SECONDS = 300;
+const invokeServiceSchema = {
+    streamId: bytes32Schema.describe("Stream id of an ACTIVE stream whose buyer is this server's wallet (from hire_verified_service or list_streams)."),
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Origin-relative request path, query string included, e.g. "/price?symbol=BTC". Defaults to "/". The ORIGIN is not a parameter: it is read from the operator-signed listing for this stream\'s serviceRef.'),
+    method: httpMethodSchema
+        .optional()
+        .describe('HTTP method. Defaults to "GET". The capability authorizes exactly this method and this path — nothing else.'),
+    headers: z
+        .record(z.string())
+        .optional()
+        .describe("Extra request headers. The capability header is attached by the server and cannot be supplied here."),
+    body: z
+        .string()
+        .optional()
+        .describe("Request body, sent verbatim. Defaults to a JSON content-type when a body is present and none is given."),
+    ttlSeconds: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_CAPABILITY_TTL_SECONDS)
+        .optional()
+        .describe(`Capability lifetime in seconds (default 60, max ${MAX_CAPABILITY_TTL_SECONDS}). Shorter is safer; it only has to outlive one request.`),
+};
 const getStreamStatusSchema = {
     streamId: bytes32Schema.describe("Stream id returned by hire_verified_service."),
 };
@@ -89,38 +129,96 @@ const metrikAgentEnvSchema = z.object({
     METRIK_AGENT_CHAIN_ID: z.string().optional(),
     METRIK_AGENT_CHAIN_NAME: z.string().optional(),
     METRIK_AGENT_MCP_STATE_FILE: z.string().optional(),
+    METRIK_AGENT_ESCROW_GENERATION: z.string().optional(),
+    METRIK_AGENT_REGISTRY_URL: z.string().url().optional(),
+    METRIK_AGENT_REGISTRY_APIKEY: z.string().optional(),
+    METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR: z.string().optional(),
+    METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW: z.string().optional(),
+    METRIK_NETWORK: z.string().optional(),
+    METRIK_AGENT_X402: z.string().optional(),
+    METRIK_AGENT_X402_ALLOWED_HOSTS: z.string().optional(),
 });
+/**
+ * Opt in to an escrow that is NOT the network's registered `StreamEscrowV2`.
+ *
+ * Off by default, because a wrong escrow does not fail at read time: the
+ * retired V1 escrow's `getStream` returns a tuple that diverges from V2's from
+ * index 5 onward, so a V2 decoder pointed at it does not revert — it decodes
+ * other fields into correctly-named ones and reports a confident wrong answer
+ * about someone's money. This repository's own shipped docs pointed
+ * `METRIK_AGENT_ESCROW` at V1 as recently as 0.10.0. Requiring the escrow to be
+ * the one the SDK network registry records for the chain refuses V1 (and any
+ * other stray address) without naming it in code. Operator-set input only.
+ */
+export const ALLOW_UNREGISTERED_ESCROW_ENV = "METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW";
+/**
+ * Opt out of the operator/serviceRef cross-check on hire. Operator-set input
+ * only — an MCP caller can neither read nor set it.
+ */
+export const ALLOW_UNVERIFIED_OPERATOR_ENV = "METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR";
+/** An unset escrow slot decodes as an all-zero struct rather than reverting. */
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * The one sentence every stream-opening surface has to carry.
+ *
+ * A reviewer made ONE call against a stream and was billed for 302 seconds. The
+ * escrow behaved exactly as designed — and nothing in the tool surface had told
+ * them what they were buying. An LLM picks a tool from its description alone, so
+ * the meter is stated in the description of every tool that opens, reads, or
+ * ends a stream, not only in the docs it will never read.
+ */
+export const METERING_MODEL = "METERING: this is TIME-metered rental of an endpoint that keeps proving it is live, NOT per-call billing. Cost = ratePerSecondUsdc x seconds the oracle VERIFIED, capped at the escrowed budget. One call and a thousand calls cost the same second, and the clock runs while you call nothing. Only closing the stream (reclaim_unspent) stops it; nothing refunds automatically.";
 export const METRIK_MCP_TOOLS = [
     {
         name: "discover_services",
-        description: "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is cryptographically verified, so an agent can go from discovery to hire without pre-known addresses.",
+        description: "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is cryptographically verified, so an agent can go from discovery to hire without pre-known addresses. Listings are priced per second, not per call.",
         movesFunds: false,
     },
     {
         name: "hire_verified_service",
-        description: "Open a verified payment stream for a third-party service. Pays only for oracle-verified delivered time. Subject to the agent's spend mandate.",
+        description: `Open a verified payment stream for a third-party service, then call it with invoke_service. Pays only for oracle-verified delivered time. Subject to the agent's spend mandate. ${METERING_MODEL}`,
         movesFunds: true,
     },
+    {
+        name: "invoke_service",
+        description: "Call the service a stream is already paying for. Signs a single-use EIP-712 capability as the stream's buyer and calls the origin the operator cryptographically signed (resolved from the verified listing — never a caller-supplied URL). This is how an agent USES what it hired. It moves no funds and adds no cost: billing is by verified elapsed time, so invoking more often is free and invoking never still costs.",
+        movesFunds: false,
+    },
     {
         name: "check_stream_status",
-        description: "Read a stream's live status, accrued amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
+        description: `Read a stream's live status, settled amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry. ${METERING_MODEL}`,
         movesFunds: false,
     },
     {
         name: "reclaim_unspent",
-        description: "Close a stream and reclaim unspent funds to the buyer. V2 reclaim follows checkpoint finalization or escape-window rules.",
+        description: "Close a stream and reclaim unspent funds to the buyer. Closing is what STOPS the per-second meter — nothing else does, and no refund is ever pushed back on its own. V2 reclaim follows checkpoint finalization or escape-window rules.",
         movesFunds: true,
     },
     {
         name: "list_streams",
-        description: "List the agent's streams and their current state.",
+        description: "List the streams this server opened and their current state. Every active stream is still accruing cost per verified second whether or not it is being invoked.",
         movesFunds: false,
     },
     {
         name: "prove_https_response",
-        description: "Generate a zkTLS proof of the exact HTTPS response consumed for a tracked stream. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence.",
+        description: "Generate a buyer-side zkTLS proof of an HTTPS response from a stream's verified service origin. PUBLIC listings only: the proof is fetched by a third-party Reclaim attestor, which cannot present this stream's caller-auth capability, so a GATED listing answers the attestor with a 403 and the tool fails closed rather than proving a rejection. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence; it is not a substitute for it.",
+        movesFunds: false,
+    },
+    {
+        name: "x402_pay",
+        description: X402_PAY_TOOL_DESCRIPTION,
+        movesFunds: true,
+    },
+    {
+        name: "refund_status",
+        description: REFUND_STATUS_TOOL_DESCRIPTION,
         movesFunds: false,
     },
+    {
+        name: "refund",
+        description: REFUND_TOOL_DESCRIPTION,
+        movesFunds: true,
+    },
 ];
 /** @deprecated Renamed to METRIK_MCP_TOOLS; retained for back-compat. */
 export const STREAMPROOF_MCP_TOOLS = METRIK_MCP_TOOLS;
@@ -135,6 +233,9 @@ export class InMemoryStreamRegistry {
     async list() {
         return Array.from(this.records.values());
     }
+    async delete(streamId) {
+        this.records.delete(streamId);
+    }
 }
 export class FileStreamRegistry {
     filePath;
@@ -153,6 +254,11 @@ export class FileStreamRegistry {
     async list() {
         return Array.from((await this.readAll()).values());
     }
+    async delete(streamId) {
+        const records = await this.readAll();
+        if (records.delete(streamId))
+            await this.writeAll(records);
+    }
     async readAll() {
         const contents = await fs.readFile(this.filePath, "utf8").catch((error) => {
             if (error.code === "ENOENT") {
@@ -171,6 +277,9 @@ export class FileStreamRegistry {
             maxDurationSeconds: z.number().int().positive(),
             openedAtSeconds: z.number().int().nonnegative(),
             mandateId: bytes32Schema,
+            refundUrl: z.string().url().optional(),
+            opener: addressSchema.optional(),
+            x402Reservation: z.boolean().optional(),
         }))
             .parse(JSON.parse(contents));
         return new Map(parsed.map((record) => [
@@ -185,6 +294,13 @@ export class FileStreamRegistry {
                 maxDurationSeconds: record.maxDurationSeconds,
                 openedAtSeconds: record.openedAtSeconds,
                 mandateId: record.mandateId,
+                ...(record.refundUrl === undefined
+                    ? {}
+                    : { refundUrl: record.refundUrl }),
+                ...(record.opener === undefined
+                    ? {}
+                    : { opener: record.opener }),
+                ...(record.x402Reservation === true ? { x402Reservation: true } : {}),
             },
         ]));
     }
@@ -212,12 +328,26 @@ function warnOnce(key, message) {
     // stderr, never stdout: stdout is the MCP stdio transport channel.
     console.error(message);
 }
-const DISCOVER_TOOL_SPEC = METRIK_MCP_TOOLS[0];
-const HIRE_TOOL_SPEC = METRIK_MCP_TOOLS[1];
-const STATUS_TOOL_SPEC = METRIK_MCP_TOOLS[2];
-const RECLAIM_TOOL_SPEC = METRIK_MCP_TOOLS[3];
-const LIST_TOOL_SPEC = METRIK_MCP_TOOLS[4];
-const PROVE_TOOL_SPEC = METRIK_MCP_TOOLS[5];
+/**
+ * Looks a tool spec up by NAME. This used to index into METRIK_MCP_TOOLS by
+ * position, which silently rebinds every description the moment a tool is
+ * inserted anywhere but the end — a tool whose advertised description belongs
+ * to a different tool is worse than a missing one, because an agent acts on it.
+ */
+function toolSpec(name) {
+    const spec = METRIK_MCP_TOOLS.find((entry) => entry.name === name);
+    if (spec === undefined) {
+        throw new Error(`unknown MCP tool spec: ${name}`);
+    }
+    return spec;
+}
+const DISCOVER_TOOL_SPEC = toolSpec("discover_services");
+const HIRE_TOOL_SPEC = toolSpec("hire_verified_service");
+const INVOKE_TOOL_SPEC = toolSpec("invoke_service");
+const STATUS_TOOL_SPEC = toolSpec("check_stream_status");
+const RECLAIM_TOOL_SPEC = toolSpec("reclaim_unspent");
+const LIST_TOOL_SPEC = toolSpec("list_streams");
+const PROVE_TOOL_SPEC = toolSpec("prove_https_response");
 const discoverServicesSchema = {
     category: z
         .string()
@@ -273,6 +403,10 @@ export function createVerifiedStreamMcpServer(options) {
     };
     const now = options.now ?? (() => Math.floor(Date.now() / 1000));
     const discover = options.discoverServices ?? defaultDiscoverServices;
+    const allowUnverifiedOperator = options.allowUnverifiedOperatorPairing ?? false;
+    if (allowUnverifiedOperator) {
+        warnOnce("mcp-unverified-operator", `[metrik] ${ALLOW_UNVERIFIED_OPERATOR_ENV} is set: hires whose operator/serviceRef pairing CANNOT be verified will proceed. The operator address is the wallet that gets paid; an unverifiable pairing can escrow to a wallet that does not own the service. A contradicted pairing is still refused.`);
+    }
     const mcpServer = new McpServer(options.serverInfo ?? {
         name: "metrik-agent-mcp",
         version: "0.1.0",
@@ -292,9 +426,14 @@ export function createVerifiedStreamMcpServer(options) {
                 ...(category === undefined ? {} : { category }),
                 ...(limit === undefined ? {} : { limit }),
             });
-            return successResult(`discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}`, { services: listings.map(serializeServiceListing) });
+            return successResult(`discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}, priced per verified second`, { services: listings.map(serializeServiceListing) });
         }
         catch (error) {
+            if (error instanceof RegistryUnavailableError) {
+                // Loud, not silent: discovery never degrades to stale local data, so
+                // "the registry is down" must not read as "there are no services".
+                return errorResult("the service registry is unreachable, so no listing could be verified. This is NOT the same as zero services — do not conclude the marketplace is empty. Retry shortly.");
+            }
             return safeToolError(error);
         }
     });
@@ -319,6 +458,49 @@ export function createVerifiedStreamMcpServer(options) {
                 ratePerSecondUsdc: BigInt(args.ratePerSecondUsdc),
                 maxDurationSeconds: args.durationSeconds ?? signedMandate.mandate.maxDurationSeconds,
             };
+            // Does this operator actually own this serviceRef?
+            //
+            // The two arrive as independent tool arguments, and `operator` is the
+            // wallet that gets paid. An LLM that pairs a real serviceRef with an
+            // attacker's payout address escrows the buyer's USDC to a stranger, and
+            // nothing downstream catches it: the escrow does not know who owns a
+            // serviceRef, and the oracle would happily verify the real endpoint
+            // while the money accrued elsewhere. Discovery DOES know — it recovers
+            // the operator's signature over the record the serviceRef is derived
+            // from — so the pairing is checked against it here.
+            //
+            // A serviceRef that is not listed at all is allowed with a warning
+            // (the registry is not the authority on what exists, and refusing would
+            // block private or freshly-listed services); a serviceRef that IS
+            // listed under a DIFFERENT operator is refused outright.
+            const pairing = await checkOperatorPairing(discover, args.serviceRef, request.operator);
+            if (pairing.verdict !== "verified") {
+                // FAIL CLOSED. Anything short of a positive match is a refusal: a
+                // registry outage is not evidence that the pairing is sound, and the
+                // money moves before any note attached to a success result could be
+                // read. The only override is an operator-set environment variable
+                // (never a tool argument), and even that never overrides a positive
+                // contradiction.
+                if (pairing.verdict === "mismatch" || !allowUnverifiedOperator) {
+                    return errorResult(explainPairingRefusal(pairing, args.serviceRef, request.operator));
+                }
+            }
+            // Is the rate inside the band the operator SIGNED? The escrow accepts
+            // any non-zero rate, but the seller's capability gateway answers every
+            // request on an out-of-band stream with 403
+            // `stream-rate-out-of-bounds`, so such a hire escrows the buyer's USDC
+            // into a stream that can never be served. Checked against the verified
+            // listing the pairing check just resolved — no second registry read,
+            // and no tool argument can widen the band. A descriptor that does not
+            // verify is a refusal, never "no band". Only an unverified pairing
+            // (which already needed the operator-set override above) has no listing
+            // to check, and its success result says so.
+            if (pairing.verdict === "verified") {
+                const band = await checkListedRateBand(async () => [pairing.listing], args.serviceRef, request.ratePerSecondUsdc, "ratePerSecondUsdc");
+                if (!band.ok) {
+                    return errorResult(`${band.message} Pick a ratePerSecondUsdc inside the band (discover_services reports it as ratePerSecondBand).`);
+                }
+            }
             // Serialize per owner: the spent-so-far read, cap check, open, and
             // registry write must be atomic, or concurrent hires could both pass
             // the cumulative-cap check on stale spend and overshoot maxTotalUsdc.
@@ -354,7 +536,15 @@ export function createVerifiedStreamMcpServer(options) {
                     openedAtSeconds: nowSeconds,
                     mandateId: signedMandate.mandateId,
                 });
-                return successResult(`opened verified stream ${result.streamId} on chain ${result.handle.chainId}`, {
+                // The meter starts HERE, not on the first invoke_service call. Say
+                // so in the result as well as the tool description: a reviewer who
+                // opened a stream, made one call and was billed for 302 seconds read
+                // the result, not the docs.
+                const maxSpendUsdc = request.budgetUsdc <
+                    request.ratePerSecondUsdc * BigInt(request.maxDurationSeconds)
+                    ? request.budgetUsdc
+                    : request.ratePerSecondUsdc * BigInt(request.maxDurationSeconds);
+                return successResult(`opened verified stream ${result.streamId} on chain ${result.handle.chainId}.${pairing.verdict === "verified" ? "" : ` WARNING: the operator/serviceRef pairing was NOT verified (${pairing.verdict}) and this server is configured to escrow anyway via ${ALLOW_UNVERIFIED_OPERATOR_ENV}. The operator is the wallet that gets paid and nothing proved it owns this service, and the operator-signed rate band could not be checked either: if this rate is outside it, the service's gateway refuses every request while the deposit stays escrowed.`} The meter is running from now at ${request.ratePerSecondUsdc} USDC base units per VERIFIED second, whether or not you call the service. Call it with invoke_service; stop the meter with reclaim_unspent.`, {
                     streamId: result.streamId,
                     txHash: result.txHash,
                     approveTxHash: result.approveTxHash,
@@ -363,6 +553,15 @@ export function createVerifiedStreamMcpServer(options) {
                         escrow: result.handle.escrow,
                         chainId: result.handle.chainId,
                     },
+                    operatorPairing: pairing.verdict,
+                    metering: {
+                        model: "time-metered",
+                        ratePerSecondUsdc: request.ratePerSecondUsdc.toString(),
+                        budgetUsdc: request.budgetUsdc.toString(),
+                        maxDurationSeconds: request.maxDurationSeconds,
+                        maxSpendUsdc: maxSpendUsdc.toString(),
+                        note: METERING_MODEL,
+                    },
                 });
             });
         }
@@ -370,6 +569,64 @@ export function createVerifiedStreamMcpServer(options) {
             return safeToolError(error);
         }
     });
+    if (options.serviceInvoker !== undefined) {
+        const serviceInvoker = options.serviceInvoker;
+        mcpServer.registerTool("invoke_service", {
+            description: INVOKE_TOOL_SPEC.description,
+            inputSchema: invokeServiceSchema,
+            annotations: {
+                // Not idempotent and not read-only: the call reaches a third party's
+                // endpoint, which may do anything. It is NOT destructive in Metrik's
+                // own terms — it signs no transaction and moves no USDC.
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+                readOnlyHint: false,
+                title: "Invoke Paid Service",
+            },
+        }, async ({ streamId, path, method, headers, body, ttlSeconds }) => {
+            const requestPath = path ?? "/";
+            // Defence in depth. `resolveInvocationUrl` is the authority — it
+            // resolves the path and proves the result did not leave the signed
+            // origin — but a tool argument that cannot possibly be a safe path is
+            // refused here, with a message the caller can act on, before anything
+            // reads the chain. A prefix check ALONE was the bug: the URL parser
+            // treats a backslash as a host separator for http(s), so a path
+            // beginning `/\\` resolved against a signed origin points somewhere
+            // else entirely while passing a `//` test.
+            if (!requestPath.startsWith("/") || requestPath.startsWith("//")) {
+                return errorResult(`path must be origin-relative and start with a single slash (got ${JSON.stringify(requestPath)}). The host is not yours to choose: it comes from the operator-signed listing.`);
+            }
+            if (hasForbiddenPathCharacter(requestPath)) {
+                return errorResult(`path must not contain a backslash or a control character (got ${JSON.stringify(requestPath)}). A backslash is a host separator to the URL parser, so it would redirect this call off the operator-signed origin.`);
+            }
+            const requestHeaders = normalizeHeaders(headers);
+            if (CAPABILITY_HEADER_NAME in requestHeaders) {
+                return errorResult(`do not set the ${CAPABILITY_HEADER_NAME} header: this server signs the capability itself, as the stream's buyer. Supplying one would be silently overwritten.`);
+            }
+            if (body !== undefined &&
+                requestHeaders["content-type"] === undefined) {
+                requestHeaders["content-type"] = "application/json";
+            }
+            try {
+                const result = await serviceInvoker.invokeService({
+                    streamId: streamId,
+                    method: method ?? "GET",
+                    path: requestPath,
+                    headers: requestHeaders,
+                    ...(body === undefined ? {} : { body }),
+                    ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+                });
+                return serializeInvocation(result);
+            }
+            catch (error) {
+                const explained = explainInvokeFailure(error, streamId);
+                return explained === null
+                    ? safeToolError(error)
+                    : errorResult(explained);
+            }
+        });
+    }
     mcpServer.registerTool("check_stream_status", {
         description: STATUS_TOOL_SPEC.description,
         inputSchema: getStreamStatusSchema,
@@ -382,7 +639,15 @@ export function createVerifiedStreamMcpServer(options) {
     }, async ({ streamId }) => {
         try {
             const status = await options.agentClient.getStreamStatus(streamId);
-            return successResult(`stream ${streamId} is ${status.stream.status}`, serializeStreamStatus(status, streamId));
+            if (status.stream.buyer === ZERO_ADDRESS) {
+                // An unset slot decodes as an all-zero struct rather than reverting,
+                // which otherwise surfaces as a confident "the stream is closed" for
+                // a stream that never existed. A real stream always has a buyer.
+                return errorResult(`no stream with id ${streamId} exists on the configured escrow. Check the id, and check that this server is pointed at the escrow the stream was opened on.`);
+            }
+            return successResult(status.stream.status === "active"
+                ? `stream ${streamId} is active and still metering at ${status.stream.ratePerSecond} USDC base units per verified second; reclaim_unspent closes it and stops the meter`
+                : `stream ${streamId} is ${status.stream.status}`, serializeStreamStatus(status, streamId));
         }
         catch (error) {
             return safeToolError(error);
@@ -400,10 +665,14 @@ export function createVerifiedStreamMcpServer(options) {
         },
     }, async ({ streamId, closeFirst }) => {
         try {
+            // The local registry is a CONVENIENCE, not an authority. It used to be
+            // required here, which meant a restarted server with in-memory state
+            // could no longer return the buyer's own money through this tool — a
+            // local bookkeeping gap standing between a buyer and their funds. The
+            // escrow itself enforces that only the buyer may close and reclaim, so
+            // proceeding without a record is safe and strictly buyer-favouring; an
+            // id that is not this wallet's stream simply reverts on chain.
             const record = await registry.get(streamId);
-            if (record === null) {
-                return errorResult(`unknown stream: ${streamId}`);
-            }
             const signedMandate = await resolveMandate();
             // Reclaim/close only RETURN unspent funds to the buyer or stop payment.
             // They are authorized on mandate-owner signature ALONE (see the SDK
@@ -416,9 +685,10 @@ export function createVerifiedStreamMcpServer(options) {
                 nowSeconds: now(),
                 ...(closeFirst === undefined ? {} : { closeFirst }),
             });
-            return successResult(`reclaimed stream ${streamId}`, {
+            return successResult(`reclaimed stream ${streamId}; the per-second meter on it has stopped${record === null ? " (this server had no local record of it — the escrow authorized the recovery on the buyer wallet alone)" : ""}`, {
                 closeTxHash: result.closeResult?.txHash ?? null,
                 reclaimTxHash: result.reclaimResult.txHash,
+                tracked: record !== null,
             });
         }
         catch (error) {
@@ -437,13 +707,20 @@ export function createVerifiedStreamMcpServer(options) {
         try {
             const records = await registry.list();
             const entries = await Promise.all(records.map(async (record) => {
-                const status = await options.agentClient
-                    .getStreamStatus(record.streamId)
-                    .then((value) => serializeStreamStatus(value, record.streamId))
-                    .catch((error) => ({
-                    streamId: record.streamId,
-                    statusError: asErrorMessage(error),
-                }));
+                // A reservation key is not an escrow stream: report it as what it
+                // is instead of reading a stream that does not exist.
+                const status = record.x402Reservation === true
+                    ? {
+                        streamId: record.streamId,
+                        x402Reservation: "an x402 payment was signed but its stream could not be confirmed; its amount stays counted against the spend mandate",
+                    }
+                    : await options.agentClient
+                        .getStreamStatus(record.streamId)
+                        .then((value) => serializeStreamStatus(value, record.streamId))
+                        .catch((error) => ({
+                        streamId: record.streamId,
+                        statusError: asErrorMessage(error),
+                    }));
                 return {
                     streamId: record.streamId,
                     buyer: record.buyer,
@@ -463,6 +740,33 @@ export function createVerifiedStreamMcpServer(options) {
             return safeToolError(error);
         }
     });
+    if (options.x402 !== undefined) {
+        registerX402Tools(mcpServer, {
+            x402: options.x402,
+            resolveMandate,
+            getSpentSoFarUsdc: (owner) => resolver.getSpentSoFarUsdc(owner),
+            getRevokedMandateIds: (owner) => resolver.getRevokedMandateIds(owner),
+            // The SAME per-owner chain as hire_verified_service: a hire and an x402
+            // payment from one owner can never both pass the cumulative cap on
+            // stale spend.
+            serialize: serializeHire,
+            recordStream: async (record) => {
+                await registry.put(record);
+            },
+            ...(registry.delete === undefined
+                ? {}
+                : {
+                    removeStream: async (streamId) => {
+                        await registry.delete?.(streamId);
+                    },
+                }),
+            findStream: async (streamId) => await registry.get(streamId),
+            now,
+            ok: successResult,
+            fail: errorResult,
+            unexpected: safeToolError,
+        });
+    }
     if (options.deliveryProofService !== undefined) {
         const deliveryProofService = options.deliveryProofService;
         mcpServer.registerTool("prove_https_response", {
@@ -480,6 +784,34 @@ export function createVerifiedStreamMcpServer(options) {
                 if (record === null) {
                     return errorResult(`unknown stream: ${streamId}`);
                 }
+                // Bind the PROOF TARGET to the stream's verified listing.
+                //
+                // Without this the tool would zkTLS-prove any URL an LLM named and
+                // stamp it with this stream's delivery binding (owner, streamId,
+                // operator, serviceRef) — a proof of someone else's endpoint,
+                // labelled as this stream's delivery. The origin has to come from the
+                // operator's signed record for the same reason invoke_service's does.
+                const listings = await discover().catch((error) => {
+                    throw new ProveTargetError(error instanceof RegistryUnavailableError
+                        ? "the service registry is unreachable, so this stream's signed service origin could not be verified. No proof was attempted."
+                        : `the service registry could not be read: ${asErrorMessage(error)}`);
+                });
+                const listing = listings.find((entry) => entry.serviceRef.toLowerCase() ===
+                    record.serviceRef.toLowerCase());
+                if (listing === undefined) {
+                    return errorResult(`no verified listing matches this stream's serviceRef (${record.serviceRef}), so there is no signed origin to prove against. Run discover_services.`);
+                }
+                if (listing.access === "gated") {
+                    // Not a degradation we can paper over. The Reclaim attestor fetches
+                    // the URL itself, from its own network position, and cannot present
+                    // this stream's single-use caller-auth capability — so the only
+                    // thing it could prove about a gated origin is its own 403.
+                    return errorResult(`this stream's service is GATED behind caller-auth (${safeOrigin(listing.accessUrl)}), and a consumer zkTLS proof cannot authenticate to it: the Reclaim attestor fetches the URL itself and cannot carry this stream's single-use capability, so it would only ever prove a 403. Use invoke_service to call it — that delivery is covered by the oracle's own L1/L4 verification. prove_https_response works for PUBLIC listings only.`);
+                }
+                const signedOrigin = safeOrigin(listing.accessUrl);
+                if (safeOrigin(url) !== signedOrigin) {
+                    return errorResult(`refusing to prove ${safeOrigin(url)} for this stream: its operator signed ${signedOrigin}. A proof of an origin the stream did not pay for is not evidence of its delivery.`);
+                }
                 const result = await deliveryProofService.proveConsumedHttpsResponse({
                     url,
                     ...(method === undefined ? {} : { method }),
@@ -501,6 +833,9 @@ export function createVerifiedStreamMcpServer(options) {
                 return successResult(`generated zkTLS response proof for stream ${streamId}`, serializeConsumedResponseProof(record.streamId, result));
             }
             catch (error) {
+                if (error instanceof ProveTargetError) {
+                    return errorResult(error.message);
+                }
                 return safeToolError(error);
             }
         });
@@ -534,24 +869,81 @@ export function parseMetrikAgentEnv(env = process.env) {
         // objects. `metrik-mcp` is started by an MCP host and fails closed on stdio,
         // so that array was the ONLY thing an operator ever saw — a correct failure
         // rendered as noise. Name the variables instead.
-        throw new Error(`metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP/Privy variables). METRIK_AGENT_CHAIN_ID defaults to Base Sepolia (${baseSepolia.id}).`);
+        throw new Error(`metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP variables — a Privy wallet is a CLI-only source and is not resolved here). METRIK_NETWORK (or METRIK_AGENT_CHAIN_ID) defaults to the registry's default network (${defaultNetwork().name}).`);
     }
     const parsed = result.data;
-    const chainId = Number(parsed.METRIK_AGENT_CHAIN_ID ?? baseSepolia.id);
-    if (!Number.isInteger(chainId) || chainId <= 0) {
-        throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
+    let chainId;
+    if (parsed.METRIK_AGENT_CHAIN_ID !== undefined) {
+        chainId = Number(parsed.METRIK_AGENT_CHAIN_ID);
+        if (!Number.isInteger(chainId) || chainId <= 0) {
+            throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
+        }
+    }
+    // "Is this a network the registry knows and the build allows": a registered
+    // TESTNET. This server signs with a key from the environment and moves funds.
+    let network;
+    try {
+        network = resolveAgentNetwork(parsed.METRIK_NETWORK !== undefined &&
+            parsed.METRIK_NETWORK.trim().length > 0
+            ? parsed.METRIK_NETWORK
+            : chainId, { testnetOnly: true });
+    }
+    catch (error) {
+        throw new Error(`unsupported METRIK_NETWORK / METRIK_AGENT_CHAIN_ID: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (chainId !== undefined && chainId !== network.chain.id) {
+        throw new Error(`METRIK_AGENT_CHAIN_ID ${chainId} does not match METRIK_NETWORK ${network.id} (chain ${network.chain.id})`);
+    }
+    // Generation: a registered deployment's comes from the registry (a
+    // contradicting env value is refused); an unregistered escrow needs it
+    // DECLARED. Only the checkpoint-settled generations (v2, v3) are served.
+    const declared = parsed.METRIK_AGENT_ESCROW_GENERATION?.trim().toLowerCase();
+    if (declared !== undefined && declared !== "v2" && declared !== "v3") {
+        throw new Error(`unsupported METRIK_AGENT_ESCROW_GENERATION "${parsed.METRIK_AGENT_ESCROW_GENERATION}": this server reads the checkpoint-settled StreamEscrowV2/V3 only. Leave it unset for a registered escrow.`);
     }
-    if (chainId !== baseSepolia.id) {
-        throw new Error(`unsupported METRIK_AGENT_CHAIN_ID ${chainId}; phase 2 is Base Sepolia only`);
+    const deployment = registeredDeployment(network, parsed.METRIK_AGENT_ESCROW);
+    let generation;
+    if (deployment !== undefined) {
+        generation = deployment.escrow.generation;
+        if (declared !== undefined && declared !== generation) {
+            throw new Error(`METRIK_AGENT_ESCROW_GENERATION "${declared}" contradicts the registry: ${parsed.METRIK_AGENT_ESCROW} is ${network.name}'s ${generation} escrow`);
+        }
+    }
+    else {
+        if (parsed.METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW !== "true") {
+            throw new Error(`METRIK_AGENT_ESCROW (${parsed.METRIK_AGENT_ESCROW}) is not a registered escrow of ${network.name} (current ${network.escrow.address}${network.legacy.length === 0 ? "" : `; legacy ${network.legacy.map((d) => d.escrow.address).join(", ")}`}). A wrong escrow does not fail at read time — the retired V1 escrow's stream tuple decodes into confident nonsense with the checkpoint decoder this server uses. Point it at a registered escrow, or set ${ALLOW_UNREGISTERED_ESCROW_ENV}=true and METRIK_AGENT_ESCROW_GENERATION for a deliberate private deployment.`);
+        }
+        if (declared === undefined) {
+            throw new Error(`${ALLOW_UNREGISTERED_ESCROW_ENV}=true also needs METRIK_AGENT_ESCROW_GENERATION ("v2" | "v3"): an unregistered escrow's generation cannot be read from the registry`);
+        }
+        generation = declared;
     }
     return {
         rpcUrl: parsed.METRIK_AGENT_RPC_URL,
         escrow: parsed.METRIK_AGENT_ESCROW,
+        escrowGeneration: generation,
+        unregisteredEscrow: deployment === undefined,
+        // Opt-IN only: any value but the exact string "true" leaves the check on.
+        allowUnverifiedOperatorPairing: parsed.METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR === "true",
+        ...(parsed.METRIK_AGENT_REGISTRY_URL === undefined
+            ? {}
+            : { registryUrl: parsed.METRIK_AGENT_REGISTRY_URL }),
+        ...(parsed.METRIK_AGENT_REGISTRY_APIKEY === undefined
+            ? {}
+            : { registryApiKey: parsed.METRIK_AGENT_REGISTRY_APIKEY }),
         usdc: parsed.METRIK_AGENT_USDC,
         chain: {
-            ...baseSepolia,
-            name: parsed.METRIK_AGENT_CHAIN_NAME ?? baseSepolia.name,
+            ...network.chain,
+            name: parsed.METRIK_AGENT_CHAIN_NAME ?? network.chain.name,
         },
+        network,
+        // Opt-IN: a fund-moving tool family whose URL the MODEL picks is never
+        // switched on by default or by an unrecognised value.
+        x402Enabled: ["1", "true", "yes", "on"].includes((parsed.METRIK_AGENT_X402 ?? "").trim().toLowerCase()),
+        x402AllowedHosts: (parsed.METRIK_AGENT_X402_ALLOWED_HOSTS ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0),
         ...(parsed.METRIK_AGENT_MCP_STATE_FILE === undefined
             ? {}
             : {
@@ -585,11 +977,21 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         chain: parsed.chain,
         transport: http(parsed.rpcUrl),
         escrow: parsed.escrow,
-        // Declare the escrow as V2 as well. Without this the SDK treats the
-        // client as V1 and routes claimable()/reclaimable() to the legacy ABI,
-        // which reverts against StreamEscrowV2 — the checkpoint escrow replaced
-        // those one-argument views with proof-carrying ones.
+        // Select the checkpoint decoder, on the strength of the DECLARED
+        // generation (`parsed.escrowGeneration`, validated in parseMetrikAgentEnv
+        // — which also refuses the retired V1 address outright). Without this the
+        // SDK treats the client as V1 and routes claimable()/reclaimable() to the
+        // legacy ABI, which reverts against StreamEscrowV2: the checkpoint escrow
+        // replaced those one-argument views with proof-carrying ones.
         escrowV2: parsed.escrow,
+        // An unregistered escrow was opted into by the operator: the SDK skips
+        // its code-hash pin only with both flags (see parseMetrikAgentEnv).
+        ...(parsed.unregisteredEscrow
+            ? {
+                allowUnregisteredEscrow: true,
+                escrowGeneration: parsed.escrowGeneration,
+            }
+            : {}),
         usdc: parsed.usdc,
         settlementTarget: {
             chainId: parsed.chain.id,
@@ -613,6 +1015,33 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         }
         return cachedMandate;
     };
+    // The "use" half. `invoke()` needs a signer that can produce an EIP-712
+    // signature; every wallet this package resolves can, but only a raw key is a
+    // viem LocalAccount by type — hence the structural check rather than a cast.
+    const serviceInvoker = createServiceInvoker({
+        streamReader: createSdkInvokeStreamReader({
+            escrowAddress: parsed.escrow,
+            rpcUrl: parsed.rpcUrl,
+            chainId: parsed.chain.id,
+            ...(parsed.unregisteredEscrow
+                ? { unregisteredEscrowGeneration: parsed.escrowGeneration }
+                : {}),
+        }),
+        buyer: requireCapabilitySigner(wallet.account),
+        domain: { chainId, verifyingContract: parsed.escrow },
+        discoverServices: defaultDiscoverServices,
+        discoverOptions: {
+            ...(parsed.registryUrl === undefined
+                ? {}
+                : { registryUrl: parsed.registryUrl }),
+            ...(parsed.registryApiKey === undefined
+                ? {}
+                : { apiKey: parsed.registryApiKey }),
+            // stderr, never stdout: stdout is the MCP stdio transport channel, and
+            // discovery warns about every listing it DROPS for a bad signature.
+            logger: { warn: (...parts) => console.error(...parts) },
+        },
+    });
     return {
         agentClient,
         signedMandate,
@@ -620,9 +1049,54 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         registry: parsed.stateFile === undefined
             ? new InMemoryStreamRegistry()
             : new FileStreamRegistry(parsed.stateFile),
+        allowUnverifiedOperatorPairing: parsed.allowUnverifiedOperatorPairing,
+        serviceInvoker,
+        ...(parsed.x402Enabled
+            ? {
+                x402: {
+                    signer: requireCapabilitySigner(wallet.account),
+                    network: parsed.network,
+                    // The SDK's on-chain quote checks (factory.predict) read through
+                    // this server's own RPC.
+                    sdkOptions: { transport: http(parsed.rpcUrl) },
+                    ...(parsed.x402AllowedHosts.length === 0
+                        ? {}
+                        : { allowedHosts: parsed.x402AllowedHosts }),
+                    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 }),
+                            // Every relay "success" is checked against the receipt.
+                            verifyWith: readOnlyMetrikClient({
+                                escrowAddress: parsed.escrow,
+                                rpcUrl: parsed.rpcUrl,
+                                chainId: parsed.chain.id,
+                            }),
+                            expectedChainId: parsed.chain.id,
+                        });
+                    },
+                },
+            }
+            : {}),
         ...(deliveryProofService === null ? {} : { deliveryProofService }),
     };
 }
+/**
+ * Narrows a resolved wallet account to something that can sign a capability.
+ *
+ * Fails closed at STARTUP with a named cause rather than at the first
+ * `invoke_service` call with a `TypeError`.
+ */
+function requireCapabilitySigner(account) {
+    if (typeof account.signTypedData !== "function") {
+        throw new Error(`the configured wallet (${account.address}) cannot sign EIP-712 typed data, so it cannot authorize a service invocation. Use a wallet whose account exposes signTypedData (a raw key, a CDP server account, or a Privy embedded wallet).`);
+    }
+    return account;
+}
 export async function createVerifiedStreamMcpServerFromEnv(env = process.env) {
     return createVerifiedStreamMcpServer(await createVerifiedStreamMcpServerOptionsFromEnv(env));
 }
@@ -641,6 +1115,26 @@ function serializeServiceListing(listing) {
         ...(listing.targetMetadata === undefined
             ? {}
             : { targetMetadata: listing.targetMetadata }),
+        ...signedRateBandField(listing),
+    };
+}
+/**
+ * The operator-signed rate band, in USDC atomic units per second, so an agent
+ * can pick a `ratePerSecondUsdc` that hire_verified_service will accept. Read
+ * from the record discovery already verified; omitted when none was signed.
+ * hire_verified_service re-verifies it before enforcing it.
+ */
+function signedRateBandField(listing) {
+    const commercial = listing.signed?.descriptor?.commercial;
+    if (commercial?.minRatePerSecond === undefined &&
+        commercial?.maxRatePerSecond === undefined) {
+        return {};
+    }
+    return {
+        ratePerSecondBand: {
+            minRatePerSecondUsdc: commercial.minRatePerSecond ?? null,
+            maxRatePerSecondUsdc: commercial.maxRatePerSecond ?? null,
+        },
     };
 }
 function serializeStreamStatus(status, streamId) {
@@ -678,6 +1172,11 @@ function serializeStreamStatus(status, streamId) {
         },
         claimable: status.claimable.toString(),
         reclaimable: status.reclaimable.toString(),
+        metering: {
+            model: "time-metered",
+            ratePerSecondUsdc: status.stream.ratePerSecond.toString(),
+            note: METERING_MODEL,
+        },
     };
 }
 function serializeConsumedResponseProof(streamId, proof) {
@@ -692,6 +1191,187 @@ function serializeConsumedResponseProof(streamId, proof) {
         verification: proof.verification,
     };
 }
+/**
+ * True when a path carries a character that must never appear in one.
+ *
+ * Mirrors `assertOriginRelativePath` in `../sdk/invoke.ts`. The backslash is the
+ * one that matters: the URL parser reads it as a host separator for http(s), so
+ * it turns an apparently origin-relative path into a different host. C0
+ * controls and DEL go with it — a header- or log-splitting character has no
+ * business in a path either.
+ */
+function hasForbiddenPathCharacter(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (character === "\\" || code < 0x20 || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Checks that `operator` — the wallet that gets paid — is the one the
+ * registry's operator-signed record for `serviceRef` names.
+ *
+ * This reports; it does not decide. Every outcome other than `verified` is
+ * treated as a refusal by the hire path (see ALLOW_UNVERIFIED_OPERATOR_ENV).
+ * An earlier version failed OPEN on anything but a positive contradiction,
+ * which meant that during any registry read failure the exact bug this check
+ * exists to stop was fully live: an attacker's `operator` paired with a genuine
+ * `serviceRef`, the oracle verifying the real endpoint, and accrual settling to
+ * the attacker. Settlement does not depend on this HTTP endpoint being
+ * reachable from the MCP host, so a read failure is no evidence of safety.
+ *
+ * A hostile registry cannot forge a match — the operator's signature over the
+ * record the serviceRef is derived from is recovered client-side — but it CAN
+ * suppress a row, which is exactly why `unlisted` must not be a soft verdict.
+ *
+ * An outage is reported distinctly from a malformed/failed read: "retry in a
+ * moment" and "something is wrong with this registry" are different next steps.
+ */
+async function checkOperatorPairing(discover, serviceRef, operator) {
+    let listings;
+    try {
+        listings = await discover();
+    }
+    catch (error) {
+        return error instanceof RegistryUnavailableError
+            ? { verdict: "registry-unavailable", detail: asErrorMessage(error) }
+            : { verdict: "registry-error", detail: asErrorMessage(error) };
+    }
+    const listing = listings.find((entry) => entry.serviceRef.toLowerCase() === serviceRef.toLowerCase());
+    if (listing === undefined) {
+        return { verdict: "unlisted" };
+    }
+    if (listing.operator.toLowerCase() !== operator.toLowerCase()) {
+        return { verdict: "mismatch", listedOperator: listing.operator };
+    }
+    return { verdict: "verified", listing };
+}
+/**
+ * Why a hire was refused, in words the caller can act on.
+ *
+ * Refusing strands nothing: no USDC has moved, and the same call succeeds once
+ * the registry answers again.
+ */
+function explainPairingRefusal(pairing, serviceRef, operator) {
+    switch (pairing.verdict) {
+        case "mismatch":
+            return `refusing to hire: serviceRef ${serviceRef} is listed under operator ${pairing.listedOperator}, not ${operator}. The operator address is the wallet that gets paid — escrowing to a different one would pay a stranger for someone else's service. Take the operator/serviceRef pair from discover_services.`;
+        case "unlisted":
+            return `refusing to hire: serviceRef ${serviceRef} is not in the verified registry, so there is no operator-signed record proving that ${operator} is the wallet this service pays. Run discover_services and hire a listed service. (A row that fails signature verification is dropped, so a revoked or malformed listing looks the same as an absent one.)`;
+        case "registry-unavailable":
+            return `refusing to hire: the service registry is unreachable (${pairing.detail}), so this hire's operator/serviceRef pairing cannot be verified and the escrow could be paid to the wrong wallet. Nothing was spent — retry when the registry answers.`;
+        case "registry-error":
+            return `refusing to hire: the service registry could not be read (${pairing.detail}), so this hire's operator/serviceRef pairing cannot be verified and the escrow could be paid to the wrong wallet. Nothing was spent.`;
+    }
+}
+/** A prove-target precondition that failed with a caller-actionable reason. */
+class ProveTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProveTargetError";
+    }
+}
+/** Origin of a URL, or the raw value when it will not parse. */
+function safeOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
+function normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        normalized[name.toLowerCase()] = value;
+    }
+    return normalized;
+}
+/**
+ * Renders an invocation as an MCP result.
+ *
+ * A non-2xx answer is returned as `isError` WITH the full structured content:
+ * the call really happened and its body may be the thing the agent needs, but a
+ * buyer who paid and got a 403 should not have to infer that from a status
+ * field. Gateway denials carry their machine-readable reason, because
+ * `stream-expired` and `nonce-replayed` call for opposite responses.
+ */
+function serializeInvocation(result) {
+    const summary = `${result.method} ${result.path} -> ${result.status}`;
+    if (result.ok) {
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: { ...result },
+        };
+    }
+    const because = result.gatewayDenialReason === null
+        ? `the service itself answered ${result.status}; the capability was accepted`
+        : `the seller's caller-auth gateway REFUSED the call: ${result.gatewayDenialReason}${gatewayDenialHint(result.gatewayDenialReason)}`;
+    return {
+        content: [{ type: "text", text: `${summary} — ${because}` }],
+        structuredContent: { ...result },
+        isError: true,
+    };
+}
+/** One actionable next step per gateway denial reason. */
+function gatewayDenialHint(reason) {
+    switch (reason) {
+        case "stream-not-funded":
+            return " — the stream's remaining budget is exhausted; open a new one with hire_verified_service.";
+        case "stream-expired":
+            return " — the stream is past its expiry; reclaim_unspent returns the unspent budget.";
+        case "stream-not-active":
+            return " — the stream is closed; open a new one with hire_verified_service.";
+        case "capability-expired":
+            return " — the signed capability outlived its TTL before the gateway saw it; retry (optionally with a larger ttlSeconds).";
+        case "nonce-replayed":
+            return " — each capability is single-use; retry to mint a fresh one.";
+        case "stream-state-stale":
+            return " — the gateway's view of the chain is too stale to authorize; retry shortly.";
+        case "buyer-mismatch":
+            return " — the stream does not belong to this server's wallet.";
+        default:
+            return "";
+    }
+}
+/**
+ * Turns an invocation failure into something an LLM can act on, or `null` when
+ * it is not a failure this layer understands (those fall through to the generic
+ * handler, which logs the detail server-side and says nothing more).
+ *
+ * The generic "the tool call failed" is correct for an unexpected RPC/viem
+ * error — it can carry internal detail — but it is useless for the three things
+ * that actually go wrong here: wrong wallet, dead stream, unlisted service.
+ */
+function explainInvokeFailure(error, streamId) {
+    if (error instanceof InvokeBuyerMismatchError) {
+        return `stream ${streamId} does not belong to this server's wallet, so this server cannot sign a capability for it. Only the stream's buyer can invoke it — use a stream from hire_verified_service or list_streams.`;
+    }
+    if (error instanceof InvokeStreamNotActiveError) {
+        return `stream ${streamId} is closed, so it authorizes nothing. Open a new one with hire_verified_service.`;
+    }
+    if (error instanceof InvokeStreamExpiredError) {
+        return `stream ${streamId} has expired, so it authorizes nothing. reclaim_unspent returns the unspent budget; hire_verified_service opens a replacement.`;
+    }
+    if (error instanceof ServiceListingNotFoundError) {
+        return `no verified listing matches this stream's serviceRef (${error.serviceRef}). Run discover_services: a listing whose operator signature fails verification is dropped, so an unlisted or revoked service cannot be invoked.`;
+    }
+    if (error instanceof InvokeServiceRefMismatchError) {
+        return `the registry's listing does not match this stream's serviceRef. The call was refused rather than sent to an origin this stream did not pay for.`;
+    }
+    if (error instanceof InvokeAccessUrlError) {
+        return `this stream's listing carries no usable signed invocation origin (${error.message}). This server refuses to call an origin the operator did not sign.`;
+    }
+    if (error instanceof InvokePathError) {
+        return `invalid request path: ${error.message}`;
+    }
+    if (error instanceof RegistryUnavailableError) {
+        return `the service registry is unreachable, so the operator-signed origin for this stream could not be verified. The call was not attempted — an unverified origin is never guessed. Retry when the registry is back.`;
+    }
+    return null;
+}
 function successResult(text, structuredContent) {
     return {
         content: [{ type: "text", text }],