@absol-labs/agent 0.3.2 → 0.5.0

package/dist/zktls/t2-delivery-proof.js

@@ -0,0 +1,336 @@
+import { canonicalJson, deliveryReceiptSchema, signDeliveryReceipt, } from "@absol-labs/shared";
+import { getHttpProviderClaimParamsFromProof, getProviderHashRequirementsFromSpec, verifyProof, } from "@reclaimprotocol/js-sdk";
+import { keccak256, stringToBytes, } from "viem";
+import { z } from "zod";
+import { asErrorMessage, buildDeliveryContextEnvelopeV2, defaultReclaimClientFactory, deliveryContextEnvelopeV2Schema, parseReclaimProofEnv, ResponseProofUnavailableError, ResponseProofVerificationError, toRequestSpec, } from "./reclaim.js";
+/**
+ * T2 consumer zkTLS delivery envelope (issue #24, metrik-protocol#67 DECISION).
+ *
+ * This is the BUYER-side counterpart to `streamproof-oracle`'s T2 accrue-on-proof
+ * ingest (`src/delivery/proof-ingest.ts`). Given the stream identity, an
+ * oracle-issued nonce (`GET /delivery/nonce`), and the paid-route request spec,
+ * it: (1) proves the paid route via a pluggable zkTLS attestor with the nonce
+ * bound into the request and the Metrik v2 envelope bound into
+ * `claimData.context`; (2) signs a `DeliveryReceipt` (`@absol-labs/shared`)
+ * committing to that proof; and (3) returns the exact `POST /delivery/proof`
+ * request body the oracle's `deliveryProofRequestSchema` expects.
+ *
+ * The attestor is pluggable (`DeliveryProofAttestor`) specifically so this can
+ * be tested WITHOUT a live Reclaim App Secret (agent#22 is the human-intervention
+ * issue for that credential) - the default production attestor
+ * (`createReclaimT2AttestorFromEnv`) still requires it.
+ */
+const bytes32Hex = /^0x[0-9a-fA-F]{64}$/;
+const evmAddress = /^0x[0-9a-fA-F]{40}$/;
+const hexSignature = /^0x[0-9a-fA-F]+$/;
+export class PaidRouteNonceInjectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaidRouteNonceInjectionError";
+    }
+}
+/** Injects the oracle-issued nonce into the paid-route request (query or body only). */
+function injectNonce(spec, nonce) {
+    if (spec.nonceInjection.in === "query") {
+        let url;
+        try {
+            url = new URL(spec.url);
+        }
+        catch (cause) {
+            throw new PaidRouteNonceInjectionError(`paid route url is not a valid absolute URL: ${asErrorMessage(cause)}`);
+        }
+        url.searchParams.set(spec.nonceInjection.name, nonce);
+        return { url: url.toString(), body: spec.body };
+    }
+    const placeholder = spec.nonceInjection.placeholder;
+    const body = spec.body ?? "";
+    if (!body.includes(placeholder)) {
+        throw new PaidRouteNonceInjectionError(`paid route body does not contain the nonce placeholder "${placeholder}"`);
+    }
+    return { url: spec.url, body: body.split(placeholder).join(nonce) };
+}
+const reclaimT2UrlSchema = z.string().url();
+/**
+ * Production `DeliveryProofAttestor`: drives the real Reclaim zkFetch + proof
+ * verification pipeline (mirrors `ReclaimConsumerProofService` in `reclaim.ts`,
+ * but binds the FLAT T2 v2 envelope directly as `context` instead of the v1
+ * `{contextAddress, contextMessage}` wrapper).
+ */
+export class ReclaimDeliveryProofAttestor {
+    client;
+    config;
+    verifyProofImpl;
+    constructor(config, options = {}) {
+        this.config = {
+            ...config,
+            logs: config.logs ?? false,
+        };
+        this.client = (options.createClient ?? defaultReclaimClientFactory)(this.config.applicationId, this.config.applicationSecret, this.config.logs ?? false);
+        this.verifyProofImpl = options.verifyProof ?? verifyProof;
+    }
+    async proveDeliveryResponse(input) {
+        reclaimT2UrlSchema.parse(input.url);
+        if (input.responseMatches.length === 0) {
+            throw new Error("at least one response match is required");
+        }
+        const context = deliveryContextEnvelopeV2Schema.parse(input.context);
+        const parsed = { ...input, context };
+        const method = parsed.method ?? "GET";
+        const proof = await this.client
+            .zkFetch(parsed.url, {
+            method,
+            ...(parsed.body === undefined ? {} : { body: parsed.body }),
+            ...(parsed.headers === undefined ? {} : { headers: parsed.headers }),
+            ...(parsed.geoLocation === undefined
+                ? {}
+                : { geoLocation: parsed.geoLocation }),
+            context: parsed.context,
+            ...(parsed.useTee === undefined ? {} : { useTee: parsed.useTee }),
+            ...(parsed.zkEngine === undefined
+                ? {}
+                : { zkEngine: parsed.zkEngine }),
+        }, {
+            ...(parsed.secretHeaders === undefined
+                ? {}
+                : { headers: parsed.secretHeaders }),
+            responseMatches: parsed.responseMatches,
+            ...(parsed.responseRedactions === undefined
+                ? {}
+                : { responseRedactions: parsed.responseRedactions }),
+            ...(parsed.cookie === undefined ? {} : { cookieStr: parsed.cookie }),
+            ...(parsed.secretParamValues === undefined
+                ? {}
+                : { paramValues: parsed.secretParamValues }),
+        })
+            .catch((error) => {
+            throw new ResponseProofUnavailableError(`failed to generate T2 zkTLS delivery proof: ${asErrorMessage(error)}`);
+        });
+        if (proof === undefined) {
+            throw new ResponseProofUnavailableError("reclaim returned no zkTLS delivery proof");
+        }
+        const verification = await this.verifyProofImpl(proof, {
+            ...getProviderHashRequirementsFromSpec({
+                requests: [toRequestSpec(parsed, method)],
+            }),
+            ...(parsed.useTee === true
+                ? { teeAttestation: { appSecret: this.config.applicationSecret } }
+                : {}),
+        });
+        if (!verification.isVerified) {
+            throw new ResponseProofVerificationError(`T2 zkTLS delivery proof verification failed: ${asErrorMessage(verification.error)}`);
+        }
+        const trusted = verification.data[0];
+        if (trusted === undefined) {
+            throw new ResponseProofVerificationError("T2 zkTLS delivery proof verification returned no trusted data");
+        }
+        const request = getHttpProviderClaimParamsFromProof(proof);
+        return {
+            proof,
+            request: {
+                url: request.url,
+                method: request.method,
+                body: request.body === "" ? null : (request.body ?? null),
+                responseMatches: request.responseMatches.map((match) => ({
+                    value: match.value,
+                    type: match.type,
+                    invert: match.invert,
+                    isOptional: match.isOptional,
+                })),
+                responseRedactions: request.responseRedactions.map((redaction) => ({
+                    regex: redaction.regex,
+                    jsonPath: redaction.jsonPath,
+                    xPath: redaction.xPath,
+                    hash: redaction.hash,
+                })),
+            },
+            verification: {
+                context: trusted.context,
+                extractedParameters: trusted.extractedParameters,
+                publicData: verification.publicData[0] ?? null,
+                isTeeAttestationVerified: verification.isTeeAttestationVerified ?? false,
+                isAttestorTeeAttestationVerified: verification.isAttestorTeeAttestationVerified ?? false,
+            },
+        };
+    }
+}
+/** `null` when `RECLAIM_APP_ID`/`RECLAIM_APP_SECRET` are not configured (see agent#22). */
+export function createReclaimT2AttestorFromEnv(env = process.env) {
+    const parsed = parseReclaimProofEnv(env);
+    if (parsed === null)
+        return null;
+    return new ReclaimDeliveryProofAttestor(parsed);
+}
+const wireDeliveryReceiptSchema = z
+    .object({
+    streamId: z.union([
+        z.string().regex(bytes32Hex),
+        z.string().regex(/^\d+$/),
+    ]),
+    serviceRef: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex serviceRef"),
+    operator: z.string().regex(evmAddress, "must be an EVM address"),
+    intervalIndex: z
+        .string()
+        .regex(/^\d+$/, "must be a non-negative integer string"),
+    nonce: z.string().regex(bytes32Hex, "must be a 32-byte hex nonce"),
+    reclaimProofId: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+    reclaimOwner: z.string().regex(evmAddress, "must be an EVM address"),
+    reclaimTimestamp: z
+        .string()
+        .regex(/^\d+$/, "must be a non-negative integer string"),
+    reclaimEpoch: z
+        .string()
+        .regex(/^\d+$/, "must be a non-negative integer string"),
+    canonicalRequestHash: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex hash"),
+    canonicalBodyHash: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex hash"),
+})
+    .strict();
+const reclaimProviderClaimDataSchema = z
+    .object({
+    provider: z.string().min(1),
+    parameters: z.string().min(1),
+    context: z.string(),
+    owner: z.string().regex(evmAddress, "must be an EVM address"),
+    timestampS: z.number().int().nonnegative(),
+    epoch: z.number().int().nonnegative(),
+    identifier: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+})
+    .strict();
+const reclaimProofWireSchema = z
+    .object({
+    identifier: z
+        .string()
+        .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+    claimData: reclaimProviderClaimDataSchema,
+    signatures: z.array(z.string().regex(hexSignature)).min(1),
+})
+    .strict();
+/**
+ * `POST /delivery/proof` request body - mirrors the oracle's own
+ * `deliveryProofRequestSchema` (`streamproof-oracle/src/delivery/dto.ts`)
+ * field-for-field. Kept as a local copy (same convention the oracle itself
+ * uses for `@absol-labs/shared` shapes) rather than an import, since the two
+ * repos do not share a package for this DTO.
+ */
+export const deliveryProofRequestBodySchema = z
+    .object({
+    receipt: wireDeliveryReceiptSchema,
+    signature: z.string().regex(hexSignature, "must be a hex signature"),
+    proof: reclaimProofWireSchema,
+})
+    .strict();
+/** Converts a bigint-typed `DeliveryReceipt` to the oracle's decimal-string wire shape. */
+export function toWireDeliveryReceipt(receipt) {
+    return {
+        streamId: receipt.streamId.toString(),
+        serviceRef: receipt.serviceRef,
+        operator: receipt.operator,
+        intervalIndex: receipt.intervalIndex.toString(),
+        nonce: receipt.nonce,
+        reclaimProofId: receipt.reclaimProofId,
+        reclaimOwner: receipt.reclaimOwner,
+        reclaimTimestamp: receipt.reclaimTimestamp.toString(),
+        reclaimEpoch: receipt.reclaimEpoch.toString(),
+        canonicalRequestHash: receipt.canonicalRequestHash,
+        canonicalBodyHash: receipt.canonicalBodyHash,
+    };
+}
+/** Deterministic keccak256 over the canonical (sorted-key) JSON of `value`. */
+function hashCanonical(value) {
+    return keccak256(stringToBytes(canonicalJson(value)));
+}
+export class NoDeliveryAttestorConfiguredError extends Error {
+    constructor() {
+        super("no zkTLS delivery attestor configured: set RECLAIM_APP_ID/RECLAIM_APP_SECRET " +
+            "(see agent#22) or pass an explicit `attestor`");
+        this.name = "NoDeliveryAttestorConfiguredError";
+    }
+}
+/**
+ * Produces a complete T2 delivery proof envelope: proves the paid route with
+ * the oracle-issued nonce bound into both the request and the Reclaim
+ * `claimData.context`, signs a `DeliveryReceipt` committing to that proof, and
+ * returns the exact body for `POST /delivery/proof`.
+ */
+export async function buildT2DeliveryProofSubmission(input) {
+    const issuedAt = input.issuedAt ?? Math.floor(Date.now() / 1000);
+    if (input.intervalIndex > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError("intervalIndex exceeds Number.MAX_SAFE_INTEGER");
+    }
+    const envelope = buildDeliveryContextEnvelopeV2({
+        streamId: input.streamId,
+        operator: input.operator,
+        serviceRef: input.serviceRef,
+        ...(input.mandateId === undefined ? {} : { mandateId: input.mandateId }),
+        nonce: input.nonce,
+        intervalIndex: Number(input.intervalIndex),
+        issuedAt,
+    });
+    const injected = injectNonce(input.request, input.nonce);
+    const attestor = input.attestor ?? createReclaimT2AttestorFromEnv();
+    if (attestor === null) {
+        throw new NoDeliveryAttestorConfiguredError();
+    }
+    const proved = await attestor.proveDeliveryResponse({
+        url: injected.url,
+        method: input.request.method,
+        body: injected.body,
+        headers: input.request.headers,
+        secretHeaders: input.request.secretHeaders,
+        responseMatches: input.request.responseMatches,
+        responseRedactions: input.request.responseRedactions,
+        cookie: input.request.cookie,
+        secretParamValues: input.request.secretParamValues,
+        geoLocation: input.request.geoLocation,
+        useTee: input.request.useTee,
+        zkEngine: input.request.zkEngine,
+        context: envelope,
+    });
+    const { proof } = proved;
+    // Deterministically bind BOTH the exact proven request (method/url/body, post
+    // nonce-injection) and the exact PROVEN (redacted/extracted) response content
+    // into the receipt, so the receipt is verifiable dispute evidence even though
+    // the oracle itself does not re-derive these hashes today.
+    const canonicalRequestHash = hashCanonical({
+        method: proved.request.method,
+        url: proved.request.url,
+        body: proved.request.body,
+    });
+    const canonicalBodyHash = hashCanonical({
+        extractedParameters: proved.verification.extractedParameters,
+    });
+    const receipt = deliveryReceiptSchema.parse({
+        streamId: BigInt(input.streamId),
+        serviceRef: input.serviceRef,
+        operator: input.operator,
+        intervalIndex: input.intervalIndex,
+        nonce: input.nonce,
+        reclaimProofId: proof.identifier,
+        reclaimOwner: proof.claimData.owner,
+        reclaimTimestamp: BigInt(proof.claimData.timestampS),
+        reclaimEpoch: BigInt(proof.claimData.epoch),
+        canonicalRequestHash,
+        canonicalBodyHash,
+    });
+    const signature = await signDeliveryReceipt(receipt, input.domain, input.buyer);
+    const body = deliveryProofRequestBodySchema.parse({
+        receipt: toWireDeliveryReceipt(receipt),
+        signature,
+        proof: {
+            identifier: proof.identifier,
+            claimData: proof.claimData,
+            signatures: proof.signatures,
+        },
+    });
+    return { body, receipt, signature, proof, envelope };
+}
+//# sourceMappingURL=t2-delivery-proof.js.map

package/dist/zktls/t2-delivery-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"t2-delivery-proof.js","sourceRoot":"","sources":["../../src/zktls/t2-delivery-proof.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -66,8 +66,8 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.4.0",
-    "@absol-labs/shared": "^0.7.1",
+    "@absol-labs/sdk": "^0.7.0",
+    "@absol-labs/shared": "^0.11.0",
     "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@reclaimprotocol/js-sdk": "^5.6.0",
@@ -108,9 +108,12 @@
     "build:e2e": "tsc -p tsconfig.e2e.build.json",
     "mcp:stdio": "tsx src/mcp/stdio.ts",
     "mcp:http": "tsx src/mcp/http-server.ts",
+    "gateway": "tsx src/gateway/server-entry.ts",
     "e2e:cdp": "node dist-e2e/scripts/e2e-cdp.js",
+    "e2e:hire": "tsx scripts/e2e-hire.ts",
     "l2:proof": "node scripts/l2-proof.mjs",
     "test": "vitest run",
+    "test:package": "node scripts/test-packed-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:e2e": "tsc -p tsconfig.e2e.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",

package/src/capability/invocation-capability.ts

@@ -0,0 +1,255 @@
+import { randomBytes } from "node:crypto";
+
+import {
+  getAddress,
+  isAddress,
+  isHex,
+  keccak256,
+  recoverTypedDataAddress,
+  stringToBytes,
+  type Address,
+  type Hex,
+  type LocalAccount,
+} from "viem";
+import { z } from "zod";
+
+/**
+ * `InvocationCapability` — the stream-bound EIP-712 credential that closes the
+ * "pay -> use" loop (metrik-protocol#62/#63/#64).
+ *
+ * A buyer who has opened an active, funded stream signs one of these per
+ * service call: "I, `buyer`, authorize exactly `method` `pathHash` against
+ * `serviceRef` under stream `streamId`, once, before `expiry`." The seller's
+ * gateway (`../gateway/caller-auth-gateway.ts`) recovers the signer, cross
+ * checks it against the on-chain stream, and enforces the nonce/expiry/route
+ * binding before proxying the call upstream.
+ *
+ * Deliberately kept LOCAL to `@absol-labs/agent` for this MVP slice (per
+ * metrik-agent#64) rather than added to `@absol-labs/shared` - it is never
+ * read on-chain (no contract parses it), so there is no cross-repo byte
+ * compatibility requirement the way there is for `DeliveryReceipt`.
+ */
+
+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",
+  );
+
+/** HTTP methods a capability may authorize. */
+export const httpMethodSchema = z.enum([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+]);
+export type HttpMethod = z.infer<typeof httpMethodSchema>;
+
+export const invocationCapabilitySchema = z.object({
+  /** The on-chain `StreamEscrowV2` stream this capability draws authority from. */
+  streamId: bytes32Schema,
+  /** Must equal `stream.buyer` and the EIP-712 signer. */
+  buyer: addressSchema,
+  /** Must equal the target service's `serviceRef` (and the stream's). */
+  serviceRef: bytes32Schema,
+  /** 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 type InvocationCapability = z.infer<typeof invocationCapabilitySchema>;
+
+export const signedInvocationCapabilitySchema =
+  invocationCapabilitySchema.extend({
+    signature: signatureSchema,
+  });
+export type SignedInvocationCapability = z.infer<
+  typeof signedInvocationCapabilitySchema
+>;
+
+/** Chain-bound domain: a capability for one chain/escrow can never be replayed against another. */
+export interface InvocationCapabilityDomainInput {
+  readonly chainId: number;
+  /** The `StreamEscrowV2` the stream settles on. */
+  readonly verifyingContract: Address;
+}
+
+export const invocationCapabilityDomainName =
+  "Metrik Invocation Capability" as const;
+export const invocationCapabilityDomainVersion = "1" as const;
+
+export const invocationCapabilityTypedData = {
+  InvocationCapability: [
+    { name: "streamId", type: "bytes32" },
+    { name: "buyer", type: "address" },
+    { name: "serviceRef", type: "bytes32" },
+    { name: "method", type: "string" },
+    { name: "pathHash", type: "bytes32" },
+    { name: "nonce", type: "bytes32" },
+    { name: "expiry", type: "uint64" },
+  ],
+} as const;
+
+/** Default single-use lifetime for a freshly-issued capability. Deliberately short. */
+export const DEFAULT_CAPABILITY_TTL_SECONDS = 60;
+
+/** Header a buyer's request carries the signed capability in. */
+export const CAPABILITY_HEADER_NAME = "x-metrik-capability";
+
+export function createInvocationCapabilityEip712Domain(
+  domain: InvocationCapabilityDomainInput,
+) {
+  return {
+    name: invocationCapabilityDomainName,
+    version: invocationCapabilityDomainVersion,
+    chainId: domain.chainId,
+    verifyingContract: getAddress(domain.verifyingContract),
+  } as const;
+}
+
+/**
+ * `keccak256` of the exact request path this capability authorizes (e.g.
+ * `/v1/infer`). Path only - no scheme/host/query/fragment - so the signer and
+ * the gateway hash the identical canonical string regardless of how each side
+ * received the full URL.
+ */
+export function hashInvocationPath(path: string): Hex {
+  return keccak256(stringToBytes(normalizeInvocationPath(path)));
+}
+
+/** Strips query/fragment and any trailing slash (except the root) for a stable canonical form. */
+export function normalizeInvocationPath(path: string): string {
+  const withoutFragment = path.split("#")[0] ?? "";
+  const withoutQuery = withoutFragment.split("?")[0] ?? "";
+  if (withoutQuery.length === 0) {
+    return "/";
+  }
+  if (withoutQuery.length > 1 && withoutQuery.endsWith("/")) {
+    return withoutQuery.slice(0, -1);
+  }
+  return withoutQuery;
+}
+
+function invocationCapabilityMessage(capability: InvocationCapability) {
+  const parsed = invocationCapabilitySchema.parse(capability);
+  return {
+    streamId: parsed.streamId as Hex,
+    buyer: getAddress(parsed.buyer),
+    serviceRef: parsed.serviceRef as Hex,
+    method: parsed.method,
+    pathHash: parsed.pathHash as Hex,
+    nonce: parsed.nonce as Hex,
+    expiry: BigInt(parsed.expiry),
+  };
+}
+
+export function buildInvocationCapabilityTypedData(
+  capability: InvocationCapability,
+  domain: InvocationCapabilityDomainInput,
+) {
+  return {
+    domain: createInvocationCapabilityEip712Domain(domain),
+    types: invocationCapabilityTypedData,
+    primaryType: "InvocationCapability" as const,
+    message: invocationCapabilityMessage(capability),
+  };
+}
+
+/** Signs an `InvocationCapability` with the buyer's own wallet. */
+export async function signInvocationCapability(
+  capability: InvocationCapability,
+  domain: InvocationCapabilityDomainInput,
+  account: LocalAccount,
+): Promise<Hex> {
+  const typedData = buildInvocationCapabilityTypedData(capability, domain);
+  return account.signTypedData(typedData);
+}
+
+/** Recovers the EIP-712 signer of a capability. Throws on a malformed signature. */
+export async function recoverInvocationCapabilitySigner(
+  capability: InvocationCapability,
+  domain: InvocationCapabilityDomainInput,
+  signature: Hex,
+): Promise<Address> {
+  const typedData = buildInvocationCapabilityTypedData(capability, domain);
+  return recoverTypedDataAddress({ ...typedData, signature });
+}
+
+/** Cryptographically random 32-byte single-use nonce. */
+export function generateCapabilityNonce(): Hex {
+  return `0x${randomBytes(32).toString("hex")}` as Hex;
+}
+
+export class InvalidCapabilityHeaderError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "InvalidCapabilityHeaderError";
+  }
+}
+
+/** Encodes a signed capability as an opaque, header-safe (base64url) string. */
+export function encodeCapabilityHeader(
+  signed: SignedInvocationCapability,
+): string {
+  const parsed = signedInvocationCapabilitySchema.parse(signed);
+  const json = JSON.stringify({
+    streamId: parsed.streamId,
+    buyer: parsed.buyer,
+    serviceRef: parsed.serviceRef,
+    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 capability header value. Fails closed on any malformation. */
+export function decodeCapabilityHeader(
+  headerValue: string,
+): SignedInvocationCapability {
+  let json: string;
+  try {
+    json = Buffer.from(headerValue, "base64url").toString("utf8");
+  } catch (cause) {
+    throw new InvalidCapabilityHeaderError(
+      "malformed base64 capability header",
+      { cause },
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (cause) {
+    throw new InvalidCapabilityHeaderError("malformed JSON capability header", {
+      cause,
+    });
+  }
+
+  const result = signedInvocationCapabilitySchema.safeParse(raw);
+  if (!result.success) {
+    throw new InvalidCapabilityHeaderError(
+      `invalid capability shape: ${result.error.message}`,
+    );
+  }
+  return result.data;
+}

package/src/frameworks/agentkit.ts

@@ -365,7 +365,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   @CreateAction({
     name: "check_stream_status",
     description:
-      "Read a Metrik stream's status: verified accrued amount, whether it is active or paused (two failed checks auto-pause), claimable-by-seller, and reclaimable-by-buyer USDC.",
+      "Read a Metrik stream's status, verified accrued amount, claimable-by-seller, and reclaimable-by-buyer USDC. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
     schema: checkStreamStatusSchema,
   })
   async checkStreamStatus(
@@ -390,7 +390,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   @CreateAction({
     name: "reclaim_unspent",
     description:
-      "Reclaim unspent escrowed USDC from a Metrik stream back to the buyer. Set closeFirst to close an active stream before reclaiming. Runs under the same signed mandate controls.",
+      "Reclaim unspent escrowed USDC from a Metrik stream back to the buyer. Set closeFirst to close an active stream before reclaiming. V2 reclaim follows checkpoint finalization or escape-window rules. Runs under the same signed mandate controls.",
     schema: reclaimUnspentSchema,
   })
   async reclaimUnspent(