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

package/src/cli/commands/claim.ts

@@ -10,6 +10,9 @@ import {
   resolveCliWallet,
 } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import type { CliReadClient } from "../deps.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
+import type { StreamV2 } from "@absol-labs/sdk";
 
 /**
  * The seller's side of the loop.
@@ -52,7 +55,7 @@ export const claimCommand: CommandSpec = {
     }
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
-    await assertCanPayGas(read, account.address);
+    await assertCanPayGas(read, account.address, config.network);
 
     const stream = await read.getStreamV2(streamId);
     if (stream.operator.toLowerCase() !== account.address.toLowerCase()) {
@@ -65,40 +68,20 @@ export const claimCommand: CommandSpec = {
       );
     }
 
-    // Accrual lives in the oracle's checkpoint proof, never in the stream tuple.
-    // No proof means no claim is possible yet, and saying that is better than
-    // paying gas for a `NothingToClaim()` revert.
-    let cumulativeAmount: bigint;
-    try {
-      cumulativeAmount = (await read.checkpointProof(streamId))
-        .cumulativeAmount;
-    } catch (error) {
-      throw new CliError(
-        "no checkpoint covers this stream yet, so there is nothing provable to claim",
-        {
-          exitCode: 4,
-          hint: `the oracle publishes roughly every 15-22s and pays only for intervals that verified; ${describeError(
-            error,
-          )}`,
-          cause: error,
-        },
-      );
-    }
-
-    const claimable = await read.claimableForV2(streamId, cumulativeAmount);
-    if (claimable === 0n) {
-      throw new CliError("this stream has nothing claimable right now", {
-        exitCode: 4,
-        hint: `everything checkpointed so far has already been claimed. See where it stands:  metrik status ${streamId}`,
-      });
-    }
+    const plan = await planClaim(
+      read,
+      streamId,
+      stream,
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
+    if (plan.kind === "nothing") throw plan.error;
 
     const write = deps.createWriteClient(
       config,
       account,
       writeClientOptions(wallet),
     );
-    const result = await write.claimStream({
+    const action = {
       streamId,
       // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
       signedMandate: isPolicyEnforced(wallet)
@@ -106,21 +89,173 @@ export const claimCommand: CommandSpec = {
         : await signClaimMandate(account, config.chainId),
       spentSoFarUsdc: 0n,
       nowSeconds: deps.nowSeconds(),
-    });
+    };
+    let result: { readonly txHash: `0x${string}` };
+    if (plan.kind === "claimWithProof") {
+      result = await write.claimStream(action);
+    } else {
+      if (write.claimProvenStream === undefined) {
+        throw new CliError(
+          "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
+          {
+            exitCode: 3,
+            hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
+          },
+        );
+      }
+      result = await write.claimProvenStream(action);
+    }
 
     out.result({
       streamId,
       txHash: result.txHash,
       operator: stream.operator,
-      claimed: claimable,
-      verifiedCumulative: cumulativeAmount,
+      claimed: plan.claimable,
+      method: plan.kind,
+      verifiedCumulative: plan.verifiedCumulative,
+      provenCumulative: plan.provenCumulative,
     });
     out.print("Claimed.");
     out.table([
       ["streamId", streamId],
       ["tx", result.txHash],
       ["operator", stream.operator],
-      ["claimed", `${formatUsdc(claimable)} (net of protocol fee)`],
+      ["claimed", `${formatUsdc(plan.claimable)} (net of protocol fee)`],
+      [
+        "via",
+        plan.kind === "claimWithProof"
+          ? "claimWithProof (the oracle's current checkpoint proof)"
+          : `claimProven (the on-chain proven high-water, ${formatUsdc(plan.provenCumulative ?? 0n)} gross — no current checkpoint proof pays more)`,
+      ],
     ]);
   },
 };
+
+/**
+ * Which claim, if any, `metrik claim` would send. Reads only, so it is
+ * testable (and checkable against a live stream) without a key.
+ *
+ * - `claimWithProof` pays `min(proofCumulative, deposit) − claimed` against ANY
+ *   retained checkpoint root.
+ * - `claimProven` (StreamEscrowV3) pays `min(provenCumulative, deposit) −
+ *   claimed` with NO proof: the high-water was itself proven against a signed
+ *   root when it was recorded. It is the only way to collect proven value whose
+ *   root has rotated out of the retained set, or that a later root regressed.
+ *
+ * Both are asked of the escrow (`claimableFor` at each cumulative; the escrow
+ * pays a claim with exactly that math), and the larger is chosen. A proof
+ * claim wins a tie, because it also raises the proven high-water. Nothing is
+ * chosen when both pay zero, so no gas is spent to learn `NothingToClaim`.
+ */
+export type ClaimPlan =
+  | {
+      readonly kind: "claimWithProof" | "claimProven";
+      /** What the operator receives, net of the protocol fee. */
+      readonly claimable: bigint;
+      /** The current proof's cumulative; `null` when no proof was available. */
+      readonly verifiedCumulative: bigint | null;
+      /** V3 proven high-water; `null` on V2 or when unreadable. */
+      readonly provenCumulative: bigint | null;
+    }
+  | { readonly kind: "nothing"; readonly error: CliError };
+
+export async function planClaim(
+  read: CliReadClient,
+  streamId: `0x${string}`,
+  stream: Pick<StreamV2, "claimedCumulative">,
+  escrowGeneration: string,
+): Promise<ClaimPlan> {
+  let verifiedCumulative: bigint | null = null;
+  let proofError: unknown = null;
+  try {
+    verifiedCumulative = (await read.checkpointProof(streamId))
+      .cumulativeAmount;
+  } catch (error) {
+    proofError = error;
+  }
+
+  let provenCumulative: bigint | null = null;
+  let provenError: string | null = null;
+  if (escrowGeneration === "v3") {
+    if (read.provenCumulativeOf === undefined) {
+      provenError = "this read client cannot read provenCumulativeOf";
+    } else {
+      try {
+        provenCumulative = await read.provenCumulativeOf(streamId);
+      } catch (error) {
+        provenError = describeError(error);
+      }
+    }
+  }
+
+  const [proofClaimable, provenClaimable] = await Promise.all([
+    verifiedCumulative === null
+      ? 0n
+      : read.claimableForV2(streamId, verifiedCumulative),
+    // `claimProven` pays at the high-water, so it is worth asking only when
+    // the high-water is above what has already been claimed.
+    provenCumulative === null || provenCumulative <= stream.claimedCumulative
+      ? 0n
+      : read.claimableForV2(streamId, provenCumulative),
+  ]);
+
+  if (proofClaimable > 0n && proofClaimable >= provenClaimable) {
+    return {
+      kind: "claimWithProof",
+      claimable: proofClaimable,
+      verifiedCumulative,
+      provenCumulative,
+    };
+  }
+  if (provenClaimable > 0n) {
+    return {
+      kind: "claimProven",
+      claimable: provenClaimable,
+      verifiedCumulative,
+      provenCumulative,
+    };
+  }
+
+  if (provenCumulative !== null && provenCumulative > 0n) {
+    return {
+      kind: "nothing",
+      error: new CliError("this stream has nothing to claim", {
+        exitCode: 4,
+        hint: `everything proven on-chain for it (${formatUsdc(provenCumulative)} gross) has already been claimed${
+          verifiedCumulative === null
+            ? ", and the latest checkpoint no longer contains it"
+            : ""
+        }. See where it stands:  metrik status ${streamId}`,
+      }),
+    };
+  }
+  if (verifiedCumulative === null) {
+    // Accrual lives in the oracle's checkpoint proof (and, on V3, the proven
+    // high-water), never in the stream tuple. Saying so is better than paying
+    // gas for a `NothingToClaim()` revert.
+    return {
+      kind: "nothing",
+      error: new CliError(
+        "no checkpoint covers this stream yet, so there is nothing provable to claim",
+        {
+          exitCode: 4,
+          hint: `the oracle publishes roughly every 15-22s and pays only for intervals that verified; ${describeError(
+            proofError,
+          )}${
+            provenError === null
+              ? ""
+              : `; the on-chain proven high-water could not be read either (${provenError})`
+          }`,
+          cause: proofError,
+        },
+      ),
+    };
+  }
+  return {
+    kind: "nothing",
+    error: new CliError("this stream has nothing claimable right now", {
+      exitCode: 4,
+      hint: `everything checkpointed so far has already been claimed. See where it stands:  metrik status ${streamId}`,
+    }),
+  };
+}

package/src/cli/commands/close.ts

@@ -1,5 +1,5 @@
 import { assertTestnetRpc, parseBytes32 } from "../config.js";
-import { usageError } from "../errors.js";
+import { CliError, usageError } from "../errors.js";
 import { signRecoveryMandate } from "../mandate.js";
 import { assertCanPayGas } from "../preflight.js";
 import { writeClientOptions } from "../deps.js";
@@ -27,7 +27,28 @@ export const closeCommand: CommandSpec = {
     const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
-    await assertCanPayGas(read, account.address);
+    // An x402 opener stream is closed through the opener, by its PAYER. Say so
+    // up front: the escrow would answer anyone else with NotBuyer, and the SDK
+    // refuses a non-payer before anything is sent.
+    const stream = await read.getStreamV2(streamId).catch(() => null);
+    const opener = stream?.opener ?? null;
+    if (opener !== null && stream !== null) {
+      out.note(
+        `x402 stream: closing through the opener ${opener}; only its payer ${stream.payer} may close it.`,
+      );
+    }
+    try {
+      await assertCanPayGas(read, account.address, config.network);
+    } catch (error) {
+      if (opener !== null && error instanceof CliError) {
+        throw new CliError(error.message, {
+          exitCode: error.exitCode,
+          hint: `${error.hint ?? ""} This stream was bought over x402: a payer with no gas can close it through the seller's refund relay instead — \`metrik refund ${streamId} --refund-url <url> --close\`.`.trim(),
+          cause: error,
+        });
+      }
+      throw error;
+    }
 
     // A policy-enforced wallet signs no mandate of its own: this is a
     // buyer-recovery action, the escrow gates it on the buyer address and the
@@ -49,11 +70,23 @@ export const closeCommand: CommandSpec = {
       nowSeconds: deps.nowSeconds(),
     });
 
-    out.result({ streamId, txHash: result.txHash, closed: true });
+    out.result({
+      streamId,
+      txHash: result.txHash,
+      closed: true,
+      opener,
+      payer: stream?.payer ?? null,
+    });
     out.print("Stream closed.");
     out.table([
       ["streamId", streamId],
       ["tx", result.txHash],
+      ...(opener === null
+        ? []
+        : ([
+            ["via opener", opener],
+            ["payer", stream?.payer ?? "-"],
+          ] as const)),
     ]);
     out.print("");
     out.print(

package/src/cli/commands/invoke.ts

@@ -157,7 +157,7 @@ function explainInvokeFailure(error: unknown, signer: string): unknown {
   return error;
 }
 
-function parseHeaders(raw: readonly string[]): Record<string, string> {
+export function parseHeaders(raw: readonly string[]): Record<string, string> {
   const headers: Record<string, string> = {};
   for (const entry of raw) {
     const separator = entry.indexOf(":");
@@ -171,7 +171,10 @@ function parseHeaders(raw: readonly string[]): Record<string, string> {
   return headers;
 }
 
-function hasHeader(headers: Record<string, string>, name: string): boolean {
+export function hasHeader(
+  headers: Record<string, string>,
+  name: string,
+): boolean {
   return Object.keys(headers).some(
     (key) => key.toLowerCase() === name.toLowerCase(),
   );

package/src/cli/commands/mcp.ts

@@ -1,6 +1,6 @@
 import { booleanFlag, stringFlag } from "../args.js";
 import { packageVersion } from "../version.js";
-import { CDP_ENV_VARS, PRIVATE_KEY_ENV } from "../wallet.js";
+import { CDP_ENV_VARS, PRIVATE_KEY_ENV, PRIVY_ENV_VARS } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
 /** The published executable an MCP host starts. Declared in `package.json#bin`. */
@@ -82,6 +82,17 @@ export const mcpCommand: CommandSpec = {
       },
     };
 
+    // Honesty about the one wallet source this block cannot carry. The CLI
+    // resolves a Privy wallet (step 3), but the MCP server's own resolver,
+    // `parseAgentWalletEnv()`, reads a raw key or CDP and nothing else — there
+    // is no Privy path from the environment there. Printing Privy variables
+    // into a config the server would ignore is the failure this says out loud.
+    if (PRIVY_ENV_VARS.some((variable) => (env[variable] ?? "").length > 0)) {
+      out.note(
+        `note: this environment configures a Privy wallet, which the CLI can use but \`${MCP_BIN}\` cannot — its wallet resolver reads ${PRIVATE_KEY_ENV} or the CDP variables only. The block below therefore carries a key placeholder; give the MCP server a raw key or a CDP account.`,
+      );
+    }
+
     out.result(document);
     out.print(
       `Paste this into your MCP client's config (Claude Desktop: claude_desktop_config.json), then replace every <…> placeholder:`,
@@ -102,6 +113,11 @@ export const mcpCommand: CommandSpec = {
  * Wallet variables, shaped to match how the environment running this command is
  * already configured — CDP if that is what is set, a raw key otherwise.
  *
+ * Privy is deliberately absent: `parseAgentWalletEnv()`, which is what the MCP
+ * server resolves its wallet with, has no Privy branch. A Privy block here
+ * would print a config that cannot start the server. The command says so on
+ * stderr instead.
+ *
  * Values are ALWAYS placeholders. `metrik` prints derived addresses and never
  * echoes a credential, and a config block is the single most likely thing to be
  * pasted into a chat window or an issue.
@@ -116,7 +132,7 @@ function walletEnv(env: NodeJS.ProcessEnv): Record<string, string> {
     );
   }
   return {
-    [PRIVATE_KEY_ENV]: "<0x… a funded Base Sepolia test key>",
+    [PRIVATE_KEY_ENV]: "<0x… a funded testnet key>",
   };
 }
 

package/src/cli/commands/open.ts

@@ -23,7 +23,12 @@ import {
   resolveCliWallet,
   PRIVATE_KEY_ENV,
 } from "../wallet.js";
-import { resolveListing } from "../listings.js";
+import { resolveListingRecord } from "../listings.js";
+import {
+  listingRateBand,
+  rateBandRefusal,
+  SignedRateBoundsError,
+} from "../../discovery/rate-band.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
 export const openCommand: CommandSpec = {
@@ -89,14 +94,21 @@ export const openCommand: CommandSpec = {
     if (account !== null && !dryRun) {
       // Both balances, before anything is signed. Gas first: a wallet with no
       // ETH cannot send the approval that the USDC check exists to protect.
-      await assertCanPayGas(read, account.address);
-      await assertCanFundStream(read, account.address, budgetUsdc);
+      await assertCanPayGas(read, account.address, config.network);
+      await assertCanFundStream(
+        read,
+        account.address,
+        budgetUsdc,
+        config.network,
+      );
     }
 
     const operatorOverride = stringFlag(args, "operator");
-    const listing = await resolveListing(context, serviceRef, {
+    const resolution = await resolveListingRecord(context, serviceRef, {
       required: operatorOverride === undefined,
     });
+    const listing = resolution.listing;
+    await assertRateInSignedBand(context, resolution, ratePerSecondUsdc);
     const operator = (operatorOverride ?? listing?.operator) as
       | `0x${string}`
       | undefined;
@@ -348,6 +360,65 @@ export const openCommand: CommandSpec = {
   },
 };
 
+/**
+ * Refuse a `--rate` outside the band the operator SIGNED, before anything is
+ * signed or broadcast — dry run included, because the rate is an invalid input
+ * for this service exactly like `--rate 0` is.
+ *
+ * The escrow accepts any non-zero rate; the seller's capability gateway does
+ * not, and answers every request on an out-of-band stream with
+ * `403 stream-rate-out-of-bounds`. Without this check the CLI locked a buyer's
+ * deposit in a stream that could never be served, and said nothing.
+ *
+ * - Listing found: its signed descriptor is re-verified and the band enforced.
+ *   A descriptor that does not verify is a refusal (exit 4), never "no band".
+ *   A legacy binding signs no commercial terms, so there is nothing to enforce.
+ * - No listing: only reachable with `--operator`, the CLI's existing,
+ *   explicit escape hatch for a service the registry cannot vouch for. The
+ *   check cannot run, so it is skipped LOUDLY rather than silently. Without
+ *   `--operator` an unreachable registry or a missing listing has already
+ *   failed the command before this point (`resolveListingRecord`).
+ */
+async function assertRateInSignedBand(
+  context: CommandContext,
+  resolution: Awaited<ReturnType<typeof resolveListingRecord>>,
+  ratePerSecondUsdc: bigint,
+): Promise<void> {
+  const { out } = context;
+  if (resolution.record === null) {
+    out.note(
+      resolution.registryUnreachable
+        ? "warning: the operator-signed rate band could NOT be checked because the registry is unreachable. If --rate is outside the band the operator signed, the service's gateway will refuse every request while the deposit stays escrowed. Re-run when the registry answers to have it checked."
+        : "note: this serviceRef has no verified listing, so there is no operator-signed rate band to check --rate against.",
+    );
+    return;
+  }
+  let bounds;
+  try {
+    bounds = await listingRateBand(resolution.record);
+  } catch (error) {
+    if (error instanceof SignedRateBoundsError) {
+      throw new CliError(
+        `the listing's operator-signed rate band could not be verified: ${error.message}`,
+        {
+          exitCode: 4,
+          hint: "nothing was broadcast. The CLI will not open a stream against a rate band it cannot verify.",
+          cause: error,
+        },
+      );
+    }
+    throw error;
+  }
+  if (bounds === null) return;
+  const refusal = rateBandRefusal(ratePerSecondUsdc, bounds, "--rate");
+  if (refusal !== undefined) {
+    throw new CliError(refusal, {
+      exitCode: 2,
+      hint: "pick a --rate inside the signed band (`--units atomic` takes base units; see `metrik discover` for each listing's band).",
+    });
+  }
+}
+
 /**
  * What the buyer is actually paying for.
  *