@absol-labs/agent 0.9.1 → 0.11.0

package/dist/mcp/server.js

@@ -1,5 +1,6 @@
 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 { http, isAddress, isHex } from "viem";
@@ -11,6 +12,9 @@ import { parseServerMandateCapsEnv, signServerMandate, ServerMandateConfigError,
 import { isCheckpointStream, } from "../sdk/client.js";
 import { createWalletBackedAgentClient, parseAgentWalletEnv, } from "../wallet/provider.js";
 import { createReclaimConsumerProofServiceFromEnv, } from "../zktls/reclaim.js";
+import { CAPABILITY_HEADER_NAME, httpMethodSchema, } from "../capability/invocation-capability.js";
+import { createSdkInvokeStreamReader, InvokeAccessUrlError, InvokeBuyerMismatchError, InvokePathError, InvokeServiceRefMismatchError, InvokeStreamExpiredError, InvokeStreamNotActiveError, } from "../sdk/invoke.js";
+import { createServiceInvoker, RegistryUnavailableError, ServiceListingNotFoundError, } from "./service-invoker.js";
 /**
  * MCP server for the agent lane.
  *
@@ -42,6 +46,41 @@ const hireVerifiedServiceSchema = {
         .optional()
         .describe("Optional max stream lifetime in seconds. Defaults to the server mandate's max duration."),
 };
+/**
+ * Ceiling on a capability's lifetime.
+ *
+ * A signed capability is a bearer credential for one method+path on one stream:
+ * anything holding it can make that call until it expires. The signer's own
+ * default is 60s; this bounds what an LLM may ask for so a single tool argument
+ * cannot mint a long-lived credential. It is a cap, not the default.
+ */
+const MAX_CAPABILITY_TTL_SECONDS = 300;
+const invokeServiceSchema = {
+    streamId: bytes32Schema.describe("Stream id of an ACTIVE stream whose buyer is this server's wallet (from hire_verified_service or list_streams)."),
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Origin-relative request path, query string included, e.g. "/price?symbol=BTC". Defaults to "/". The ORIGIN is not a parameter: it is read from the operator-signed listing for this stream\'s serviceRef.'),
+    method: httpMethodSchema
+        .optional()
+        .describe('HTTP method. Defaults to "GET". The capability authorizes exactly this method and this path — nothing else.'),
+    headers: z
+        .record(z.string())
+        .optional()
+        .describe("Extra request headers. The capability header is attached by the server and cannot be supplied here."),
+    body: z
+        .string()
+        .optional()
+        .describe("Request body, sent verbatim. Defaults to a JSON content-type when a body is present and none is given."),
+    ttlSeconds: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_CAPABILITY_TTL_SECONDS)
+        .optional()
+        .describe(`Capability lifetime in seconds (default 60, max ${MAX_CAPABILITY_TTL_SECONDS}). Shorter is safer; it only has to outlive one request.`),
+};
 const getStreamStatusSchema = {
     streamId: bytes32Schema.describe("Stream id returned by hire_verified_service."),
 };
@@ -89,36 +128,73 @@ 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";
+/**
+ * The one sentence every stream-opening surface has to carry.
+ *
+ * A reviewer made ONE call against a stream and was billed for 302 seconds. The
+ * escrow behaved exactly as designed — and nothing in the tool surface had told
+ * them what they were buying. An LLM picks a tool from its description alone, so
+ * the meter is stated in the description of every tool that opens, reads, or
+ * ends a stream, not only in the docs it will never read.
+ */
+export const METERING_MODEL = "METERING: this is TIME-metered rental of an endpoint that keeps proving it is live, NOT per-call billing. Cost = ratePerSecondUsdc x seconds the oracle VERIFIED, capped at the escrowed budget. One call and a thousand calls cost the same second, and the clock runs while you call nothing. Only closing the stream (reclaim_unspent) stops it; nothing refunds automatically.";
 export const METRIK_MCP_TOOLS = [
     {
         name: "discover_services",
-        description: "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is cryptographically verified, so an agent can go from discovery to hire without pre-known addresses.",
+        description: "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is cryptographically verified, so an agent can go from discovery to hire without pre-known addresses. Listings are priced per second, not per call.",
         movesFunds: false,
     },
     {
         name: "hire_verified_service",
-        description: "Open a verified payment stream for a third-party service. Pays only for oracle-verified delivered time. Subject to the agent's spend mandate.",
+        description: `Open a verified payment stream for a third-party service, then call it with invoke_service. Pays only for oracle-verified delivered time. Subject to the agent's spend mandate. ${METERING_MODEL}`,
         movesFunds: true,
     },
+    {
+        name: "invoke_service",
+        description: "Call the service a stream is already paying for. Signs a single-use EIP-712 capability as the stream's buyer and calls the origin the operator cryptographically signed (resolved from the verified listing — never a caller-supplied URL). This is how an agent USES what it hired. It moves no funds and adds no cost: billing is by verified elapsed time, so invoking more often is free and invoking never still costs.",
+        movesFunds: false,
+    },
     {
         name: "check_stream_status",
-        description: "Read a stream's live status, accrued amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
+        description: `Read a stream's live status, settled amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry. ${METERING_MODEL}`,
         movesFunds: false,
     },
     {
         name: "reclaim_unspent",
-        description: "Close a stream and reclaim unspent funds to the buyer. V2 reclaim follows checkpoint finalization or escape-window rules.",
+        description: "Close a stream and reclaim unspent funds to the buyer. Closing is what STOPS the per-second meter — nothing else does, and no refund is ever pushed back on its own. V2 reclaim follows checkpoint finalization or escape-window rules.",
         movesFunds: true,
     },
     {
         name: "list_streams",
-        description: "List the agent's streams and their current state.",
+        description: "List the streams this server opened and their current state. Every active stream is still accruing cost per verified second whether or not it is being invoked.",
         movesFunds: false,
     },
     {
         name: "prove_https_response",
-        description: "Generate a zkTLS proof of the exact HTTPS response consumed for a tracked stream. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence.",
+        description: "Generate a buyer-side zkTLS proof of an HTTPS response from a stream's verified service origin. PUBLIC listings only: the proof is fetched by a third-party Reclaim attestor, which cannot present this stream's caller-auth capability, so a GATED listing answers the attestor with a 403 and the tool fails closed rather than proving a rejection. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence; it is not a substitute for it.",
         movesFunds: false,
     },
 ];
@@ -212,12 +288,26 @@ function warnOnce(key, message) {
     // stderr, never stdout: stdout is the MCP stdio transport channel.
     console.error(message);
 }
-const DISCOVER_TOOL_SPEC = METRIK_MCP_TOOLS[0];
-const HIRE_TOOL_SPEC = METRIK_MCP_TOOLS[1];
-const STATUS_TOOL_SPEC = METRIK_MCP_TOOLS[2];
-const RECLAIM_TOOL_SPEC = METRIK_MCP_TOOLS[3];
-const LIST_TOOL_SPEC = METRIK_MCP_TOOLS[4];
-const PROVE_TOOL_SPEC = METRIK_MCP_TOOLS[5];
+/**
+ * Looks a tool spec up by NAME. This used to index into METRIK_MCP_TOOLS by
+ * position, which silently rebinds every description the moment a tool is
+ * inserted anywhere but the end — a tool whose advertised description belongs
+ * to a different tool is worse than a missing one, because an agent acts on it.
+ */
+function toolSpec(name) {
+    const spec = METRIK_MCP_TOOLS.find((entry) => entry.name === name);
+    if (spec === undefined) {
+        throw new Error(`unknown MCP tool spec: ${name}`);
+    }
+    return spec;
+}
+const DISCOVER_TOOL_SPEC = toolSpec("discover_services");
+const HIRE_TOOL_SPEC = toolSpec("hire_verified_service");
+const INVOKE_TOOL_SPEC = toolSpec("invoke_service");
+const STATUS_TOOL_SPEC = toolSpec("check_stream_status");
+const RECLAIM_TOOL_SPEC = toolSpec("reclaim_unspent");
+const LIST_TOOL_SPEC = toolSpec("list_streams");
+const PROVE_TOOL_SPEC = toolSpec("prove_https_response");
 const discoverServicesSchema = {
     category: z
         .string()
@@ -273,6 +363,10 @@ export function createVerifiedStreamMcpServer(options) {
     };
     const now = options.now ?? (() => Math.floor(Date.now() / 1000));
     const discover = options.discoverServices ?? defaultDiscoverServices;
+    const allowUnverifiedOperator = options.allowUnverifiedOperatorPairing ?? false;
+    if (allowUnverifiedOperator) {
+        warnOnce("mcp-unverified-operator", `[metrik] ${ALLOW_UNVERIFIED_OPERATOR_ENV} is set: hires whose operator/serviceRef pairing CANNOT be verified will proceed. The operator address is the wallet that gets paid; an unverifiable pairing can escrow to a wallet that does not own the service. A contradicted pairing is still refused.`);
+    }
     const mcpServer = new McpServer(options.serverInfo ?? {
         name: "metrik-agent-mcp",
         version: "0.1.0",
@@ -292,9 +386,14 @@ export function createVerifiedStreamMcpServer(options) {
                 ...(category === undefined ? {} : { category }),
                 ...(limit === undefined ? {} : { limit }),
             });
-            return successResult(`discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}`, { services: listings.map(serializeServiceListing) });
+            return successResult(`discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}, priced per verified second`, { services: listings.map(serializeServiceListing) });
         }
         catch (error) {
+            if (error instanceof RegistryUnavailableError) {
+                // Loud, not silent: discovery never degrades to stale local data, so
+                // "the registry is down" must not read as "there are no services".
+                return errorResult("the service registry is unreachable, so no listing could be verified. This is NOT the same as zero services — do not conclude the marketplace is empty. Retry shortly.");
+            }
             return safeToolError(error);
         }
     });
@@ -319,6 +418,33 @@ export function createVerifiedStreamMcpServer(options) {
                 ratePerSecondUsdc: BigInt(args.ratePerSecondUsdc),
                 maxDurationSeconds: args.durationSeconds ?? signedMandate.mandate.maxDurationSeconds,
             };
+            // Does this operator actually own this serviceRef?
+            //
+            // The two arrive as independent tool arguments, and `operator` is the
+            // wallet that gets paid. An LLM that pairs a real serviceRef with an
+            // attacker's payout address escrows the buyer's USDC to a stranger, and
+            // nothing downstream catches it: the escrow does not know who owns a
+            // serviceRef, and the oracle would happily verify the real endpoint
+            // while the money accrued elsewhere. Discovery DOES know — it recovers
+            // the operator's signature over the record the serviceRef is derived
+            // from — so the pairing is checked against it here.
+            //
+            // A serviceRef that is not listed at all is allowed with a warning
+            // (the registry is not the authority on what exists, and refusing would
+            // block private or freshly-listed services); a serviceRef that IS
+            // listed under a DIFFERENT operator is refused outright.
+            const pairing = await checkOperatorPairing(discover, args.serviceRef, request.operator);
+            if (pairing.verdict !== "verified") {
+                // FAIL CLOSED. Anything short of a positive match is a refusal: a
+                // registry outage is not evidence that the pairing is sound, and the
+                // money moves before any note attached to a success result could be
+                // read. The only override is an operator-set environment variable
+                // (never a tool argument), and even that never overrides a positive
+                // contradiction.
+                if (pairing.verdict === "mismatch" || !allowUnverifiedOperator) {
+                    return errorResult(explainPairingRefusal(pairing, args.serviceRef, request.operator));
+                }
+            }
             // Serialize per owner: the spent-so-far read, cap check, open, and
             // registry write must be atomic, or concurrent hires could both pass
             // the cumulative-cap check on stale spend and overshoot maxTotalUsdc.
@@ -354,7 +480,15 @@ export function createVerifiedStreamMcpServer(options) {
                     openedAtSeconds: nowSeconds,
                     mandateId: signedMandate.mandateId,
                 });
-                return successResult(`opened verified stream ${result.streamId} on chain ${result.handle.chainId}`, {
+                // The meter starts HERE, not on the first invoke_service call. Say
+                // so in the result as well as the tool description: a reviewer who
+                // opened a stream, made one call and was billed for 302 seconds read
+                // the result, not the docs.
+                const maxSpendUsdc = request.budgetUsdc <
+                    request.ratePerSecondUsdc * BigInt(request.maxDurationSeconds)
+                    ? request.budgetUsdc
+                    : request.ratePerSecondUsdc * BigInt(request.maxDurationSeconds);
+                return successResult(`opened verified stream ${result.streamId} on chain ${result.handle.chainId}.${pairing.verdict === "verified" ? "" : ` WARNING: the operator/serviceRef pairing was NOT verified (${pairing.verdict}) and this server is configured to escrow anyway via ${ALLOW_UNVERIFIED_OPERATOR_ENV}. The operator is the wallet that gets paid and nothing proved it owns this service.`} The meter is running from now at ${request.ratePerSecondUsdc} USDC base units per VERIFIED second, whether or not you call the service. Call it with invoke_service; stop the meter with reclaim_unspent.`, {
                     streamId: result.streamId,
                     txHash: result.txHash,
                     approveTxHash: result.approveTxHash,
@@ -363,6 +497,15 @@ export function createVerifiedStreamMcpServer(options) {
                         escrow: result.handle.escrow,
                         chainId: result.handle.chainId,
                     },
+                    operatorPairing: pairing.verdict,
+                    metering: {
+                        model: "time-metered",
+                        ratePerSecondUsdc: request.ratePerSecondUsdc.toString(),
+                        budgetUsdc: request.budgetUsdc.toString(),
+                        maxDurationSeconds: request.maxDurationSeconds,
+                        maxSpendUsdc: maxSpendUsdc.toString(),
+                        note: METERING_MODEL,
+                    },
                 });
             });
         }
@@ -370,6 +513,64 @@ export function createVerifiedStreamMcpServer(options) {
             return safeToolError(error);
         }
     });
+    if (options.serviceInvoker !== undefined) {
+        const serviceInvoker = options.serviceInvoker;
+        mcpServer.registerTool("invoke_service", {
+            description: INVOKE_TOOL_SPEC.description,
+            inputSchema: invokeServiceSchema,
+            annotations: {
+                // Not idempotent and not read-only: the call reaches a third party's
+                // endpoint, which may do anything. It is NOT destructive in Metrik's
+                // own terms — it signs no transaction and moves no USDC.
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+                readOnlyHint: false,
+                title: "Invoke Paid Service",
+            },
+        }, async ({ streamId, path, method, headers, body, ttlSeconds }) => {
+            const requestPath = path ?? "/";
+            // Defence in depth. `resolveInvocationUrl` is the authority — it
+            // resolves the path and proves the result did not leave the signed
+            // origin — but a tool argument that cannot possibly be a safe path is
+            // refused here, with a message the caller can act on, before anything
+            // reads the chain. A prefix check ALONE was the bug: the URL parser
+            // treats a backslash as a host separator for http(s), so a path
+            // beginning `/\\` resolved against a signed origin points somewhere
+            // else entirely while passing a `//` test.
+            if (!requestPath.startsWith("/") || requestPath.startsWith("//")) {
+                return errorResult(`path must be origin-relative and start with a single slash (got ${JSON.stringify(requestPath)}). The host is not yours to choose: it comes from the operator-signed listing.`);
+            }
+            if (hasForbiddenPathCharacter(requestPath)) {
+                return errorResult(`path must not contain a backslash or a control character (got ${JSON.stringify(requestPath)}). A backslash is a host separator to the URL parser, so it would redirect this call off the operator-signed origin.`);
+            }
+            const requestHeaders = normalizeHeaders(headers);
+            if (CAPABILITY_HEADER_NAME in requestHeaders) {
+                return errorResult(`do not set the ${CAPABILITY_HEADER_NAME} header: this server signs the capability itself, as the stream's buyer. Supplying one would be silently overwritten.`);
+            }
+            if (body !== undefined &&
+                requestHeaders["content-type"] === undefined) {
+                requestHeaders["content-type"] = "application/json";
+            }
+            try {
+                const result = await serviceInvoker.invokeService({
+                    streamId: streamId,
+                    method: method ?? "GET",
+                    path: requestPath,
+                    headers: requestHeaders,
+                    ...(body === undefined ? {} : { body }),
+                    ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+                });
+                return serializeInvocation(result);
+            }
+            catch (error) {
+                const explained = explainInvokeFailure(error, streamId);
+                return explained === null
+                    ? safeToolError(error)
+                    : errorResult(explained);
+            }
+        });
+    }
     mcpServer.registerTool("check_stream_status", {
         description: STATUS_TOOL_SPEC.description,
         inputSchema: getStreamStatusSchema,
@@ -382,7 +583,15 @@ export function createVerifiedStreamMcpServer(options) {
     }, async ({ streamId }) => {
         try {
             const status = await options.agentClient.getStreamStatus(streamId);
-            return successResult(`stream ${streamId} is ${status.stream.status}`, serializeStreamStatus(status, streamId));
+            if (status.stream.buyer === ZERO_ADDRESS) {
+                // An unset slot decodes as an all-zero struct rather than reverting,
+                // which otherwise surfaces as a confident "the stream is closed" for
+                // a stream that never existed. A real stream always has a buyer.
+                return errorResult(`no stream with id ${streamId} exists on the configured escrow. Check the id, and check that this server is pointed at the escrow the stream was opened on.`);
+            }
+            return successResult(status.stream.status === "active"
+                ? `stream ${streamId} is active and still metering at ${status.stream.ratePerSecond} USDC base units per verified second; reclaim_unspent closes it and stops the meter`
+                : `stream ${streamId} is ${status.stream.status}`, serializeStreamStatus(status, streamId));
         }
         catch (error) {
             return safeToolError(error);
@@ -400,10 +609,14 @@ export function createVerifiedStreamMcpServer(options) {
         },
     }, async ({ streamId, closeFirst }) => {
         try {
+            // The local registry is a CONVENIENCE, not an authority. It used to be
+            // required here, which meant a restarted server with in-memory state
+            // could no longer return the buyer's own money through this tool — a
+            // local bookkeeping gap standing between a buyer and their funds. The
+            // escrow itself enforces that only the buyer may close and reclaim, so
+            // proceeding without a record is safe and strictly buyer-favouring; an
+            // id that is not this wallet's stream simply reverts on chain.
             const record = await registry.get(streamId);
-            if (record === null) {
-                return errorResult(`unknown stream: ${streamId}`);
-            }
             const signedMandate = await resolveMandate();
             // Reclaim/close only RETURN unspent funds to the buyer or stop payment.
             // They are authorized on mandate-owner signature ALONE (see the SDK
@@ -416,9 +629,10 @@ export function createVerifiedStreamMcpServer(options) {
                 nowSeconds: now(),
                 ...(closeFirst === undefined ? {} : { closeFirst }),
             });
-            return successResult(`reclaimed stream ${streamId}`, {
+            return successResult(`reclaimed stream ${streamId}; the per-second meter on it has stopped${record === null ? " (this server had no local record of it — the escrow authorized the recovery on the buyer wallet alone)" : ""}`, {
                 closeTxHash: result.closeResult?.txHash ?? null,
                 reclaimTxHash: result.reclaimResult.txHash,
+                tracked: record !== null,
             });
         }
         catch (error) {
@@ -480,6 +694,34 @@ export function createVerifiedStreamMcpServer(options) {
                 if (record === null) {
                     return errorResult(`unknown stream: ${streamId}`);
                 }
+                // Bind the PROOF TARGET to the stream's verified listing.
+                //
+                // Without this the tool would zkTLS-prove any URL an LLM named and
+                // stamp it with this stream's delivery binding (owner, streamId,
+                // operator, serviceRef) — a proof of someone else's endpoint,
+                // labelled as this stream's delivery. The origin has to come from the
+                // operator's signed record for the same reason invoke_service's does.
+                const listings = await discover().catch((error) => {
+                    throw new ProveTargetError(error instanceof RegistryUnavailableError
+                        ? "the service registry is unreachable, so this stream's signed service origin could not be verified. No proof was attempted."
+                        : `the service registry could not be read: ${asErrorMessage(error)}`);
+                });
+                const listing = listings.find((entry) => entry.serviceRef.toLowerCase() ===
+                    record.serviceRef.toLowerCase());
+                if (listing === undefined) {
+                    return errorResult(`no verified listing matches this stream's serviceRef (${record.serviceRef}), so there is no signed origin to prove against. Run discover_services.`);
+                }
+                if (listing.access === "gated") {
+                    // Not a degradation we can paper over. The Reclaim attestor fetches
+                    // the URL itself, from its own network position, and cannot present
+                    // this stream's single-use caller-auth capability — so the only
+                    // thing it could prove about a gated origin is its own 403.
+                    return errorResult(`this stream's service is GATED behind caller-auth (${safeOrigin(listing.accessUrl)}), and a consumer zkTLS proof cannot authenticate to it: the Reclaim attestor fetches the URL itself and cannot carry this stream's single-use capability, so it would only ever prove a 403. Use invoke_service to call it — that delivery is covered by the oracle's own L1/L4 verification. prove_https_response works for PUBLIC listings only.`);
+                }
+                const signedOrigin = safeOrigin(listing.accessUrl);
+                if (safeOrigin(url) !== signedOrigin) {
+                    return errorResult(`refusing to prove ${safeOrigin(url)} for this stream: its operator signed ${signedOrigin}. A proof of an origin the stream did not pay for is not evidence of its delivery.`);
+                }
                 const result = await deliveryProofService.proveConsumedHttpsResponse({
                     url,
                     ...(method === undefined ? {} : { method }),
@@ -501,6 +743,9 @@ export function createVerifiedStreamMcpServer(options) {
                 return successResult(`generated zkTLS response proof for stream ${streamId}`, serializeConsumedResponseProof(record.streamId, result));
             }
             catch (error) {
+                if (error instanceof ProveTargetError) {
+                    return errorResult(error.message);
+                }
                 return safeToolError(error);
             }
         });
@@ -516,8 +761,27 @@ export function createVerifiedStreamMcpServer(options) {
         },
     };
 }
+/** One readable line per invalid or missing environment variable. */
+function describeEnvIssues(error) {
+    const seen = new Set();
+    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 = process.env) {
-    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");
@@ -525,9 +789,28 @@ export function parseMetrikAgentEnv(env = process.env) {
     if (chainId !== baseSepolia.id) {
         throw new Error(`unsupported METRIK_AGENT_CHAIN_ID ${chainId}; phase 2 is Base Sepolia only`);
     }
+    // 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,
+        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,
         chain: {
             ...baseSepolia,
@@ -566,11 +849,13 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         chain: parsed.chain,
         transport: http(parsed.rpcUrl),
         escrow: parsed.escrow,
-        // Declare the escrow as V2 as well. Without this the SDK treats the
-        // client as V1 and routes claimable()/reclaimable() to the legacy ABI,
-        // which reverts against StreamEscrowV2 — the checkpoint escrow replaced
-        // those one-argument views with proof-carrying ones.
-        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,
@@ -594,6 +879,29 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         }
         return cachedMandate;
     };
+    // The "use" half. `invoke()` needs a signer that can produce an EIP-712
+    // signature; every wallet this package resolves can, but only a raw key is a
+    // viem LocalAccount by type — hence the structural check rather than a cast.
+    const serviceInvoker = createServiceInvoker({
+        streamReader: createSdkInvokeStreamReader({
+            escrowAddress: parsed.escrow,
+            rpcUrl: parsed.rpcUrl,
+        }),
+        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,
@@ -601,9 +909,23 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(env = process.
         registry: 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) {
+    if (typeof account.signTypedData !== "function") {
+        throw new Error(`the configured wallet (${account.address}) cannot sign EIP-712 typed data, so it cannot authorize a service invocation. Use a wallet whose account exposes signTypedData (a raw key, a CDP server account, or a Privy embedded wallet).`);
+    }
+    return account;
+}
 export async function createVerifiedStreamMcpServerFromEnv(env = process.env) {
     return createVerifiedStreamMcpServer(await createVerifiedStreamMcpServerOptionsFromEnv(env));
 }
@@ -659,6 +981,11 @@ function serializeStreamStatus(status, streamId) {
         },
         claimable: status.claimable.toString(),
         reclaimable: status.reclaimable.toString(),
+        metering: {
+            model: "time-metered",
+            ratePerSecondUsdc: status.stream.ratePerSecond.toString(),
+            note: METERING_MODEL,
+        },
     };
 }
 function serializeConsumedResponseProof(streamId, proof) {
@@ -673,6 +1000,187 @@ function serializeConsumedResponseProof(streamId, proof) {
         verification: proof.verification,
     };
 }
+/**
+ * True when a path carries a character that must never appear in one.
+ *
+ * Mirrors `assertOriginRelativePath` in `../sdk/invoke.ts`. The backslash is the
+ * one that matters: the URL parser reads it as a host separator for http(s), so
+ * it turns an apparently origin-relative path into a different host. C0
+ * controls and DEL go with it — a header- or log-splitting character has no
+ * business in a path either.
+ */
+function hasForbiddenPathCharacter(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (character === "\\" || code < 0x20 || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Checks that `operator` — the wallet that gets paid — is the one the
+ * registry's operator-signed record for `serviceRef` names.
+ *
+ * This reports; it does not decide. Every outcome other than `verified` is
+ * treated as a refusal by the hire path (see ALLOW_UNVERIFIED_OPERATOR_ENV).
+ * An earlier version failed OPEN on anything but a positive contradiction,
+ * which meant that during any registry read failure the exact bug this check
+ * exists to stop was fully live: an attacker's `operator` paired with a genuine
+ * `serviceRef`, the oracle verifying the real endpoint, and accrual settling to
+ * the attacker. Settlement does not depend on this HTTP endpoint being
+ * reachable from the MCP host, so a read failure is no evidence of safety.
+ *
+ * A hostile registry cannot forge a match — the operator's signature over the
+ * record the serviceRef is derived from is recovered client-side — but it CAN
+ * suppress a row, which is exactly why `unlisted` must not be a soft verdict.
+ *
+ * An outage is reported distinctly from a malformed/failed read: "retry in a
+ * moment" and "something is wrong with this registry" are different next steps.
+ */
+async function checkOperatorPairing(discover, serviceRef, operator) {
+    let listings;
+    try {
+        listings = await discover();
+    }
+    catch (error) {
+        return error instanceof RegistryUnavailableError
+            ? { verdict: "registry-unavailable", detail: asErrorMessage(error) }
+            : { verdict: "registry-error", detail: asErrorMessage(error) };
+    }
+    const listing = listings.find((entry) => entry.serviceRef.toLowerCase() === serviceRef.toLowerCase());
+    if (listing === undefined) {
+        return { verdict: "unlisted" };
+    }
+    if (listing.operator.toLowerCase() !== operator.toLowerCase()) {
+        return { verdict: "mismatch", listedOperator: listing.operator };
+    }
+    return { verdict: "verified" };
+}
+/**
+ * Why a hire was refused, in words the caller can act on.
+ *
+ * Refusing strands nothing: no USDC has moved, and the same call succeeds once
+ * the registry answers again.
+ */
+function explainPairingRefusal(pairing, serviceRef, operator) {
+    switch (pairing.verdict) {
+        case "mismatch":
+            return `refusing to hire: serviceRef ${serviceRef} is listed under operator ${pairing.listedOperator}, not ${operator}. The operator address is the wallet that gets paid — escrowing to a different one would pay a stranger for someone else's service. Take the operator/serviceRef pair from discover_services.`;
+        case "unlisted":
+            return `refusing to hire: serviceRef ${serviceRef} is not in the verified registry, so there is no operator-signed record proving that ${operator} is the wallet this service pays. Run discover_services and hire a listed service. (A row that fails signature verification is dropped, so a revoked or malformed listing looks the same as an absent one.)`;
+        case "registry-unavailable":
+            return `refusing to hire: the service registry is unreachable (${pairing.detail}), so this hire's operator/serviceRef pairing cannot be verified and the escrow could be paid to the wrong wallet. Nothing was spent — retry when the registry answers.`;
+        case "registry-error":
+            return `refusing to hire: the service registry could not be read (${pairing.detail}), so this hire's operator/serviceRef pairing cannot be verified and the escrow could be paid to the wrong wallet. Nothing was spent.`;
+    }
+}
+/** A prove-target precondition that failed with a caller-actionable reason. */
+class ProveTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProveTargetError";
+    }
+}
+/** Origin of a URL, or the raw value when it will not parse. */
+function safeOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
+function normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        normalized[name.toLowerCase()] = value;
+    }
+    return normalized;
+}
+/**
+ * Renders an invocation as an MCP result.
+ *
+ * A non-2xx answer is returned as `isError` WITH the full structured content:
+ * the call really happened and its body may be the thing the agent needs, but a
+ * buyer who paid and got a 403 should not have to infer that from a status
+ * field. Gateway denials carry their machine-readable reason, because
+ * `stream-expired` and `nonce-replayed` call for opposite responses.
+ */
+function serializeInvocation(result) {
+    const summary = `${result.method} ${result.path} -> ${result.status}`;
+    if (result.ok) {
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: { ...result },
+        };
+    }
+    const because = result.gatewayDenialReason === null
+        ? `the service itself answered ${result.status}; the capability was accepted`
+        : `the seller's caller-auth gateway REFUSED the call: ${result.gatewayDenialReason}${gatewayDenialHint(result.gatewayDenialReason)}`;
+    return {
+        content: [{ type: "text", text: `${summary} — ${because}` }],
+        structuredContent: { ...result },
+        isError: true,
+    };
+}
+/** One actionable next step per gateway denial reason. */
+function gatewayDenialHint(reason) {
+    switch (reason) {
+        case "stream-not-funded":
+            return " — the stream's remaining budget is exhausted; open a new one with hire_verified_service.";
+        case "stream-expired":
+            return " — the stream is past its expiry; reclaim_unspent returns the unspent budget.";
+        case "stream-not-active":
+            return " — the stream is closed; open a new one with hire_verified_service.";
+        case "capability-expired":
+            return " — the signed capability outlived its TTL before the gateway saw it; retry (optionally with a larger ttlSeconds).";
+        case "nonce-replayed":
+            return " — each capability is single-use; retry to mint a fresh one.";
+        case "stream-state-stale":
+            return " — the gateway's view of the chain is too stale to authorize; retry shortly.";
+        case "buyer-mismatch":
+            return " — the stream does not belong to this server's wallet.";
+        default:
+            return "";
+    }
+}
+/**
+ * Turns an invocation failure into something an LLM can act on, or `null` when
+ * it is not a failure this layer understands (those fall through to the generic
+ * handler, which logs the detail server-side and says nothing more).
+ *
+ * The generic "the tool call failed" is correct for an unexpected RPC/viem
+ * error — it can carry internal detail — but it is useless for the three things
+ * that actually go wrong here: wrong wallet, dead stream, unlisted service.
+ */
+function explainInvokeFailure(error, streamId) {
+    if (error instanceof InvokeBuyerMismatchError) {
+        return `stream ${streamId} does not belong to this server's wallet, so this server cannot sign a capability for it. Only the stream's buyer can invoke it — use a stream from hire_verified_service or list_streams.`;
+    }
+    if (error instanceof InvokeStreamNotActiveError) {
+        return `stream ${streamId} is closed, so it authorizes nothing. Open a new one with hire_verified_service.`;
+    }
+    if (error instanceof InvokeStreamExpiredError) {
+        return `stream ${streamId} has expired, so it authorizes nothing. reclaim_unspent returns the unspent budget; hire_verified_service opens a replacement.`;
+    }
+    if (error instanceof ServiceListingNotFoundError) {
+        return `no verified listing matches this stream's serviceRef (${error.serviceRef}). Run discover_services: a listing whose operator signature fails verification is dropped, so an unlisted or revoked service cannot be invoked.`;
+    }
+    if (error instanceof InvokeServiceRefMismatchError) {
+        return `the registry's listing does not match this stream's serviceRef. The call was refused rather than sent to an origin this stream did not pay for.`;
+    }
+    if (error instanceof InvokeAccessUrlError) {
+        return `this stream's listing carries no usable signed invocation origin (${error.message}). This server refuses to call an origin the operator did not sign.`;
+    }
+    if (error instanceof InvokePathError) {
+        return `invalid request path: ${error.message}`;
+    }
+    if (error instanceof RegistryUnavailableError) {
+        return `the service registry is unreachable, so the operator-signed origin for this stream could not be verified. The call was not attempted — an unverified origin is never guessed. Retry when the registry is back.`;
+    }
+    return null;
+}
 function successResult(text, structuredContent) {
     return {
         content: [{ type: "text", text }],