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

package/README.md

@@ -12,9 +12,9 @@ It builds on [`@absol-labs/sdk`](https://github.com/Absol-Labs/metrik-sdk), whic
 to the on-chain metered escrow. This layer wraps that client in the guardrails and
 integration surfaces an agent actually needs: owner-signed spend mandates that gate every
 fund move, a Metrik-native `402` challenge flow that turns a payment challenge into a verified
-stream, **a spec-compliant x402 facilitator that refuses to settle payment for a service its
-own oracle says is not delivering** (read [`docs/x402.md`](./docs/x402.md) — the two `402`
-flows are different and only one of them is x402), an MCP server that exposes
+stream (not the x402 protocol), an opt-in x402 v2 facilitator and gateway mode that settle
+standard x402 `exact` payments through the on-chain stream opener (off by default — see
+[`docs/x402.md`](./docs/x402.md)), an MCP server that exposes
 hire/monitor/reclaim as agent tools,
 adapters for the major agent frameworks,
 Reclaim consumer zkTLS for buyer-side delivery proofs, and non-custodial Coinbase CDP/Privy
@@ -38,7 +38,9 @@ npx --package @absol-labs/agent metrik discover
 `metrik` is the CLI below; `metrik-mcp` starts the MCP server over stdio
 (`metrik mcp --print-config` prints the client config that runs it);
 `metrik-mcp-http` starts the hosted multi-tenant MCP transport; `metrik-gateway`
-starts the reference caller-auth gateway a seller puts in front of their service.
+starts the reference caller-auth gateway a seller puts in front of their service;
+`metrik-x402-opener-facilitator` starts the x402 v2 opener facilitator (off unless
+enabled; see [`docs/x402.md`](./docs/x402.md)).
 
 The package is **ESM-only** (`"type": "module"`) and targets **Node `>=20.19 <25`** (verified on 20.19, 22 LTS and 24). It ships
 `@absol-labs/sdk`, `@absol-labs/shared`, `viem`, `zod`, the Reclaim zkTLS SDKs, the
@@ -66,36 +68,14 @@ stream is opened through the SDK.
 > string (`streamproof-verified-stream`), its own challenge and payload shapes, and its
 > own `X-METRIK-PAYMENT` header. It does **not** speak the x402 wire format and will
 > **not** interoperate with `x402-fetch`, `x402-axios`, `x402-express`, or any standard
-> x402 client or facilitator. For that, see the separate facilitator below.
-
-**The x402 verified-delivery facilitator** (`metrik-x402-facilitator`) is the other,
-genuinely-x402 half. It implements the standard facilitator interface — `POST /verify`,
-`POST /settle`, `GET /supported` — for the standard `exact` scheme, and then asks one
-question no other facilitator can: **is this service currently passing Metrik's delivery
-checks?** If the oracle says it is failing, `/verify` answers `isValid: false` and `/settle`
-broadcasts nothing. Standard headers, standard schemes, `x402-fetch` works untouched, no
-contract change.
-
-The seller-side gateway has a matching opt-in mode: a request with no Metrik capability gets
-a real x402 `402` carrying `PaymentRequirements` whose `payTo` is derived from the
-operator-signed listing, so an agent holding only `x402-fetch` can pay per call.
-
-`POST /settle` makes the operator's relayer sign and pay gas, so it is fenced: an **asset
-allowlist** (default the chain's USDC) so the relayer can never be induced to call a
-caller-chosen contract, a **bearer token** (`METRIK_X402_FACILITATOR_TOKEN`, required at
-startup), a **settlement scope** limiting gas spend to resources Metrik tracks, and
-network/non-zero-amount checks. `/verify` and `/supported` stay public.
-
-> This is **weaker buyer protection than a stream, and deliberately so.** An `exact`
-> payment holds nothing in escrow: the gate can PREVENT a payment to a failing service, it
-> can **never** recover one that already went through. Only the stream path makes unearned
-> money recoverable. [`docs/x402.md`](./docs/x402.md) has the full account, the
-> 90-second freshness window and the reasoning behind it, and what is still unproven.
+> x402 client or facilitator.
 >
-> **Settlement has never broadcast a transaction from this repo.** `/settle` is implemented
-> end to end and delegates to the real `x402` `settle()`, but running it needs a relayer
-> wallet funded with gas that does not exist yet. The server refuses to start without a
-> relayer key unless `METRIK_X402_ALLOW_VERIFY_ONLY=true` is set explicitly.
+> Standard x402 is supported separately, as **x402 v2 `exact` through the stream
+> opener**: `metrik-x402-opener-facilitator` and the gateway's opt-in
+> `METRIK_GATEWAY_X402V2_OPENER` mode, both off by default. The opener `payTo` must only
+> ever be settled by that facilitator — a stock x402 facilitator would strand the payment.
+> Read [`docs/x402.md`](./docs/x402.md) before enabling either. The older x402 v1
+> integration, which paid the seller directly, was removed.
 
 **The MCP server** exposes `discover_services`, `hire_verified_service`, `invoke_service`,
 `check_stream_status`, `reclaim_unspent`, `list_streams`, and — when Reclaim credentials are
@@ -276,10 +256,9 @@ const { streamId } = await facilitator.open(header); // mandate-gated, opens on-
 The scheme name is exported as `METRIK_STREAM_SCHEME`; `parseStreamChallengeJson`,
 `parseStreamPayloadHeader`, and `encodeStreamPayloadHeader` handle the wire format on both
 sides, and the payload travels under `METRIK_PAYMENT_HEADER` (`x-metrik-payment`) — never
-under x402's `X-PAYMENT` (the gateway's separate x402 mode uses that header, because there
-it really is x402; a request carrying both is refused with `400 ambiguous-payment-mode`).
-This wire format is Metrik's own; see [`docs/x402.md`](./docs/x402.md). The older `X402*`
-identifiers still work as deprecated aliases, but the names above are canonical.
+under x402's `X-PAYMENT`. This wire format is Metrik's own; see
+[`docs/x402.md`](./docs/x402.md). The deprecated `X402*` / `x402*` aliases of these names
+were removed; use the names above.
 
 ### The CLI
 
@@ -299,11 +278,23 @@ metrik reclaim <streamId>
 metrik claim   <streamId>                    # operator: redeem what verified
 metrik reclaim-unverified <streamId> --forfeit-unclaimed   # buyer escape hatch
 metrik mcp --print-config
+
+# the x402 opener path (docs/x402.md), under a spend mandate
+metrik pay    https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik refund <streamId> --refund-url <url> --close --reclaim   # gasless; NOT automatic
 ```
 
-- **Testnet only.** The CLI refuses any chain outside Base Sepolia (`84532`), and
-  re-reads the chain id the RPC endpoint actually serves before it signs anything.
-  There is no override flag.
+- **Testnet only, registry-driven.** Every chain fact (chain id, escrow, USDC,
+  RPC, oracle, gas token) comes from the `@absol-labs/sdk` network registry;
+  `--network` / `METRIK_NETWORK` selects one. The CLI refuses any network the
+  registry does not mark as a testnet (today: Base Sepolia, `84532`), and re-reads
+  the chain id the RPC endpoint actually serves before it signs anything. There is
+  no override flag.
+- **`metrik pay` is gated by a spend mandate** like `metrik open`: the payment's
+  opener terms (price vs per-stream/total caps, rate, window, operator) pass
+  `checkMandate()` before anything is signed, and the SDK's own x402 protections
+  stay on. It prints the response, the `streamId` and the refund URL. See
+  [`docs/cli.md`](./docs/cli.md#metrik-pay-x402).
 - **The meter runs on verified availability, not on your calls.** A stream is a
   per-second rental of an endpoint that keeps proving it is alive — not per-request
   billing. You are charged for the seconds that verified whether or not you invoked
@@ -397,15 +388,18 @@ import {
 
 console.log(METRIK_MCP_TOOLS.map((t) => t.name));
 // discover_services, hire_verified_service, invoke_service, check_stream_status,
-// reclaim_unspent, list_streams, prove_https_response
+// reclaim_unspent, list_streams, prove_https_response,
+// x402_pay,
+// refund_status, refund
 
 await startVerifiedStreamMcpServerStdio(); // reads process.env, connects stdio
 // or, for custom transport wiring:
 // const runtime = await createVerifiedStreamMcpServerFromEnv();
 ```
 
-Core env surface: `METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW`, `METRIK_AGENT_USDC`,
-`METRIK_AGENT_CHAIN_ID` (`84532`), and one wallet source — either
+Core env surface: `METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW` (must be the network's
+registered escrow), `METRIK_AGENT_USDC`, `METRIK_NETWORK` / `METRIK_AGENT_CHAIN_ID`
+(default: the registry's default network), and one wallet source — either
 `METRIK_AGENT_PRIVATE_KEY` (injected signer) or the CDP set (`CDP_API_KEY_ID`,
 `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`, `METRIK_AGENT_CDP_OWNER_NAME`). Set
 `RECLAIM_APP_ID` / `RECLAIM_APP_SECRET` to enable the `prove_https_response` zkTLS tool.
@@ -599,12 +593,9 @@ pnpm test
 pnpm build
 ```
 
-The Metrik `402` challenge flow, the x402 verified-delivery facilitator, zkTLS proof path,
-signed-mandate engine, MCP server, and framework adapters are all real and tested in-repo.
-The x402 suite drives the published `x402-fetch` client through a full 402 -> pay -> retry
-cycle against the gateway and asserts the same valid payment is refused when the oracle
-reports the service as failing; only the payer's on-chain balance and the broadcast are
-fixtures, and nothing is ever broadcast. The `*.int.test.ts` integration suites deploy the
+The Metrik `402` challenge flow, zkTLS proof path, signed-mandate engine, MCP server,
+caller-auth gateway, and framework adapters are all real and tested in-repo. The
+`*.int.test.ts` integration suites deploy the
 hardened `StreamEscrow` on a throwaway `anvil` node and self-skip when `anvil` is not on
 `PATH`, so default CI stays green. A full hire → stream → settle walkthrough lives in
 [`examples/hire-stream-settle.ts`](examples/hire-stream-settle.ts).
@@ -615,4 +606,5 @@ hardened `StreamEscrow` on a throwaway `anvil` node and self-skip when `anvil` i
 - Docs: [metrik.live](https://metrik.live) · App: [app.metrik.live](https://app.metrik.live)
 - SDK: [`@absol-labs/sdk`](https://github.com/Absol-Labs/metrik-sdk)
 - Quickstart: [`docs/quickstart.md`](./docs/quickstart.md) · Design + narrative: [`docs/agent-layer.md`](./docs/agent-layer.md) · Security review: [`docs/threat-model.md`](./docs/threat-model.md)
-- Metrik and x402 — the facilitator, the delivery gate, and what is still unproven: [`docs/x402.md`](./docs/x402.md)
+- Metrik and x402 — the x402 v2 opener facilitator and gateway mode, the rule that only the opener facilitator may settle an opener `payTo`, and what was removed: [`docs/x402.md`](./docs/x402.md)
+- Letting the verifier check a **gated** listing's paid route (opt-in, seller-side): [`docs/probe-capability.md`](./docs/probe-capability.md)

package/dist/capability/invocation-capability.d.ts

@@ -54,8 +54,8 @@ export declare const signedInvocationCapabilitySchema: z.ZodObject<{
 } & {
     signature: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    signature: string;
     streamId: string;
+    signature: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     serviceRef: string;
     nonce: string;
@@ -63,8 +63,8 @@ export declare const signedInvocationCapabilitySchema: z.ZodObject<{
     pathHash: string;
     expiry: number;
 }, {
-    signature: string;
     streamId: string;
+    signature: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     serviceRef: string;
     nonce: string;

package/dist/capability/probe-capability.d.ts

@@ -0,0 +1,225 @@
+import { type Address, type Hex, type LocalAccount } from "viem";
+import { z } from "zod";
+export declare const probeCapabilitySchema: z.ZodObject<{
+    /**
+     * The service being probed. Must match the target gateway's configured
+     * `serviceRef`. There is deliberately no `streamId` field — see the class
+     * docs.
+     */
+    serviceRef: z.ZodEffects<z.ZodString, string, string>;
+    /**
+     * The minting oracle signer. Must equal the EIP-712 signer AND be a member of
+     * the escrow's on-chain `getOracleSigners()` set at verification time.
+     */
+    oracle: z.ZodEffects<z.ZodString, `0x${string}`, string>;
+    /** The single HTTP method this capability authorizes. */
+    method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: z.ZodEffects<z.ZodString, string, string>;
+    /** Single-use anti-replay nonce. */
+    nonce: z.ZodEffects<z.ZodString, string, string>;
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    serviceRef: string;
+    nonce: string;
+    pathHash: string;
+    expiry: number;
+    oracle: `0x${string}`;
+}, {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    serviceRef: string;
+    nonce: string;
+    pathHash: string;
+    expiry: number;
+    oracle: string;
+}>;
+export type ProbeCapability = z.infer<typeof probeCapabilitySchema>;
+export declare const signedProbeCapabilitySchema: z.ZodObject<{
+    /**
+     * The service being probed. Must match the target gateway's configured
+     * `serviceRef`. There is deliberately no `streamId` field — see the class
+     * docs.
+     */
+    serviceRef: z.ZodEffects<z.ZodString, string, string>;
+    /**
+     * The minting oracle signer. Must equal the EIP-712 signer AND be a member of
+     * the escrow's on-chain `getOracleSigners()` set at verification time.
+     */
+    oracle: z.ZodEffects<z.ZodString, `0x${string}`, string>;
+    /** The single HTTP method this capability authorizes. */
+    method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: z.ZodEffects<z.ZodString, string, string>;
+    /** Single-use anti-replay nonce. */
+    nonce: z.ZodEffects<z.ZodString, string, string>;
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.ZodNumber;
+} & {
+    signature: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    serviceRef: string;
+    nonce: string;
+    pathHash: string;
+    expiry: number;
+    oracle: `0x${string}`;
+}, {
+    signature: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    serviceRef: string;
+    nonce: string;
+    pathHash: string;
+    expiry: number;
+    oracle: string;
+}>;
+export type SignedProbeCapability = z.infer<typeof signedProbeCapabilitySchema>;
+/**
+ * Chain-bound domain. `verifyingContract` is the `StreamEscrowV2` whose
+ * `getOracleSigners()` defines who may mint — so a capability minted for one
+ * escrow can never authorize a probe against a gateway fronting another.
+ */
+export interface ProbeCapabilityDomainInput {
+    readonly chainId: number;
+    readonly verifyingContract: Address;
+}
+/**
+ * Distinct from `Metrik Invocation Capability`, so a buyer's invocation
+ * signature can never be replayed as a probe (or the reverse) even though both
+ * share a chainId and verifying contract.
+ */
+export declare const probeCapabilityDomainName: "Metrik Probe Capability";
+export declare const probeCapabilityDomainVersion: "1";
+export declare const probeCapabilityTypedData: {
+    readonly ProbeCapability: readonly [{
+        readonly name: "serviceRef";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "oracle";
+        readonly type: "address";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+    }, {
+        readonly name: "pathHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }];
+};
+/**
+ * Default lifetime of a freshly-minted probe capability, in seconds.
+ *
+ * Shorter than the ~15-22s checkpoint cadence would race a slow upstream; much
+ * longer would widen the window in which a captured capability is replayable
+ * against a gateway with no nonce cache. 30s is one to two probe intervals.
+ */
+export declare const DEFAULT_PROBE_CAPABILITY_TTL_SECONDS = 30;
+/** Header a probe request carries the signed capability in. */
+export declare const PROBE_CAPABILITY_HEADER_NAME = "x-metrik-probe-capability";
+/**
+ * Header the gateway adds to the UPSTREAM request when it authorized a probe.
+ * Advisory: it exists so a seller's own metering/analytics can exclude
+ * verification traffic from billable usage.
+ */
+export declare const PROBE_MARKER_HEADER_NAME = "x-metrik-probe";
+export declare function createProbeCapabilityEip712Domain(domain: ProbeCapabilityDomainInput): {
+    readonly name: "Metrik Probe Capability";
+    readonly version: "1";
+    readonly chainId: number;
+    readonly verifyingContract: `0x${string}`;
+};
+/**
+ * `keccak256` of the exact request path this capability authorizes. Shares the
+ * canonical form with `InvocationCapability` so both sides of a gateway hash
+ * paths identically.
+ */
+export declare function hashProbePath(path: string): Hex;
+/** Re-exported for symmetry; identical canonicalization to the invocation path. */
+export declare function normalizeProbePath(path: string): string;
+export declare function buildProbeCapabilityTypedData(capability: ProbeCapability, domain: ProbeCapabilityDomainInput): {
+    domain: {
+        readonly name: "Metrik Probe Capability";
+        readonly version: "1";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly ProbeCapability: readonly [{
+            readonly name: "serviceRef";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "oracle";
+            readonly type: "address";
+        }, {
+            readonly name: "method";
+            readonly type: "string";
+        }, {
+            readonly name: "pathHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "ProbeCapability";
+    message: {
+        serviceRef: Hex;
+        oracle: `0x${string}`;
+        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+        pathHash: Hex;
+        nonce: Hex;
+        expiry: bigint;
+    };
+};
+/** The minimum an oracle signer must expose to mint a probe capability. */
+export type ProbeCapabilitySigner = Pick<LocalAccount, "address" | "signTypedData">;
+/** Signs a `ProbeCapability` with an oracle signer's own key. */
+export declare function signProbeCapability(capability: ProbeCapability, domain: ProbeCapabilityDomainInput, account: ProbeCapabilitySigner): Promise<Hex>;
+/** Recovers the EIP-712 signer of a probe capability. Throws on a malformed signature. */
+export declare function recoverProbeCapabilitySigner(capability: ProbeCapability, domain: ProbeCapabilityDomainInput, signature: Hex): Promise<Address>;
+/** Cryptographically random 32-byte single-use nonce. */
+export declare function generateProbeNonce(): Hex;
+export declare class InvalidProbeCapabilityHeaderError extends Error {
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Encodes a signed probe capability as an opaque, header-safe (base64url) string. */
+export declare function encodeProbeCapabilityHeader(signed: SignedProbeCapability): string;
+/** Decodes and schema-validates a probe capability header. Fails closed on any malformation. */
+export declare function decodeProbeCapabilityHeader(headerValue: string): SignedProbeCapability;
+export interface MintProbeCapabilityOptions {
+    readonly serviceRef: Hex;
+    readonly method: ProbeCapability["method"];
+    /** The exact request path to be probed (query/fragment are stripped). */
+    readonly path: string;
+    readonly domain: ProbeCapabilityDomainInput;
+    readonly account: ProbeCapabilitySigner;
+    readonly ttlSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. */
+    readonly now?: () => number;
+    /** Injectable nonce source, for tests. */
+    readonly nonce?: () => Hex;
+}
+/**
+ * Mint one fresh, single-use, short-lived probe capability and return its
+ * encoded header value. Called once PER PROBE PER VANTAGE by the coordinator:
+ * the gateway's replay cache is single-use, so two vantages sharing one
+ * capability would see the second rejected as a replay.
+ */
+export declare function mintProbeCapabilityHeader(options: MintProbeCapabilityOptions): Promise<{
+    readonly headerName: string;
+    readonly headerValue: string;
+    readonly capability: SignedProbeCapability;
+}>;
+//# sourceMappingURL=probe-capability.d.ts.map

package/dist/capability/probe-capability.d.ts.map

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

package/dist/capability/probe-capability.js

@@ -0,0 +1,248 @@
+import { randomBytes } from "node:crypto";
+import { getAddress, isAddress, isHex, recoverTypedDataAddress, } from "viem";
+import { z } from "zod";
+import { hashInvocationPath, httpMethodSchema, normalizeInvocationPath, } from "./invocation-capability.js";
+/**
+ * `ProbeCapability` — the ORACLE-signed EIP-712 credential that lets the
+ * neutral verifier exercise the PAID route of a `gated` listing.
+ *
+ * ## The gap this closes
+ *
+ * A gated listing's paid route requires an `InvocationCapability` signed by the
+ * stream's BUYER (see `./invocation-capability.ts`). The oracle is not a buyer
+ * and holds no buyer key, so before this type existed the oracle could only
+ * probe a gated service's HEALTH route. "The seller earns only for intervals
+ * that verified" therefore meant "the health endpoint answered" — not "the paid
+ * route delivered". This capability is the missing credential.
+ *
+ * ## Why this is not just "give the workers a credential"
+ *
+ * Three properties, all load-bearing:
+ *
+ * 1. **No shared secret.** Authority is an EIP-712 signature by an address in
+ *    the escrow's `getOracleSigners()`. That list is PUBLICLY READABLE on-chain,
+ *    so a third-party seller performs the identical check with no credential
+ *    distribution, no registration, and nothing for either side to leak.
+ * 2. **No signing key leaves the coordinator.** The oracle coordinator mints one
+ *    fresh capability per probe and hands the encoded header to the regional
+ *    worker. A worker holds a bearer token for the coordinator and nothing else;
+ *    compromising every worker yields no ability to mint a capability.
+ * 3. **Not stream-bound.** Deliberately carries NO `streamId` and NO `buyer`.
+ *    That is what makes the same mechanism usable to probe a listing that has no
+ *    stream at all — and it is also the structural guarantee that a probe can
+ *    never consume a buyer's budget: there is no stream for it to be billed
+ *    against. Accrual is only ever produced by an oracle checkpoint keyed to a
+ *    stream; a gateway call produces none.
+ *
+ * ## What a probe is NOT
+ *
+ * A probe is verification, not delivery to a buyer. A gateway authorizing one
+ * MUST NOT meter it, settle any payment for it, or count it as a paid call.
+ * The reference gateway enforces this structurally (see
+ * `../gateway/caller-auth-gateway.ts`) and marks the upstream request with
+ * {@link PROBE_MARKER_HEADER_NAME} so a seller's own metering can exclude it.
+ *
+ * ## Honest note for third-party sellers
+ *
+ * This CHANGES what a seller's gateway must implement to get paid-route
+ * verification. A gated listing fronted by a gateway that has not adopted
+ * `ProbeCapability` stays HEALTH-ROUTE-ONLY, and the oracle reports it as
+ * unverifiable rather than passing. Adoption is the seller's choice; silence
+ * about it is not the oracle's.
+ *
+ * Kept LOCAL to `@absol-labs/agent` for the same reason as
+ * `InvocationCapability`: no contract parses it, so there is no on-chain byte
+ * compatibility requirement. Cross-repo compatibility with the oracle's minter
+ * is pinned by a shared digest test vector — see
+ * `test/probe-capability.test.ts` and the oracle's mirror of the same constant.
+ */
+const addressSchema = z
+    .string()
+    .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+    .string()
+    .refine((value) => isHex(value, { strict: true }) && value.length === 66, "must be bytes32 hex");
+const signatureSchema = z
+    .string()
+    .refine((value) => isHex(value, { strict: true }) && value.length === 132, "must be a 65-byte signature");
+export const probeCapabilitySchema = z.object({
+    /**
+     * The service being probed. Must match the target gateway's configured
+     * `serviceRef`. There is deliberately no `streamId` field — see the class
+     * docs.
+     */
+    serviceRef: bytes32Schema,
+    /**
+     * The minting oracle signer. Must equal the EIP-712 signer AND be a member of
+     * the escrow's on-chain `getOracleSigners()` set at verification time.
+     */
+    oracle: addressSchema,
+    /** The single HTTP method this capability authorizes. */
+    method: httpMethodSchema,
+    /** `keccak256` of the exact request path this capability authorizes. */
+    pathHash: bytes32Schema,
+    /** Single-use anti-replay nonce. */
+    nonce: bytes32Schema,
+    /** Unix seconds after which the capability is no longer valid. */
+    expiry: z.number().int().positive(),
+});
+export const signedProbeCapabilitySchema = probeCapabilitySchema.extend({
+    signature: signatureSchema,
+});
+/**
+ * Distinct from `Metrik Invocation Capability`, so a buyer's invocation
+ * signature can never be replayed as a probe (or the reverse) even though both
+ * share a chainId and verifying contract.
+ */
+export const probeCapabilityDomainName = "Metrik Probe Capability";
+export const probeCapabilityDomainVersion = "1";
+export const probeCapabilityTypedData = {
+    ProbeCapability: [
+        { name: "serviceRef", type: "bytes32" },
+        { name: "oracle", type: "address" },
+        { name: "method", type: "string" },
+        { name: "pathHash", type: "bytes32" },
+        { name: "nonce", type: "bytes32" },
+        { name: "expiry", type: "uint64" },
+    ],
+};
+/**
+ * Default lifetime of a freshly-minted probe capability, in seconds.
+ *
+ * Shorter than the ~15-22s checkpoint cadence would race a slow upstream; much
+ * longer would widen the window in which a captured capability is replayable
+ * against a gateway with no nonce cache. 30s is one to two probe intervals.
+ */
+export const DEFAULT_PROBE_CAPABILITY_TTL_SECONDS = 30;
+/** Header a probe request carries the signed capability in. */
+export const PROBE_CAPABILITY_HEADER_NAME = "x-metrik-probe-capability";
+/**
+ * Header the gateway adds to the UPSTREAM request when it authorized a probe.
+ * Advisory: it exists so a seller's own metering/analytics can exclude
+ * verification traffic from billable usage.
+ */
+export const PROBE_MARKER_HEADER_NAME = "x-metrik-probe";
+export function createProbeCapabilityEip712Domain(domain) {
+    return {
+        name: probeCapabilityDomainName,
+        version: probeCapabilityDomainVersion,
+        chainId: domain.chainId,
+        verifyingContract: getAddress(domain.verifyingContract),
+    };
+}
+/**
+ * `keccak256` of the exact request path this capability authorizes. Shares the
+ * canonical form with `InvocationCapability` so both sides of a gateway hash
+ * paths identically.
+ */
+export function hashProbePath(path) {
+    return hashInvocationPath(path);
+}
+/** Re-exported for symmetry; identical canonicalization to the invocation path. */
+export function normalizeProbePath(path) {
+    return normalizeInvocationPath(path);
+}
+function probeCapabilityMessage(capability) {
+    const parsed = probeCapabilitySchema.parse(capability);
+    return {
+        serviceRef: parsed.serviceRef,
+        oracle: getAddress(parsed.oracle),
+        method: parsed.method,
+        pathHash: parsed.pathHash,
+        nonce: parsed.nonce,
+        expiry: BigInt(parsed.expiry),
+    };
+}
+export function buildProbeCapabilityTypedData(capability, domain) {
+    return {
+        domain: createProbeCapabilityEip712Domain(domain),
+        types: probeCapabilityTypedData,
+        primaryType: "ProbeCapability",
+        message: probeCapabilityMessage(capability),
+    };
+}
+/** Signs a `ProbeCapability` with an oracle signer's own key. */
+export async function signProbeCapability(capability, domain, account) {
+    const typedData = buildProbeCapabilityTypedData(capability, domain);
+    return account.signTypedData(typedData);
+}
+/** Recovers the EIP-712 signer of a probe capability. Throws on a malformed signature. */
+export async function recoverProbeCapabilitySigner(capability, domain, signature) {
+    const typedData = buildProbeCapabilityTypedData(capability, domain);
+    return recoverTypedDataAddress({ ...typedData, signature });
+}
+/** Cryptographically random 32-byte single-use nonce. */
+export function generateProbeNonce() {
+    return `0x${randomBytes(32).toString("hex")}`;
+}
+export class InvalidProbeCapabilityHeaderError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "InvalidProbeCapabilityHeaderError";
+    }
+}
+/** Encodes a signed probe capability as an opaque, header-safe (base64url) string. */
+export function encodeProbeCapabilityHeader(signed) {
+    const parsed = signedProbeCapabilitySchema.parse(signed);
+    const json = JSON.stringify({
+        serviceRef: parsed.serviceRef,
+        oracle: parsed.oracle,
+        method: parsed.method,
+        pathHash: parsed.pathHash,
+        nonce: parsed.nonce,
+        expiry: parsed.expiry,
+        signature: parsed.signature,
+    });
+    return Buffer.from(json, "utf8").toString("base64url");
+}
+/** Decodes and schema-validates a probe capability header. Fails closed on any malformation. */
+export function decodeProbeCapabilityHeader(headerValue) {
+    let json;
+    try {
+        json = Buffer.from(headerValue, "base64url").toString("utf8");
+    }
+    catch (cause) {
+        throw new InvalidProbeCapabilityHeaderError("malformed base64 probe capability header", { cause });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (cause) {
+        throw new InvalidProbeCapabilityHeaderError("malformed JSON probe capability header", { cause });
+    }
+    const result = signedProbeCapabilitySchema.safeParse(raw);
+    if (!result.success) {
+        throw new InvalidProbeCapabilityHeaderError(`invalid probe capability shape: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Mint one fresh, single-use, short-lived probe capability and return its
+ * encoded header value. Called once PER PROBE PER VANTAGE by the coordinator:
+ * the gateway's replay cache is single-use, so two vantages sharing one
+ * capability would see the second rejected as a replay.
+ */
+export async function mintProbeCapabilityHeader(options) {
+    const nowSeconds = (options.now ?? (() => Math.floor(Date.now() / 1000)))();
+    const ttl = options.ttlSeconds ?? DEFAULT_PROBE_CAPABILITY_TTL_SECONDS;
+    if (!Number.isInteger(ttl) || ttl <= 0) {
+        throw new Error("probe capability ttlSeconds must be a positive integer");
+    }
+    const capability = {
+        serviceRef: options.serviceRef,
+        oracle: getAddress(options.account.address),
+        method: options.method,
+        pathHash: hashProbePath(options.path),
+        nonce: (options.nonce ?? generateProbeNonce)(),
+        expiry: nowSeconds + ttl,
+    };
+    const signature = await signProbeCapability(capability, options.domain, options.account);
+    const signed = { ...capability, signature };
+    return {
+        headerName: PROBE_CAPABILITY_HEADER_NAME,
+        headerValue: encodeProbeCapabilityHeader(signed),
+        capability: signed,
+    };
+}
+//# sourceMappingURL=probe-capability.js.map