@absol-labs/agent 0.9.0 → 0.10.0

package/src/cli/wallet.ts

@@ -0,0 +1,241 @@
+import { privateKeyToAccount } from "viem/accounts";
+import type { Account, LocalAccount } from "viem";
+
+import { resolveAgentWallet } from "../wallet/provider.js";
+import { configError } from "./errors.js";
+
+/**
+ * The ONLY place the CLI resolves a signing wallet.
+ *
+ * There is deliberately NO `--private-key` flag, and no flag for any other
+ * credential. A secret passed on the command line lands in shell history, in
+ * `ps` output, and in any CI log that echoes the command; an environment
+ * variable does none of those. Secrets are also never echoed back: commands
+ * print the derived ADDRESS only.
+ *
+ * ## Resolution order (first match wins, checked in this order)
+ *
+ *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
+ *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
+ *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *
+ * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures every surface the same way. It is checked in a
+ * FIXED order rather than "whichever is configured", because an environment
+ * carrying both is ambiguous about which address funds the stream — and that
+ * ambiguity is a fund-moving one. When both are present the private key wins
+ * and `resolveCliWallet` says so on stderr rather than silently picking.
+ *
+ * ## Why CDP is wired and Privy is not
+ *
+ * CDP is the only wallet path in this package with live CI evidence
+ * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
+ * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
+ * viem local account, so it drops straight into the CLI's existing
+ * `http(rpcUrl)` transport with no other change.
+ *
+ * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
+ * account with no `signTransaction`: they sign and broadcast by sending
+ * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
+ * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
+ * that into the CLI is not a matter of reading three more variables — it
+ * changes the transport for every fund-moving command, and `metrik invoke`
+ * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
+ * `assertLocalSigner` below therefore REFUSES a non-local account with that
+ * fact, instead of accepting one and failing later inside viem. See
+ * `docs/cli.md` § Wallet.
+ */
+export const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
+
+/** Every environment variable the CDP path reads. Named in errors, never printed. */
+export const CDP_ENV_VARS = [
+  "CDP_API_KEY_ID",
+  "CDP_API_KEY_SECRET",
+  "CDP_WALLET_SECRET",
+  "METRIK_AGENT_CDP_OWNER_NAME",
+] as const;
+
+/**
+ * What the key is for, in the words of the command that needs it. `invoke`
+ * signs an EIP-712 invocation capability and broadcasts NOTHING; telling its
+ * caller "this command signs a transaction" was simply false.
+ */
+export type KeyPurpose = "transaction" | "capability";
+
+const PURPOSE_TEXT: Record<KeyPurpose, string> = {
+  transaction: "signs a transaction",
+  capability:
+    "signs an off-chain EIP-712 invocation capability (no transaction is broadcast)",
+};
+
+/** Which environment configured the signer, for output and for error text. */
+export type CliWalletSource = "private-key" | "cdp";
+
+export interface CliWallet {
+  readonly source: CliWalletSource;
+  /**
+   * A LOCAL signer. Every CLI path either broadcasts through `http(rpcUrl)`
+   * (which cannot sign) or signs EIP-712 off-chain, so a signer that delegates
+   * to a remote provider is refused at resolution rather than mid-command.
+   */
+  readonly account: LocalAccount;
+  /** One line naming the signer's origin. Safe to print: no secret in it. */
+  readonly description: string;
+}
+
+const WALLET_HINT =
+  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), or configure a Coinbase CDP wallet with ` +
+  `${CDP_ENV_VARS.join(", ")}. Both are read from the environment only — never pass a credential as a command-line flag.`;
+
+/**
+ * Resolves the signing wallet, or throws an actionable configuration error.
+ *
+ * `note` receives one line when the environment is ambiguous (both wallet
+ * sources configured). It is optional so `resolveCliWallet` stays usable from a
+ * context with no printer; commands always pass `out.note`.
+ */
+export async function resolveCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: {
+    readonly purpose?: KeyPurpose;
+    readonly note?: (line: string) => void;
+  } = {},
+): Promise<CliWallet> {
+  const wallet = await optionalCliWallet(env, options);
+  if (wallet === null) {
+    throw configError(
+      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: neither ${PRIVATE_KEY_ENV} nor the CDP variables are set`,
+      WALLET_HINT,
+    );
+  }
+  return wallet;
+}
+
+/**
+ * The same resolution, but "nothing configured" is not an error. Used by
+ * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
+ * broadcast nothing and must therefore work for someone who does not yet have a
+ * funded wallet — which is exactly who a dry run is for.
+ *
+ * A wallet that is PARTIALLY configured is still an error here: "you set three
+ * of the four CDP variables" and "you configured no wallet" are different
+ * facts, and rendering the first as the second sends the reader looking in the
+ * wrong place.
+ */
+export async function optionalCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: { readonly note?: (line: string) => void } = {},
+): Promise<CliWallet | null> {
+  const privateKeyAccount = optionalCliAccount(env);
+  const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+
+  if (privateKeyAccount !== null) {
+    if (cdpConfigured) {
+      options.note?.(
+        `warning: both ${PRIVATE_KEY_ENV} and CDP wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the CDP wallet.`,
+      );
+    }
+    return {
+      source: "private-key",
+      account: privateKeyAccount,
+      description: `${privateKeyAccount.address} (from ${PRIVATE_KEY_ENV})`,
+    };
+  }
+
+  if (!cdpConfigured) return null;
+
+  const missing = CDP_ENV_VARS.filter((name) => !isSet(env[name]));
+  if (missing.length > 0) {
+    throw configError(
+      `the CDP wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`,
+      `a CDP wallet needs all of ${CDP_ENV_VARS.join(", ")}. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others and use ${PRIVATE_KEY_ENV} instead.`,
+    );
+  }
+
+  // A CDP SMART account is an ERC-4337 contract account at a DIFFERENT address
+  // from its owner EOA, and it is reached through a bundler — which this CLI
+  // does not route to: every command broadcasts through `http(--rpc-url)`. So a
+  // smart-account environment would silently sign and spend from the OWNER,
+  // while the user funded the smart account. Refuse instead.
+  if (
+    isSet(env.METRIK_AGENT_CDP_SMART_ACCOUNT_NAME) ||
+    isTruthy(env.METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT)
+  ) {
+    throw configError(
+      "the CLI cannot sign from a CDP smart account: METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT / METRIK_AGENT_CDP_SMART_ACCOUNT_NAME is set",
+      "a CDP smart account is an ERC-4337 account at a different address from its owner, reached through a bundler; this CLI broadcasts through --rpc-url and would spend from the OWNER address instead. Unset those two variables to use the owner account directly, or use the SDK's account-abstraction path.",
+    );
+  }
+
+  const ownerName = env.METRIK_AGENT_CDP_OWNER_NAME as string;
+  let account: Account;
+  try {
+    const resolved = await resolveAgentWallet({
+      cdp: {
+        apiKeyId: env.CDP_API_KEY_ID as string,
+        apiKeySecret: env.CDP_API_KEY_SECRET as string,
+        walletSecret: env.CDP_WALLET_SECRET as string,
+        ownerName,
+      },
+    });
+    account = resolved.account;
+  } catch (error) {
+    // Reaching CDP is a network call against an authenticated API, so this is
+    // where a wrong key, a revoked key or an outage surfaces. Say which wallet
+    // failed; the underlying message carries the rest.
+    throw configError(
+      `could not resolve the CDP wallet "${ownerName}"`,
+      `check ${CDP_ENV_VARS.join(", ")}, and that '@coinbase/cdp-sdk' (an optional peer dependency) is installed. Underlying error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return {
+    source: "cdp",
+    account: assertLocalSigner(account, "cdp"),
+    description: `${account.address} (CDP account "${ownerName}")`,
+  };
+}
+
+/**
+ * The raw `METRIK_AGENT_PRIVATE_KEY` read, kept separate so the wallet-source
+ * precedence above reads as one list rather than as nested conditionals.
+ */
+export function optionalCliAccount(
+  env: NodeJS.ProcessEnv,
+): LocalAccount | null {
+  const raw = env[PRIVATE_KEY_ENV];
+  if (raw === undefined || raw.length === 0) return null;
+  if (!/^0x[0-9a-fA-F]{64}$/.test(raw)) {
+    throw configError(
+      `${PRIVATE_KEY_ENV} must be a 0x-prefixed 32-byte hex private key`,
+    );
+  }
+  return privateKeyToAccount(raw as `0x${string}`);
+}
+
+/**
+ * Every CLI signing path needs a LOCAL signer: fund-moving commands broadcast
+ * through `http(--rpc-url)`, which cannot sign, and `invoke` needs a
+ * `LocalAccount` to sign the EIP-712 capability. A JSON-RPC account (Privy's
+ * adapters) would type-check as an `Account` and then fail somewhere inside
+ * viem with a message about a missing method, so it is rejected here with the
+ * actual reason.
+ */
+function assertLocalSigner(
+  account: Account,
+  source: CliWalletSource,
+): LocalAccount {
+  if (account.type === "local") return account;
+  throw configError(
+    `the ${source} wallet returned a ${account.type} account, which cannot sign locally`,
+    "the CLI broadcasts through --rpc-url and signs EIP-712 capabilities in-process, so it needs a local signer.",
+  );
+}
+
+function isSet(value: string | undefined): boolean {
+  return value !== undefined && value.length > 0;
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return value === "true" || value === "1";
+}

package/src/frameworks/agentkit.ts

@@ -21,6 +21,7 @@ import {
 } from "../discovery/registry.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
+  isCheckpointStream,
   MandateDeniedError,
   VerifiedStreamAgentClient,
   type AgentSdkClientFactory,
@@ -400,9 +401,13 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
 
     return (
       `Stream ${streamId} is ${stream.status}${paused ? " (payment halted)" : ""}. ` +
-      `Verified accrued: ${formatUsdc(stream.accrued)} USDC of ${formatUsdc(stream.deposit)} deposited. ` +
-      `Claimable by seller: ${formatUsdc(claimable)} USDC. Reclaimable by buyer: ${formatUsdc(reclaimable)} USDC. ` +
-      `Consecutive failed checks: ${stream.consecutiveFailures}.`
+      (isCheckpointStream(stream)
+        ? `Verified entitlement: ${formatUsdc(stream.settledCumulative)} USDC of ` +
+          `${formatUsdc(stream.deposit)} deposited, of which ` +
+          `${formatUsdc(stream.claimedCumulative)} USDC has been claimed. `
+        : `Verified accrued: ${formatUsdc(stream.accrued)} USDC of ` +
+          `${formatUsdc(stream.deposit)} deposited. `) +
+      `Claimable by seller: ${formatUsdc(claimable)} USDC. Reclaimable by buyer: ${formatUsdc(reclaimable)} USDC.`
     );
   }
 

package/src/frameworks/crewai.ts

@@ -23,13 +23,24 @@ export interface CrewAiVerifiedStreamMcpConfigOptions {
   readonly cacheToolsList?: boolean;
 }
 
+/**
+ * The default launcher: the `metrik-mcp` bin this package ships.
+ *
+ * It used to be `pnpm mcp:stdio`, which only resolves INSIDE this repository —
+ * a CrewAI user who installed `@absol-labs/agent` from npm got a config that
+ * could never start. `metrik-mcp` is on `PATH` wherever the package is
+ * installed (npm/pnpm link it into `node_modules/.bin`), and `npx` resolves it
+ * with no install at all.
+ */
+export const CREWAI_DEFAULT_MCP_COMMAND = "metrik-mcp";
+
 export function createCrewAiVerifiedStreamMcpConfig(
   options: CrewAiVerifiedStreamMcpConfigOptions = {},
 ): CrewAiVerifiedStreamMcpConfig {
   return {
     transport: "stdio",
-    command: options.command ?? "pnpm",
-    args: options.args ?? ["mcp:stdio"],
+    command: options.command ?? CREWAI_DEFAULT_MCP_COMMAND,
+    args: options.args ?? [],
     env: options.env ?? {},
     allowedToolNames:
       options.allowedToolNames ?? CREWAI_VERIFIED_STREAM_TOOL_NAMES,

package/src/frameworks/eliza.ts

@@ -15,6 +15,7 @@ import {
 } from "../discovery/registry.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
+  isCheckpointStream,
   type MandateAuthorizedStreamActionInput,
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamResult,
@@ -733,9 +734,19 @@ function serializeStreamStatus(
       ...result.stream,
       deposit: result.stream.deposit.toString(),
       ratePerSecond: result.stream.ratePerSecond.toString(),
-      accrued: result.stream.accrued.toString(),
-      claimed: result.stream.claimed.toString(),
-      lastSequence: result.stream.lastSequence.toString(),
+      // The two escrow generations report entitlement differently; emit the
+      // vocabulary of whichever one answered rather than inventing a shared one.
+      ...(isCheckpointStream(result.stream)
+        ? {
+            settledCumulative: result.stream.settledCumulative.toString(),
+            claimedCumulative: result.stream.claimedCumulative.toString(),
+            feesPaid: result.stream.feesPaid.toString(),
+          }
+        : {
+            accrued: result.stream.accrued.toString(),
+            claimed: result.stream.claimed.toString(),
+            lastSequence: result.stream.lastSequence.toString(),
+          }),
     },
     claimable: result.claimable.toString(),
     reclaimable: result.reclaimable.toString(),

package/src/frameworks/langchain.ts

@@ -9,6 +9,7 @@ import {
 } from "../discovery/registry.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
+  isCheckpointStream,
   type MandateAuthorizedStreamActionInput,
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamResult,
@@ -332,9 +333,19 @@ function serializeStreamStatus(
       ...result.stream,
       deposit: result.stream.deposit.toString(),
       ratePerSecond: result.stream.ratePerSecond.toString(),
-      accrued: result.stream.accrued.toString(),
-      claimed: result.stream.claimed.toString(),
-      lastSequence: result.stream.lastSequence.toString(),
+      // The two escrow generations report entitlement differently; emit the
+      // vocabulary of whichever one answered rather than inventing a shared one.
+      ...(isCheckpointStream(result.stream)
+        ? {
+            settledCumulative: result.stream.settledCumulative.toString(),
+            claimedCumulative: result.stream.claimedCumulative.toString(),
+            feesPaid: result.stream.feesPaid.toString(),
+          }
+        : {
+            accrued: result.stream.accrued.toString(),
+            claimed: result.stream.claimed.toString(),
+            lastSequence: result.stream.lastSequence.toString(),
+          }),
     },
     claimable: result.claimable.toString(),
     reclaimable: result.reclaimable.toString(),

package/src/gateway/server-entry.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startCallerAuthGatewayServerFromEnv } from "./http-server.js";
 
 /**

package/src/index.ts

@@ -104,6 +104,8 @@ export {
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamOptions,
   type ReclaimVerifiedStreamResult,
+  isCheckpointStream,
+  type StreamStatusStream,
   type StreamStatusView,
   type VerifiedStreamAgentOpener,
 } from "./sdk/client.js";

package/src/mcp/http-server.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startHostedMcpHttpServerFromEnv } from "./http.js";
 
 /**

package/src/mcp/server.ts

@@ -20,6 +20,7 @@ import {
   ServerMandateConfigError,
 } from "../mandates/env.js";
 import {
+  isCheckpointStream,
   VerifiedStreamAgentClient,
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamResult,
@@ -798,10 +799,34 @@ export function createVerifiedStreamMcpServer(
   };
 }
 
+/** One readable line per invalid or missing environment variable. */
+function describeEnvIssues(error: z.ZodError): string {
+  const seen = new Set<string>();
+  for (const issue of error.issues) {
+    const name = issue.path.join(".");
+    seen.add(
+      issue.code === "invalid_type" && issue.received === "undefined"
+        ? `${name} is not set`
+        : `${name} is invalid (${issue.message})`,
+    );
+  }
+  return [...seen].join("; ");
+}
+
 export function parseMetrikAgentEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): ParsedMetrikAgentEnv {
-  const parsed = metrikAgentEnvSchema.parse(env);
+  const result = metrikAgentEnvSchema.safeParse(env);
+  if (!result.success) {
+    // `.parse()` threw a ZodError whose message is a JSON array of issue
+    // objects. `metrik-mcp` is started by an MCP host and fails closed on stdio,
+    // so that array was the ONLY thing an operator ever saw — a correct failure
+    // rendered as noise. Name the variables instead.
+    throw new Error(
+      `metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP/Privy variables). METRIK_AGENT_CHAIN_ID defaults to Base Sepolia (${baseSepolia.id}).`,
+    );
+  }
+  const parsed = result.data;
   const chainId = Number(parsed.METRIK_AGENT_CHAIN_ID ?? baseSepolia.id);
   if (!Number.isInteger(chainId) || chainId <= 0) {
     throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
@@ -859,6 +884,11 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
       chain: parsed.chain,
       transport: http(parsed.rpcUrl),
       escrow: parsed.escrow,
+      // Declare the escrow as V2 as well. Without this the SDK treats the
+      // client as V1 and routes claimable()/reclaimable() to the legacy ABI,
+      // which reverts against StreamEscrowV2 — the checkpoint escrow replaced
+      // those one-argument views with proof-carrying ones.
+      escrowV2: parsed.escrow,
       usdc: parsed.usdc,
       settlementTarget: {
         chainId: parsed.chain.id,
@@ -943,15 +973,30 @@ function serializeStreamStatus(
       operator: status.stream.operator,
       serviceRef: status.stream.serviceRef,
       deposit: status.stream.deposit.toString(),
+      // Informational on a checkpoint escrow: it stores the rate but computes
+      // no accrual. Emit the vocabulary of whichever escrow generation answered
+      // instead of flattening two incompatible tuples into one shape.
       ratePerSecond: status.stream.ratePerSecond.toString(),
-      accrued: status.stream.accrued.toString(),
-      claimed: status.stream.claimed.toString(),
       openedAt: status.stream.openedAt,
       expiresAt: status.stream.expiresAt,
-      lastVerifiedAt: status.stream.lastVerifiedAt,
-      lastSequence: status.stream.lastSequence.toString(),
-      consecutiveFailures: status.stream.consecutiveFailures,
       status: status.stream.status,
+      ...(isCheckpointStream(status.stream)
+        ? {
+            settlement: "checkpoint" as const,
+            settledCumulative: status.stream.settledCumulative.toString(),
+            claimedCumulative: status.stream.claimedCumulative.toString(),
+            feesPaid: status.stream.feesPaid.toString(),
+            closedAt: status.stream.closedAt,
+            reclaimed: status.stream.reclaimed,
+          }
+        : {
+            settlement: "per-attestation" as const,
+            accrued: status.stream.accrued.toString(),
+            claimed: status.stream.claimed.toString(),
+            lastVerifiedAt: status.stream.lastVerifiedAt,
+            lastSequence: status.stream.lastSequence.toString(),
+            consecutiveFailures: status.stream.consecutiveFailures,
+          }),
     },
     claimable: status.claimable.toString(),
     reclaimable: status.reclaimable.toString(),

package/src/mcp/stdio.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startVerifiedStreamMcpServerStdio } from "./server.js";
 
 startVerifiedStreamMcpServerStdio().catch((error) => {

package/src/sdk/client.ts

@@ -3,6 +3,7 @@ import {
   type HireComputeResult,
   type StreamProofClientConfig,
   type StreamProofStream,
+  type StreamV2,
 } from "@absol-labs/sdk";
 
 import {
@@ -25,8 +26,23 @@ export interface OpenVerifiedStreamInput {
   readonly revokedMandateIds?: Iterable<`0x${string}`>;
 }
 
+/**
+ * A stream as read from the configured escrow. Checkpoint escrows (V2) and the
+ * legacy per-attestation escrow (V1) expose incompatible tuples, so the view
+ * carries whichever one the client is pointed at. Narrow with
+ * {@link isCheckpointStream} before touching version-specific fields.
+ */
+export type StreamStatusStream = StreamProofStream | StreamV2;
+
+/** True when the stream came from a checkpoint-settled (V2) escrow. */
+export function isCheckpointStream(
+  stream: StreamStatusStream,
+): stream is StreamV2 {
+  return "settledCumulative" in stream;
+}
+
 export interface StreamStatusView {
-  readonly stream: StreamProofStream;
+  readonly stream: StreamStatusStream;
   readonly claimable: bigint;
   readonly reclaimable: bigint;
 }
@@ -63,12 +79,26 @@ export interface AgentSdkClient {
     readonly ratePerSecond: bigint;
     readonly maxDurationSeconds: number;
   }): Promise<HireComputeResult>;
+  // Both decoders. The SDK deliberately makes `getStream` throw once a V2
+  // escrow is configured (the tuples are incompatible), so the caller must pick
+  // based on configuration rather than probing.
   getStream(streamId: `0x${string}`): Promise<StreamProofStream>;
+  getStreamV2(streamId: `0x${string}`): Promise<StreamV2>;
   claimable(streamId: `0x${string}`): Promise<bigint>;
   reclaimable(streamId: `0x${string}`): Promise<bigint>;
   claim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   close(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   reclaim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  /**
+   * The BUYER's no-proof escape hatch. Every other buyer path to the money
+   * (`reclaim` -> `reclaimWithProof`) needs a Merkle proof fetched from the
+   * oracle, so it is only as available as the oracle is. `reclaimUnverified`
+   * takes no proof, no quorum and no guardian — it is the path that exists
+   * precisely for the case where that dependency has failed.
+   */
+  reclaimUnverified(
+    streamId: `0x${string}`,
+  ): Promise<StreamProofTransactionResult>;
 }
 
 export type AgentSdkClientFactory = (
@@ -93,6 +123,12 @@ export class MandateDeniedError extends Error {
 
 export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
   private readonly sdkClient: AgentSdkClient;
+  /**
+   * Whether the configured escrow is checkpoint-settled. Set once from config:
+   * the SDK throws rather than guessing if the wrong decoder is used, so this
+   * has to be decided here instead of discovered by trial.
+   */
+  private readonly checkpointSettled: boolean;
 
   constructor(
     config: StreamProofClientConfig,
@@ -101,6 +137,15 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
     this.sdkClient = (options.createSdkClient ?? defaultSdkClientFactory)(
       config,
     );
+    this.checkpointSettled = config.escrowV2 !== undefined;
+  }
+
+  private async readStream(
+    streamId: `0x${string}`,
+  ): Promise<StreamStatusStream> {
+    return this.checkpointSettled
+      ? await this.sdkClient.getStreamV2(streamId)
+      : await this.sdkClient.getStream(streamId);
   }
 
   async openVerifiedStream(
@@ -132,7 +177,7 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
 
   async getStreamStatus(streamId: `0x${string}`): Promise<StreamStatusView> {
     const [stream, claimable, reclaimable] = await Promise.all([
-      this.sdkClient.getStream(streamId),
+      this.readStream(streamId),
       this.sdkClient.claimable(streamId),
       this.sdkClient.reclaimable(streamId),
     ]);
@@ -166,7 +211,29 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
   }
 
   /**
-   * Authorizes a BUYER-RECOVERY action (close / reclaim). These only return
+   * Buyer-only escape hatch: reclaim WITHOUT a checkpoint proof, available only
+   * once `block.timestamp >= expiresAt + escapeGraceSeconds` on the escrow.
+   *
+   * Authorized exactly like `close` / `reclaim` — on the mandate owner's
+   * signature alone (see {@link authorizeBuyerRecovery}) — because it only
+   * returns the buyer's own unspent escrow. It is a SEPARATE method rather than
+   * an option on {@link reclaimStream} because it is not an alternative route to
+   * the same outcome: `reclaimUnverified` pays the buyer
+   * `deposit - claimedCumulative` and permanently forfeits every operator
+   * voucher that was earned but not yet redeemed on-chain.
+   *
+   * Takes no `closeFirst`: the escrow gates this path on `expiresAt`, never on
+   * `closedAt`, so closing first would buy nothing but a second gas fee.
+   */
+  async reclaimUnverifiedStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    await this.authorizeBuyerRecovery(input);
+    return await this.sdkClient.reclaimUnverified(input.streamId);
+  }
+
+  /**
+   * Authorizes a BUYER-RECOVERY action (close / reclaim / reclaimUnverified). These only return
    * unspent funds to the buyer or stop payment, so they are authorized on
    * mandate-owner signature ALONE — never gated by expiry, revocation, or caps,
    * which would otherwise let a lapsed mandate strand the buyer's own funds.
@@ -183,7 +250,7 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
   private async authorizeExistingStreamAction(
     input: MandateAuthorizedStreamActionInput,
   ): Promise<void> {
-    const stream = await this.sdkClient.getStream(input.streamId);
+    const stream = await this.readStream(input.streamId);
     const decision = await checkMandate(
       input.signedMandate,
       {