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

package/src/cli/commands/reclaim.ts

@@ -1,4 +1,9 @@
-import { SettlementWindowOpenError } from "@absol-labs/sdk";
+import {
+  CheckpointNotReadyError,
+  ReclaimFailedError,
+  SettlementWindowOpenError,
+  StreamNotInCheckpointError,
+} from "@absol-labs/sdk";
 
 import { booleanFlag, integerFlag } from "../args.js";
 import { formatUsdc } from "../amounts.js";
@@ -11,7 +16,14 @@ import {
 } from "../escape-hatch.js";
 import { signRecoveryMandate } from "../mandate.js";
 import { assertCanPayGas } from "../preflight.js";
-import { resolveCliWallet } from "../wallet.js";
+import { writeClientOptions } from "../deps.js";
+import {
+  describeAwaitingCheckpoint,
+  describeTerminalBlocker,
+  readReclaimBlocker,
+  type ReclaimBlocker,
+} from "../reclaimability.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient, CliWriteClient } from "../deps.js";
 import type {
@@ -19,6 +31,9 @@ import type {
   StreamProofTransactionResult,
 } from "../../sdk/client.js";
 import type { StreamV2 } from "@absol-labs/sdk";
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import { parseEventLogs, type Log } from "viem";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 /**
  * How long to keep retrying a reclaim that is blocked only by an open
@@ -48,12 +63,45 @@ export const reclaimCommand: CommandSpec = {
     if (attempts < 1) throw usageError("--attempts must be at least 1");
     if (interval < 1) throw usageError("--interval must be at least 1 second");
 
-    const { account } = await resolveCliWallet(env, { note: out.note });
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
-    await assertCanPayGas(read, account.address);
 
-    const write = deps.createWriteClient(config, account);
+    // Name the condition from chain state BEFORE anything is built or spent.
+    // The public endpoint's revert data is not dependable enough to tell
+    // "already reclaimed" from "still running" from "not checkpointed yet", and
+    // those three have nothing in common but the word "reverted". See
+    // `../reclaimability.ts`.
+    const blocker = await readReclaimBlocker(read, streamId, deps.nowSeconds());
+    // `--close-first` exists precisely to clear a running stream, so it is the
+    // one caller allowed past that refusal. Nothing gets past "already
+    // reclaimed": there is no money left to take, with or without a close.
+    if (blocker !== null && !(closeFirst && blocker.kind === "running")) {
+      throwIfTerminal(blocker, streamId);
+      if (blocker.kind === "awaiting-checkpoint") {
+        out.note(describeAwaitingCheckpoint(blocker));
+      }
+    }
+
+    await assertCanPayGas(read, account.address, config.network);
+
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
+
+    // A policy-enforced wallet (Privy) signs no mandate of its own: these are
+    // buyer-recovery actions, gated by the escrow on the buyer address and by
+    // the broker on `stream.buyer == wallet`. See `../spend-policy.ts`.
+    const recoveryMandate = async () =>
+      isPolicyEnforced(wallet)
+        ? null
+        : await signRecoveryMandate(account, config.chainId);
 
     // `--close-first` is TWO transactions, and the second one only simulates
     // successfully against post-close state. Sequencing them inside a single SDK
@@ -75,7 +123,7 @@ export const reclaimCommand: CommandSpec = {
       } else {
         closeResult = await closeBeforeReclaim(write, {
           streamId,
-          signedMandate: await signRecoveryMandate(account, config.chainId),
+          signedMandate: await recoveryMandate(),
           spentSoFarUsdc: 0n,
           nowSeconds: deps.nowSeconds(),
         });
@@ -89,6 +137,19 @@ export const reclaimCommand: CommandSpec = {
             `closed in ${closeResult.txHash} — waiting for it to land …`,
           );
           await awaitClosed(read, streamId, deps.sleep, closeResult.txHash);
+          // A stream closed before any checkpoint covers its stop time is the
+          // ORDINARY outcome of a short trial run, not an exotic one — and it
+          // is the state `--close-first` leaves behind by construction. Say
+          // what is being waited for, so the retries below read as the
+          // advertised wait rather than as a command that has stalled.
+          const afterClose = await readReclaimBlocker(
+            read,
+            streamId,
+            deps.nowSeconds(),
+          );
+          if (afterClose?.kind === "awaiting-checkpoint") {
+            out.note(describeAwaitingCheckpoint(afterClose));
+          }
         }
       }
     }
@@ -97,7 +158,7 @@ export const reclaimCommand: CommandSpec = {
       write,
       async () => ({
         streamId,
-        signedMandate: await signRecoveryMandate(account, config.chainId),
+        signedMandate: await recoveryMandate(),
         spentSoFarUsdc: 0n,
         nowSeconds: deps.nowSeconds(),
       }),
@@ -105,6 +166,15 @@ export const reclaimCommand: CommandSpec = {
         attempts,
         intervalMs: interval * 1_000,
         sleep: deps.sleep,
+        isRetryable: async (error) =>
+          await isWaitingForCheckpoint(
+            error,
+            read,
+            streamId,
+            deps.nowSeconds(),
+          ),
+        explainFailure: async (error) =>
+          await explainReclaimFailure(error, read, streamId, deps.nowSeconds()),
         onRetry: (attempt, reason) =>
           out.note(
             `reclaim blocked: no checkpoint covers the stream's stop time yet (attempt ${attempt}/${attempts}) — ${reason}`,
@@ -114,18 +184,31 @@ export const reclaimCommand: CommandSpec = {
         // give-up message names the path that needs no proof, and says whether
         // it is open yet.
         exhaustedHint: async () =>
-          await describeLastResort(read, streamId, deps.nowSeconds()),
+          await describeLastResort(
+            read,
+            streamId,
+            deps.nowSeconds(),
+            escrowGenerationFor(config.chainId, config.escrow),
+          ),
       },
     );
 
     // Read the settled figure back only once the node we are reading from has
-    // actually applied the reclaim. `sepolia.base.org` is load-balanced, so an
+    // actually applied the reclaim. The public RPC is load-balanced, so an
     // immediate read can land on a lagged node and report `settledCumulative: 0`
     // for a stream that just settled a non-zero amount — printing "settled to
     // operator 0 USDC" when it was not zero. Poll for `reclaimed` (which the
     // transaction we just landed sets) so the number beside it is from the same
     // post-reclaim state. Bounded, and falls back to the last value read.
     const stream = await readSettledStream(read, streamId, deps.sleep);
+    // The refund comes from the reclaim's own BuyerReclaimed event, never from
+    // a post-reclaim read: reclaim overwrites `deposit` with the operator's
+    // entitlement, so deposit − settled reads 0 after every reclaim.
+    const refunded = refundFromReceipt(
+      result.reclaimResult.receipt,
+      config.escrow,
+      streamId,
+    );
     out.result({
       streamId,
       txHash: result.reclaimResult.txHash,
@@ -135,6 +218,14 @@ export const reclaimCommand: CommandSpec = {
       // asked for".
       closeSkippedAlreadyClosed: closeFirst ? alreadyClosed : null,
       settledCumulative: stream?.settledCumulative ?? null,
+      // What the reclaim sent back: everything not settled to the operator.
+      // Only reported once the read reflects the reclaim, so a lagged node can
+      // never print a refund figure computed from pre-reclaim state.
+      refundedAmount: refunded,
+      // For an x402 stream the refund goes to the opener's payer, whoever sent
+      // the (permissionless) reclaim.
+      opener: stream?.opener ?? null,
+      refundedTo: stream === null ? null : (stream.payer ?? stream.buyer),
     });
     out.print("Reclaimed.");
     out.table([
@@ -149,6 +240,22 @@ export const reclaimCommand: CommandSpec = {
         ? []
         : ([
             ["settled to operator", formatUsdc(stream.settledCumulative)],
+            ...(refunded === null
+              ? []
+              : ([
+                  [
+                    (stream.opener ?? null) === null
+                      ? "returned to buyer"
+                      : "returned to payer",
+                    formatUsdc(refunded),
+                  ],
+                ] as const)),
+            ...((stream.opener ?? null) === null
+              ? []
+              : ([
+                  ["via opener", stream.opener as string],
+                  ["refunded to payer", stream.payer],
+                ] as const)),
           ] as const)),
     ]);
   },
@@ -190,7 +297,7 @@ function isAlreadyClosed(error: unknown): boolean {
  * Block until the node we read from reports the stream as closed.
  *
  * The close transaction's own receipt is awaited inside the SDK, but
- * `sepolia.base.org` is load-balanced: the receipt can come back from one node
+ * the public RPC is load-balanced: the receipt can come back from one node
  * while the very next `simulateContract` lands on another that has not imported
  * the block yet. That node simulates `reclaim` against PRE-close state and
  * reverts `StreamNotReclaimable()`. Confirming the close through the same read
@@ -226,8 +333,16 @@ export async function awaitClosed(
  * time. That is not an error condition — it is the normal ordering of a
  * checkpoint rail, and it happens on the FIRST attempt essentially every time.
  * A CLI that surfaced the raw revert would teach every user that reclaim is
- * broken, so the wait is built in and narrated. Any other failure is rethrown
- * immediately: only an open settlement window is retried.
+ * broken, so the wait is built in and narrated.
+ *
+ * What counts as "wait for the next checkpoint" is decided by `isRetryable`,
+ * NOT by this function. It used to be `instanceof SettlementWindowOpenError`
+ * alone, which missed the two ways the wait actually shows up in practice: the
+ * ORACLE refusing a proof for a stream it has not checkpointed yet (the SDK
+ * fetches the proof before it ever simulates, so the escrow's revert never
+ * happens), and the endpoint returning revert data the ABI cannot decode. Both
+ * killed the advertised retry on its first attempt — the second one right
+ * after `--close-first` had already spent the buyer's close.
  */
 export async function reclaimWithBoundedRetry(
   write: CliWriteClient,
@@ -236,6 +351,10 @@ export async function reclaimWithBoundedRetry(
     readonly attempts: number;
     readonly intervalMs: number;
     readonly sleep: (ms: number) => Promise<void>;
+    /** True when this failure is the checkpoint wait and will clear on its own. */
+    readonly isRetryable: (error: unknown) => Promise<boolean>;
+    /** Turn a failure that will NOT clear into something worth reading. */
+    readonly explainFailure: (error: unknown) => Promise<unknown>;
     readonly onRetry: (attempt: number, reason: string) => void;
     /** What to tell the buyer once the budget is spent. See `describeLastResort`. */
     readonly exhaustedHint?: () => Promise<string>;
@@ -246,7 +365,8 @@ export async function reclaimWithBoundedRetry(
     try {
       return await write.reclaimStream(await buildInput());
     } catch (error) {
-      if (!isSettlementWindowOpen(error)) throw explainReclaimFailure(error);
+      if (!(await options.isRetryable(error)))
+        throw await options.explainFailure(error);
       lastError = error;
       if (attempt === options.attempts) break;
       options.onRetry(attempt, describeError(error));
@@ -282,25 +402,123 @@ async function describeLastResort(
   read: CliReadClient,
   streamId: `0x${string}`,
   fallbackNowSeconds: number,
+  generation: string,
 ): Promise<string> {
   const [stream, grace] = await Promise.all([
     read.getStreamV2(streamId),
     read.escapeGraceSeconds(),
   ]);
   const now = await readChainNow(read, fallbackNowSeconds);
-  const window = escapeHatchWindow(stream, grace, now.seconds);
+  const window = escapeHatchWindow(stream, grace, now.seconds, generation);
   const escapeCommand = `metrik reclaim-unverified ${streamId} --forfeit-unclaimed`;
   return window.ready
     ? `the funds are not lost. The no-proof escape hatch is OPEN (${describeEscapeHatch(window)}): \`${escapeCommand}\` takes them back without the oracle — at the cost of forfeiting whatever the operator earned but has not yet claimed. Retrying this command only helps if the oracle comes back.`
     : `the funds are not lost, but retrying only helps if the oracle comes back — this path needs a proof from it. The no-proof escape hatch ${describeEscapeHatch(window)}; from then on \`${escapeCommand}\` takes them back without the oracle, forfeiting whatever the operator earned but has not yet claimed.`;
 }
 
+/** Raise a blocker that will not clear on its own as a named CliError. */
+function throwIfTerminal(
+  blocker: ReclaimBlocker,
+  streamId: `0x${string}`,
+  cause?: unknown,
+): void {
+  const terminal = describeTerminalBlocker(blocker, streamId);
+  if (terminal === null) return;
+  throw new CliError(terminal.message, {
+    exitCode: 4,
+    hint: terminal.hint,
+    ...(cause === undefined ? {} : { cause }),
+  });
+}
+
+/**
+ * Is this failure the checkpoint wait, i.e. will it clear on its own?
+ *
+ * Three shapes, in increasing order of how little the endpoint told us:
+ *
+ *  1. `SettlementWindowOpenError` — the escrow said so and the ABI decoded it.
+ *  2. `StreamNotInCheckpointError` / `CheckpointNotReadyError` — the ORACLE has
+ *     no proof for this stream yet, so the SDK never reached the escrow at all.
+ *     This is the state `--close-first` creates by construction on a stream
+ *     closed before its first covering checkpoint, and treating it as fatal is
+ *     what stranded a buyer's deposit in escrow for three minutes of manual
+ *     retries while the CLI's own help promised it would wait.
+ *  3. A reclaim revert the ABI could not decode. Nothing in the error names the
+ *     condition, so ask the chain instead — the state is authoritative and the
+ *     answer is the same one the pre-flight computes.
+ *
+ * Case 3 is deliberately narrowed to `ReclaimFailedError`: an unrelated failure
+ * (no gas, a dead RPC) must still fail on its first attempt rather than burn
+ * twelve of them.
+ */
+async function isWaitingForCheckpoint(
+  error: unknown,
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  nowSeconds: number,
+): Promise<boolean> {
+  if (isSettlementWindowOpen(error)) return true;
+  if (hasNoCheckpointProofYet(error)) return true;
+  if (!isReclaimRevert(error)) return false;
+  const blocker = await readReclaimBlocker(read, streamId, nowSeconds).catch(
+    () => null,
+  );
+  return blocker?.kind === "awaiting-checkpoint";
+}
+
+/**
+ * The oracle could not supply a proof yet: it has no leaf for this stream in
+ * the latest checkpoint (404), or no internally consistent checkpoint is ready
+ * (503). Both resolve when the next checkpoint lands, ~15-22s apart.
+ */
+function hasNoCheckpointProofYet(error: unknown): boolean {
+  for (let current: unknown = error, depth = 0; depth < 8; depth++) {
+    if (
+      current instanceof StreamNotInCheckpointError ||
+      current instanceof CheckpointNotReadyError
+    ) {
+      return true;
+    }
+    if (!(current instanceof Error) || current.cause === undefined)
+      return false;
+    current = current.cause;
+  }
+  return false;
+}
+
+/** True when the escrow rejected the reclaim, whatever the reason decoded to. */
+function isReclaimRevert(error: unknown): boolean {
+  for (let current: unknown = error, depth = 0; depth < 8; depth++) {
+    if (current instanceof ReclaimFailedError) return true;
+    if (!(current instanceof Error) || current.cause === undefined)
+      return false;
+    current = current.cause;
+  }
+  return false;
+}
+
 /**
- * `StreamNotReclaimable()` means exactly one thing: the stream is neither closed
- * nor past its expiry. Say that, and say which command fixes it, instead of
- * handing the reader a selector.
+ * Name a failure that will not clear.
+ *
+ * `StreamNotReclaimable()` means exactly one thing when the ABI decodes it: the
+ * stream is neither closed nor past its expiry. When it does NOT decode — the
+ * live failure mode on the public endpoint — the chain is asked the same
+ * question, so "already reclaimed" and "still running" are still told apart and
+ * still say which command fixes them. The raw error is kept as the `cause`
+ * either way.
  */
-function explainReclaimFailure(error: unknown): unknown {
+async function explainReclaimFailure(
+  error: unknown,
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  nowSeconds: number,
+): Promise<unknown> {
   if (!(error instanceof Error)) return error;
   for (let current: unknown = error, depth = 0; depth < 8; depth++) {
     if (!(current instanceof Error)) break;
@@ -309,7 +527,7 @@ function explainReclaimFailure(error: unknown): unknown {
         "the stream is still running, so there is nothing to reclaim yet",
         {
           exitCode: 4,
-          hint: "stop the clock first — `metrik close <streamId>`, or re-run this command with --close-first — or wait for the stream to expire.",
+          hint: `stop the clock first — \`metrik close ${streamId}\`, or re-run this command with --close-first — or wait for the stream to expire.`,
           cause: error,
         },
       );
@@ -317,6 +535,18 @@ function explainReclaimFailure(error: unknown): unknown {
     if (current.cause === undefined) break;
     current = current.cause;
   }
+  if (isReclaimRevert(error)) {
+    const blocker = await readReclaimBlocker(read, streamId, nowSeconds).catch(
+      () => null,
+    );
+    if (blocker !== null) {
+      try {
+        throwIfTerminal(blocker, streamId, error);
+      } catch (named) {
+        return named;
+      }
+    }
+  }
   return error;
 }
 
@@ -342,6 +572,31 @@ const SETTLED_READ_ATTEMPTS = 5;
 // `--interval`), so the two waits are tellable apart in tests and in logs.
 const SETTLED_READ_INTERVAL_MS = 500;
 
+/**
+ * The amount the reclaim returned, decoded from its BuyerReclaimed event (same
+ * signature on V2 and V3). Null when the receipt carries no matching log, so
+ * the CLI prints nothing rather than a guessed figure.
+ */
+export function refundFromReceipt(
+  receipt: { logs?: readonly Log[] } | undefined,
+  escrow: string,
+  streamId: `0x${string}`,
+): bigint | null {
+  const logs = receipt?.logs;
+  if (!Array.isArray(logs)) return null;
+  const events = parseEventLogs({
+    abi: streamEscrowV2Abi,
+    eventName: "BuyerReclaimed",
+    logs: logs.filter(
+      (log) => log.address?.toLowerCase() === escrow.toLowerCase(),
+    ),
+  });
+  const match = events.find(
+    (event) => event.args.streamId.toLowerCase() === streamId.toLowerCase(),
+  );
+  return match === undefined ? null : match.args.amount;
+}
+
 async function readSettledStream(
   read: { getStreamV2(streamId: `0x${string}`): Promise<StreamV2> },
   streamId: `0x${string}`,