@absol-labs/agent 0.9.1 → 0.10.0

package/dist/cli/deps.js

@@ -0,0 +1,227 @@
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import { MetrikClient, } from "@absol-labs/sdk";
+import { erc20Abi, getAbiItem, http } from "viem";
+import { discoverServicesDetailed, } from "../discovery/registry.js";
+import { invoke as sdkInvoke, } from "../sdk/invoke.js";
+import { VerifiedStreamAgentClient, } from "../sdk/client.js";
+import { RPC_RETRY_COUNT, RPC_TIMEOUT_MS, withReadTimeout } from "./timeout.js";
+/**
+ * The `StreamOpened` ABI entry, resolved once. Taken from the shared V2 ABI
+ * rather than re-declared: a hand-written copy that drifted by one indexed
+ * argument would silently match nothing.
+ */
+const STREAM_OPENED_EVENT = getAbiItem({
+    abi: streamEscrowV2Abi,
+    name: "StreamOpened",
+});
+/**
+ * The RPC transport, with an explicit per-call budget.
+ *
+ * viem's defaults leave a single `eth_call` able to hang for a long time behind
+ * three backing-off retries, which is how a `status` run reached two minutes
+ * with nothing on screen. Bounding it here bounds every read and every
+ * simulation the SDK performs, in one place.
+ */
+function rpcTransport(config) {
+    return http(config.rpcUrl, {
+        timeout: RPC_TIMEOUT_MS,
+        retryCount: RPC_RETRY_COUNT,
+    });
+}
+/** Shared `MetrikClient` construction: one escrow, declared as V2 on both keys. */
+function createMetrikClient(config, account) {
+    return new MetrikClient({
+        chain: config.chain,
+        transport: rpcTransport(config),
+        escrow: config.escrow,
+        // Declared on BOTH keys: without `escrowV2` the SDK routes reads and
+        // settlement through the legacy V1 ABI, which reverts against
+        // StreamEscrowV2 (its one-argument views were replaced by proof-carrying
+        // ones, and `reclaim` becomes `reclaimWithProof`).
+        escrowV2: config.escrow,
+        usdc: config.usdc,
+        oracleBaseUrl: config.oracleBaseUrl,
+        settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+        ...(account === undefined ? {} : { account }),
+    });
+}
+export const defaultCliDependencies = {
+    createReadClient(config) {
+        const metrik = createMetrikClient(config);
+        return {
+            async getChainId() {
+                return await metrik.publicClient.getChainId();
+            },
+            async getStreamV2(streamId) {
+                return await metrik.getStreamV2(streamId);
+            },
+            async checkpointProof(streamId) {
+                // Not an RPC call: this is an HTTP fetch against the oracle, so the
+                // transport budget above does not cover it.
+                return await withReadTimeout(async () => await metrik.checkpointProof(streamId), `the oracle at ${config.oracleBaseUrl}`);
+            },
+            async claimableForV2(streamId, cumulativeAmount) {
+                return await metrik.claimableForV2(streamId, cumulativeAmount);
+            },
+            async reclaimableForV2(streamId, cumulativeAmount) {
+                return await metrik.reclaimableForV2(streamId, cumulativeAmount);
+            },
+            async nativeBalance(address) {
+                return await metrik.publicClient.getBalance({ address });
+            },
+            async usdcBalance(address) {
+                return await metrik.publicClient.readContract({
+                    address: config.usdc,
+                    abi: erc20Abi,
+                    functionName: "balanceOf",
+                    args: [address],
+                });
+            },
+            async blockNumber() {
+                return await metrik.publicClient.getBlockNumber();
+            },
+            async streamOpenedLogs({ role, address, fromBlock, toBlock }) {
+                const logs = await metrik.publicClient.getLogs({
+                    address: config.escrow,
+                    event: STREAM_OPENED_EVENT,
+                    args: { [role]: address },
+                    fromBlock,
+                    toBlock,
+                });
+                // Returned as-is: the topic filter is evaluated by the node, so
+                // re-checking `log.args.buyer === address` here would imply the filter
+                // is decorative and would hide a mis-built filter behind a second pass.
+                // A wrong filter should produce a visibly wrong result, not a quietly
+                // correct one.
+                return logs.flatMap((log) => log.args.streamId === undefined ||
+                    log.args.buyer === undefined ||
+                    log.args.operator === undefined ||
+                    log.args.serviceRef === undefined ||
+                    log.args.deposit === undefined ||
+                    log.args.ratePerSecond === undefined ||
+                    log.args.expiresAt === undefined
+                    ? []
+                    : [
+                        {
+                            streamId: log.args.streamId,
+                            buyer: log.args.buyer,
+                            operator: log.args.operator,
+                            serviceRef: log.args.serviceRef,
+                            deposit: log.args.deposit,
+                            ratePerSecond: log.args.ratePerSecond,
+                            expiresAt: Number(log.args.expiresAt),
+                            blockNumber: log.blockNumber ?? 0n,
+                        },
+                    ]);
+            },
+            async escrowLogCountAt(block) {
+                const logs = await metrik.publicClient.getLogs({
+                    address: config.escrow,
+                    fromBlock: block,
+                    toBlock: block,
+                });
+                return logs.length;
+            },
+            async protocolFeeBps() {
+                const bps = await metrik.publicClient.readContract({
+                    address: config.escrow,
+                    abi: streamEscrowV2Abi,
+                    functionName: "protocolFeeBps",
+                });
+                return Number(bps);
+            },
+            async escapeGraceSeconds() {
+                const seconds = await metrik.publicClient.readContract({
+                    address: config.escrow,
+                    abi: streamEscrowV2Abi,
+                    functionName: "escapeGraceSeconds",
+                });
+                return Number(seconds);
+            },
+            async latestCheckpointCheckedAt() {
+                const checkedAt = await metrik.publicClient.readContract({
+                    address: config.escrow,
+                    abi: streamEscrowV2Abi,
+                    functionName: "latestCheckpointCheckedAt",
+                });
+                return Number(checkedAt);
+            },
+            async latestBlockTimestamp() {
+                const block = await metrik.publicClient.getBlock();
+                return Number(block.timestamp);
+            },
+            async oracleSigners() {
+                return await metrik.publicClient.readContract({
+                    address: config.escrow,
+                    abi: streamEscrowV2Abi,
+                    functionName: "getOracleSigners",
+                });
+            },
+        };
+    },
+    createWriteClient(config, account) {
+        const clientConfig = {
+            chain: config.chain,
+            transport: rpcTransport(config),
+            escrow: config.escrow,
+            escrowV2: config.escrow,
+            usdc: config.usdc,
+            oracleBaseUrl: config.oracleBaseUrl,
+            settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+            ...(account === null ? {} : { account }),
+        };
+        // The mandate-gated agent client owns every fund-moving call; the raw SDK
+        // client is used only for the build-only `--dry-run` preview, which
+        // broadcasts nothing.
+        const agentClient = new VerifiedStreamAgentClient(clientConfig);
+        const metrik = createMetrikClient(config, ...(account === null ? [] : [account]));
+        return {
+            async buildHireTx(input) {
+                return await metrik.buildHireTx(input);
+            },
+            async openVerifiedStream(input) {
+                return await agentClient.openVerifiedStream(input);
+            },
+            async closeStream(input) {
+                return await agentClient.closeStream(input);
+            },
+            async reclaimStream(input) {
+                return await agentClient.reclaimStream(input);
+            },
+            async reclaimUnverifiedStream(input) {
+                return await agentClient.reclaimUnverifiedStream(input);
+            },
+            async claimStream(input) {
+                return await agentClient.claimStream(input);
+            },
+        };
+    },
+    async discover(options) {
+        return await discoverServicesDetailed(options);
+    },
+    async invoke(streamId, request, options) {
+        return await sdkInvoke(streamId, request, options);
+    },
+    createInvokeStreamReader(config) {
+        const metrik = createMetrikClient(config);
+        return {
+            async getStreamV2(streamId) {
+                const stream = await metrik.getStreamV2(streamId);
+                return {
+                    buyer: stream.buyer,
+                    operator: stream.operator,
+                    serviceRef: stream.serviceRef,
+                    status: stream.status,
+                    expiresAt: stream.expiresAt,
+                };
+            },
+        };
+    },
+    nowSeconds() {
+        return Math.floor(Date.now() / 1000);
+    },
+    async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    },
+};
+//# sourceMappingURL=deps.js.map

package/dist/cli/deps.js.map

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

package/dist/cli/descriptor.d.ts

@@ -0,0 +1,61 @@
+import type { SignedServiceBinding, SignedServiceDescriptor } from "@absol-labs/shared";
+import type { DiscoveredService } from "../discovery/registry.js";
+/**
+ * What a listing's SIGNED descriptor already tells a newcomer — surfaced rather
+ * than discarded.
+ *
+ * The registry's signed records carry the callable endpoints, one worked example
+ * call, and the operator's accepted rate band. `metrik discover` used to project
+ * them away, so the CLI could show a `serviceRef` but never what the service
+ * DOES, what path to call, or what `--rate` the operator will accept. Everything
+ * here is read from the record whose signature was already recovered and
+ * matched, so nothing unsigned is ever presented as fact.
+ */
+export interface ListingEndpoint {
+    readonly name: string;
+    readonly path: string;
+    readonly method: string;
+    readonly description: string | null;
+}
+export interface ListingExample {
+    readonly endpoint: string;
+    readonly description: string | null;
+    readonly request: unknown;
+    readonly response: unknown;
+}
+export interface ListingRates {
+    /** USDC base units per second, as signed (decimal strings, never floats). */
+    readonly minRatePerSecond: string | null;
+    readonly maxRatePerSecond: string | null;
+    readonly currency: string | null;
+    readonly slaDescription: string | null;
+    readonly refundPolicy: string | null;
+}
+export interface ListingDetail {
+    readonly endpoints: readonly ListingEndpoint[];
+    readonly example: ListingExample | null;
+    readonly rates: ListingRates | null;
+    readonly authModel: string | null;
+}
+/**
+ * Project the signed record onto the presentable detail. A legacy binding (which
+ * carries no interface at all) yields empty detail rather than an invented one.
+ */
+export declare function listingDetail(signed: SignedServiceBinding | SignedServiceDescriptor | undefined): ListingDetail;
+/**
+ * How much verification a listing actually declares. Used to order `discover`
+ * strongest-first so `--limit 1` returns the best-attested listing rather than
+ * whatever the registry happened to serve first — which is how a newcomer's very
+ * first result ended up being a deliberately-failing test fixture.
+ *
+ * This ranks the DECLARED verification spec, which is the only thing the signed
+ * record can tell us. It is a presentation order, not a trust score.
+ */
+export declare function verificationStrength(service: DiscoveredService): number;
+/**
+ * Deterministic, strongest-verification-first order. Ties break on `serviceRef`
+ * so the same registry always renders in the same order and `--limit N` is
+ * reproducible between runs.
+ */
+export declare function orderListings<T extends DiscoveredService>(services: readonly T[]): T[];
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/cli/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../src/cli/descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,oBAAoB,GAAG,uBAAuB,GAAG,SAAS,GACjE,aAAa,CAmCf;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CASvE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,iBAAiB,EACvD,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,EAAE,CAOL"}

package/dist/cli/descriptor.js

@@ -0,0 +1,78 @@
+const EMPTY_DETAIL = {
+    endpoints: [],
+    example: null,
+    rates: null,
+    authModel: null,
+};
+/**
+ * Project the signed record onto the presentable detail. A legacy binding (which
+ * carries no interface at all) yields empty detail rather than an invented one.
+ */
+export function listingDetail(signed) {
+    const descriptor = signed
+        ?.descriptor;
+    if (descriptor === undefined)
+        return EMPTY_DETAIL;
+    const iface = descriptor.interface;
+    const commercial = descriptor.commercial;
+    return {
+        endpoints: (iface?.endpoints ?? []).map((endpoint) => ({
+            name: endpoint.name,
+            path: endpoint.path,
+            method: endpoint.method,
+            description: endpoint.description ?? null,
+        })),
+        example: iface?.example === undefined
+            ? null
+            : {
+                endpoint: iface.example.endpoint,
+                description: iface.example.description ?? null,
+                request: iface.example.request ?? null,
+                response: iface.example.response ?? null,
+            },
+        rates: commercial === undefined
+            ? null
+            : {
+                minRatePerSecond: commercial.minRatePerSecond ?? null,
+                maxRatePerSecond: commercial.maxRatePerSecond ?? null,
+                currency: commercial.currency ?? null,
+                slaDescription: commercial.slaDescription ?? null,
+                refundPolicy: commercial.refundPolicy ?? null,
+            },
+        authModel: iface?.authModel ?? null,
+    };
+}
+/**
+ * How much verification a listing actually declares. Used to order `discover`
+ * strongest-first so `--limit 1` returns the best-attested listing rather than
+ * whatever the registry happened to serve first — which is how a newcomer's very
+ * first result ended up being a deliberately-failing test fixture.
+ *
+ * This ranks the DECLARED verification spec, which is the only thing the signed
+ * record can tell us. It is a presentation order, not a trust score.
+ */
+export function verificationStrength(service) {
+    const summary = service.verification;
+    if (summary === null)
+        return 0;
+    return ((summary.hasReexec ? 8 : 0) +
+        (summary.hasSchema ? 4 : 0) +
+        (summary.hasSla ? 2 : 0) +
+        Math.min(summary.canaries, 1));
+}
+/**
+ * Deterministic, strongest-verification-first order. Ties break on `serviceRef`
+ * so the same registry always renders in the same order and `--limit N` is
+ * reproducible between runs.
+ */
+export function orderListings(services) {
+    return [...services].sort((left, right) => {
+        if (left.tier !== right.tier)
+            return right.tier - left.tier;
+        const strength = verificationStrength(right) - verificationStrength(left);
+        if (strength !== 0)
+            return strength;
+        return left.serviceRef.localeCompare(right.serviceRef);
+    });
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/cli/descriptor.js.map

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

package/dist/cli/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CLI error taxonomy. Every expected failure surfaces as a `CliError` so the
+ * runner can print one actionable line instead of a viem/zod stack dump, and so
+ * a script can branch on the exit code.
+ */
+export type CliExitCode = 
+/** Bad flags, missing arguments, unparseable amounts. */
+2
+/** Configuration refused: wrong chain, missing key, mainnet target. */
+ | 3
+/** The operation itself failed (RPC, registry, escrow revert, HTTP). */
+ | 4;
+export declare class CliError extends Error {
+    readonly exitCode: CliExitCode;
+    /** Optional next step printed under the message in human mode. */
+    readonly hint: string | undefined;
+    constructor(message: string, options?: {
+        readonly exitCode?: CliExitCode;
+        readonly hint?: string;
+        readonly cause?: unknown;
+    });
+}
+/** Usage error: the caller typed something the CLI cannot act on. */
+export declare function usageError(message: string, hint?: string): CliError;
+/** Configuration error: the environment/flags describe a target we refuse. */
+export declare function configError(message: string, hint?: string): CliError;
+/**
+ * Unwrap the most useful message from an arbitrary thrown value.
+ *
+ * Boilerplate links are dropped once something in the chain has already named
+ * the revert; when nothing has, ONE is kept, because "it reverted" is then the
+ * only fact available and losing it would leave a bare "close failed".
+ */
+export declare function describeError(error: unknown): string;
+/** Exported for the test that pins the shape of the chain, not the wording. */
+export declare function stripRedundantBoilerplate(chain: readonly string[]): readonly string[];
+/**
+ * Tidy one message line for display.
+ *
+ * viem renders an undecodable revert payload as `Execution reverted with
+ * reason: <the raw bytes as text>`, which arrives as mojibake glued to the end
+ * of an otherwise excellent error ("… Execution reverted with reason: ׃.x."). A
+ * revert reason that is not printable ASCII carries no information for a reader,
+ * so the unreadable tail is dropped and the useful prefix kept. Legitimate
+ * reasons — which are ASCII strings the contract author wrote — are untouched.
+ */
+export declare function presentMessage(raw: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cli/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/cli/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,WAAW;AACrB,yDAAyD;AACvD,CAAC;AACH,uEAAuE;GACrE,CAAC;AACH,wEAAwE;GACtE,CAAC,CAAC;AAEN,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;KACrB;CAOT;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKnE;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKpE;AAmCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpD;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,MAAM,EAAE,CAenB;AAaD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAelD"}

package/dist/cli/errors.js

@@ -0,0 +1,129 @@
+export class CliError extends Error {
+    exitCode;
+    /** Optional next step printed under the message in human mode. */
+    hint;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? {} : { cause: options.cause });
+        this.name = "CliError";
+        this.exitCode = options.exitCode ?? 4;
+        this.hint = options.hint;
+    }
+}
+/** Usage error: the caller typed something the CLI cannot act on. */
+export function usageError(message, hint) {
+    return new CliError(message, {
+        exitCode: 2,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+/** Configuration error: the environment/flags describe a target we refuse. */
+export function configError(message, hint) {
+    return new CliError(message, {
+        exitCode: 3,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+/**
+ * viem's generic tail. Each of these is true and each carries zero information
+ * once an outer link has already named the revert:
+ *
+ *   NothingToReclaim() — …this will not change on retry:
+ *     The contract function "reclaim" reverted.:
+ *     Execution reverted for an unknown reason.
+ *
+ * The message names the reason and then says the reason is unknown. Matched
+ * against a WHOLE link, so a message that merely contains one of these phrases
+ * alongside real detail is never dropped.
+ */
+const VIEM_BOILERPLATE = [
+    /^The contract function "[^"]*" reverted\.?$/,
+    /^Execution reverted for an unknown reason\.?$/,
+    /^Execution reverted\.?$/,
+    /^Execution reverted\.? \(the revert payload is not a readable reason string\)$/,
+    /^An unknown RPC error occurred\.?$/,
+];
+/** Does this link name a concrete revert — a custom error, reason or panic? */
+function namesTheRevert(line) {
+    return (/\b[A-Z][A-Za-z0-9]*\([^)]*\)/.test(line) ||
+        /\breverted:/.test(line) ||
+        /\bpanicked with code\b/.test(line));
+}
+function isBoilerplate(line) {
+    return VIEM_BOILERPLATE.some((pattern) => pattern.test(line));
+}
+/**
+ * Unwrap the most useful message from an arbitrary thrown value.
+ *
+ * Boilerplate links are dropped once something in the chain has already named
+ * the revert; when nothing has, ONE is kept, because "it reverted" is then the
+ * only fact available and losing it would leave a bare "close failed".
+ */
+export function describeError(error) {
+    if (error instanceof Error) {
+        const chain = [];
+        for (let current = error, depth = 0; depth < 4; depth++) {
+            if (!(current instanceof Error))
+                break;
+            const line = presentMessage(current.message.split("\n")[0] ?? "");
+            if (line.length > 0 && !chain.includes(line)) {
+                chain.push(line);
+            }
+            current = current.cause;
+        }
+        return stripRedundantBoilerplate(chain).join(": ");
+    }
+    return presentMessage(String(error));
+}
+/** Exported for the test that pins the shape of the chain, not the wording. */
+export function stripRedundantBoilerplate(chain) {
+    const decoded = chain.some((line) => namesTheRevert(line) && !isBoilerplate(line));
+    let keptBoilerplate = false;
+    const kept = chain.filter((line, index) => {
+        if (!isBoilerplate(line))
+            return true;
+        // The first link is the thrown error's own message: never dropped, or a
+        // failure whose entire message is boilerplate would print as nothing.
+        if (index === 0)
+            return true;
+        if (decoded || keptBoilerplate)
+            return false;
+        keptBoilerplate = true;
+        return true;
+    });
+    return kept.length > 0 ? kept : chain;
+}
+/**
+ * Internal SDK method names that mean nothing to someone running a CLI. The
+ * message is otherwise good, so the name is rewritten rather than the whole line
+ * discarded. `getStreamV2` in particular is an SDK METHOD, not a contract
+ * function — printing it invites a reader to go looking for it on the escrow.
+ */
+const INTERNAL_NAMES = [
+    [/\bgetStreamV2 failed for stream\b/g, "could not read stream"],
+    [/\bgetStream failed for stream\b/g, "could not read stream"],
+];
+/**
+ * Tidy one message line for display.
+ *
+ * viem renders an undecodable revert payload as `Execution reverted with
+ * reason: <the raw bytes as text>`, which arrives as mojibake glued to the end
+ * of an otherwise excellent error ("… Execution reverted with reason: ׃.x."). A
+ * revert reason that is not printable ASCII carries no information for a reader,
+ * so the unreadable tail is dropped and the useful prefix kept. Legitimate
+ * reasons — which are ASCII strings the contract author wrote — are untouched.
+ */
+export function presentMessage(raw) {
+    let message = raw.trim();
+    for (const [pattern, replacement] of INTERNAL_NAMES) {
+        message = message.replace(pattern, replacement);
+    }
+    message = message.replace(/(Execution reverted with reason:)\s*(.*)$/, (whole, prefix, reason) => {
+        const trimmed = reason.trim();
+        if (trimmed.length >= 3 && /^[\x20-\x7e]+$/.test(trimmed))
+            return whole;
+        return `${prefix.replace(/ with reason:$/, ".")} (the revert payload is not a readable reason string)`;
+    });
+    // Strip control characters wherever they survived: they corrupt a terminal.
+    return message.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim();
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/errors.js.map

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

package/dist/cli/escape-hatch.d.ts

@@ -0,0 +1,50 @@
+import type { StreamV2 } from "@absol-labs/sdk";
+import type { CliReadClient } from "./deps.js";
+/**
+ * The buyer's no-proof escape hatch, as the CLI reasons about it.
+ *
+ * Every OTHER route the CLI has to a buyer's money goes through
+ * `reclaimWithProof`, which needs a Merkle proof fetched from the oracle. So the
+ * whole proof-based path is only as available as the oracle is.
+ * `StreamEscrowV2.reclaimUnverified` is the path that is not: buyer-only, no
+ * proof, no signer quorum, no guardian. It is gated on one thing —
+ *
+ *     block.timestamp >= expiresAt + escapeGraceSeconds
+ *
+ * — and `escapeGraceSeconds` is a public immutable on the escrow, so readiness
+ * is fully computable before a single wei of gas is spent.
+ *
+ * Note which timestamp the escrow uses: `expiresAt`, NEVER `closedAt`. Closing a
+ * stream early does not bring the escape hatch forward, and the CLI must not
+ * imply that it does.
+ */
+export interface EscapeHatchWindow {
+    /** `escapeGraceSeconds` as read from the escrow. */
+    readonly graceSeconds: number;
+    /** The exact unix second at which `reclaimUnverified` stops reverting. */
+    readonly readyAt: number;
+    readonly ready: boolean;
+    /** Seconds left until `readyAt`; `0` once the window is open. */
+    readonly secondsRemaining: number;
+}
+export declare function escapeHatchWindow(stream: Pick<StreamV2, "expiresAt">, graceSeconds: number, nowSeconds: number): EscapeHatchWindow;
+/** `2026-09-17T09:15:00.000Z (1789…)`, or `-` for an unset timestamp. */
+export declare function formatTimestamp(seconds: number): string;
+/** One line describing where the escape hatch stands, for humans. */
+export declare function describeEscapeHatch(window: EscapeHatchWindow): string;
+export interface ChainNow {
+    readonly seconds: number;
+    /** `local` means the chain would not answer and the caller's clock was used. */
+    readonly source: "chain" | "local";
+}
+/**
+ * The time the ESCROW will compare against, not the time this machine thinks it
+ * is. `reclaimUnverified` reverts on `block.timestamp`, so a readiness answer
+ * computed from a skewed laptop clock could tell a buyer to spend gas on a
+ * guaranteed revert — or tell them to wait when the hatch is already open.
+ *
+ * A failed read is not fatal: the caller's clock is the fallback, and the
+ * `source` field is reported so the difference is never hidden.
+ */
+export declare function readChainNow(read: Pick<CliReadClient, "latestBlockTimestamp">, fallbackSeconds: number): Promise<ChainNow>;
+//# sourceMappingURL=escape-hatch.d.ts.map

package/dist/cli/escape-hatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-hatch.d.ts","sourceRoot":"","sources":["../../src/cli/escape-hatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,EACnC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,iBAAiB,CASnB;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAMrE;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,sBAAsB,CAAC,EACjD,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,QAAQ,CAAC,CAUnB"}