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

package/src/mcp/server.ts

@@ -1,11 +1,11 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 
+import type { MetrikNetwork } from "@absol-labs/sdk";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { privateKeyToAccount } from "viem/accounts";
 import { http, isAddress, isHex, type Chain } from "viem";
-import { baseSepolia } from "viem/chains";
 import { z } from "zod";
 
 import {
@@ -13,6 +13,7 @@ import {
   type DiscoverServicesOptions,
   type ServiceListing,
 } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
   parseServerMandateCapsEnv,
@@ -31,12 +32,47 @@ import {
   createWalletBackedAgentClient,
   parseAgentWalletEnv,
   type AgentWalletInput,
+  type ResolvedAgentWallet,
 } from "../wallet/provider.js";
 import {
   createReclaimConsumerProofServiceFromEnv,
   type ConsumerDeliveryProofService,
   type VerifiedConsumedHttpsResponseProof,
 } from "../zktls/reclaim.js";
+import {
+  CAPABILITY_HEADER_NAME,
+  httpMethodSchema,
+  type InvocationCapabilitySigner,
+} from "../capability/invocation-capability.js";
+import {
+  createSdkInvokeStreamReader,
+  InvokeAccessUrlError,
+  InvokeBuyerMismatchError,
+  InvokePathError,
+  InvokeServiceRefMismatchError,
+  InvokeStreamExpiredError,
+  InvokeStreamNotActiveError,
+} from "../sdk/invoke.js";
+import {
+  createServiceInvoker,
+  RegistryUnavailableError,
+  ServiceListingNotFoundError,
+  type ServiceInvocationResult,
+  type ServiceInvoker,
+} 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,
+  type McpX402Options,
+} from "./x402-tools.js";
 
 /**
  * MCP server for the agent lane.
@@ -85,6 +121,55 @@ const hireVerifiedServiceSchema = {
     ),
 } as const;
 
+/**
+ * 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.`,
+    ),
+} as const;
+
 const getStreamStatusSchema = {
   streamId: bytes32Schema.describe(
     "Stream id returned by hire_verified_service.",
@@ -147,8 +232,51 @@ 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" as const;
+
+/**
+ * Escrow generations this server can talk to.
+ *
+ * Declared, not inferred. The client sets `escrowV2` (which selects the
+ * checkpoint decoder for every read) purely from configuration, so the
+ * generation has to be a stated fact that can be wrong out loud, rather than an
+ * assumption buried in one constructor argument.
+ */
+export type EscrowGeneration = "v2" | "v3";
+
 export interface McpToolSpec {
   name: string;
   description: string;
@@ -156,42 +284,74 @@ export interface McpToolSpec {
   movesFunds: boolean;
 }
 
+/**
+ * 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: readonly McpToolSpec[] = [
   {
     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.",
+      "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: "check_stream_status",
+    name: "invoke_service",
     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.",
+      "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, 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.",
+      "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.",
+      "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,
+  },
 ] as const;
 
 /** @deprecated Renamed to METRIK_MCP_TOOLS; retained for back-compat. */
@@ -207,12 +367,28 @@ export interface StoredStreamRecord {
   readonly maxDurationSeconds: number;
   readonly openedAtSeconds: number;
   readonly mandateId: `0x${string}`;
+  /** x402 streams only: the seller's refund relay URL for this stream. */
+  readonly refundUrl?: string;
+  /** x402 streams only: the X402StreamOpener that bought the stream. */
+  readonly opener?: `0x${string}`;
+  /**
+   * An x402 payment approved and signed whose stream is not (yet) known. It
+   * counts against the cumulative cap exactly like a stream; `streamId` is a
+   * reservation key, not an escrow stream id.
+   */
+  readonly x402Reservation?: boolean;
 }
 
 export interface StreamRegistry {
   put(record: StoredStreamRecord): Promise<void>;
   get(streamId: `0x${string}`): Promise<StoredStreamRecord | null>;
   list(): Promise<readonly StoredStreamRecord[]>;
+  /**
+   * Remove a record. Used ONLY to release an x402 spend reservation that
+   * provably never moved money, or one superseded by its real stream. A
+   * registry without it keeps reservations (they over-count: buyer-favouring).
+   */
+  delete?(streamId: `0x${string}`): Promise<void>;
 }
 
 export class InMemoryStreamRegistry implements StreamRegistry {
@@ -229,6 +405,10 @@ export class InMemoryStreamRegistry implements StreamRegistry {
   async list(): Promise<readonly StoredStreamRecord[]> {
     return Array.from(this.records.values());
   }
+
+  async delete(streamId: `0x${string}`): Promise<void> {
+    this.records.delete(streamId);
+  }
 }
 
 export class FileStreamRegistry implements StreamRegistry {
@@ -249,6 +429,11 @@ export class FileStreamRegistry implements StreamRegistry {
     return Array.from((await this.readAll()).values());
   }
 
+  async delete(streamId: `0x${string}`): Promise<void> {
+    const records = await this.readAll();
+    if (records.delete(streamId)) await this.writeAll(records);
+  }
+
   private async readAll(): Promise<Map<`0x${string}`, StoredStreamRecord>> {
     const contents = await fs.readFile(this.filePath, "utf8").catch((error) => {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
@@ -268,6 +453,9 @@ export class FileStreamRegistry implements StreamRegistry {
           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));
@@ -285,6 +473,13 @@ export class FileStreamRegistry implements StreamRegistry {
           maxDurationSeconds: record.maxDurationSeconds,
           openedAtSeconds: record.openedAtSeconds,
           mandateId: record.mandateId as `0x${string}`,
+          ...(record.refundUrl === undefined
+            ? {}
+            : { refundUrl: record.refundUrl }),
+          ...(record.opener === undefined
+            ? {}
+            : { opener: record.opener as `0x${string}` }),
+          ...(record.x402Reservation === true ? { x402Reservation: true } : {}),
         },
       ]),
     );
@@ -343,6 +538,23 @@ export interface VerifiedStreamMcpServerOptions {
     | SignedSpendMandate
     | Promise<SignedSpendMandate>;
   readonly registry?: StreamRegistry;
+  /**
+   * Escape hatch for the operator/serviceRef cross-check, from
+   * {@link ALLOW_UNVERIFIED_OPERATOR_ENV}.
+   *
+   * OFF by default and deliberately not reachable from a tool argument: the
+   * caller being asked to relax a fund-safety check is the LLM the check exists
+   * to constrain. Even when on, a positive contradiction (`mismatch`) is still
+   * refused — this only downgrades "could not verify" from a refusal to a
+   * warning, for an operator who has accepted that risk explicitly.
+   */
+  readonly allowUnverifiedOperatorPairing?: boolean;
+  /**
+   * Drives `invoke_service`. Omitted, the tool is not registered at all rather
+   * than advertised and broken — the env builder always supplies one, so this
+   * is only omitted by callers wiring the server by hand (and by tests).
+   */
+  readonly serviceInvoker?: ServiceInvoker;
   readonly deliveryProofService?: ConsumerDeliveryProofService;
   readonly mandateStateResolver?: Partial<MandateStateResolver>;
   readonly now?: () => number;
@@ -352,6 +564,12 @@ export interface VerifiedStreamMcpServerOptions {
    * the registry URL/apikey come from env inside `discoverServices`.
    */
   readonly discoverServices?: DiscoverServicesFn;
+  /**
+   * The buyer side of x402. When set, `x402_pay`, `refund_status` and `refund`
+   * are registered (mandate-gated like `hire_verified_service`); unset, the
+   * tool surface is exactly as before.
+   */
+  readonly x402?: McpX402Options;
   readonly serverInfo?: {
     readonly name: string;
     readonly version: string;
@@ -368,8 +586,27 @@ export interface VerifiedStreamMcpServerRuntime {
 export interface ParsedMetrikAgentEnv {
   readonly rpcUrl: string;
   readonly escrow: `0x${string}`;
+  /** Which escrow generation {@link escrow} is, as CONFIGURED (never probed). */
+  readonly escrowGeneration: EscrowGeneration;
+  /**
+   * True when `escrow` is NOT a registered deployment and the operator opted
+   * in (`METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW=true` + an explicit
+   * `METRIK_AGENT_ESCROW_GENERATION`); the SDK then skips its code-hash pin.
+   */
+  readonly unregisteredEscrow: boolean;
+  /** Registry the invocation origin is verified against. Undefined = the public default. */
+  readonly registryUrl?: string;
+  readonly registryApiKey?: string;
+  /** {@link ALLOW_UNVERIFIED_OPERATOR_ENV}; false unless explicitly `true`. */
+  readonly allowUnverifiedOperatorPairing: boolean;
   readonly usdc: `0x${string}`;
   readonly chain: Chain;
+  /** The registered network this server settles on (SDK network registry). */
+  readonly network: MetrikNetwork;
+  /** `METRIK_AGENT_X402`: register the x402 tools. OPT-IN: only `1`/`true`/`yes`/`on`. */
+  readonly x402Enabled: boolean;
+  /** `METRIK_AGENT_X402_ALLOWED_HOSTS`, comma-separated; empty = any public host. */
+  readonly x402AllowedHosts: readonly string[];
   readonly stateFile?: string;
   readonly wallet: AgentWalletInput;
 }
@@ -392,12 +629,27 @@ function warnOnce(key: string, message: string): void {
   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: string): McpToolSpec {
+  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
@@ -480,6 +732,14 @@ export function createVerifiedStreamMcpServer(
 
   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 ?? {
@@ -507,10 +767,17 @@ export function createVerifiedStreamMcpServer(
           ...(limit === undefined ? {} : { limit }),
         });
         return successResult(
-          `discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}`,
+          `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);
       }
     },
@@ -542,6 +809,64 @@ export function createVerifiedStreamMcpServer(
             args.durationSeconds ?? signedMandate.mandate.maxDurationSeconds,
         } satisfies Parameters<typeof checkMandate>[1];
 
+        // 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 as `0x${string}`,
+          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.
@@ -587,8 +912,18 @@ export function createVerifiedStreamMcpServer(
             mandateId: signedMandate.mandateId as `0x${string}`,
           });
 
+          // 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}`,
+            `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,
@@ -598,6 +933,15 @@ export function createVerifiedStreamMcpServer(
                 escrow: result.handle.escrow,
                 chainId: result.handle.chainId,
               },
+              operatorPairing: pairing.verdict,
+              metering: {
+                model: "time-metered" as const,
+                ratePerSecondUsdc: request.ratePerSecondUsdc.toString(),
+                budgetUsdc: request.budgetUsdc.toString(),
+                maxDurationSeconds: request.maxDurationSeconds,
+                maxSpendUsdc: maxSpendUsdc.toString(),
+                note: METERING_MODEL,
+              },
             },
           );
         });
@@ -607,6 +951,77 @@ export function createVerifiedStreamMcpServer(
     },
   );
 
+  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 as `0x${string}`,
+            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",
     {
@@ -624,8 +1039,18 @@ export function createVerifiedStreamMcpServer(
         const status = await options.agentClient.getStreamStatus(
           streamId as `0x${string}`,
         );
+        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(
-          `stream ${streamId} is ${status.stream.status}`,
+          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 as `0x${string}`),
         );
       } catch (error) {
@@ -649,10 +1074,14 @@ export function createVerifiedStreamMcpServer(
     },
     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 as `0x${string}`);
-        if (record === null) {
-          return errorResult(`unknown stream: ${streamId}`);
-        }
         const signedMandate = await resolveMandate();
 
         // Reclaim/close only RETURN unspent funds to the buyer or stop payment.
@@ -667,10 +1096,14 @@ export function createVerifiedStreamMcpServer(
           ...(closeFirst === undefined ? {} : { closeFirst }),
         });
 
-        return successResult(`reclaimed stream ${streamId}`, {
-          closeTxHash: result.closeResult?.txHash ?? null,
-          reclaimTxHash: result.reclaimResult.txHash,
-        });
+        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) {
         return safeToolError(error);
       }
@@ -693,13 +1126,24 @@ export function createVerifiedStreamMcpServer(
         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,
@@ -725,6 +1169,34 @@ export function createVerifiedStreamMcpServer(
     },
   );
 
+  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: `0x${string}`) => {
+              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(
@@ -757,6 +1229,46 @@ export function createVerifiedStreamMcpServer(
             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: unknown) => {
+            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 }),
@@ -781,6 +1293,9 @@ export function createVerifiedStreamMcpServer(
             serializeConsumedResponseProof(record.streamId, result),
           );
         } catch (error) {
+          if (error instanceof ProveTargetError) {
+            return errorResult(error.message);
+          }
           return safeToolError(error);
         }
       },
@@ -823,28 +1338,100 @@ export function parseMetrikAgentEnv(
     // 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}).`,
+      `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: number | undefined;
+  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");
+    }
   }
-  if (chainId !== baseSepolia.id) {
+  // "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: MetrikNetwork;
+  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_AGENT_CHAIN_ID ${chainId}; phase 2 is Base Sepolia only`,
+      `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.`,
+    );
+  }
+  const deployment = registeredDeployment(network, parsed.METRIK_AGENT_ESCROW);
+  let generation: EscrowGeneration;
+  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 as `0x${string}`,
+    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 as `0x${string}`,
     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
       ? {}
       : {
@@ -884,11 +1471,21 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
       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,
@@ -919,6 +1516,34 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
     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,
@@ -927,10 +1552,62 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
       parsed.stateFile === undefined
         ? new InMemoryStreamRegistry()
         : new FileStreamRegistry(parsed.stateFile),
+    allowUnverifiedOperatorPairing: parsed.allowUnverifiedOperatorPairing,
+    serviceInvoker,
+    ...(parsed.x402Enabled
+      ? {
+          x402: {
+            signer: requireCapabilitySigner(
+              wallet.account,
+            ) as unknown as McpX402Options["signer"],
+            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,
+              });
+            },
+          } satisfies McpX402Options,
+        }
+      : {}),
     ...(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: ResolvedAgentWallet["account"],
+): InvocationCapabilitySigner {
+  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 as InvocationCapabilitySigner;
+}
+
 export async function createVerifiedStreamMcpServerFromEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<VerifiedStreamMcpServerRuntime> {
@@ -959,6 +1636,42 @@ function serializeServiceListing(
     ...(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: ServiceListing): {
+  readonly ratePerSecondBand?: Record<string, string | null>;
+} {
+  const commercial = (
+    listing.signed as
+      | {
+          readonly descriptor?: {
+            readonly commercial?: {
+              readonly minRatePerSecond?: string;
+              readonly maxRatePerSecond?: string;
+            };
+          };
+        }
+      | undefined
+  )?.descriptor?.commercial;
+  if (
+    commercial?.minRatePerSecond === undefined &&
+    commercial?.maxRatePerSecond === undefined
+  ) {
+    return {};
+  }
+  return {
+    ratePerSecondBand: {
+      minRatePerSecondUsdc: commercial.minRatePerSecond ?? null,
+      maxRatePerSecondUsdc: commercial.maxRatePerSecond ?? null,
+    },
   };
 }
 
@@ -1000,6 +1713,11 @@ function serializeStreamStatus(
     },
     claimable: status.claimable.toString(),
     reclaimable: status.reclaimable.toString(),
+    metering: {
+      model: "time-metered" as const,
+      ratePerSecondUsdc: status.stream.ratePerSecond.toString(),
+      note: METERING_MODEL,
+    },
   };
 }
 
@@ -1019,6 +1737,217 @@ function serializeConsumedResponseProof(
   };
 }
 
+/**
+ * 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: string): boolean {
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (character === "\\" || code < 0x20 || code === 0x7f) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Lower-cases header names so duplicate/odd-cased keys collapse to one. */
+type OperatorPairing =
+  | { readonly verdict: "verified"; readonly listing: ServiceListing }
+  | { readonly verdict: "mismatch"; readonly listedOperator: `0x${string}` }
+  | { readonly verdict: "unlisted" }
+  | {
+      readonly verdict: "registry-unavailable" | "registry-error";
+      readonly detail: string;
+    };
+
+/**
+ * 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: DiscoverServicesFn,
+  serviceRef: `0x${string}`,
+  operator: `0x${string}`,
+): Promise<OperatorPairing> {
+  let listings: readonly ServiceListing[];
+  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: Exclude<OperatorPairing, { verdict: "verified" }>,
+  serviceRef: string,
+  operator: string,
+): string {
+  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: string) {
+    super(message);
+    this.name = "ProveTargetError";
+  }
+}
+
+/** Origin of a URL, or the raw value when it will not parse. */
+function safeOrigin(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value;
+  }
+}
+
+function normalizeHeaders(
+  headers: Record<string, string> | undefined,
+): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  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: ServiceInvocationResult) {
+  const summary = `${result.method} ${result.path} -> ${result.status}`;
+  if (result.ok) {
+    return {
+      content: [{ type: "text" as const, 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" as const, text: `${summary} — ${because}` }],
+    structuredContent: { ...result },
+    isError: true,
+  };
+}
+
+/** One actionable next step per gateway denial reason. */
+function gatewayDenialHint(reason: string): string {
+  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: unknown, streamId: string): string | null {
+  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: string,
   structuredContent?: Record<string, unknown>,