@absol-labs/agent 0.9.1 → 0.11.0

package/src/mcp/server.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 
+import { BASE_SEPOLIA_ESCROW_V2 } 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";
@@ -31,12 +32,34 @@ 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";
 
 /**
  * MCP server for the agent lane.
@@ -85,6 +108,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 +219,44 @@ 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(),
 });
 
+/**
+ * The retired V1 metered escrow.
+ *
+ * Refused by NAME rather than left to fail at read time, because it does not
+ * fail at read time: V1 and V2 `getStream` return different tuples that diverge
+ * from index 5 onward, so a V2 decoder pointed at V1 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` here as recently as 0.10.0.
+ */
+const RETIRED_V1_ESCROW = "0x21948a5e6ae8d9a3d1050791ab6138657fb54286";
+
+/**
+ * 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";
+
 export interface McpToolSpec {
   name: string;
   description: string;
@@ -156,40 +264,57 @@ 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,
   },
 ] as const;
@@ -343,6 +468,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;
@@ -368,6 +510,13 @@ 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;
+  /** 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;
   readonly stateFile?: string;
@@ -392,12 +541,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 +644,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 +679,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 +721,40 @@ 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),
+            );
+          }
+        }
+
         // 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 +800,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.`} 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 +821,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 +839,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 +927,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 +962,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 +984,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);
       }
@@ -757,6 +1078,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 +1142,9 @@ export function createVerifiedStreamMcpServer(
             serializeConsumedResponseProof(record.streamId, result),
           );
         } catch (error) {
+          if (error instanceof ProveTargetError) {
+            return errorResult(error.message);
+          }
           return safeToolError(error);
         }
       },
@@ -799,10 +1163,34 @@ export function createVerifiedStreamMcpServer(
   };
 }
 
+/** One readable line per invalid or missing environment variable. */
+function describeEnvIssues(error: z.ZodError): string {
+  const seen = new Set<string>();
+  for (const issue of error.issues) {
+    const name = issue.path.join(".");
+    seen.add(
+      issue.code === "invalid_type" && issue.received === "undefined"
+        ? `${name} is not set`
+        : `${name} is invalid (${issue.message})`,
+    );
+  }
+  return [...seen].join("; ");
+}
+
 export function parseMetrikAgentEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): ParsedMetrikAgentEnv {
-  const parsed = metrikAgentEnvSchema.parse(env);
+  const result = metrikAgentEnvSchema.safeParse(env);
+  if (!result.success) {
+    // `.parse()` threw a ZodError whose message is a JSON array of issue
+    // 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}).`,
+    );
+  }
+  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");
@@ -813,9 +1201,36 @@ export function parseMetrikAgentEnv(
     );
   }
 
+  // Generation is CONFIGURED. `v2` is the only generation the checkpoint escrow
+  // semantics this server implements apply to, so anything else is refused up
+  // front instead of silently mis-decoded (see RETIRED_V1_ESCROW).
+  const generation = (
+    parsed.METRIK_AGENT_ESCROW_GENERATION ?? "v2"
+  ).toLowerCase();
+  if (generation !== "v2") {
+    throw new Error(
+      `unsupported METRIK_AGENT_ESCROW_GENERATION "${parsed.METRIK_AGENT_ESCROW_GENERATION}": this server reads checkpoint-settled StreamEscrowV2 only. Leave it unset (or set it to "v2") and point METRIK_AGENT_ESCROW at the V2 escrow.`,
+    );
+  }
+  if (parsed.METRIK_AGENT_ESCROW.toLowerCase() === RETIRED_V1_ESCROW) {
+    throw new Error(
+      `METRIK_AGENT_ESCROW is the RETIRED V1 metered escrow (${parsed.METRIK_AGENT_ESCROW}). It is no longer settled by the oracle, and its stream tuple is incompatible with the checkpoint decoder this server uses — reads would not revert, they would return confident nonsense. Point it at the live StreamEscrowV2 (${BASE_SEPOLIA_ESCROW_V2}).`,
+    );
+  }
+
   return {
     rpcUrl: parsed.METRIK_AGENT_RPC_URL,
     escrow: parsed.METRIK_AGENT_ESCROW as `0x${string}`,
+    escrowGeneration: "v2",
+    // 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,
@@ -860,11 +1275,13 @@ 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.
-      escrowV2: parsed.escrow,
+      // 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.
+      ...(parsed.escrowGeneration === "v2" ? { escrowV2: parsed.escrow } : {}),
       usdc: parsed.usdc,
       settlementTarget: {
         chainId: parsed.chain.id,
@@ -895,6 +1312,30 @@ 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,
+    }),
+    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,
@@ -903,10 +1344,29 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
       parsed.stateFile === undefined
         ? new InMemoryStreamRegistry()
         : new FileStreamRegistry(parsed.stateFile),
+    allowUnverifiedOperatorPairing: parsed.allowUnverifiedOperatorPairing,
+    serviceInvoker,
     ...(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> {
@@ -976,6 +1436,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,
+    },
   };
 }
 
@@ -995,6 +1460,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 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" };
+}
+
+/**
+ * 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>,