@absol-labs/agent 0.9.1 → 0.11.0

package/dist/cli/commands/open.js

@@ -0,0 +1,331 @@
+import { MandateDeniedError } from "../../sdk/client.js";
+import { booleanFlag, requiredStringFlag, stringFlag } from "../args.js";
+import { formatDuration, formatUsdc, parseAmountUnits, parseDurationSeconds, parseUsdcAmount, } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { writeClientOptions } from "../deps.js";
+import { CliError, configError } from "../errors.js";
+import { assertWithinOperatorCaps, assertWithinSpendPolicy, } from "../spend-policy.js";
+import { cliMandateCaps, signCliMandate } from "../mandate.js";
+import { assertCanFundStream, assertCanPayGas } from "../preflight.js";
+import { isPolicyEnforced, optionalCliWallet, resolveCliWallet, PRIVATE_KEY_ENV, } from "../wallet.js";
+import { resolveListing } from "../listings.js";
+export const openCommand = {
+    name: "open",
+    summary: "Hire a verified service: escrow USDC into a metered stream",
+    usage: "metrik open --service <serviceRef> --rate <usdc/s> --budget <usdc> --duration <seconds> [--units atomic] [--dry-run]",
+    flags: [
+        "service",
+        "rate",
+        "budget",
+        "duration",
+        "units",
+        "operator",
+        "dry-run",
+    ],
+    signs: true,
+    async run(context) {
+        const { args, config, env, out, deps } = context;
+        const units = parseAmountUnits(stringFlag(args, "units"));
+        const serviceRef = parseBytes32(requiredStringFlag(args, "service"), "--service");
+        const budgetUsdc = parseUsdcAmount(requiredStringFlag(args, "budget"), units, "budget");
+        const ratePerSecondUsdc = parseUsdcAmount(requiredStringFlag(args, "rate"), units, "rate");
+        const durationSeconds = parseDurationSeconds(requiredStringFlag(args, "duration"));
+        const dryRun = booleanFlag(args, "dry-run");
+        if (budgetUsdc <= 0n || ratePerSecondUsdc <= 0n) {
+            throw new CliError("--budget and --rate must both be greater than zero", {
+                exitCode: 2,
+            });
+        }
+        const maxSpend = ratePerSecondUsdc * BigInt(durationSeconds);
+        if (maxSpend > budgetUsdc) {
+            out.note(`note: --rate x --duration (${formatUsdc(maxSpend)}) exceeds --budget; accrual is capped at the deposit and the stream simply runs out of budget before it expires.`);
+        }
+        // `--dry-run` broadcasts nothing, so it does NOT require a key: it is the
+        // look-before-you-leap path, and the person most in need of it is exactly
+        // the one who has not funded a wallet yet. Without a key the preview prints
+        // the intended call and says which parts (allowance, simulation, mandate
+        // signature) could not be produced, rather than inventing them.
+        const wallet = dryRun
+            ? await optionalCliWallet(env, { note: out.note, rpcUrl: config.rpcUrl })
+            : await resolveCliWallet(env, { note: out.note, rpcUrl: config.rpcUrl });
+        const account = wallet?.account ?? null;
+        const read = deps.createReadClient(config);
+        await assertTestnetRpc(config, () => read.getChainId());
+        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);
+        }
+        const operatorOverride = stringFlag(args, "operator");
+        const listing = await resolveListing(context, serviceRef, {
+            required: operatorOverride === undefined,
+        });
+        const operator = (operatorOverride ?? listing?.operator);
+        if (operator === undefined) {
+            throw configError(`serviceRef ${serviceRef} is not in the registry and no --operator was given`, "run `metrik discover` to find a listed service, or pass --operator explicitly.");
+        }
+        const spend = { operator, budgetUsdc, ratePerSecondUsdc, durationSeconds };
+        const mandateCaps = cliMandateCaps(spend, env);
+        // A policy-enforced wallet (Privy) is capped by its broker, not by a
+        // mandate this process signs for itself. Read the REAL ceiling and hold it
+        // to that instead — see `../spend-policy.ts` for why that substitution is
+        // the stronger of the two, and why re-adding the self-signed mandate here
+        // would both weaken it and break the wallet outright.
+        const policy = wallet !== null && isPolicyEnforced(wallet)
+            ? await wallet.readSpendPolicy()
+            : null;
+        if (policy !== null && !dryRun) {
+            assertWithinSpendPolicy(policy, spend);
+            // The operator's own standing ceiling still applies, and may be TIGHTER
+            // than the broker's. Enforced here because no mandate is signed to carry
+            // it — "policy-enforced" retires the self-signed mandate, not the caps
+            // the operator deliberately configured.
+            if (mandateCaps.source === "env") {
+                assertWithinOperatorCaps(mandateCaps.caps, spend);
+            }
+        }
+        const mandate = account === null || policy !== null
+            ? null
+            : await signCliMandate(account, spend, {
+                chainId: config.chainId,
+                env,
+            });
+        const write = deps.createWriteClient(config, account, writeClientOptions(wallet));
+        const hire = {
+            operator,
+            serviceRef,
+            budgetUsdc,
+            ratePerSecond: ratePerSecondUsdc,
+            maxDurationSeconds: durationSeconds,
+        };
+        if (dryRun) {
+            const preview = await write.buildHireTx(hire);
+            // A dry run simulates `openStream` from the CURRENT chain state, which
+            // does not include the USDC approval the real command sends first. So the
+            // simulation reverts on the allowance every time the allowance is not
+            // already in place — which, on a first hire, is always. Reporting that as
+            // `simulationError` made the one command meant to build confidence
+            // predict failure on first use. It is a known ordering step, not a fault.
+            const approvalBlocksSimulation = isApprovalOrdering(preview);
+            // Reported, never enforced: a dry run broadcasts nothing, so an
+            // underfunded wallet is information here, not a refusal. The same read
+            // IS a gate on the real path (`assertCanFundStream` above).
+            const usdcBalance = account === null
+                ? null
+                : await read.usdcBalance(account.address).catch(() => null);
+            out.result({
+                dryRun: true,
+                buyer: account?.address ?? null,
+                operator,
+                serviceRef,
+                budgetUsdc,
+                ratePerSecondUsdc,
+                durationSeconds,
+                mandateSource: mandateCaps.source,
+                mandateSigned: mandate !== null,
+                spendPolicy: policy === null
+                    ? null
+                    : {
+                        brokerUrl: policy.brokerUrl,
+                        maxTotalUsdc: policy.maxTotalUsdc,
+                        maxRatePerSecondUsdc: policy.maxRatePerSecondUsdc,
+                        maxDurationSeconds: policy.maxDurationSeconds,
+                        fits: budgetUsdc <= policy.maxTotalUsdc &&
+                            ratePerSecondUsdc <= policy.maxRatePerSecondUsdc &&
+                            durationSeconds <= policy.maxDurationSeconds,
+                    },
+                to: preview.to,
+                data: preview.data,
+                chainId: preview.chainId,
+                approval: {
+                    required: preview.approval.required,
+                    amount: preview.approval.amount,
+                    spender: preview.approval.spender,
+                    token: preview.approval.token,
+                },
+                usdcBalance,
+                usdcSufficient: usdcBalance === null ? null : usdcBalance >= budgetUsdc,
+                simulatedStreamId: preview.simulatedStreamId,
+                // Mutually exclusive by construction: an allowance-ordering revert is
+                // reported as `simulationPendingApproval`, never as an error, so a
+                // script branching on `simulationError` does not treat the expected
+                // first-hire path as a failure.
+                simulationPendingApproval: approvalBlocksSimulation,
+                ...(preview.simulationError === undefined || approvalBlocksSimulation
+                    ? {}
+                    : { simulationError: preview.simulationError }),
+            });
+            out.print("Dry run — nothing was broadcast.");
+            out.table([
+                [
+                    "buyer",
+                    account?.address ??
+                        `unknown (no wallet configured — set ${PRIVATE_KEY_ENV} or the CDP variables to preview from a real address)`,
+                ],
+                ["operator", operator],
+                ["serviceRef", serviceRef],
+                ["budget", formatUsdc(budgetUsdc)],
+                ["rate", `${formatUsdc(ratePerSecondUsdc)} / second`],
+                ["duration", formatDuration(durationSeconds)],
+                [
+                    "mandate",
+                    mandate !== null
+                        ? `self-signed, caps from ${mandateCaps.source}`
+                        : policy !== null
+                            ? "not signed — this wallet's ceiling is enforced by its broker, which is stronger"
+                            : `not signed (no wallet); caps would come from ${mandateCaps.source}`,
+                ],
+                ...(policy === null
+                    ? []
+                    : [
+                        [
+                            "spend policy",
+                            `${formatUsdc(policy.maxTotalUsdc)} total, ${policy.maxRatePerSecondUsdc} atomic/second, ${formatDuration(policy.maxDurationSeconds)} max — enforced by ${policy.brokerUrl}`,
+                        ],
+                        [
+                            "fits policy",
+                            budgetUsdc <= policy.maxTotalUsdc &&
+                                ratePerSecondUsdc <= policy.maxRatePerSecondUsdc &&
+                                durationSeconds <= policy.maxDurationSeconds
+                                ? "yes"
+                                : "NO — a real open would be refused before broadcasting",
+                        ],
+                    ]),
+                ["escrow", preview.to],
+                [
+                    "usdc balance",
+                    usdcBalance === null
+                        ? "unread (no wallet configured)"
+                        : usdcBalance >= budgetUsdc
+                            ? `${formatUsdc(usdcBalance)} (covers the budget)`
+                            : `${formatUsdc(usdcBalance)} — SHORT of the ${formatUsdc(budgetUsdc)} budget; a real open would be refused`,
+                ],
+                [
+                    "usdc approval",
+                    preview.approval.required === null
+                        ? `${formatUsdc(preview.approval.amount)} (allowance unread)`
+                        : preview.approval.required
+                            ? `${formatUsdc(preview.approval.amount)} (required)`
+                            : "already sufficient",
+                ],
+                [
+                    "simulated streamId",
+                    preview.simulatedStreamId ??
+                        (approvalBlocksSimulation
+                            ? "not simulated yet — the bounded USDC approval above is sent FIRST by a real open, and the escrow cannot pull the deposit until it lands. Expected on a first hire, not a failure."
+                            : `unavailable (${preview.simulationError ?? "simulation did not run"})`),
+                ],
+            ]);
+            out.print("");
+            out.print(METERING_NOTE);
+            return;
+        }
+        out.note(`opening a stream on chain ${config.chainId} for ${formatUsdc(budgetUsdc)} …`);
+        // Unreachable without a wallet: `resolveCliWallet` above throws when the
+        // command is not a dry run. The narrowing keeps that a type-level fact.
+        if (account === null) {
+            throw configError("this command signs a transaction and needs a wallet, and none was resolved");
+        }
+        let result;
+        try {
+            result = await write.openVerifiedStream({
+                operator,
+                serviceRef,
+                budgetUsdc,
+                ratePerSecondUsdc,
+                maxDurationSeconds: durationSeconds,
+                // `null` for a policy-enforced wallet: the ceiling was checked against
+                // the broker's own policy above, and the broker checks it again on the
+                // transaction it signs.
+                signedMandate: mandate === null ? null : mandate.signed,
+                spentSoFarUsdc: 0n,
+                nowSeconds: deps.nowSeconds(),
+            });
+        }
+        catch (error) {
+            if (error instanceof MandateDeniedError) {
+                throw new CliError(`spend mandate denied this hire: ${error.reason}`, {
+                    exitCode: 3,
+                    hint: mandateCaps.source === "env"
+                        ? "the requested hire exceeds your METRIK_AGENT_MANDATE_* ceiling."
+                        : "the hire does not satisfy the mandate signed for it.",
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        out.result({
+            streamId: result.streamId,
+            txHash: result.txHash,
+            approveTxHash: result.approveTxHash,
+            buyer: account.address,
+            operator,
+            serviceRef,
+            budgetUsdc,
+            ratePerSecondUsdc,
+            durationSeconds,
+            escrow: result.handle.escrow,
+            chainId: result.handle.chainId,
+        });
+        out.print("Stream opened.");
+        out.table([
+            ["streamId", result.streamId],
+            ["tx", result.txHash],
+            ["approve tx", result.approveTxHash ?? "not needed"],
+            ["buyer", account.address],
+            ["operator", operator],
+            ["budget", formatUsdc(budgetUsdc)],
+            ["rate", `${formatUsdc(ratePerSecondUsdc)} / second`],
+            ["duration", formatDuration(durationSeconds)],
+        ]);
+        out.print("");
+        out.print(METERING_NOTE);
+        out.print("");
+        out.print(`Next:  metrik status ${result.streamId}`);
+    },
+};
+/**
+ * What the buyer is actually paying for.
+ *
+ * A live acceptance run made ONE `invoke` call and paid for 302 seconds, which
+ * is exactly the design — and exactly what nothing in the CLI said. "Pay for
+ * verified delivery" reads as "pay for delivery TO ME", so a buyer expects
+ * per-call billing and gets a rental meter. The meter runs on the oracle's
+ * probes of the endpoint, not on the buyer's own requests; one call and a
+ * thousand calls cost the same second.
+ */
+const METERING_NOTE = "How you are billed: this is TIME-metered rental of an endpoint the oracle keeps probing — not per-call billing. The meter runs on verified availability, so it charges the same whether you send one request or a thousand, and it keeps charging while you send none. `metrik close <streamId>` stops the clock; nothing else does.";
+/**
+ * Shapes that mean "the spender's allowance is too small", across the OpenZeppelin
+ * string revert and the ERC-6093 custom error. Matched as phrases, never on the
+ * bare word `allowance`: the no-wallet preview reports `no account configured —
+ * allowance and simulation skipped`, which contains the word and is a COMPLETELY
+ * different fact. Excusing that as "an approval will be sent first" would state
+ * a reason the CLI does not have.
+ */
+const ALLOWANCE_SHORTFALL = [
+    /transfer amount exceeds allowance/i,
+    /insufficient allowance/i,
+    /ERC20InsufficientAllowance/,
+];
+/**
+ * True when the dry run's simulation failed ONLY because the USDC approval a
+ * real open sends first has not been sent.
+ *
+ * Deliberately narrow: it requires an actual REVERT, whose reason is an
+ * allowance shortfall, on a preview that says an approval is (or may be)
+ * needed. Anything else keeps being reported as a simulation error, because
+ * every other failure is a real one the buyer should see before spending.
+ */
+function isApprovalOrdering(preview) {
+    const error = preview.simulationError;
+    if (error === undefined || preview.simulatedStreamId != null)
+        return false;
+    if (preview.approval.required === false)
+        return false;
+    if (!/\brevert(ed)?\b/i.test(error))
+        return false;
+    return ALLOWANCE_SHORTFALL.some((pattern) => pattern.test(error));
+}
+//# sourceMappingURL=open.js.map

package/dist/cli/commands/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../../src/cli/commands/open.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/reclaim-unverified.d.ts

@@ -0,0 +1,3 @@
+import type { CommandSpec } from "../context.js";
+export declare const reclaimUnverifiedCommand: CommandSpec;
+//# sourceMappingURL=reclaim-unverified.d.ts.map

package/dist/cli/commands/reclaim-unverified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim-unverified.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/reclaim-unverified.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AA2CjE,eAAO,MAAM,wBAAwB,EAAE,WAwGtC,CAAC"}

package/dist/cli/commands/reclaim-unverified.js

@@ -0,0 +1,172 @@
+import { booleanFlag } from "../args.js";
+import { formatDuration, formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, usageError } from "../errors.js";
+import { escapeHatchWindow, formatTimestamp, readChainNow, } from "../escape-hatch.js";
+import { signRecoveryMandate } from "../mandate.js";
+import { assertCanPayGas } from "../preflight.js";
+import { writeClientOptions } from "../deps.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
+/**
+ * The acknowledgement this command will not run without.
+ *
+ * `reclaim-unverified` is deliberately BOTH a command of its own and a command
+ * that refuses to run on its arguments alone:
+ *
+ *  - it is not `metrik reclaim --unverified`, because that is one token away
+ *    from the safe path, sits in the same command's flag list (so a script that
+ *    templates flags can pick it up), and shell completion offers it beside
+ *    `--close-first`;
+ *  - and the flag below has no default and no `--no-` form, so the only way to
+ *    reach the transaction is to type a phrase that says what it costs.
+ *
+ * Nothing about this command is reachable by fat-fingering the ordinary one.
+ */
+const ACKNOWLEDGEMENT_FLAG = "forfeit-unclaimed";
+/**
+ * Exactly what the escrow does, so the warning does not have to be trusted.
+ *
+ * `StreamEscrowV2.reclaimUnverified` sets `entitlement = stream.claimedCumulative`
+ * and then `settledCumulative = entitlement; deposit = entitlement`. The
+ * operator's own redemption path caps at that value once the stream is
+ * reclaimed (`if (stream.reclaimed && payableCumulative > stream.settledCumulative)
+ * payableCumulative = stream.settledCumulative;`) and then requires
+ * `payableCumulative > stream.claimedCumulative` — which can never hold again.
+ * Every voucher earned but not yet redeemed on-chain is therefore forfeit
+ * PERMANENTLY, and its value is paid to the buyer.
+ */
+const FORFEIT_WARNING = [
+    "This pays you deposit - claimedCumulative with NO proof and NO oracle.",
+    "What it costs the operator: everything they verifiably earned but have not yet",
+    "claimed on-chain is forfeited to you, permanently. The escrow caps their",
+    "entitlement at what they had already claimed, so every later claim reverts",
+    "NothingToClaim(). There is no way to pay it back afterwards.",
+    "",
+    "Use it when the oracle cannot give you a proof. Where `metrik reclaim` works,",
+    "use that instead — it settles the operator honestly and pays you the rest.",
+];
+export const reclaimUnverifiedCommand = {
+    name: "reclaim-unverified",
+    summary: "Escape hatch: reclaim with no proof when the oracle cannot give you one",
+    usage: `metrik reclaim-unverified <streamId> --${ACKNOWLEDGEMENT_FLAG}`,
+    flags: [ACKNOWLEDGEMENT_FLAG],
+    signs: true,
+    async run(context) {
+        const { args, config, env, out, deps } = context;
+        const [streamIdArg] = args.positionals;
+        if (streamIdArg === undefined) {
+            throw usageError("metrik reclaim-unverified requires a <streamId>");
+        }
+        const streamId = parseBytes32(streamIdArg, "<streamId>");
+        if (!booleanFlag(args, ACKNOWLEDGEMENT_FLAG)) {
+            throw usageError(`metrik reclaim-unverified forfeits the operator's unclaimed earnings, so it requires --${ACKNOWLEDGEMENT_FLAG}`, [
+                ...FORFEIT_WARNING,
+                "",
+                `Re-run with --${ACKNOWLEDGEMENT_FLAG} once that is what you intend.`,
+            ].join("\n  "));
+        }
+        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 stream = await read.getStreamV2(streamId);
+        if (stream.reclaimed) {
+            throw new CliError("this stream has already been reclaimed — there is nothing left to take back", {
+                exitCode: 4,
+                hint: `check where it went:  metrik status ${streamId}`,
+            });
+        }
+        // Readiness is computed against the chain's clock, because the escrow
+        // compares against `block.timestamp`. Spending gas on a guaranteed
+        // `EscapeHatchNotReady()` revert is exactly the failure this gate exists to
+        // prevent.
+        const grace = await readEscapeGrace(read);
+        const now = await readChainNow(read, deps.nowSeconds());
+        const window = escapeHatchWindow(stream, grace, now.seconds);
+        if (!window.ready) {
+            throw notReady(streamId, window, now.source);
+        }
+        // The amount at stake, when it is knowable. It usually is not: the reason to
+        // be on this path at all is that the oracle is not answering, and the
+        // operator's redeemable balance is derived from the oracle's proof.
+        const forfeit = await readForfeitEstimate(read, streamId);
+        out.note("");
+        for (const line of FORFEIT_WARNING)
+            out.note(line);
+        out.note(forfeit === null
+            ? "Operator balance at stake: unknown — the oracle did not answer, which is the situation this command is for."
+            : `Operator balance at stake right now: ${formatUsdc(forfeit)} (net of protocol fee). This transaction forfeits it.`);
+        out.note("");
+        const write = deps.createWriteClient(config, account, writeClientOptions(wallet));
+        const result = await write.reclaimUnverifiedStream({
+            streamId,
+            // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
+            signedMandate: isPolicyEnforced(wallet)
+                ? null
+                : await signRecoveryMandate(account, config.chainId),
+            spentSoFarUsdc: 0n,
+            nowSeconds: deps.nowSeconds(),
+        });
+        out.result({
+            streamId,
+            txHash: result.txHash,
+            unverified: true,
+            escapeHatchReadyAt: window.readyAt,
+            escapeGraceSeconds: window.graceSeconds,
+            forfeitedOperatorClaimable: forfeit,
+        });
+        out.print("Reclaimed without a proof.");
+        out.table([
+            ["streamId", streamId],
+            ["tx", result.txHash],
+            ["escape hatch opened", formatTimestamp(window.readyAt)],
+            [
+                "operator earnings forfeited",
+                forfeit === null ? "unknown (oracle unreachable)" : formatUsdc(forfeit),
+            ],
+        ]);
+    },
+};
+function notReady(streamId, window, clock) {
+    return new CliError(`the no-proof escape hatch is not open yet: it unlocks at ${formatTimestamp(window.readyAt)}, in ${formatDuration(window.secondsRemaining)}`, {
+        exitCode: 4,
+        hint: [
+            `The escrow gates this on expiresAt + escapeGraceSeconds (${window.graceSeconds}s), never on when you closed${clock === "chain"
+                ? ""
+                : " — and the chain's own clock could not be read, so this is your machine's"}.`,
+            `Until then the honest path is the proof-based one:  metrik reclaim ${streamId}`,
+        ].join(" "),
+    });
+}
+/** `escapeGraceSeconds` is a public immutable; failing to read it is fatal here. */
+async function readEscapeGrace(read) {
+    try {
+        return await read.escapeGraceSeconds();
+    }
+    catch (error) {
+        throw new CliError("could not read escapeGraceSeconds from the escrow, so whether the escape hatch is open is unknown", {
+            exitCode: 4,
+            hint: "this command refuses to broadcast on a guess: retry when the RPC endpoint answers.",
+            cause: error,
+        });
+    }
+}
+/**
+ * What the operator could redeem right now, i.e. what this transaction takes
+ * from them. `null` when the oracle cannot be reached — which is the normal case
+ * on this path and is reported as unknown rather than as zero.
+ */
+async function readForfeitEstimate(read, streamId) {
+    try {
+        const proof = await read.checkpointProof(streamId);
+        return await read.claimableForV2(streamId, proof.cumulativeAmount);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=reclaim-unverified.js.map

package/dist/cli/commands/reclaim-unverified.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim-unverified.js","sourceRoot":"","sources":["../../../src/cli/commands/reclaim-unverified.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,GAEb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIlE;;;;;;;;;;;;;;GAcG;AACH,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,eAAe,GAAG;IACtB,wEAAwE;IACxE,gFAAgF;IAChF,0EAA0E;IAC1E,4EAA4E;IAC5E,8DAA8D;IAC9D,EAAE;IACF,+EAA+E;IAC/E,4EAA4E;CAC7E,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAgB;IACnD,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EACL,yEAAyE;IAC3E,KAAK,EAAE,0CAA0C,oBAAoB,EAAE;IACvE,KAAK,EAAE,CAAC,oBAAoB,CAAC;IAC7B,KAAK,EAAE,IAAI;IACX,KAAK,CAAC,GAAG,CAAC,OAAuB;QAC/B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;QACjD,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,UAAU,CAAC,iDAAiD,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAEzD,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,oBAAoB,CAAC,EAAE,CAAC;YAC7C,MAAM,UAAU,CACd,0FAA0F,oBAAoB,EAAE,EAChH;gBACE,GAAG,eAAe;gBAClB,EAAE;gBACF,iBAAiB,oBAAoB,gCAAgC;aACtE,CAAC,IAAI,CAAC,MAAM,CAAC,CACf,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE;YACzC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACxD,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAE7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,QAAQ,CAChB,6EAA6E,EAC7E;gBACE,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,uCAAuC,QAAQ,EAAE;aACxD,CACF,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,mEAAmE;QACnE,4EAA4E;QAC5E,WAAW;QACX,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/C,CAAC;QAED,6EAA6E;QAC7E,sEAAsE;QACtE,oEAAoE;QACpE,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACb,KAAK,MAAM,IAAI,IAAI,eAAe;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,GAAG,CAAC,IAAI,CACN,OAAO,KAAK,IAAI;YACd,CAAC,CAAC,6GAA6G;YAC/G,CAAC,CAAC,wCAAwC,UAAU,CAAC,OAAO,CAAC,uDAAuD,CACvH,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEb,MAAM,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAClC,MAAM,EACN,OAAO,EACP,kBAAkB,CAAC,MAAM,CAAC,CAC3B,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,uBAAuB,CAAC;YACjD,QAAQ;YACR,kEAAkE;YAClE,aAAa,EAAE,gBAAgB,CAAC,MAAM,CAAC;gBACrC,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,MAAM,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC;YACtD,cAAc,EAAE,EAAE;YAClB,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;SAC9B,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC;YACT,QAAQ;YACR,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,IAAI;YAChB,kBAAkB,EAAE,MAAM,CAAC,OAAO;YAClC,kBAAkB,EAAE,MAAM,CAAC,YAAY;YACvC,0BAA0B,EAAE,OAAO;SACpC,CAAC,CAAC;QACH,GAAG,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACxC,GAAG,CAAC,KAAK,CAAC;YACR,CAAC,UAAU,EAAE,QAAQ,CAAC;YACtB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,CAAC,qBAAqB,EAAE,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxD;gBACE,6BAA6B;gBAC7B,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;aACxE;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,SAAS,QAAQ,CACf,QAAuB,EACvB,MAAyB,EACzB,KAAwB;IAExB,OAAO,IAAI,QAAQ,CACjB,4DAA4D,eAAe,CACzE,MAAM,CAAC,OAAO,CACf,QAAQ,cAAc,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAClD;QACE,QAAQ,EAAE,CAAC;QACX,IAAI,EAAE;YACJ,4DAA4D,MAAM,CAAC,YAAY,+BAC7E,KAAK,KAAK,OAAO;gBACf,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,2EACN,GAAG;YACH,sEAAsE,QAAQ,EAAE;SACjF,CAAC,IAAI,CAAC,GAAG,CAAC;KACZ,CACF,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,KAAK,UAAU,eAAe,CAAC,IAAmB;IAChD,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAChB,mGAAmG,EACnG;YACE,QAAQ,EAAE,CAAC;YACX,IAAI,EAAE,oFAAoF;YAC1F,KAAK,EAAE,KAAK;SACb,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,mBAAmB,CAChC,IAAmB,EACnB,QAAuB;IAEvB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QACnD,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cli/commands/reclaim.d.ts

@@ -0,0 +1,33 @@
+import type { CommandSpec } from "../context.js";
+import type { CliReadClient, CliWriteClient } from "../deps.js";
+import type { ReclaimVerifiedStreamResult, StreamProofTransactionResult } from "../../sdk/client.js";
+export declare const reclaimCommand: CommandSpec;
+/**
+ * Send the close that `--close-first` asks for, tolerating the one race that
+ * matters: a stale read said "active" but the stream was in fact already closed.
+ * That is the state the caller wanted, so it is reported as `null` (no close
+ * sent) rather than as a failure — re-running the command must never dead-end on
+ * `StreamClosedAlready()` while the buyer's money is still reclaimable.
+ *
+ * Every OTHER close failure is rethrown untouched.
+ */
+export declare function closeBeforeReclaim(write: CliWriteClient, input: Parameters<CliWriteClient["closeStream"]>[0]): Promise<StreamProofTransactionResult | null>;
+export declare function awaitClosed(read: Pick<CliReadClient, "getStreamV2">, streamId: `0x${string}`, sleep: (ms: number) => Promise<void>, closeTxHash: string): Promise<void>;
+/**
+ * `reclaimWithProof` reverts with `SettlementWindowOpen` until the oracle has
+ * published a checkpoint whose `checkedAt` is at or after the stream's stop
+ * 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.
+ */
+export declare function reclaimWithBoundedRetry(write: CliWriteClient, buildInput: () => Promise<Parameters<CliWriteClient["reclaimStream"]>[0]>, options: {
+    readonly attempts: number;
+    readonly intervalMs: number;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly onRetry: (attempt: number, reason: string) => void;
+    /** What to tell the buyer once the budget is spent. See `describeLastResort`. */
+    readonly exhaustedHint?: () => Promise<string>;
+}): Promise<ReclaimVerifiedStreamResult>;
+//# sourceMappingURL=reclaim.d.ts.map

package/dist/cli/commands/reclaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/reclaim.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAW7B,eAAO,MAAM,cAAc,EAAE,WA4I5B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAO9C;AA0BD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,EACxC,QAAQ,EAAE,KAAK,MAAM,EAAE,EACvB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EACpC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACzE,OAAO,EAAE;IACP,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,iFAAiF;IACjF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD,GACA,OAAO,CAAC,2BAA2B,CAAC,CAuBtC"}