@absol-labs/agent 0.4.0 → 0.6.0

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/discovery/registry.ts

@@ -1,7 +1,11 @@
 import {
   deriveServiceRef,
   recoverServiceBindingSigner,
+  recoverServiceDescriptorSigner,
   serviceBindingSchema,
+  serviceDescriptorSchema,
+  type SignedServiceBinding,
+  type SignedServiceDescriptor,
 } from "@absol-labs/shared";
 import { isHex } from "viem";
 import { z } from "zod";
@@ -35,9 +39,14 @@ export interface ServiceListing {
   readonly serviceRef: `0x${string}`;
   readonly operator: `0x${string}`;
   readonly publicUrl: string;
+  readonly access: "public" | "gated";
+  /** Signed invocation origin; gated listings fail closed if this is absent. */
+  readonly accessUrl: string;
+  /** The schema-validated and cryptographically verified signed record. */
+  readonly signed: SignedServiceBinding | SignedServiceDescriptor;
   /** Unsigned informational category from the listings row (may be absent). */
   readonly category: string | null;
-  /** Optional signed operator-supplied target metadata (e.g. resolver hints). */
+  /** Optional unsigned operator-supplied resolver hints; never used for invocation. */
   readonly targetMetadata?: Record<string, string>;
 }
 
@@ -76,14 +85,16 @@ export const DEFAULT_METRIK_REGISTRY_URL =
 const DEFAULT_TIMEOUT_MS = 5_000;
 
 /**
- * `serviceRef` of the built-in verified demo listing. Kept as a named constant so
+ * `serviceRef` of the built-in verified live-data listing. Kept as a named constant so
  * callers can recognise (and dedupe against) the seeded row.
  */
-export const DEMO_SEED_SERVICE_REF =
-  "0x84ef78c5ac9fc084422dc2d3e1ef19623bb05d0d81c097d4da49f9c47ec3ed12" as const;
+export const LIVE_DATA_SEED_SERVICE_REF =
+  "0x79e57358e98a35273c1cd9d5f1bf9ae1e0af8705db432eb706459dc4f88b6fe0" as const;
+/** @deprecated Use {@link LIVE_DATA_SEED_SERVICE_REF}. */
+export const DEMO_SEED_SERVICE_REF = LIVE_DATA_SEED_SERVICE_REF;
 
 /**
- * A REAL, operator-signed demo listing row embedded so `discoverServices()` returns
+ * A real, operator-signed live-data listing row embedded so `discoverServices()` returns
  * something hireable with ZERO configuration (no Supabase anon key, no registry URL).
  *
  * This is PUBLIC data — a signed {@link https://github.com/Absol-Labs | Metrik}
@@ -94,23 +105,115 @@ export const DEMO_SEED_SERVICE_REF =
  * with any field here and the seed silently drops itself, identically to a bad
  * registry row. The `category` column is unsigned informational metadata only.
  */
-export const DEMO_SEED_LISTING = {
-  service_ref: DEMO_SEED_SERVICE_REF,
-  operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
-  public_url: "https://metrik-demo-service.vercel.app",
-  category: "demo",
+export const LIVE_DATA_SEED_LISTING = {
+  service_ref: LIVE_DATA_SEED_SERVICE_REF,
+  operator: "0xB3e162711920dFD8933609019Dc35C73cC1a09F0",
+  public_url: "https://livedata.137.23.50.249.sslip.io",
+  category: "live-data",
   signed_binding: {
-    serviceRef: DEMO_SEED_SERVICE_REF,
-    binding: {
-      version: 2,
-      operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
-      publicUrl: "https://metrik-demo-service.vercel.app",
-      issuedAt: 1_787_500_000,
+    serviceRef: LIVE_DATA_SEED_SERVICE_REF,
+    descriptor: {
+      version: 3,
+      operator: "0xB3e162711920dFD8933609019Dc35C73cC1a09F0",
+      publicUrl: "https://livedata.137.23.50.249.sslip.io",
+      issuedAt: 1_787_772_057,
+      interface: {
+        baseUrl: "https://livedata.137.23.50.249.sslip.io",
+        healthPath: "/health",
+        endpoints: [
+          {
+            name: "health",
+            path: "/health",
+            method: "GET",
+            description: "Liveness probe.",
+          },
+          {
+            name: "readiness",
+            path: "/readiness",
+            method: "GET",
+            description:
+              "Non-value dependency readiness backed by the same real BTC cache policy.",
+          },
+          {
+            name: "price",
+            path: "/price",
+            method: "GET",
+            description:
+              "Real live crypto spot price (?symbol=BTC|ETH|SOL) from CoinGecko's public API.",
+          },
+        ],
+        authModel: "caller-auth",
+        example: {
+          endpoint: "price",
+          request: { symbol: "BTC" },
+          response: { symbol: "BTC", source: "coingecko-public-api" },
+          description:
+            "Real, nondeterministic live price — no re-execution guarantee.",
+        },
+        expectedStatuses: [200],
+      },
+      verification: {
+        canaries: [
+          {
+            path: "/readiness",
+            method: "GET",
+            matcher: {
+              type: "json-field-equals",
+              field: "source",
+              expected: "coingecko-public-api",
+            },
+            nonce: {
+              inject: { in: "query", name: "nonce" },
+              echo: { from: "json-path", path: "nonce" },
+            },
+          },
+          {
+            path: "/canary",
+            method: "GET",
+            matcher: {
+              type: "includes",
+              expected: "metrik-canary:live-data:",
+            },
+            nonce: {
+              inject: { in: "query", name: "nonce" },
+              echo: { from: "json-path", path: "nonce" },
+            },
+          },
+        ],
+        schema: {
+          path: "/readiness?nonce=metrik-schema",
+          required: [
+            { pointer: "ready", type: "boolean" },
+            { pointer: "source", type: "string", nonEmpty: true },
+            { pointer: "fetchedAt", type: "string", nonEmpty: true },
+            { pointer: "priceAgeMs", type: "number" },
+            { pointer: "freshness", type: "string", nonEmpty: true },
+          ],
+        },
+        sla: { maxLatencyMs: 5000, freshnessSeconds: 60 },
+      },
+      commercial: {
+        minRatePerSecond: "100",
+        maxRatePerSecond: "10000",
+        currency: "USDC",
+        slaDescription:
+          "Failed or unproven intervals do not advance verified cumulative entitlement; the stream remains active until buyer close or expiry.",
+        refundPolicy:
+          "The buyer reclaims unspent escrow using the latest checkpoint after close/expiry, or the unverified escape path after its grace window.",
+      },
+      access: "gated",
+      callerAuth: {
+        mechanism: "on-chain",
+        role: "buyer",
+        accessUrl: "https://gateway.137.23.50.249.sslip.io",
+      },
     },
     signature:
-      "0x17917e96836a63238d0abe70c8c55081c4d694ad43311cdb3ea91dad349827fa6480657be2362e0b7f0524a0ee4ba0c48068255c3423a965392724874d244cd21b",
+      "0x2f4d2784eb40b1542517bc19f12534fb2e97da4ade5a3ff56193fcfb97fbef921309f77af3445e336cb07a4379011b080bba700033a098f672b0b2f096197f161b",
   },
 } as const;
+/** @deprecated Use {@link LIVE_DATA_SEED_LISTING}. */
+export const DEMO_SEED_LISTING = LIVE_DATA_SEED_LISTING;
 
 const signature65HexSchema = z
   .string()
@@ -135,12 +238,25 @@ const signedBindingRecordSchema = z.object({
   targetMetadata: z.record(z.string()).optional(),
 });
 
+const signedDescriptorRecordSchema = z.object({
+  serviceRef: bytes32HexSchema,
+  descriptor: serviceDescriptorSchema,
+  signature: signature65HexSchema,
+  targetMetadata: z.record(z.string()).optional(),
+});
+
 /** A Supabase `listings` row. Only `signed_binding` is trusted; `category` is
  * carried through as unsigned informational metadata. Unknown columns are ignored. */
 const listingRowSchema = z
   .object({
+    service_ref: bytes32HexSchema.optional(),
+    operator: z.string().optional(),
+    public_url: z.string().optional(),
     category: z.string().nullish(),
-    signed_binding: signedBindingRecordSchema,
+    signed_binding: z.union([
+      signedBindingRecordSchema,
+      signedDescriptorRecordSchema,
+    ]),
   })
   .passthrough();
 
@@ -167,13 +283,13 @@ export async function discoverServices(
 
   // `registryUnavailable` = the registry could not be queried at all (no fetch /
   // network error / non-200). It never throws into the hire flow; instead it
-  // degrades to the built-in verified demo seed (when enabled) so a cold user
+  // degrades to the built-in verified live-data seed (when enabled) so a cold user
   // still discovers a hireable service.
   let rows: unknown[] = [];
   let registryUnavailable = false;
   if (typeof fetchImpl !== "function") {
     logger.warn(
-      "metrik discovery: no fetch implementation available; falling back to demo seed only",
+      "metrik discovery: no fetch implementation available; falling back to live-data seed only",
     );
     registryUnavailable = true;
   } else {
@@ -182,9 +298,9 @@ export async function discoverServices(
     } catch (error) {
       // Fail-safe / buyer-favouring: a down, unreachable, or 401 registry (the
       // Supabase default rejects credential-free reads) must never throw into the
-      // agent's hire flow — it degrades to the demo seed.
+      // agent's hire flow — it degrades to the live-data seed.
       logger.warn(
-        `metrik discovery: listings registry unavailable (${errorMessage(error)}); falling back to demo seed only`,
+        `metrik discovery: listings registry unavailable (${errorMessage(error)}); falling back to live-data seed only`,
       );
       registryUnavailable = true;
     }
@@ -210,21 +326,21 @@ export async function discoverServices(
     }
   }
 
-  // Append the built-in verified demo listing when the registry did not already
+  // Append the built-in verified live-data listing when the registry did not already
   // surface it. Runs through the SAME fail-closed verifyRow path, so it is
   // verified exactly like a registry row and can never be a trust bypass.
   if (includeDemoSeed && !seedAlreadyPresent) {
-    const seed = await verifyRow(DEMO_SEED_LISTING, "demo-seed", logger);
+    const seed = await verifyRow(DEMO_SEED_LISTING, "live-data-seed", logger);
     if (seed === null) {
       // Defensive: only reachable if the embedded constant were corrupted.
       logger.warn(
-        "metrik discovery: built-in demo seed failed fail-closed verification; not seeding",
+        "metrik discovery: built-in live-data seed failed fail-closed verification; not seeding",
       );
     } else if (opts.category === undefined || seed.category === opts.category) {
       logger.warn(
         registryUnavailable
-          ? "metrik discovery: registry unavailable — serving the built-in verified demo listing"
-          : "metrik discovery: registry did not include the demo service — appending the built-in verified demo listing",
+          ? "metrik discovery: registry unavailable — serving the built-in verified live-data listing"
+          : "metrik discovery: registry did not include live data — appending the built-in verified listing",
       );
       listings.push(seed);
     }
@@ -284,26 +400,59 @@ async function verifyRow(
   }
   const { signed_binding: record, category } = parsed.data;
 
+  const signedIdentity =
+    "descriptor" in record
+      ? {
+          operator: record.descriptor.operator,
+          publicUrl: record.descriptor.publicUrl,
+        }
+      : {
+          operator: record.binding.operator,
+          publicUrl: record.binding.publicUrl,
+        };
+  if (
+    (parsed.data.service_ref !== undefined &&
+      !eqHex(parsed.data.service_ref, record.serviceRef)) ||
+    (parsed.data.operator !== undefined &&
+      !eqHex(parsed.data.operator, signedIdentity.operator)) ||
+    (parsed.data.public_url !== undefined &&
+      parsed.data.public_url !== signedIdentity.publicUrl)
+  ) {
+    logger.warn(
+      `metrik discovery: row ${index} dropped — flat identity columns disagree with signed record`,
+    );
+    return null;
+  }
+
   let signer: `0x${string}` | null;
   try {
-    signer = (await recoverServiceBindingSigner(
-      record.binding,
-      record.signature as `0x${string}`,
-    )) as `0x${string}` | null;
+    signer = (
+      "descriptor" in record
+        ? await recoverServiceDescriptorSigner(
+            record.descriptor,
+            record.signature as `0x${string}`,
+          )
+        : await recoverServiceBindingSigner(
+            record.binding,
+            record.signature as `0x${string}`,
+          )
+    ) as `0x${string}` | null;
   } catch (error) {
     logger.warn(
       `metrik discovery: row ${index} dropped — signature recovery threw (${errorMessage(error)})`,
     );
     return null;
   }
-  if (signer === null || !eqHex(signer, record.binding.operator)) {
+  if (signer === null || !eqHex(signer, signedIdentity.operator)) {
     logger.warn(
       `metrik discovery: row ${index} dropped — signature does not recover to operator (recovered ${signer ?? "null"})`,
     );
     return null;
   }
 
-  const derivedRef = deriveServiceRef(record.binding);
+  const derivedRef = deriveServiceRef(
+    "descriptor" in record ? record.descriptor : record.binding,
+  );
   if (!eqHex(derivedRef, record.serviceRef)) {
     logger.warn(
       `metrik discovery: row ${index} dropped — serviceRef ${record.serviceRef} does not match derived ${derivedRef}`,
@@ -311,10 +460,31 @@ async function verifyRow(
     return null;
   }
 
+  const access =
+    "descriptor" in record ? (record.descriptor.access ?? "public") : "public";
+  const accessUrl =
+    "descriptor" in record
+      ? access === "gated"
+        ? record.descriptor.callerAuth?.accessUrl
+        : (record.descriptor.interface?.baseUrl ?? record.descriptor.publicUrl)
+      : record.binding.publicUrl;
+  if (
+    accessUrl === undefined ||
+    (access === "gated" && !isHttpsUrl(accessUrl))
+  ) {
+    logger.warn(
+      `metrik discovery: row ${index} dropped — gated descriptor has no signed HTTPS callerAuth.accessUrl`,
+    );
+    return null;
+  }
+
   return {
     serviceRef: derivedRef,
-    operator: record.binding.operator as `0x${string}`,
-    publicUrl: record.binding.publicUrl,
+    operator: signedIdentity.operator as `0x${string}`,
+    publicUrl: signedIdentity.publicUrl,
+    access,
+    accessUrl,
+    signed: record as SignedServiceBinding | SignedServiceDescriptor,
     category: category ?? null,
     ...(record.targetMetadata === undefined
       ? {}
@@ -322,6 +492,14 @@ async function verifyRow(
   };
 }
 
+function isHttpsUrl(value: string): boolean {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 function eqHex(a: string, b: string): boolean {
   return a.toLowerCase() === b.toLowerCase();
 }

package/src/frameworks/agentkit.ts

@@ -290,7 +290,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     }
     const lines = listings.map(
       (listing) =>
-        `- ${listing.serviceRef} operator=${listing.operator} url=${listing.publicUrl}${listing.category ? ` category=${listing.category}` : ""}`,
+        `- ${listing.serviceRef} operator=${listing.operator} verificationUrl=${listing.publicUrl} access=${listing.access} accessUrl=${listing.accessUrl}${listing.category ? ` category=${listing.category}` : ""}`,
     );
     return (
       `Discovered ${listings.length} verified Metrik service${listings.length === 1 ? "" : "s"} ` +
@@ -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(

package/src/frameworks/crewai.ts

@@ -72,7 +72,7 @@ export function renderCrewAiVerifiedStreamPythonExample(
     "",
     "buyer_agent = Agent(",
     '    role="Verified Compute Buyer",',
-    '    goal="Hire a verified service and stop work when the stream pauses.",',
+    '    goal="Hire a verified service and close it if delivery is no longer verified.",',
     '    backstory="An operator that only pays for oracle-verified delivery.",',
     "    mcps=[metrik_mcp],",
     ")",

package/src/frameworks/eliza.ts

@@ -368,7 +368,7 @@ function createStatusAction(agentClient: MetrikElizaClient): Action {
       "is the service still delivering",
     ],
     description:
-      "Read the current Metrik stream status — verified accrual, active/paused state (two failed checks auto-pause), and claimable/reclaimable USDC — plus whether the agent should stop work.",
+      "Read the current Metrik stream status, verified accrual, and claimable/reclaimable USDC, plus whether the agent should stop work. In V2, failed or unproven intervals do not advance cumulative entitlement; buyer close or expiry ends the session.",
     examples: createExamples("CHECK_STREAM_STATUS"),
     validate: async (_runtime, message) =>
       canParseElizaActionInput(message.content, "CHECK_STREAM_STATUS"),
@@ -408,7 +408,7 @@ function createReclaimAction(
       "refund the remaining balance",
     ],
     description:
-      "Reclaim unspent escrowed USDC from a verified stream back to the buyer under the original signed mandate. Set closeFirst to close an active stream before reclaiming.",
+      "Reclaim unspent escrowed USDC from a verified stream back to the buyer under the original signed mandate. Set closeFirst to close an active stream before reclaiming. V2 reclaim follows checkpoint finalization or escape-window rules.",
     examples: createExamples("RECLAIM_UNSPENT"),
     validate: async (_runtime, message) =>
       canParseElizaActionInput(message.content, "RECLAIM_UNSPENT"),