@absol-labs/agent 0.9.1 → 0.11.0

package/dist/cli/scan-range.js

@@ -0,0 +1,57 @@
+/**
+ * Pure block-range arithmetic for the escrow log scan behind `metrik streams`.
+ * No RPC, no clock, no env — so the coverage rules below are unit-testable
+ * without a network, which is the point: they decide when an empty result is
+ * allowed to be rendered as "you have no streams".
+ *
+ * ## Why the anchor is the deploy block
+ *
+ * A fixed lookback ("the last N blocks") cannot describe coverage: a wallet
+ * whose stream predates the window is shown an empty list with nothing to
+ * distinguish it from a wallet that never opened one. For a payments tool,
+ * telling someone their escrowed funds do not exist is the worst failure we
+ * have. The escrow has NO history before its deploy block, so that block is the
+ * honest anchor — and whether the budget reached it is then a fact the command
+ * can state.
+ *
+ * ## Why the window is 10 000 blocks
+ *
+ * `buyer` and `operator` are INDEXED on `StreamOpened`, so a per-wallet scan is
+ * a server-side topic filter whose response is tiny regardless of range. What
+ * public RPCs cap is the per-call BLOCK RANGE, and a topic filter does not lift
+ * it: `sepolia.base.org` answers a wider range with `-32614 "eth_getLogs is
+ * limited to a 10,000 range"`. So the page size is the cap, not a guess below
+ * it.
+ */
+/**
+ * getLogs page size. The window is `chunk + 1` blocks (bounds inclusive), so
+ * 9 999 is the largest page `sepolia.base.org` accepts.
+ */
+export const LOG_SCAN_CHUNK = 9999n;
+/**
+ * Window budget for one scan. 400 x 10 000 = 4 000 000 blocks, comfortably more
+ * than the live escrow's history (~1.06M blocks on 2026-09-17), so the default
+ * scan is complete rather than merely large. It is a CEILING, not a fixed cost:
+ * windows are built for the actual anchor-to-head span. Exceeding it is not an
+ * error — it is reported as `degraded`.
+ */
+export const LOG_SCAN_MAX_WINDOWS = 400;
+/**
+ * Page `[anchor, head]` into non-overlapping inclusive windows.
+ *
+ * An RPC that is behind the deployment yields an empty-but-valid range rather
+ * than a negative one, and an anchor past the head is clamped: a node still
+ * syncing must not produce a nonsense scan.
+ */
+export function escrowScanRange(head, anchorBlock, chunk = LOG_SCAN_CHUNK, maxWindows = LOG_SCAN_MAX_WINDOWS) {
+    const anchor = anchorBlock < 0n ? 0n : anchorBlock > head ? head : anchorBlock;
+    const maxSpan = (chunk + 1n) * BigInt(maxWindows);
+    const degraded = head - anchor > maxSpan;
+    const fromBlock = degraded ? head - maxSpan : anchor;
+    const windows = [];
+    for (let start = fromBlock; start <= head; start += chunk + 1n) {
+        windows.push([start, start + chunk > head ? head : start + chunk]);
+    }
+    return { fromBlock, toBlock: head, windows, degraded };
+}
+//# sourceMappingURL=scan-range.js.map

package/dist/cli/scan-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-range.js","sourceRoot":"","sources":["../../src/cli/scan-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAM,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAWxC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,WAAmB,EACnB,QAAgB,cAAc,EAC9B,aAAqB,oBAAoB;IAEzC,MAAM,MAAM,GACV,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IAClE,MAAM,OAAO,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAErD,MAAM,OAAO,GAAkC,EAAE,CAAC;IAClD,KAAK,IAAI,KAAK,GAAG,SAAS,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}

package/dist/cli/spend-policy.d.ts

@@ -0,0 +1,60 @@
+import type { PrivySpendPolicy } from "./privy.js";
+import type { RequestedSpend } from "./mandate.js";
+import type { ServerMandateCaps } from "../mandates/env.js";
+/**
+ * Where a hire's spend ceiling comes from, and who enforces it.
+ *
+ * The CLI has two kinds of wallet, and they differ in WHO holds the key — which
+ * is the whole reason the self-signed spend mandate exists at all:
+ *
+ *  - **Key-holding wallet** (a raw private key, a CDP account). The person
+ *    typing the command holds the key, so nothing outside this process bounds
+ *    what that key can spend. `signCliMandate()` makes the agent state its own
+ *    ceiling, and `checkMandate()` enforces it here. That is the best available
+ *    guarantee when the client is the last line of defence.
+ *
+ *  - **Policy-enforced wallet** (Privy, either shape). The key lives at Privy
+ *    and is exercised by the broker, which caps every `openStream` against a
+ *    policy the client CANNOT reach or raise. Re-signing a local mandate on top
+ *    of that adds nothing: it is an agent attesting to its own limits when a
+ *    stronger limit is already enforced somewhere the agent cannot touch. Worse,
+ *    it cannot even be produced — the broker's typed-data policy allows an
+ *    `InvocationCapability` and nothing else — so insisting on it would block
+ *    the wallet whose ceiling is the stronger of the two.
+ *
+ * So for a policy-enforced wallet the CLI does not self-sign a mandate. It
+ * SUBSTITUTES the real ceiling rather than dropping the check: it reads the
+ * broker's public `/v1/config` and refuses an over-ceiling hire locally, in the
+ * same shape as the gas and USDC preflights — fail early with an actionable
+ * message instead of paying gas to learn a knowable fact.
+ *
+ * **Do not "restore" the mandate here for consistency.** Its premise is
+ * key-holding, and that premise is false for these wallets. Reinstating it
+ * would weaken the property that makes them non-custodial (the broker would
+ * have to be widened to sign `SpendMandate`) while making every fund-moving
+ * command fail against the broker as deployed.
+ */
+export interface SpendCeiling {
+    readonly policy: PrivySpendPolicy;
+}
+/**
+ * Refuse a hire the broker will refuse anyway, before any gas is spent.
+ *
+ * Mirrors the broker's own `openStream` check exactly — `deposit`,
+ * `ratePerSecond` and `duration` each against their ceiling — because a
+ * divergent copy would either block hires the broker would allow or promise
+ * hires it will not.
+ */
+export declare function assertWithinSpendPolicy(policy: PrivySpendPolicy, spend: RequestedSpend): void;
+/**
+ * Refuse a hire that exceeds an OPERATOR-SET standing ceiling.
+ *
+ * `METRIK_AGENT_MANDATE_*` is not the self-signed mandate: it is a ceiling the
+ * operator deliberately configured, and it can be TIGHTER than the broker
+ * policy. A policy-enforced wallet skips the self-signed mandate, so without
+ * this the env caps would silently stop applying to exactly the wallets an
+ * unattended run is most likely to use. Enforced locally here instead, with the
+ * same comparisons `checkMandate()` makes.
+ */
+export declare function assertWithinOperatorCaps(caps: ServerMandateCaps, spend: RequestedSpend): void;
+//# sourceMappingURL=spend-policy.d.ts.map

package/dist/cli/spend-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-policy.d.ts","sourceRoot":"","sources":["../../src/cli/spend-policy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,cAAc,GACpB,IAAI,CA4BN;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,cAAc,GACpB,IAAI,CAyCN"}

package/dist/cli/spend-policy.js

@@ -0,0 +1,65 @@
+import { formatUsdc } from "./amounts.js";
+import { CliError } from "./errors.js";
+/**
+ * Refuse a hire the broker will refuse anyway, before any gas is spent.
+ *
+ * Mirrors the broker's own `openStream` check exactly — `deposit`,
+ * `ratePerSecond` and `duration` each against their ceiling — because a
+ * divergent copy would either block hires the broker would allow or promise
+ * hires it will not.
+ */
+export function assertWithinSpendPolicy(policy, spend) {
+    const over = [];
+    if (spend.budgetUsdc > policy.maxTotalUsdc) {
+        over.push(`--budget ${formatUsdc(spend.budgetUsdc)} exceeds the policy ceiling of ${formatUsdc(policy.maxTotalUsdc)}`);
+    }
+    if (spend.ratePerSecondUsdc > policy.maxRatePerSecondUsdc) {
+        over.push(`--rate ${spend.ratePerSecondUsdc} atomic/second exceeds the policy ceiling of ${policy.maxRatePerSecondUsdc} atomic/second`);
+    }
+    if (spend.durationSeconds > policy.maxDurationSeconds) {
+        over.push(`--duration ${spend.durationSeconds}s exceeds the policy ceiling of ${policy.maxDurationSeconds}s`);
+    }
+    if (over.length === 0)
+        return;
+    throw new CliError(`this hire is outside the spend policy your wallet is capped at: ${over.join("; ")}`, {
+        exitCode: 3,
+        hint: `the ceiling is enforced by the broker at ${policy.brokerUrl} (GET /v1/config), not by this CLI — you cannot raise it from this side, ` +
+            "which is exactly what makes the wallet non-custodial. Size the stream to fit, or use a key-holding wallet.",
+    });
+}
+/**
+ * Refuse a hire that exceeds an OPERATOR-SET standing ceiling.
+ *
+ * `METRIK_AGENT_MANDATE_*` is not the self-signed mandate: it is a ceiling the
+ * operator deliberately configured, and it can be TIGHTER than the broker
+ * policy. A policy-enforced wallet skips the self-signed mandate, so without
+ * this the env caps would silently stop applying to exactly the wallets an
+ * unattended run is most likely to use. Enforced locally here instead, with the
+ * same comparisons `checkMandate()` makes.
+ */
+export function assertWithinOperatorCaps(caps, spend) {
+    const over = [];
+    if (spend.budgetUsdc > caps.maxPerStreamUsdc) {
+        over.push(`--budget ${formatUsdc(spend.budgetUsdc)} exceeds METRIK_AGENT_MANDATE max-per-stream ${formatUsdc(caps.maxPerStreamUsdc)}`);
+    }
+    if (spend.budgetUsdc > caps.maxTotalUsdc) {
+        over.push(`--budget ${formatUsdc(spend.budgetUsdc)} exceeds METRIK_AGENT_MANDATE max-total ${formatUsdc(caps.maxTotalUsdc)}`);
+    }
+    if (spend.ratePerSecondUsdc > caps.maxRatePerSecondUsdc) {
+        over.push(`--rate ${spend.ratePerSecondUsdc} atomic/second exceeds METRIK_AGENT_MANDATE max rate ${caps.maxRatePerSecondUsdc} atomic/second`);
+    }
+    if (spend.durationSeconds > caps.maxDurationSeconds) {
+        over.push(`--duration ${spend.durationSeconds}s exceeds METRIK_AGENT_MANDATE max duration ${caps.maxDurationSeconds}s`);
+    }
+    if (caps.allowedOperators.length > 0 &&
+        !caps.allowedOperators.some((operator) => operator.toLowerCase() === spend.operator.toLowerCase())) {
+        over.push(`operator ${spend.operator} is not in METRIK_AGENT_MANDATE_ALLOWED_OPERATORS`);
+    }
+    if (over.length === 0)
+        return;
+    throw new CliError(`this hire is outside the standing mandate caps in your environment: ${over.join("; ")}`, {
+        exitCode: 3,
+        hint: "these caps come from METRIK_AGENT_MANDATE_* and are yours to change. They are enforced locally for a policy-enforced wallet, which signs no mandate of its own.",
+    });
+}
+//# sourceMappingURL=spend-policy.js.map

package/dist/cli/spend-policy.js.map

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

package/dist/cli/status.d.ts

@@ -0,0 +1,90 @@
+import type { CheckpointProof, StreamV2 } from "@absol-labs/sdk";
+import { type AttesterSet } from "./attesters.js";
+import { type EscapeHatchWindow } from "./escape-hatch.js";
+import type { CliReadClient } from "./deps.js";
+/**
+ * Whether the accrual figures on this screen are FINAL.
+ *
+ * `reclaimableFor` is answered against a checkpoint's cumulative, and the
+ * escrow's own `reclaimWithProof` refuses until a checkpoint's `checkedAt`
+ * reaches the stream's stop time (`SettlementWindowOpen`). Between closing a
+ * stream and the first checkpoint that covers the close, the latest checkpoint
+ * therefore describes a SHORTER stream than the one that exists — so the
+ * reclaimable figure computed from it is larger than the amount that can
+ * actually be reclaimed, and shrinks when the covering checkpoint lands.
+ *
+ * A live acceptance run read `reclaimable: 1400` immediately after `close`, `0`
+ * two minutes later, and got `NothingToReclaim()` from the reclaim in between.
+ * Nobody reads "buyer reclaimable 0.0014 USDC" as "a provisional figure that
+ * may fall to zero" — they read it as money they have. So while this is
+ * pending, the CLI prints no settled-looking number at all.
+ */
+export interface SettlementCoverage {
+    /**
+     * The instant accrual stops: `closedAt`, or `expiresAt` once it has passed.
+     * `null` while the stream is still running, where there is nothing to cover.
+     */
+    readonly stopAt: number | null;
+    /** How far the oracle has published. `null` when it could not be read. */
+    readonly coveredUpTo: number | null;
+    /** True when a stop time exists and no known checkpoint reaches it. */
+    readonly pending: boolean;
+}
+/**
+ * Coverage from the three facts that decide it. Pure, so the rule is testable
+ * without an RPC.
+ *
+ * Unknown coverage counts as PENDING, not as covered: the buyer-favouring error
+ * is to withhold a number we cannot stand behind, never to print one we cannot.
+ */
+export declare function settlementCoverage(stream: Pick<StreamV2, "closedAt" | "expiresAt">, latestCheckpointCheckedAt: number | null, nowSeconds: number): SettlementCoverage;
+/**
+ * A stream as the CLI reports it.
+ *
+ * The accrual figures come from the ORACLE's checkpoint proof, not from the
+ * stream tuple. `StreamEscrowV2.getStream` reports `claimedCumulative = 0` and
+ * `settledCumulative = 0` for a stream's whole active life — `settledCumulative`
+ * is written by `reclaim` — so a status built from stream fields would print
+ * "earned: 0" for a stream that had been delivering for an hour.
+ */
+export interface StreamReport {
+    readonly streamId: `0x${string}`;
+    readonly stream: StreamV2;
+    /** `null` until the oracle has published a checkpoint covering this stream. */
+    readonly proof: CheckpointProof | null;
+    /** Why there is no proof yet, when applicable. */
+    readonly proofUnavailable: string | null;
+    readonly claimable: bigint | null;
+    readonly reclaimable: bigint | null;
+    readonly protocolFeeBps: number | null;
+    /**
+     * When the buyer's no-proof escape hatch opens, and whether it already has.
+     * `null` only when the escrow would not answer.
+     *
+     * Without this a buyer had no command that could tell them "the proof path is
+     * blocked, but the no-proof path opens at T+grace" — the two facts they need
+     * together when the oracle has stopped answering.
+     */
+    readonly escapeHatch: EscapeHatchWindow | null;
+    /**
+     * How far the oracle has published (`latestCheckpointCheckedAt`). A stale
+     * value beside a blocked reclaim IS the explanation for the blocked reclaim.
+     */
+    readonly latestCheckpointCheckedAt: number | null;
+    readonly nowSeconds: number;
+    /** `local` when the chain's clock could not be read and the caller's was used. */
+    readonly clockSource: "chain" | "local";
+    /** Whether `claimable` / `reclaimable` are final. See {@link SettlementCoverage}. */
+    readonly settlement: SettlementCoverage;
+    /**
+     * The escrow's oracle signer set, and therefore whether this stream's
+     * operator is also one of the parties attesting to its own delivery.
+     * `signers: null` means the set could not be read — which is UNKNOWN, not
+     * "no overlap".
+     */
+    readonly attesters: AttesterSet;
+}
+export declare function readStreamReport(read: CliReadClient, streamId: `0x${string}`, nowSeconds: number): Promise<StreamReport>;
+export declare function streamReportJson(report: StreamReport): unknown;
+export declare function streamReportRows(report: StreamReport): (readonly [string, string])[];
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/cli/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGjE,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,WAAW,CAAC,EAChD,yBAAyB,EAAE,MAAM,GAAG,IAAI,EACxC,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAgBpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,kDAAkD;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,KAAK,MAAM,EAAE,EACvB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAwEvB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAgE9D;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,GACnB,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAuF/B"}

package/dist/cli/status.js

@@ -0,0 +1,252 @@
+import { formatDuration, formatUsdc } from "./amounts.js";
+import { operatorAttestsOwnDelivery, readAttesterSet, } from "./attesters.js";
+import { describeError } from "./errors.js";
+import { describeEscapeHatch, escapeHatchWindow, formatTimestamp, readChainNow, } from "./escape-hatch.js";
+/**
+ * Coverage from the three facts that decide it. Pure, so the rule is testable
+ * without an RPC.
+ *
+ * Unknown coverage counts as PENDING, not as covered: the buyer-favouring error
+ * is to withhold a number we cannot stand behind, never to print one we cannot.
+ */
+export function settlementCoverage(stream, latestCheckpointCheckedAt, nowSeconds) {
+    const stopAt = stream.closedAt > 0
+        ? stream.closedAt
+        : nowSeconds >= stream.expiresAt
+            ? stream.expiresAt
+            : null;
+    const coveredUpTo = latestCheckpointCheckedAt !== null && latestCheckpointCheckedAt > 0
+        ? latestCheckpointCheckedAt
+        : null;
+    return {
+        stopAt,
+        coveredUpTo,
+        pending: stopAt !== null && (coveredUpTo === null || coveredUpTo < stopAt),
+    };
+}
+export async function readStreamReport(read, streamId, nowSeconds) {
+    const stream = await read.getStreamV2(streamId);
+    // Timing is answered against the chain, because every deadline on this screen
+    // — expiry, and the escape hatch in particular — is compared against
+    // `block.timestamp` by the escrow, not against this machine's clock.
+    const now = await readChainNow(read, nowSeconds);
+    let proof = null;
+    let proofUnavailable = null;
+    try {
+        proof = await read.checkpointProof(streamId);
+    }
+    catch (error) {
+        proofUnavailable = describeError(error);
+    }
+    let claimable = null;
+    let reclaimable = null;
+    if (proof !== null) {
+        [claimable, reclaimable] = await Promise.all([
+            read.claimableForV2(streamId, proof.cumulativeAmount),
+            read.reclaimableForV2(streamId, proof.cumulativeAmount),
+        ]);
+    }
+    let protocolFeeBps = null;
+    try {
+        protocolFeeBps = await read.protocolFeeBps();
+    }
+    catch {
+        protocolFeeBps = null;
+    }
+    let escapeHatch = null;
+    try {
+        escapeHatch = escapeHatchWindow(stream, await read.escapeGraceSeconds(), now.seconds);
+    }
+    catch {
+        escapeHatch = null;
+    }
+    let latestCheckpointCheckedAt = null;
+    try {
+        latestCheckpointCheckedAt = await read.latestCheckpointCheckedAt();
+    }
+    catch {
+        latestCheckpointCheckedAt = null;
+    }
+    const settlement = settlementCoverage(stream, latestCheckpointCheckedAt, now.seconds);
+    const attesters = await readAttesterSet(read);
+    return {
+        streamId,
+        stream,
+        proof,
+        proofUnavailable,
+        claimable,
+        reclaimable,
+        protocolFeeBps,
+        escapeHatch,
+        latestCheckpointCheckedAt,
+        nowSeconds: now.seconds,
+        clockSource: now.source,
+        settlement,
+        attesters,
+    };
+}
+export function streamReportJson(report) {
+    const { stream, proof } = report;
+    return {
+        streamId: report.streamId,
+        // StreamEscrowV2 has exactly two states. There is no "paused".
+        status: stream.status,
+        reclaimed: stream.reclaimed,
+        buyer: stream.buyer,
+        operator: stream.operator,
+        serviceRef: stream.serviceRef,
+        deposit: stream.deposit,
+        ratePerSecond: stream.ratePerSecond,
+        claimedCumulative: stream.claimedCumulative,
+        settledCumulative: stream.settledCumulative,
+        feesPaid: stream.feesPaid,
+        openedAt: stream.openedAt,
+        expiresAt: stream.expiresAt,
+        closedAt: stream.closedAt,
+        protocolFeeBps: report.protocolFeeBps,
+        verifiedAccrual: proof === null
+            ? null
+            : {
+                cumulativeAmount: proof.cumulativeAmount,
+                checkpointId: proof.checkpointId,
+                checkedAt: proof.checkedAt,
+                root: proof.root,
+            },
+        verifiedAccrualUnavailable: report.proofUnavailable,
+        // `null` while settlement is pending. A consumer that reads this field gets
+        // either an amount that can actually be obtained or nothing — never a
+        // settled-looking number derived from a checkpoint that predates the
+        // stream's stop time. The superseded figure is still available, explicitly
+        // labelled, under `settlement.provisionalReclaimable`.
+        claimable: report.claimable,
+        reclaimable: report.settlement.pending ? null : report.reclaimable,
+        settlement: {
+            pending: report.settlement.pending,
+            stopAt: report.settlement.stopAt,
+            coveredUpTo: report.settlement.coveredUpTo,
+            provisionalReclaimable: report.settlement.pending
+                ? report.reclaimable
+                : null,
+            provisionalClaimable: report.settlement.pending ? report.claimable : null,
+        },
+        // Who attests. `operatorIsOracleSigner: null` means the signer set could
+        // not be read — UNKNOWN, never "no overlap".
+        oracleSigners: report.attesters.signers,
+        oracleSignersUnavailable: report.attesters.unavailable,
+        operatorIsOracleSigner: operatorAttestsOwnDelivery(report.attesters, stream.operator),
+        latestCheckpointCheckedAt: report.latestCheckpointCheckedAt,
+        escapeHatch: report.escapeHatch === null
+            ? null
+            : {
+                escapeGraceSeconds: report.escapeHatch.graceSeconds,
+                readyAt: report.escapeHatch.readyAt,
+                ready: report.escapeHatch.ready,
+                secondsUntilReady: report.escapeHatch.secondsRemaining,
+            },
+    };
+}
+export function streamReportRows(report) {
+    const { stream, proof } = report;
+    const rows = [
+        [
+            "status",
+            stream.reclaimed ? `${stream.status} (reclaimed)` : stream.status,
+        ],
+        ["buyer", stream.buyer],
+        ["operator", stream.operator],
+        ["serviceRef", stream.serviceRef],
+        ["deposit", formatUsdc(stream.deposit)],
+        ["rate", `${formatUsdc(stream.ratePerSecond)} / second`],
+        ["opened", formatTimestamp(stream.openedAt)],
+        ["expires", describeDeadline(stream.expiresAt, report.nowSeconds)],
+    ];
+    if (stream.closedAt > 0) {
+        rows.push(["closed", formatTimestamp(stream.closedAt)]);
+    }
+    rows.push([
+        "verified accrual",
+        proof === null
+            ? `not checkpointed yet (${report.proofUnavailable ?? "no proof"})`
+            : `${formatUsdc(proof.cumulativeAmount)} @ checkpoint ${proof.checkpointId} (${formatTimestamp(Number(proof.checkedAt))})`,
+    ]);
+    // `claim` accepts ANY retained root, so the operator's balance is obtainable
+    // now — it is merely not FINAL until the covering checkpoint lands, and it
+    // can only grow. `reclaim` requires the LATEST root to reach the stop time,
+    // so the buyer's figure is not obtainable at all while that is pending: it is
+    // withheld rather than printed as money the buyer does not have.
+    rows.push([
+        "operator claimable",
+        report.claimable === null
+            ? "-"
+            : report.settlement.pending
+                ? `${formatUsdc(report.claimable)} so far — not final until the checkpoint covering the stop time lands`
+                : formatUsdc(report.claimable),
+    ]);
+    rows.push([
+        "buyer reclaimable",
+        report.settlement.pending
+            ? describePendingSettlement(report.settlement)
+            : report.reclaimable === null
+                ? "-"
+                : formatUsdc(report.reclaimable),
+    ]);
+    rows.push(["fees paid", formatUsdc(stream.feesPaid)]);
+    rows.push([
+        "oracle checkpoint",
+        report.latestCheckpointCheckedAt === null
+            ? "-"
+            : report.latestCheckpointCheckedAt <= 0
+                ? "none posted yet"
+                : `latest covers up to ${formatTimestamp(report.latestCheckpointCheckedAt)}`,
+    ]);
+    // The no-proof path. Printed for every stream, not only blocked ones: a buyer
+    // should learn that this exists before they need it.
+    rows.push([
+        "escape hatch",
+        report.escapeHatch === null
+            ? "-"
+            : `${describeEscapeHatch(report.escapeHatch)} — no-proof reclaim, forfeits the operator's unclaimed earnings`,
+    ]);
+    // The same row, read from the seller's side. `reclaimUnverified` pays the
+    // buyer the WHOLE remaining deposit with no proof, so an operator who has
+    // earned but not claimed loses it the moment that window opens. The window is
+    // `expiresAt + escapeGraceSeconds` and the grace is immutable on the live
+    // escrow, so the only thing an operator can do about it is claim in time —
+    // which they cannot do if nothing tells them the deadline exists.
+    if (report.escapeHatch !== null &&
+        report.claimable !== null &&
+        report.claimable > 0n) {
+        rows.push([
+            "operator deadline",
+            report.escapeHatch.ready
+                ? `${formatUsdc(report.claimable)} is unclaimed and the buyer's no-proof reclaim is ALREADY open — it would take this amount from the operator`
+                : `${formatUsdc(report.claimable)} is unclaimed; \`metrik claim\` it before ${formatTimestamp(report.escapeHatch.readyAt)}, after which a buyer's no-proof reclaim can take it`,
+        ]);
+    }
+    if (report.protocolFeeBps !== null) {
+        rows.push([
+            "protocol fee",
+            `${report.protocolFeeBps} bps (read from the escrow)`,
+        ]);
+    }
+    return rows;
+}
+/**
+ * What is being waited for, in the place a number used to be. Names the two
+ * timestamps whose ordering decides it, so the reader can see the wait end.
+ */
+function describePendingSettlement(settlement) {
+    const stopAt = settlement.stopAt === null ? "unknown" : formatTimestamp(settlement.stopAt);
+    const covered = settlement.coveredUpTo === null
+        ? "unknown (the escrow would not answer)"
+        : formatTimestamp(settlement.coveredUpTo);
+    return `pending final checkpoint — the stream stopped at ${stopAt}, the oracle has published only to ${covered}. Reclaim reverts until a checkpoint reaches the stop time (~15-22s apart).`;
+}
+function describeDeadline(expiresAt, nowSeconds) {
+    const remaining = expiresAt - nowSeconds;
+    const suffix = remaining > 0
+        ? `in ${formatDuration(remaining)}`
+        : `${formatDuration(-remaining)} ago`;
+    return `${formatTimestamp(expiresAt)} — ${suffix}`;
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/status.js.map

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

package/dist/cli/timeout.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How long any single READ is allowed to take before the CLI gives up on it.
+ *
+ * A live acceptance run found `status` calls that ran past two minutes with no
+ * output, and a `close` that took 8s once and 142s the next time. An unbounded
+ * wait is indistinguishable from a wedged command, and the only honest way to
+ * tell them apart is to stop waiting and say so.
+ *
+ * Deliberately generous: Base Sepolia's public endpoint is load-balanced and
+ * occasionally slow, and a timeout that fires on a merely-slow node would turn
+ * a working command into a spurious failure.
+ */
+export declare const READ_TIMEOUT_MS = 20000;
+/**
+ * Per-RPC-call budget handed to viem's HTTP transport, with a bounded retry
+ * count so one slow endpoint cannot multiply into minutes of silence. viem
+ * retries with exponential backoff, so `retryCount` is a multiplier on this.
+ */
+export declare const RPC_TIMEOUT_MS = 15000;
+export declare const RPC_RETRY_COUNT = 2;
+/**
+ * Bound a read.
+ *
+ * ONLY safe for reads. A broadcast must never be abandoned on a timer: the
+ * transaction may already be in the mempool, and a CLI that walked away from it
+ * would report a failure for something that in fact settled. Write paths keep
+ * waiting, and the heartbeat (`./progress.ts`) is what makes that wait legible.
+ */
+export declare function withReadTimeout<T>(operation: () => Promise<T>, label: string, timeoutMs?: number): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/cli/timeout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAwB,GAClC,OAAO,CAAC,CAAC,CAAC,CA2BZ"}

package/dist/cli/timeout.js

@@ -0,0 +1,55 @@
+import { CliError } from "./errors.js";
+/**
+ * How long any single READ is allowed to take before the CLI gives up on it.
+ *
+ * A live acceptance run found `status` calls that ran past two minutes with no
+ * output, and a `close` that took 8s once and 142s the next time. An unbounded
+ * wait is indistinguishable from a wedged command, and the only honest way to
+ * tell them apart is to stop waiting and say so.
+ *
+ * Deliberately generous: Base Sepolia's public endpoint is load-balanced and
+ * occasionally slow, and a timeout that fires on a merely-slow node would turn
+ * a working command into a spurious failure.
+ */
+export const READ_TIMEOUT_MS = 20_000;
+/**
+ * Per-RPC-call budget handed to viem's HTTP transport, with a bounded retry
+ * count so one slow endpoint cannot multiply into minutes of silence. viem
+ * retries with exponential backoff, so `retryCount` is a multiplier on this.
+ */
+export const RPC_TIMEOUT_MS = 15_000;
+export const RPC_RETRY_COUNT = 2;
+/**
+ * Bound a read.
+ *
+ * ONLY safe for reads. A broadcast must never be abandoned on a timer: the
+ * transaction may already be in the mempool, and a CLI that walked away from it
+ * would report a failure for something that in fact settled. Write paths keep
+ * waiting, and the heartbeat (`./progress.ts`) is what makes that wait legible.
+ */
+export async function withReadTimeout(operation, label, timeoutMs = READ_TIMEOUT_MS) {
+    let timer;
+    const pending = operation();
+    // Attached before the race so an eventual rejection of the abandoned promise
+    // is never an unhandled rejection that takes the process down.
+    pending.catch(() => { });
+    try {
+        return await Promise.race([
+            pending,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new CliError(`${label} did not answer within ${Math.round(timeoutMs / 1000)}s`, {
+                        exitCode: 4,
+                        hint: "the endpoint is unreachable or very slow — retry, or point --rpc-url / --oracle-url at a different one.",
+                    }));
+                }, timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=timeout.js.map