@absol-labs/agent 0.4.0 → 0.5.0

package/dist/sdk/invoke.js

@@ -0,0 +1,158 @@
+import { MetrikClient } from "@absol-labs/sdk";
+import { buildT2DeliveryProofSubmission, } from "../zktls/t2-delivery-proof.js";
+import { CAPABILITY_HEADER_NAME, encodeCapabilityHeader, generateCapabilityNonce, hashInvocationPath, signInvocationCapability, DEFAULT_CAPABILITY_TTL_SECONDS, } from "../capability/invocation-capability.js";
+/** Default `InvokeStreamReader`: a real, read-only `MetrikClient` (no wallet, no writes). */
+export function createSdkInvokeStreamReader(options) {
+    const metrik = MetrikClient.baseSepolia({
+        escrow: options.escrowAddress,
+        rpcUrl: options.rpcUrl,
+    });
+    return {
+        async getStreamV2(streamId) {
+            const stream = await metrik.getStreamV2(streamId);
+            return {
+                buyer: stream.buyer,
+                operator: stream.operator,
+                serviceRef: stream.serviceRef,
+                status: stream.status,
+                expiresAt: stream.expiresAt,
+            };
+        },
+    };
+}
+export class InvokeStreamNotActiveError extends Error {
+    constructor(streamId, status) {
+        super(`stream ${streamId} is not active (status=${status})`);
+        this.name = "InvokeStreamNotActiveError";
+    }
+}
+export class InvokeStreamExpiredError extends Error {
+    constructor(streamId, expiresAt) {
+        super(`stream ${streamId} expired at ${expiresAt}`);
+        this.name = "InvokeStreamExpiredError";
+    }
+}
+export class InvokeBuyerMismatchError extends Error {
+    constructor(streamId, streamBuyer, signer) {
+        super(`stream ${streamId} buyer ${streamBuyer} does not match the signing account ${signer}`);
+        this.name = "InvokeBuyerMismatchError";
+    }
+}
+/**
+ * Builds and signs a minimal-scope `InvocationCapability` for one
+ * `method`+`path` call against `streamId`, WITHOUT touching the network.
+ */
+export async function capabilityFor(streamId, request, options) {
+    const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const capability = {
+        streamId,
+        buyer: options.buyer.address,
+        serviceRef: options.serviceRef,
+        method: request.method,
+        pathHash: hashInvocationPath(request.path),
+        nonce: options.nonce ?? generateCapabilityNonce(),
+        expiry: nowSeconds + (options.ttlSeconds ?? DEFAULT_CAPABILITY_TTL_SECONDS),
+    };
+    const signature = await signInvocationCapability(capability, options.domain, options.buyer);
+    return { ...capability, signature };
+}
+/**
+ * `open()` -> `invoke()`: loads the stream, builds+signs a capability scoped
+ * to exactly this `method`+`path`, and calls the gateway-fronted service.
+ * Fails closed BEFORE any network call to the service if the stream is not
+ * active, is expired, or does not belong to the signing account.
+ */
+export async function invoke(streamId, request, options) {
+    const stream = await options.streamReader.getStreamV2(streamId);
+    const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+        throw new InvokeBuyerMismatchError(streamId, stream.buyer, options.buyer.address);
+    }
+    if (stream.status !== "active") {
+        throw new InvokeStreamNotActiveError(streamId, stream.status);
+    }
+    if (nowSeconds >= stream.expiresAt) {
+        throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+    }
+    const capability = await capabilityFor(streamId, request, {
+        buyer: options.buyer,
+        domain: options.domain,
+        serviceRef: stream.serviceRef,
+        ...(options.ttlSeconds === undefined
+            ? {}
+            : { ttlSeconds: options.ttlSeconds }),
+        ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+        nowSeconds,
+    });
+    const header = encodeCapabilityHeader(capability);
+    const url = new URL(request.path, options.serviceBaseUrl).toString();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchImpl(url, {
+        method: request.method,
+        headers: {
+            ...(request.headers ?? {}),
+            [CAPABILITY_HEADER_NAME]: header,
+        },
+        ...(request.body === undefined ? {} : { body: request.body }),
+    });
+    return { response, capability, stream };
+}
+/**
+ * The T2 variant of `invoke()`: the SAME capability-authorized call the
+ * gateway serves is what the buyer's Reclaim attestor proves, so usage and
+ * delivery proof are one action (issue #63's "the invocation IS the
+ * delivery"). Attaches the `InvocationCapability` header to the exact request
+ * `buildT2DeliveryProofSubmission` proves via zkTLS, then signs the resulting
+ * `DeliveryReceipt` - identical evidence chain as the plain T2 flow, just
+ * capability-gated at the gateway.
+ */
+export async function invokeWithT2DeliveryProof(streamId, options) {
+    const stream = await options.streamReader.getStreamV2(streamId);
+    const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+        throw new InvokeBuyerMismatchError(streamId, stream.buyer, options.buyer.address);
+    }
+    if (stream.status !== "active") {
+        throw new InvokeStreamNotActiveError(streamId, stream.status);
+    }
+    if (nowSeconds >= stream.expiresAt) {
+        throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+    }
+    const path = new URL(options.request.url).pathname;
+    const capability = await capabilityFor(streamId, { method: options.request.method ?? "GET", path }, {
+        buyer: options.buyer,
+        domain: options.domain,
+        serviceRef: stream.serviceRef,
+        ...(options.capabilityTtlSeconds === undefined
+            ? {}
+            : { ttlSeconds: options.capabilityTtlSeconds }),
+        ...(options.capabilityNonce === undefined
+            ? {}
+            : { nonce: options.capabilityNonce }),
+        nowSeconds,
+    });
+    const requestWithCapability = {
+        ...options.request,
+        headers: {
+            ...(options.request.headers ?? {}),
+            [CAPABILITY_HEADER_NAME]: encodeCapabilityHeader(capability),
+        },
+    };
+    const t2 = await buildT2DeliveryProofSubmission({
+        streamId,
+        operator: stream.operator,
+        serviceRef: stream.serviceRef,
+        intervalIndex: options.intervalIndex,
+        nonce: options.nonce,
+        buyer: options.buyer,
+        domain: options.domain,
+        request: requestWithCapability,
+        ...(options.issuedAt === undefined ? {} : { issuedAt: options.issuedAt }),
+        ...(options.mandateId === undefined
+            ? {}
+            : { mandateId: options.mandateId }),
+        ...(options.attestor === undefined ? {} : { attestor: options.attestor }),
+    });
+    return { capability, stream, t2 };
+}
+//# sourceMappingURL=invoke.js.map

package/dist/sdk/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../src/sdk/invoke.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EACL,8BAA8B,GAI/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,wBAAwB,EAKxB,8BAA8B,GAC/B,MAAM,wCAAwC,CAAC;AAwBhD,6FAA6F;AAC7F,MAAM,UAAU,2BAA2B,CAAC,OAG3C;IACC,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,CAAC;QACtC,MAAM,EAAE,OAAO,CAAC,aAAa;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,OAAO;QACL,KAAK,CAAC,WAAW,CAAC,QAAQ;YACxB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAClD,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,QAAa,EAAE,MAAc;QACvC,KAAK,CAAC,UAAU,QAAQ,0BAA0B,MAAM,GAAG,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,QAAa,EAAE,SAAiB;QAC1C,KAAK,CAAC,UAAU,QAAQ,eAAe,SAAS,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,QAAa,EAAE,WAAoB,EAAE,MAAe;QAC9D,KAAK,CACH,UAAU,QAAQ,UAAU,WAAW,uCAAuC,MAAM,EAAE,CACvF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAcD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAa,EACb,OAA+D,EAC/D,OAA6B;IAE7B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACvE,MAAM,UAAU,GAAyB;QACvC,QAAQ;QACR,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;QAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;QAC1C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,uBAAuB,EAAE;QACjD,MAAM,EAAE,UAAU,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,8BAA8B,CAAC;KAC5E,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,wBAAwB,CAC9C,UAAU,EACV,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,KAAK,CACd,CAAC;IACF,OAAO,EAAE,GAAG,UAAU,EAAE,SAAS,EAAE,CAAC;AACtC,CAAC;AA+BD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,QAAa,EACb,OAA2B,EAC3B,OAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAEvE,IAAI,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACvE,MAAM,IAAI,wBAAwB,CAChC,QAAQ,EACR,MAAM,CAAC,KAAK,EACZ,OAAO,CAAC,KAAK,CAAC,OAAO,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,0BAA0B,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,UAAU,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE;QACxD,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS;YAClC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QACvC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAChE,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;YAC1B,CAAC,sBAAsB,CAAC,EAAE,MAAM;SACjC;QACD,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;KAC9D,CAAC,CAAC;IAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC1C,CAAC;AA4BD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,QAAa,EACb,OAAyC;IAEzC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAEvE,IAAI,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACvE,MAAM,IAAI,wBAAwB,CAChC,QAAQ,EACR,MAAM,CAAC,KAAK,EACZ,OAAO,CAAC,KAAK,CAAC,OAAO,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,0BAA0B,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,UAAU,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IACnD,MAAM,UAAU,GAAG,MAAM,aAAa,CACpC,QAAQ,EACR,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,IAAI,EAAE,EACjD;QACE,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,OAAO,CAAC,oBAAoB,KAAK,SAAS;YAC5C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;QACjD,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC;QACvC,UAAU;KACX,CACF,CAAC;IAEF,MAAM,qBAAqB,GAAyB;QAClD,GAAG,OAAO,CAAC,OAAO;QAClB,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;YAClC,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC,UAAU,CAAC;SAC7D;KACF,CAAC;IAEF,MAAM,EAAE,GAAG,MAAM,8BAA8B,CAAC;QAC9C,QAAQ;QACR,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,qBAAqB;QAC9B,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;QACrC,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC,CAAC;IAEH,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACpC,CAAC"}

package/dist/wallet/lifecycle.d.ts

@@ -0,0 +1,101 @@
+import { erc20Abi, type Address } from "viem";
+/**
+ * Agent wallet lifecycle helpers (metrik-agent#65).
+ *
+ * `../wallet/provider.ts` already resolves a wallet (injected key or a
+ * Coinbase CDP Server Wallet v2 account) and hands back a viem `Account` that
+ * can sign directly — `resolveAgentWallet()`'s CDP path is create-OR-restore
+ * by construction (`cdp.evm.getOrCreateAccount({ name })` is idempotent: the
+ * same `ownerName` always resolves to the same on-chain address, so a second
+ * run with the same env "restores" rather than creates a new wallet).
+ *
+ * This module adds the remaining thin, non-custodial lifecycle pieces the
+ * issue asks for: reading balances, a testnet faucet hint, and requesting
+ * funds from the CDP faucet. It deliberately does NOT wrap signing — a
+ * `ResolvedAgentWallet.account` is already a plain viem `Account`
+ * (`signMessage` / `signTypedData` / `signTransaction` all work as-is), and
+ * adding a second signing surface here would be exactly the "second wallet
+ * system" AGENTS.md warns against.
+ */
+/** Native gas balance + USDC balance for one address. */
+export interface WalletBalances {
+    /** Native token balance (ETH on Base/Base Sepolia), in wei. */
+    readonly nativeWei: bigint;
+    /** USDC balance, in atomic units (6 decimals). */
+    readonly usdcAtomic: bigint;
+}
+/** The subset of a viem `PublicClient` balance reads need. Duck-typed so any real client satisfies it. */
+export interface BalanceReader {
+    getBalance(args: {
+        readonly address: Address;
+    }): Promise<bigint>;
+    readContract(args: {
+        readonly address: Address;
+        readonly abi: typeof erc20Abi;
+        readonly functionName: "balanceOf";
+        readonly args: readonly [Address];
+    }): Promise<unknown>;
+}
+export interface GetWalletBalancesOptions {
+    readonly publicClient: BalanceReader;
+    readonly address: Address;
+    /** The USDC token contract to read the ERC-20 balance from. */
+    readonly usdc: Address;
+}
+/** Reads a wallet's native gas balance and USDC balance in one call. Read-only — no signing, no writes. */
+export declare function getWalletBalances(options: GetWalletBalancesOptions): Promise<WalletBalances>;
+/** Human-facing pointers to fund a freshly created/restored testnet wallet. */
+export interface FaucetHint {
+    readonly network: string;
+    /** Coinbase CDP faucet — funds native ETH (and, on some networks, USDC) for a CDP-managed address. */
+    readonly cdpFaucetUrl: string;
+    /** Circle's own Base Sepolia USDC faucet — an alternative USDC source that doesn't require a CDP account. */
+    readonly usdcFaucetUrl: string;
+    /** How to request the same funds programmatically from a CDP wallet — see {@link requestCdpFaucet}. */
+    readonly programmaticHint: string;
+}
+export declare class UnsupportedFaucetChainError extends Error {
+    constructor(chainId: number);
+}
+/** A faucet hint for the given chain. Only Base Sepolia (84532) is supported — Metrik is testnet-only, single-chain. */
+export declare function faucetHint(chainId: number): FaucetHint;
+export type FaucetToken = "eth" | "usdc";
+/** The subset of the Coinbase CDP client the faucet request needs. Duck-typed for testability. */
+export interface CdpFaucetClientLike {
+    readonly evm: {
+        requestFaucet(options: {
+            readonly address: Address;
+            readonly network: string;
+            readonly token: FaucetToken;
+        }): Promise<{
+            readonly transactionHash: string;
+        }>;
+    };
+}
+export interface RequestCdpFaucetOptions {
+    readonly cdp: CdpFaucetClientLike;
+    readonly address: Address;
+    readonly token: FaucetToken;
+    /** Default `"base-sepolia"`. */
+    readonly network?: string;
+}
+export interface FaucetRequestResult {
+    /** `true` iff the faucet accepted the request (a tx hash was returned). */
+    readonly requested: boolean;
+    readonly txHash?: string;
+    /**
+     * Set when `requested` is `false`. The CDP faucet enforces a 24h per-address
+     * rate limit, so a failure here is an EXPECTED, non-fatal outcome — never
+     * thrown. Callers should log this and fall back to checking whether the
+     * balance is already sufficient.
+     */
+    readonly error?: string;
+}
+/**
+ * Requests testnet funds from the Coinbase CDP faucet for a CDP-managed
+ * address. Tolerates the faucet's 24h rate limit and any other request
+ * failure by returning `{ requested: false, error }` — it never throws, so a
+ * caller can always fall through to reading the current balance instead.
+ */
+export declare function requestCdpFaucet(options: RequestCdpFaucetOptions): Promise<FaucetRequestResult>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/wallet/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/wallet/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,YAAY,CAAC,IAAI,EAAE;QACjB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,QAAQ,CAAC;QAC9B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;QACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,2GAA2G;AAC3G,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CAWzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6GAA6G;IAC7G,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uGAAuG;IACvG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAM5B;AAYD,wHAAwH;AACxH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAKtD;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE;QACZ,aAAa,CAAC,OAAO,EAAE;YACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;YAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;YACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;SAC7B,GAAG,OAAO,CAAC;YAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACnD,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAc9B"}

package/dist/wallet/lifecycle.js

@@ -0,0 +1,57 @@
+import { erc20Abi } from "viem";
+/** Reads a wallet's native gas balance and USDC balance in one call. Read-only — no signing, no writes. */
+export async function getWalletBalances(options) {
+    const [nativeWei, usdcAtomic] = await Promise.all([
+        options.publicClient.getBalance({ address: options.address }),
+        options.publicClient.readContract({
+            address: options.usdc,
+            abi: erc20Abi,
+            functionName: "balanceOf",
+            args: [options.address],
+        }),
+    ]);
+    return { nativeWei, usdcAtomic: usdcAtomic };
+}
+export class UnsupportedFaucetChainError extends Error {
+    constructor(chainId) {
+        super(`no known testnet faucet for chainId ${chainId} (Metrik is Base Sepolia (84532) only)`);
+        this.name = "UnsupportedFaucetChainError";
+    }
+}
+const BASE_SEPOLIA_CHAIN_ID = 84532;
+const BASE_SEPOLIA_FAUCET_HINT = {
+    network: "base-sepolia",
+    cdpFaucetUrl: "https://portal.cdp.coinbase.com/products/faucet",
+    usdcFaucetUrl: "https://faucet.circle.com",
+    programmaticHint: "requestCdpFaucet({ cdp, address, token: 'eth' | 'usdc' }) — subject to a 24h per-address rate limit",
+};
+/** A faucet hint for the given chain. Only Base Sepolia (84532) is supported — Metrik is testnet-only, single-chain. */
+export function faucetHint(chainId) {
+    if (chainId !== BASE_SEPOLIA_CHAIN_ID) {
+        throw new UnsupportedFaucetChainError(chainId);
+    }
+    return BASE_SEPOLIA_FAUCET_HINT;
+}
+/**
+ * Requests testnet funds from the Coinbase CDP faucet for a CDP-managed
+ * address. Tolerates the faucet's 24h rate limit and any other request
+ * failure by returning `{ requested: false, error }` — it never throws, so a
+ * caller can always fall through to reading the current balance instead.
+ */
+export async function requestCdpFaucet(options) {
+    try {
+        const result = await options.cdp.evm.requestFaucet({
+            address: options.address,
+            network: options.network ?? "base-sepolia",
+            token: options.token,
+        });
+        return { requested: true, txHash: result.transactionHash };
+    }
+    catch (error) {
+        return {
+            requested: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/wallet/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/wallet/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgB,MAAM,MAAM,CAAC;AA+C9C,2GAA2G;AAC3G,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiC;IAEjC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChD,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7D,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC;YAChC,OAAO,EAAE,OAAO,CAAC,IAAI;YACrB,GAAG,EAAE,QAAQ;YACb,YAAY,EAAE,WAAW;YACzB,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;SACxB,CAAC;KACH,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAoB,EAAE,CAAC;AACzD,CAAC;AAaD,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,OAAe;QACzB,KAAK,CACH,uCAAuC,OAAO,wCAAwC,CACvF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAEpC,MAAM,wBAAwB,GAAe;IAC3C,OAAO,EAAE,cAAc;IACvB,YAAY,EAAE,iDAAiD;IAC/D,aAAa,EAAE,2BAA2B;IAC1C,gBAAgB,EACd,qGAAqG;CACxG,CAAC;AAEF,wHAAwH;AACxH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,IAAI,OAAO,KAAK,qBAAqB,EAAE,CAAC;QACtC,MAAM,IAAI,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAoCD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC;YACjD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,cAAc;YAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QACH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.4.0",
+  "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,7 +66,7 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.4.0",
+    "@absol-labs/sdk": "^0.7.0",
     "@absol-labs/shared": "^0.11.0",
     "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.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(

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"),