@absol-labs/agent 0.12.0-rc.3 → 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,20 +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;
-/**
- * After a close/reclaim, how many times the summary re-reads the relay until
- * it reflects the transaction just mined (a load-balanced RPC behind the relay
- * can answer from a node that has not seen it yet), and how long it waits
- * between reads. Bounded: past it the summary is derived from the verified
- * receipts instead.
- */
-const POST_ACTION_READS = 6;
-const POST_ACTION_INTERVAL_MS = 1_500;
+/** 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",
@@ -106,112 +108,39 @@ 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,
+      );
     }
-
-    // The summary describes the state AFTER what this run did: re-read until
-    // the relay reflects the close/reclaim just mined (bounded), else derive
-    // it from the verified receipts. Never the pre-action state.
-    const status = await statusAfterActions(refunds, {
-      closed: closeResult !== null,
+    const {
+      close: closeResult,
+      closeSkipped,
       reclaim: reclaimResult,
-      payer: stream.payer ?? null,
-      opener,
-      streamId,
-      sleep: deps.sleep,
-    });
-    // A reclaim THIS run performed is reported as a reclaim, not as "already
-    // finished".
-    const finished =
-      reclaimResult === null
-        ? (finishedReason(status) ?? finishedByRelay)
-        : null;
+      reclaimSkipped,
+      status,
+      finished,
+    } = actions;
     out.result({
       streamId,
       opener,
@@ -264,87 +193,6 @@ export const refundCommand: CommandSpec = {
   },
 };
 
-/**
- * The relay's view of a stream AFTER this run's actions. Reads until it
- * reflects them (closed after a close, reclaimed after a reclaim), bounded;
- * if the relay still lags, the state those verified transactions imply is
- * reported instead, marked as derived. With no action, one plain read.
- */
-async function statusAfterActions(
-  refunds: RefundClient,
-  done: {
-    readonly closed: boolean;
-    readonly reclaim: RefundRelayResult | null;
-    readonly payer: `0x${string}` | null;
-    readonly opener: `0x${string}`;
-    readonly streamId: `0x${string}`;
-    readonly sleep: (ms: number) => Promise<void>;
-  },
-): Promise<RefundStatus> {
-  const reclaimed = done.reclaim !== null;
-  if (!done.closed && !reclaimed) return await relay(() => refunds.status());
-  const reflects = (status: RefundStatus): boolean =>
-    (!done.closed || status.status === "closed" || status.reclaimed) &&
-    (!reclaimed || status.reclaimed);
-  let last: RefundStatus | null = null;
-  for (let attempt = 1; attempt <= POST_ACTION_READS; attempt++) {
-    try {
-      const status = await refunds.status();
-      if (reflects(status)) return status;
-      last = status;
-    } catch {
-      // A lagging relay (503 chain-lagging, a stale not-found, a blip): the
-      // transactions already happened, so keep going and derive if need be.
-    }
-    if (attempt < POST_ACTION_READS) await done.sleep(POST_ACTION_INTERVAL_MS);
-  }
-  return derivedStatus(last, done);
-}
-
-/** The state this run's verified close/reclaim imply, when the relay lags. */
-function derivedStatus(
-  last: RefundStatus | null,
-  done: {
-    readonly closed: boolean;
-    readonly reclaim: RefundRelayResult | null;
-    readonly payer: `0x${string}` | null;
-    readonly opener: `0x${string}`;
-    readonly streamId: `0x${string}`;
-  },
-): RefundStatus {
-  const reclaimed = done.reclaim !== null;
-  const note =
-    "derived from this run's transaction receipts; the refund relay had not caught up with them yet";
-  return {
-    streamId: done.streamId,
-    chainId: last?.chainId ?? 0,
-    opener: last?.opener ?? done.opener,
-    payer: last?.payer ?? done.payer ?? done.opener,
-    status: "closed",
-    reclaimed: reclaimed || (last?.reclaimed ?? false),
-    chainTime: last?.chainTime ?? null,
-    reclaimable: null,
-    // Both legs this run verified are on-chain facts: the stream is closed.
-    state: "closed",
-    onChainStatus: "closed",
-    maxRefund: last?.maxRefund ?? null,
-    maxRefundMeaning: last?.maxRefundMeaning ?? null,
-    reclaimableMeaning: last?.reclaimableMeaning ?? null,
-    next: reclaimed
-      ? {
-          action: "none",
-          message:
-            "Reclaimed: the unearned remainder was returned to the payer. Nothing further to do.",
-        }
-      : {
-          action: "reclaim",
-          message:
-            "Closed. Reclaim the unearned remainder once a checkpoint covering the close is posted (usually within a minute).",
-        },
-    raw: { derived: true, note },
-  } satisfies RefundStatus;
-}
-
 /** `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";
@@ -364,43 +212,6 @@ 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.`;
 }
 
-/** 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";
-  }
-  return null;
-}
-
-/** 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;
-}
-
 /** The `metrik refund` answer for an upfront-only payment (exit 0). */
 function reportNothingToRefund(
   context: CommandContext,
@@ -463,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) {
@@ -613,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/mcp/server.ts

@@ -389,6 +389,22 @@ export interface StoredStreamRecord {
    * seller at settlement). Informational: `budgetUsdc` always counts it.
    */
   readonly nonRefundableUsdc?: bigint;
+  /**
+   * x402 streams only: base units this server's own reclaim returned to the
+   * payer (`x402_pay` with `closeAfter`), as proven by the mined receipt's
+   * `ReclaimForwarded`. Subtracted from `budgetUsdc` when counting spend, so
+   * only what the payment finally kept counts against the mandate. Never set
+   * from a relay's unverified word.
+   */
+  readonly reclaimedUsdc?: bigint;
+}
+
+/** What a record counts against the spend mandate: the budget less a verified reclaim. */
+export function countedSpendUsdc(record: StoredStreamRecord): bigint {
+  const reclaimed = record.reclaimedUsdc ?? 0n;
+  return reclaimed > 0n && reclaimed <= record.budgetUsdc
+    ? record.budgetUsdc - reclaimed
+    : record.budgetUsdc;
 }
 
 export interface StreamRegistry {
@@ -470,6 +486,7 @@ export class FileStreamRegistry implements StreamRegistry {
           x402Reservation: z.boolean().optional(),
           x402Charge: z.literal("upfront-only").optional(),
           nonRefundableUsdc: decimalStringSchema.optional(),
+          reclaimedUsdc: decimalStringSchema.optional(),
         }),
       )
       .parse(JSON.parse(contents));
@@ -500,6 +517,9 @@ export class FileStreamRegistry implements StreamRegistry {
           ...(record.nonRefundableUsdc === undefined
             ? {}
             : { nonRefundableUsdc: BigInt(record.nonRefundableUsdc) }),
+          ...(record.reclaimedUsdc === undefined
+            ? {}
+            : { reclaimedUsdc: BigInt(record.reclaimedUsdc) }),
         },
       ]),
     );
@@ -519,6 +539,9 @@ export class FileStreamRegistry implements StreamRegistry {
           ...(record.nonRefundableUsdc === undefined
             ? {}
             : { nonRefundableUsdc: record.nonRefundableUsdc.toString() }),
+          ...(record.reclaimedUsdc === undefined
+            ? {}
+            : { reclaimedUsdc: record.reclaimedUsdc.toString() }),
         })),
         null,
         2,
@@ -711,7 +734,7 @@ export function createVerifiedStreamMcpServer(
     const records = await registry.list();
     return records
       .filter((record) => record.buyer.toLowerCase() === owner.toLowerCase())
-      .reduce((sum, record) => sum + record.budgetUsdc, 0n);
+      .reduce((sum, record) => sum + countedSpendUsdc(record), 0n);
   };
   if (options.mandateStateResolver?.getRevokedMandateIds === undefined) {
     warnOnce(
@@ -1186,6 +1209,9 @@ export function createVerifiedStreamMcpServer(
               ...(record.nonRefundableUsdc === undefined
                 ? {}
                 : { nonRefundableUsdc: record.nonRefundableUsdc.toString() }),
+              ...(record.reclaimedUsdc === undefined
+                ? {}
+                : { reclaimedUsdc: record.reclaimedUsdc.toString() }),
               status,
             };
           }),
@@ -1607,6 +1633,9 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
                   ? {}
                   : { opener: target.opener }),
                 ...(target.fetch === undefined ? {} : { fetch: target.fetch }),
+                ...(target.settledAt === undefined
+                  ? {}
+                  : { settledAt: target.settledAt }),
                 // Every relay "success" is checked against the receipt.
                 verifyWith: readOnlyMetrikClient({
                   escrowAddress: parsed.escrow,