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

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.
  *

package/src/cli/commands/pay.ts

@@ -0,0 +1,442 @@
+import type { X402PayerSigner } from "@absol-labs/sdk/x402";
+
+import {
+  DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+  parseServerMandateCapsEnv,
+  signServerMandate,
+  type ServerMandateCaps,
+} from "../../mandates/env.js";
+import {
+  booleanFlag,
+  integerFlag,
+  jsonBodyFlag,
+  stringFlag,
+  stringFlags,
+} from "../args.js";
+import {
+  formatDuration,
+  formatUsdc,
+  parseAmountUnits,
+  parseDurationSeconds,
+  parseUsdcAmount,
+} from "../amounts.js";
+import { assertTestnetRpc } from "../config.js";
+import { rpcTransport, type CliX402 } from "../deps.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { usdcFundingHint } from "../../network.js";
+import { isPrivyWalletSource, resolveCliWallet } from "../wallet.js";
+import { hasHeader, parseHeaders } from "./invoke.js";
+import type { X402PostSignatureError } from "../../x402-buyer/pay.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/** Default stream window a request-sized mandate allows (one day). */
+const DEFAULT_MAX_DURATION_SECONDS = 86_400;
+/** Longest response body printed in human mode before it is truncated. */
+const MAX_PRINTED_BODY_CHARS = 64 * 1024;
+
+export const payCommand: CommandSpec = {
+  name: "pay",
+  summary:
+    "Pay an x402 endpoint into a recoverable escrow stream, under a spend mandate",
+  usage:
+    'metrik pay <url> [--json \'{"text":"hi"}\' | --data <body>] [--method POST] [--header "K: V"] --max-amount <usdc> [--max-rate <usdc/s>] [--max-duration <seconds>] [--min-duration <seconds>] [--operator <address>] [--units atomic]',
+  flags: [
+    "data",
+    "json-body",
+    "method",
+    "header",
+    "max-amount",
+    "max-rate",
+    "max-duration",
+    "min-duration",
+    "operator",
+    "units",
+    "allow-legacy-factory",
+  ],
+  // It moves the payer's USDC (an EIP-3009 authorization the facilitator
+  // settles into the escrow). The PAYER broadcasts nothing and needs no gas,
+  // but it is a fund-moving command and is gated like one.
+  signs: true,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const x402 = requireX402(deps.x402);
+    const [urlArg] = args.positionals;
+    if (urlArg === undefined) {
+      throw usageError("metrik pay requires the <url> of an x402 endpoint");
+    }
+    const url = parseResourceUrl(urlArg);
+    const units = parseAmountUnits(stringFlag(args, "units"));
+    const maxAmountRaw = stringFlag(args, "max-amount");
+    const maxAmount =
+      maxAmountRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxAmountRaw, units, "max-amount");
+    const maxRateRaw = stringFlag(args, "max-rate");
+    const maxRate =
+      maxRateRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxRateRaw, units, "max-rate");
+    const maxDurationRaw = stringFlag(args, "max-duration");
+    const maxDuration =
+      maxDurationRaw === undefined
+        ? undefined
+        : parseDurationSeconds(maxDurationRaw);
+    const minDuration = integerFlag(args, "min-duration");
+    const operator = stringFlag(args, "operator");
+    if (operator !== undefined && !/^0x[0-9a-fA-F]{40}$/.test(operator)) {
+      throw usageError(`--operator must be an EVM address (got "${operator}")`);
+    }
+    if (maxAmount !== undefined && maxAmount <= 0n) {
+      throw usageError("--max-amount must be greater than zero");
+    }
+    if (maxRate !== undefined && maxRate <= 0n) {
+      throw usageError("--max-rate must be greater than zero");
+    }
+
+    const init = buildRequest(context);
+
+    // The mandate: an operator-set standing ceiling (METRIK_AGENT_MANDATE_*),
+    // or one sized to exactly this payment. Either way it is SIGNED and
+    // `checkMandate()` gates the quote before anything is signed for the
+    // seller. There is no unbounded path: without standing caps, --max-amount
+    // is required.
+    const envCaps = parseServerMandateCapsEnv(env);
+    if (envCaps === null && maxAmount === undefined) {
+      throw usageError(
+        "metrik pay needs a spend ceiling: pass --max-amount <usdc> (or configure a standing mandate with METRIK_AGENT_MANDATE_*)",
+        "no spend without a mandate: the seller picks the price, so the buyer must cap it. Nothing was sent.",
+      );
+    }
+    const caps = intersectCaps(envCaps, {
+      maxAmount,
+      maxRate,
+      maxDuration,
+      operator: operator as `0x${string}` | undefined,
+    });
+
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    if (isPrivyWalletSource(wallet.source)) {
+      throw configError(
+        "metrik pay cannot sign with a Privy wallet",
+        "an x402 payment is an EIP-3009 TransferWithAuthorization signature, and the Privy broker's typed-data policy allows only an InvocationCapability. Pay with METRIK_AGENT_PRIVATE_KEY or a CDP wallet.",
+      );
+    }
+    const { account } = wallet;
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    // The payer needs USDC only — no gas: the facilitator's relayer submits
+    // the authorization. A zero balance is a knowable fact before signing.
+    const balance = await read.usdcBalance(account.address).catch(() => null);
+    if (balance === 0n) {
+      throw new CliError(
+        `wallet ${account.address} holds 0 USDC on ${config.network.name}, so it cannot pay`,
+        {
+          exitCode: 3,
+          hint: `${usdcFundingHint(config.network)}, then re-run. (An x402 payer needs USDC only; no gas.)`,
+        },
+      );
+    }
+
+    const signedMandate = await signServerMandate(account, caps, {
+      chainId: config.chainId,
+    });
+
+    out.note(
+      `paying ${url} (ceiling ${formatUsdc(maxAmount === undefined ? caps.maxPerStreamUsdc : maxAmount < caps.maxPerStreamUsdc ? maxAmount : caps.maxPerStreamUsdc)}, mandate from ${envCaps === null ? "this command" : "METRIK_AGENT_MANDATE_*"}) …`,
+    );
+    const result = await payOrExplain(x402, {
+      url,
+      init,
+      signer: account as unknown as X402PayerSigner,
+      network: config.network,
+      signedMandate,
+      spentSoFarUsdc: 0n,
+      nowSeconds: deps.nowSeconds(),
+      ...(maxAmount === undefined ? {} : { maxAmount }),
+      ...(maxRate === undefined ? {} : { maxRatePerSecond: maxRate }),
+      ...(minDuration === undefined ? {} : { minDurationSeconds: minDuration }),
+      sdkOptions: {
+        transport: rpcTransport(config),
+        // A LEGACY deployment's factory is refused by the SDK unless the
+        // buyer opts in: streams there can still be closed and reclaimed, but
+        // nothing new should open on a generation being retired by default.
+        ...(booleanFlag(args, "allow-legacy-factory")
+          ? { allowLegacyFactory: true }
+          : {}),
+      },
+    });
+
+    const bodyText = await result.response.text();
+    const opener = result.metrikStreamOpener;
+    const quote = result.quote;
+    out.result({
+      paid: result.paid,
+      httpStatus: result.response.status,
+      contentType: result.response.headers.get("content-type"),
+      body: bodyText,
+      streamId: opener?.streamId ?? null,
+      opener: opener?.opener ?? null,
+      refundUrl: opener?.refundUrl ?? null,
+      escrow: opener?.escrow ?? null,
+      deposit: opener?.deposit ?? null,
+      ratePerSecond: opener?.ratePerSecond ?? null,
+      expiresAt: opener?.expiresAt ?? null,
+      operator: quote?.operator ?? null,
+      serviceRef: quote?.serviceRef ?? null,
+      minEarnSeconds: quote?.minEarnSeconds ?? null,
+      mandateSource: envCaps === null ? "request" : "env",
+      refundIsAutomatic: false,
+    });
+
+    if (!result.paid) {
+      out.print(
+        `The endpoint answered ${result.response.status} without asking for payment; nothing was signed or paid.`,
+      );
+      out.print(truncate(bodyText));
+      return;
+    }
+    out.print(`Paid. HTTP ${result.response.status}`);
+    out.print(truncate(bodyText));
+    out.print("");
+    if (opener !== null) {
+      out.table([
+        ["streamId", opener.streamId],
+        ["opener", opener.opener],
+        ["payer", account.address],
+        ...(opener.deposit === null
+          ? []
+          : ([["deposit", formatUsdc(opener.deposit)]] as const)),
+        ...(opener.ratePerSecond === null
+          ? []
+          : ([
+              ["rate", `${formatUsdc(opener.ratePerSecond)} / verified second`],
+            ] as const)),
+        ...(quote?.minEarnSeconds === null ||
+        quote?.minEarnSeconds === undefined
+          ? []
+          : ([
+              [
+                "fully earned after",
+                `${formatDuration(Number(quote.minEarnSeconds))} of verified delivery`,
+              ],
+            ] as const)),
+        ...(opener.expiresAt === null
+          ? []
+          : ([
+              ["expires", new Date(opener.expiresAt * 1000).toISOString()],
+            ] as const)),
+        ["refund url", opener.refundUrl ?? "(the seller advertised no relay)"],
+      ]);
+      out.print("");
+      // A stream on another (e.g. legacy) registered escrow is reached by
+      // naming that escrow; the CLI defaults to the network's current one.
+      const escrowFlag =
+        opener.escrow !== null &&
+        opener.escrow.toLowerCase() !== config.escrow.toLowerCase()
+          ? ` --escrow ${opener.escrow}`
+          : "";
+      out.print(
+        "Refunds are NOT automatic. The seller earns only for verified seconds; whatever is unearned stays in the escrow until someone reclaims it for you:",
+      );
+      out.print(
+        opener.refundUrl === null
+          ? `  metrik reclaim ${opener.streamId}${escrowFlag}      (anyone may send it; the refund always goes to the payer)`
+          : `  metrik refund ${opener.streamId} --refund-url ${opener.refundUrl}${escrowFlag} --close --reclaim`,
+      );
+    }
+  },
+};
+
+const minBig = (a: bigint, b: bigint | undefined): bigint =>
+  b !== undefined && b < a ? b : a;
+
+/**
+ * The mandate this command signs: a standing `METRIK_AGENT_MANDATE_*` ceiling
+ * INTERSECTED with every flag (the most restrictive value wins), or, with no
+ * standing ceiling, one sized to the flags. A flag can only tighten a
+ * standing ceiling, never loosen or bypass it; an `--operator` outside a
+ * standing allowlist is refused outright.
+ */
+export function intersectCaps(
+  envCaps: ServerMandateCaps | null,
+  flags: {
+    readonly maxAmount: bigint | undefined;
+    readonly maxRate: bigint | undefined;
+    readonly maxDuration: number | undefined;
+    readonly operator: `0x${string}` | undefined;
+  },
+): ServerMandateCaps {
+  if (envCaps === null) {
+    const amount = flags.maxAmount as bigint;
+    return {
+      maxPerStreamUsdc: amount,
+      maxTotalUsdc: amount,
+      // No --max-rate: the price is the only cap on how fast the seller can
+      // earn it. Reported as minEarnSeconds so the buyer can see it.
+      maxRatePerSecondUsdc: flags.maxRate ?? amount,
+      maxDurationSeconds: flags.maxDuration ?? DEFAULT_MAX_DURATION_SECONDS,
+      allowedOperators: flags.operator === undefined ? [] : [flags.operator],
+      ttlSeconds: DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+    };
+  }
+  let allowedOperators = envCaps.allowedOperators;
+  if (flags.operator !== undefined) {
+    if (
+      allowedOperators.length > 0 &&
+      !allowedOperators.some(
+        (entry) => entry.toLowerCase() === flags.operator?.toLowerCase(),
+      )
+    ) {
+      throw new CliError(
+        `--operator ${flags.operator} is not in METRIK_AGENT_MANDATE_ALLOWED_OPERATORS`,
+        {
+          exitCode: 3,
+          hint: "a flag can only narrow the standing mandate, never widen it. Nothing was sent.",
+        },
+      );
+    }
+    allowedOperators = [flags.operator];
+  }
+  return {
+    maxPerStreamUsdc: minBig(envCaps.maxPerStreamUsdc, flags.maxAmount),
+    maxTotalUsdc: minBig(envCaps.maxTotalUsdc, flags.maxAmount),
+    maxRatePerSecondUsdc: minBig(envCaps.maxRatePerSecondUsdc, flags.maxRate),
+    maxDurationSeconds:
+      flags.maxDuration !== undefined &&
+      flags.maxDuration < envCaps.maxDurationSeconds
+        ? flags.maxDuration
+        : envCaps.maxDurationSeconds,
+    allowedOperators,
+    ttlSeconds: envCaps.ttlSeconds,
+  };
+}
+
+function requireX402(x402: CliX402 | undefined): CliX402 {
+  if (x402 === undefined) {
+    throw new CliError(
+      "this CLI build has no x402 dependency wired (CliDependencies.x402)",
+      { exitCode: 4 },
+    );
+  }
+  return x402;
+}
+
+function parseResourceUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw usageError(`<url> must be an absolute http(s) URL (got "${raw}")`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw usageError(`<url> must be http(s) (got "${url.protocol}")`);
+  }
+  return url.toString();
+}
+
+function buildRequest(context: CommandContext): RequestInit {
+  const { args } = context;
+  const data = stringFlag(args, "data");
+  const jsonValue = jsonBodyFlag(args);
+  const jsonAlias = stringFlag(args, "json-body");
+  if (jsonValue !== undefined && jsonAlias !== undefined) {
+    throw usageError(
+      "give the JSON body once: --json <body> or --json-body <body>",
+    );
+  }
+  const jsonBody = jsonValue ?? jsonAlias;
+  if (data !== undefined && jsonBody !== undefined) {
+    throw usageError("give either --data or --json <body>, not both");
+  }
+  if (jsonBody !== undefined) {
+    try {
+      JSON.parse(jsonBody);
+    } catch {
+      throw usageError("--json <body> must be valid JSON");
+    }
+  }
+  const body = jsonBody ?? data;
+  const method = (
+    stringFlag(args, "method") ?? (body === undefined ? "GET" : "POST")
+  ).toUpperCase();
+  const headers = parseHeaders(stringFlags(args, "header"));
+  if (jsonBody !== undefined && !hasHeader(headers, "content-type")) {
+    headers["content-type"] = "application/json";
+  }
+  for (const name of Object.keys(headers)) {
+    if (name === "payment-signature" || name === "x-payment") {
+      throw usageError(
+        `do not set the ${name} header: the payment is signed by this command, after the quote passes the mandate`,
+      );
+    }
+  }
+  return {
+    method,
+    headers,
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+function truncate(text: string): string {
+  return text.length <= MAX_PRINTED_BODY_CHARS
+    ? text
+    : `${text.slice(0, MAX_PRINTED_BODY_CHARS)}\n… (${text.length - MAX_PRINTED_BODY_CHARS} more characters; use --json for the whole body)`;
+}
+
+async function payOrExplain(
+  x402: CliX402,
+  input: Parameters<CliX402["pay"]>[0],
+): ReturnType<CliX402["pay"]> {
+  try {
+    return await x402.pay(input);
+  } catch (error) {
+    throw explainPayFailure(error);
+  }
+}
+
+/** Map the SDK's and the mandate's typed failures onto CLI exit codes. */
+export function explainPayFailure(error: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  switch (error.name) {
+    case "X402MandateDeniedError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: "raise --max-amount / --max-rate / --max-duration (or METRIK_AGENT_MANDATE_*) only if you mean to pay that much, that fast, for that long.",
+        cause: error,
+      });
+    case "X402PaymentRefusedError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: /exceeds maxAmount|exceeds maxRatePerSecond/.test(error.message)
+          ? "that ceiling is your spend mandate's (--max-amount / --max-rate or METRIK_AGENT_MANDATE_*), handed to the SDK as a second gate. Nothing was signed."
+          : "the quote failed one of the SDK's protections (wrong network or token, unknown factory, payTo != factory.predict(terms), not an opener payment, ...). Nothing was signed.",
+        cause: error,
+      });
+    case "X402PostSignatureError": {
+      // The signature was handed out: never say "nothing moved" unless the
+      // chain proves the authorization can never be used.
+      const post = error as X402PostSignatureError;
+      const recover =
+        post.streamId === null
+          ? ""
+          : ` Recover the unearned part: metrik refund ${post.streamId} --refund-url <the seller's relay> --close --reclaim (or metrik reclaim ${post.streamId}).`;
+      return new CliError(error.message, {
+        exitCode: 4,
+        hint:
+          post.state === "used"
+            ? `the money LEFT the payer.${post.streamId === null ? " Its stream could not be identified on-chain; keep this output as evidence (see docs/x402.md)." : ` It is in stream ${post.streamId} (opener ${post.opener}).`}${recover}`
+            : post.state === "possibly-used"
+              ? "whether the authorization was used could not be established: treat the payment as SPENT and check USDC.authorizationState before paying again (see docs/x402.md)."
+              : post.state === "unused-but-valid"
+                ? "it has not moved yet, but the seller holds a signature valid until its validBefore: treat it as spent, or cancel it with USDC.cancelAuthorization (needs gas). See docs/x402.md."
+                : "the authorization was never used and has expired: nothing moved.",
+        cause: error,
+      });
+    }
+    default:
+      return error;
+  }
+}

package/src/cli/commands/reclaim-unverified.ts

@@ -14,6 +14,7 @@ import { writeClientOptions } from "../deps.js";
 import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient } from "../deps.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 /**
  * The acknowledgement this command will not run without.
@@ -88,7 +89,7 @@ export const reclaimUnverifiedCommand: CommandSpec = {
     const { account } = wallet;
     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.reclaimed) {
@@ -107,7 +108,12 @@ export const reclaimUnverifiedCommand: CommandSpec = {
     // prevent.
     const grace = await readEscapeGrace(read);
     const now = await readChainNow(read, deps.nowSeconds());
-    const window = escapeHatchWindow(stream, grace, now.seconds);
+    const window = escapeHatchWindow(
+      stream,
+      grace,
+      now.seconds,
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
     if (!window.ready) {
       throw notReady(streamId, window, now.source);
     }