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

package/src/cli/commands/refund.ts

@@ -6,6 +6,13 @@ import type {
 } from "@absol-labs/sdk/x402";
 
 import { verifyMandateOwnerSignature } from "../../mandates/mandate.js";
+import {
+  RefundActionsError,
+  runRefundActions,
+  type FinishedReason,
+  type RefundActionsResult,
+  type SkipReason,
+} from "../../x402-buyer/refund-actions.js";
 import { booleanFlag, integerFlag, stringFlag } from "../args.js";
 import { formatUsdc } from "../amounts.js";
 import { assertTestnetRpc, parseBytes32 } from "../config.js";
@@ -20,11 +27,15 @@ import {
 } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
+export { finishedReason } from "../../x402-buyer/refund-actions.js";
+export type { FinishedReason, SkipReason };
+
 /** Environment fallback for `--refund-url`. */
 export const REFUND_URL_ENV = "METRIK_AGENT_REFUND_URL";
 
-const DEFAULT_ATTEMPTS = 5;
-const DEFAULT_MAX_WAIT_SECONDS = 60;
+/** Relay attempts / longest single wait of a reclaim (also `pay --close-after`'s). */
+export const DEFAULT_ATTEMPTS = 5;
+export const DEFAULT_MAX_WAIT_SECONDS = 60;
 
 export const refundCommand: CommandSpec = {
   name: "refund",
@@ -97,107 +108,47 @@ export const refundCommand: CommandSpec = {
       maxDelayMs: maxWait * 1_000,
     });
 
-    let closeResult: RefundRelayResult | null = null;
-    let closeSkipped: SkipReason | null = null;
-    // Set when the relay itself says there is nothing left: the stream was
-    // already reclaimed, or the verified delivery covers the whole deposit.
-    // Those are FINISHED recoveries, not failures — a second
-    // `--close --reclaim` on a done stream must exit 0 and must never point
-    // the payer at a gas-spending on-chain recovery that cannot recover a cent.
-    let finishedByRelay: FinishedReason | null = null;
-    if (doClose) {
-      // Ask first: a stream that is already closed (or already finished) needs
-      // no Close, so there is nothing to sign and no wallet is needed.
-      const before = await relay(() => refunds.status());
-      const finishedBefore = finishedReason(before);
-      if (finishedBefore !== null || before.status === "closed") {
-        closeSkipped = finishedBefore ?? "already-closed";
-        finishedByRelay = finishedBefore;
-        out.note(
-          finishedBefore === null
-            ? "stream is already closed — no Close to sign."
-            : `stream is already closed and ${finishedBefore === "reclaimed" ? "reclaimed" : "has nothing left to reclaim"} — no Close to sign.`,
-        );
-      } else {
-        const wallet = await resolveCliWallet(env, {
-          purpose: "payer-close",
-          note: out.note,
-          rpcUrl: config.rpcUrl,
-        });
-        if (isPrivyWalletSource(wallet.source)) {
-          throw configError(
-            "metrik refund --close cannot sign with a Privy wallet",
-            "the payer signs the opener's EIP-712 Close, which the Privy broker's typed-data policy does not allow. Use the key that paid.",
-          );
-        }
-        // Buyer recovery: authorized on the mandate OWNER's signature alone,
-        // like `metrik close` — never on caps or expiry, so nothing can strand
-        // the payer's own money. The SDK then refuses a signer that is not
-        // `payerOf(streamId)` before anything is signed for the relay.
-        const mandate = await signRecoveryMandate(
-          wallet.account,
-          config.chainId,
-        );
-        const decision = await verifyMandateOwnerSignature(mandate);
-        if (!decision.allowed) {
-          throw new CliError(`mandate denied: ${decision.reason}`, {
-            exitCode: 3,
-          });
-        }
-        try {
-          closeResult = await relay(() =>
-            refunds.close({
-              signer: wallet.account as unknown as X402PayerSigner,
+    let actions: RefundActionsResult;
+    try {
+      actions = await runRefundActions({
+        refunds,
+        streamId,
+        opener,
+        payer: stream.payer ?? null,
+        close: doClose,
+        reclaim: doReclaim,
+        closeSigner: () => payerCloseSigner(context, "metrik refund --close"),
+        sleep: deps.sleep,
+        note: out.note,
+        ...(context.progress === undefined
+          ? {}
+          : {
+              setActivity: (activity: string | null) =>
+                context.progress?.setActivity(activity),
             }),
-          );
-          out.note(
-            `close relayed in ${closeResult.transaction}${closeResult.verified ? " (receipt verified on-chain)" : ""}`,
-          );
-        } catch (error) {
-          // The status read above said "active", but the stream closed in the
-          // meantime (it reached expiresAt, or another close landed): the
-          // state the payer asked for. Anything else is a real failure.
-          if (relayCode(error) !== "already-closed") throw error;
-          closeSkipped = "already-closed";
-          out.note("stream was already closed — no Close was needed.");
-        }
-      }
-    }
-
-    let reclaimResult: RefundRelayResult | null = null;
-    let reclaimSkipped: SkipReason | null = null;
-    if (doReclaim) {
-      if (finishedByRelay !== null) {
-        reclaimSkipped = finishedByRelay;
-      } else {
-        context.progress?.setActivity(
-          `waiting on the refund relay's reclaim (it retries up to ${attempts} time${attempts === 1 ? "" : "s"} while the settlement window is open, at most ${maxWait}s per wait)`,
-        );
-        try {
-          reclaimResult = await relay(() => refunds.reclaim());
-        } catch (error) {
-          const finished = finishedFromRelayCode(relayCode(error));
-          if (finished === null) throw error;
-          reclaimSkipped = finished;
-          finishedByRelay = finished;
-        } finally {
-          context.progress?.setActivity(null);
-        }
-      }
+        reclaimActivity: reclaimActivity(attempts, maxWait),
+      });
+    } catch (error) {
+      throw explainRefundFailure(
+        error instanceof RefundActionsError ? error.cause : error,
+      );
     }
-
-    const status = await relay(() => refunds.status());
-    // A reclaim THIS run performed is reported as a reclaim, not as "already
-    // finished".
-    const finished =
-      reclaimResult === null
-        ? (finishedReason(status) ?? finishedByRelay)
-        : null;
+    const {
+      close: closeResult,
+      closeSkipped,
+      reclaim: reclaimResult,
+      reclaimSkipped,
+      status,
+      finished,
+    } = actions;
     out.result({
       streamId,
       opener,
       payer: status.payer,
+      // The escrow's own on-chain status, verbatim.
       status: status.status,
+      // What it means now: an Active stream past expiresAt is "expired".
+      state: stateOf(status),
       reclaimed: status.reclaimed,
       reclaimable: status.reclaimable,
       next: status.next,
@@ -233,48 +184,32 @@ export const refundCommand: CommandSpec = {
     );
     out.print("");
     out.print(
-      finished === null
-        ? nextStep(status, streamId, refundUrl)
-        : describeFinished(finished),
+      reclaimResult !== null
+        ? describeReclaimed(reclaimResult)
+        : finished === null
+          ? nextStep(status, streamId, refundUrl)
+          : describeFinished(finished),
     );
   },
 };
 
-/** Why a recovery is over. */
-export type FinishedReason = "reclaimed" | "nothing-to-reclaim";
-/** Why a requested `--close` / `--reclaim` sent nothing. */
-export type SkipReason = FinishedReason | "already-closed";
-
-/**
- * Whether the relay's status says nothing is left to recover. `reclaimed` is
- * the chain's one-reclaim-per-stream flag; `next: none` with `reclaimable: 0`
- * is the relay's "the verified delivery covers the whole deposit".
- */
-export function finishedReason(status: RefundStatus): FinishedReason | null {
-  if (status.reclaimed) return "reclaimed";
-  if (status.next.action === "none" && status.reclaimable === 0n) {
-    return "nothing-to-reclaim";
+/** `closed`, `expired` (Active on-chain but past expiresAt) or `active`. */
+export function stateOf(status: RefundStatus): "active" | "expired" | "closed" {
+  if (status.status === "closed" || status.reclaimed) return "closed";
+  const raw = status.raw as { state?: unknown; expiresAt?: unknown };
+  if (raw.state === "expired") return "expired";
+  if (
+    typeof raw.expiresAt === "number" &&
+    status.chainTime !== null &&
+    status.chainTime >= raw.expiresAt
+  ) {
+    return "expired";
   }
-  return null;
+  return "active";
 }
 
-/** The relay's 409 codes that mean "finished", not "failed". */
-function finishedFromRelayCode(code: string | null): FinishedReason | null {
-  if (code === "already-reclaimed") return "reclaimed";
-  if (code === "nothing-to-reclaim") return "nothing-to-reclaim";
-  return null;
-}
-
-function relayCode(error: unknown): string | null {
-  for (let current: unknown = error, depth = 0; depth < 4; depth++) {
-    if (!(current instanceof Error)) return null;
-    const code = (current as { code?: unknown }).code;
-    if (current.name === "RefundRelayError" && typeof code === "string") {
-      return code;
-    }
-    current = current.cause;
-  }
-  return null;
+function describeReclaimed(result: RefundRelayResult): string {
+  return `Reclaimed: ${result.amount === null ? "the unearned remainder" : formatUsdc(result.amount)} was returned to the payer${result.verified ? " (receipt verified on-chain)" : ""}. Nothing further to do for this stream.`;
 }
 
 /** The `metrik refund` answer for an upfront-only payment (exit 0). */
@@ -339,14 +274,6 @@ export function resolveRefundUrl(
   return url.toString();
 }
 
-async function relay<T>(task: () => Promise<T>): Promise<T> {
-  try {
-    return await task();
-  } catch (error) {
-    throw explainRefundFailure(error);
-  }
-}
-
 export function explainRefundFailure(error: unknown): unknown {
   if (!(error instanceof Error)) return error;
   switch (error.name) {
@@ -414,10 +341,19 @@ function statusRows(
   closeSkipped: SkipReason | null,
   finished: FinishedReason | null,
 ): (readonly [string, string])[] {
+  const state = stateOf(status);
+  const derived = (status.raw as { derived?: unknown }).derived === true;
   const rows: (readonly [string, string])[] = [
     [
       "status",
-      status.reclaimed ? `${status.status} (reclaimed)` : status.status,
+      (status.reclaimed
+        ? `${state} (reclaimed)`
+        : state === status.status
+          ? state
+          : `${state} (on-chain: ${status.status}; past expiresAt, accrues nothing more)`) +
+        (derived
+          ? " — from this run's receipts; the relay is still catching up"
+          : ""),
     ],
     ...(finished === null
       ? []
@@ -425,10 +361,14 @@ function statusRows(
     ["payer", status.payer],
     ["opener", status.opener],
     [
-      "reclaimable",
-      status.reclaimable === null ? "-" : formatUsdc(status.reclaimable),
+      "reclaimable now",
+      reclaimResult !== null || status.reclaimed
+        ? "- (already reclaimed)"
+        : status.reclaimable === null
+          ? "-"
+          : formatUsdc(status.reclaimable),
     ],
-    ["next", status.next.action],
+    ["next", reclaimResult !== null ? "none" : status.next.action],
   ];
   if (closeResult === null && closeSkipped !== null) {
     rows.push(["close", "skipped — already closed"]);
@@ -462,6 +402,10 @@ function nextStep(
   const base = `metrik refund ${streamId} --refund-url ${refundUrl}`;
   switch (status.next.action) {
     case "close":
+      if (status.status === "closed") {
+        // Never "still running" for a stream the chain shows closed.
+        return `Refunds are NOT automatic. The stream is closed: reclaim the unearned remainder with  ${base} --reclaim`;
+      }
       return `Refunds are NOT automatic. The stream is still running: stop it with  ${base} --close --reclaim`;
     case "reclaim":
       return `Refunds are NOT automatic. Reclaim the unearned remainder with  ${base} --reclaim`;
@@ -472,4 +416,50 @@ function nextStep(
   }
 }
 
+/**
+ * The payer's signer for an opener Close, authorized the way every buyer
+ * recovery is: on the mandate OWNER's signature alone (like `metrik close`) —
+ * never on caps or expiry, so nothing can strand the payer's own money. The
+ * SDK then refuses a signer that is not `payerOf(streamId)` before anything is
+ * signed for the relay.
+ */
+export async function payerCloseSigner(
+  context: CommandContext,
+  commandLabel: string,
+): Promise<X402PayerSigner> {
+  const { config, env, out } = context;
+  const wallet = await resolveCliWallet(env, {
+    purpose: "payer-close",
+    note: out.note,
+    rpcUrl: config.rpcUrl,
+  });
+  if (isPrivyWalletSource(wallet.source)) {
+    throw configError(
+      `${commandLabel} cannot sign with a Privy wallet`,
+      "the payer signs the opener's EIP-712 Close, which the Privy broker's typed-data policy does not allow. Use the key that paid.",
+    );
+  }
+  return await authorizeCloseSigner(wallet.account, config.chainId);
+}
+
+/** {@link payerCloseSigner} for an account the command already holds. */
+export async function authorizeCloseSigner(
+  account: Parameters<typeof signRecoveryMandate>[0],
+  chainId: number,
+): Promise<X402PayerSigner> {
+  const mandate = await signRecoveryMandate(account, chainId);
+  const decision = await verifyMandateOwnerSignature(mandate);
+  if (!decision.allowed) {
+    throw new CliError(`mandate denied: ${decision.reason}`, {
+      exitCode: 3,
+    });
+  }
+  return account as unknown as X402PayerSigner;
+}
+
+/** What the heartbeat says while the relay's reclaim waits for the checkpoint. */
+export function reclaimActivity(attempts: number, maxWait: number): string {
+  return `waiting on the refund relay's reclaim (it retries up to ${attempts} time${attempts === 1 ? "" : "s"} while the settlement window is open, at most ${maxWait}s per wait)`;
+}
+
 export type { RefundClient };

package/src/cli/deps.ts

@@ -262,6 +262,12 @@ export interface CliX402 {
       readonly opener?: `0x${string}`;
       readonly maxAttempts?: number;
       readonly maxDelayMs?: number;
+      /**
+       * When the payment settled, unix ms (`pay --close-after`): a relay that
+       * has not seen the just-opened stream yet answers `404`, which is then
+       * waited out briefly instead of failing.
+       */
+      readonly settledAt?: number;
     },
   ) => Promise<RefundClient>;
 }
@@ -613,6 +619,9 @@ export const defaultCliDependencies: CliDependencies = {
         ...(target.maxDelayMs === undefined
           ? {}
           : { maxDelayMs: target.maxDelayMs }),
+        ...(target.settledAt === undefined
+          ? {}
+          : { settledAt: target.settledAt }),
       });
     },
   },

package/src/cli/errors.ts

@@ -9,7 +9,14 @@ export type CliExitCode =
   /** Configuration refused: wrong chain, missing key, mainnet target. */
   | 3
   /** The operation itself failed (RPC, registry, escrow revert, HTTP). */
-  | 4;
+  | 4
+  /**
+   * `metrik pay --close-after`: the payment and its response SUCCEEDED, but
+   * the buyer's close + reclaim of the stream did not finish. Nothing is lost
+   * (the unearned part stays in the escrow for the payer); the hint names the
+   * exact `metrik refund` command that finishes it.
+   */
+  | 5;
 
 export class CliError extends Error {
   readonly exitCode: CliExitCode;

package/src/cli/status.ts

@@ -564,7 +564,7 @@ export function streamReportRows(
     ],
     ["rate", `${formatUsdc(stream.ratePerSecond)} / second`],
     ["opened", formatTimestamp(stream.openedAt)],
-    ["expires", describeDeadline(stream.expiresAt, report.nowSeconds)],
+    describeDeadline(stream, report.nowSeconds),
   ];
   if (stream.closedAt > 0) {
     rows.push(["closed", formatTimestamp(stream.closedAt)]);
@@ -781,11 +781,32 @@ function describePendingSettlement(settlement: SettlementCoverage): string {
   return `pending final checkpoint — the stream stopped at ${stopAt}, the oracle has published only to ${covered}. Reclaim reverts until a checkpoint reaches the stop time (~15-22s apart).`;
 }
 
-function describeDeadline(expiresAt: number, nowSeconds: number): string {
+/**
+ * The expiry row. A stream that was closed before its expiry never reaches
+ * it, so it never reads as a countdown ("in 57m") — that looked like a stream
+ * still running. Exported for tests.
+ */
+export function describeDeadline(
+  stream: Pick<StreamV2, "expiresAt" | "closedAt">,
+  nowSeconds: number,
+): readonly [string, string] {
+  const { expiresAt } = stream;
+  const closedEarly = stream.closedAt > 0 && stream.closedAt < expiresAt;
+  if (closedEarly) {
+    return [
+      "would have expired",
+      `${formatTimestamp(expiresAt)} — not reached: closed early at ${formatTimestamp(stream.closedAt)}, so it accrues nothing more`,
+    ];
+  }
   const remaining = expiresAt - nowSeconds;
-  const suffix =
-    remaining > 0
-      ? `in ${formatDuration(remaining)}`
-      : `${formatDuration(-remaining)} ago`;
-  return `${formatTimestamp(expiresAt)} — ${suffix}`;
+  if (remaining > 0) {
+    return [
+      "expires",
+      `${formatTimestamp(expiresAt)} — in ${formatDuration(remaining)}`,
+    ];
+  }
+  return [
+    "expired",
+    `${formatTimestamp(expiresAt)} — ${formatDuration(-remaining)} ago`,
+  ];
 }

package/src/gateway/x402-opener-mode.ts

@@ -14,7 +14,11 @@ import {
   type SettleResultContext,
 } from "@x402/core/server";
 import type { Network } from "@x402/core/types";
-import { decodePaymentSignatureHeader } from "@x402/core/http";
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentSignatureHeader,
+  encodePaymentRequiredHeader,
+} from "@x402/core/http";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
 import {
   createPublicClient,
@@ -1029,7 +1033,16 @@ async function handleX402GatewayRequest(
     claim !== undefined &&
     !mode.authorizations.claim(claim.key, claim.validBefore)
   ) {
-    io.writeJson(409, "x402-payment-already-used");
+    // Refused exactly as strictly as before (no verify, no upstream, no
+    // settle), but in the x402 v2 shape: a 402 with a FRESH PAYMENT-REQUIRED
+    // whose `error` says why, so a stock client can pay again or report it.
+    await writePaymentRejected(
+      mode,
+      io,
+      context,
+      "x402-payment-already-used",
+      "this PAYMENT-SIGNATURE's authorization was already used (or is being settled) for another request; each authorization buys at most one response. Sign a new payment to call again.",
+    );
     return;
   }
   const release = () => {
@@ -1054,7 +1067,10 @@ async function handleX402GatewayRequest(
   }
   if (result.type === "payment-error") {
     release();
-    writeInstructions(io, result.response);
+    // The stock 402: a fresh PAYMENT-REQUIRED whose `error` is the verifier's
+    // reason (e.g. an authorization whose validBefore is too short). The body
+    // is made readable too, instead of `{}`.
+    writeInstructions(io, result.response, "x402-payment-invalid");
     return;
   }
 
@@ -1133,8 +1149,14 @@ async function handleX402GatewayRequest(
         release();
       }
     }
-    // No upstream body on a failed settlement.
-    writeInstructions(io, settled.response);
+    // No upstream body on a failed settlement. The stock settlement-failure
+    // 402 carries PAYMENT-RESPONSE (success false, errorReason).
+    writeInstructions(
+      io,
+      settled.response,
+      "x402-settlement-failed",
+      settled.errorReason,
+    );
     return;
   }
   if (claim !== undefined) {
@@ -1159,6 +1181,8 @@ async function handleX402GatewayRequest(
 function writeInstructions(
   io: X402GatewayRequestIO,
   response: HTTPResponseInstructions,
+  reason?: "x402-payment-invalid" | "x402-settlement-failed",
+  settlementError?: string,
 ): void {
   const headers: Record<string, string> = { ...response.headers };
   if (response.isHtml === true) {
@@ -1167,5 +1191,106 @@ function writeInstructions(
     return;
   }
   headers["Content-Type"] = "application/json";
-  io.write(response.status, headers, JSON.stringify(response.body ?? {}));
+  let body = response.body ?? {};
+  if (
+    reason !== undefined &&
+    typeof body === "object" &&
+    body !== null &&
+    Object.keys(body).length === 0
+  ) {
+    // Same JSON shape as the gateway's other refusals, plus the x402 error.
+    const error = settlementError ?? paymentRequiredError(headers);
+    body = {
+      authorized: false,
+      reason,
+      ...(error === undefined ? {} : { error }),
+    };
+  }
+  io.write(response.status, headers, JSON.stringify(body));
+}
+
+/** The `error` carried in a response's PAYMENT-REQUIRED header, if any. */
+function paymentRequiredError(
+  headers: Record<string, string>,
+): string | undefined {
+  const value = headerValue(headers, "payment-required");
+  if (value === undefined) return undefined;
+  try {
+    const decoded = decodePaymentRequiredHeader(value);
+    return typeof decoded.error === "string" ? decoded.error : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function headerValue(
+  headers: Record<string, string>,
+  name: string,
+): string | undefined {
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) return value;
+  }
+  return undefined;
+}
+
+/**
+ * A spec-shaped x402 v2 refusal of a payment the gateway will not accept: a
+ * `402` with a fresh `PAYMENT-REQUIRED` (built by the same resource server
+ * that quotes every 402, with no payment attached, so nothing is verified or
+ * settled) whose `error` is `reason`, and a JSON body naming it.
+ */
+async function writePaymentRejected(
+  mode: GatewayX402OpenerMode,
+  io: X402GatewayRequestIO,
+  context: HTTPRequestContext,
+  reason: "x402-payment-already-used",
+  message: string,
+): Promise<void> {
+  const body = JSON.stringify({
+    authorized: false,
+    reason,
+    error: reason,
+    message,
+  });
+  let headers: Record<string, string> = {};
+  try {
+    const { paymentHeader: _omitted, ...unpaid } = context;
+    const challenge = await mode.httpServer.processHTTPRequest({
+      ...unpaid,
+      adapter: {
+        ...context.adapter,
+        // The core reads the payment from the adapter's headers: hide it, so
+        // this builds a quote only and NOTHING is verified or settled.
+        getHeader: (name: string) =>
+          ["payment-signature", "x-payment"].includes(name.toLowerCase())
+            ? undefined
+            : context.adapter.getHeader(name),
+        // Always the machine-readable 402, never the browser paywall.
+        getAcceptHeader: () => "application/json",
+      },
+    });
+    if (challenge.type === "payment-error") {
+      for (const [key, value] of Object.entries(challenge.response.headers)) {
+        if (key.toLowerCase() === "content-type") continue;
+        headers[key] = value;
+      }
+      const required = headerValue(headers, "payment-required");
+      if (required !== undefined) {
+        const decoded = decodePaymentRequiredHeader(required);
+        for (const key of Object.keys(headers)) {
+          if (key.toLowerCase() === "payment-required") delete headers[key];
+        }
+        headers["PAYMENT-REQUIRED"] = encodePaymentRequiredHeader({
+          ...decoded,
+          error: reason,
+        });
+      }
+    }
+  } catch (error) {
+    // Still a 402 refusal (never served, never settled); just without a quote.
+    io.logError("x402 fresh PAYMENT-REQUIRED failed", error);
+    headers = {};
+  }
+  headers["Content-Type"] = "application/json";
+  io.write(402, headers, body);
 }