@absol-labs/agent 0.9.1 → 0.11.0

package/src/cli/scan-range.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 = 9_999n;
+
+/**
+ * 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;
+
+export interface ScanRange {
+  readonly fromBlock: bigint;
+  readonly toBlock: bigint;
+  /** Inclusive `[from, to]` windows, in ascending order. */
+  readonly windows: readonly (readonly [bigint, bigint])[];
+  /** True iff the budget could NOT reach `anchor`, i.e. the scan is partial. */
+  readonly degraded: boolean;
+}
+
+/**
+ * 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: bigint,
+  anchorBlock: bigint,
+  chunk: bigint = LOG_SCAN_CHUNK,
+  maxWindows: number = LOG_SCAN_MAX_WINDOWS,
+): ScanRange {
+  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: (readonly [bigint, bigint])[] = [];
+  for (let start = fromBlock; start <= head; start += chunk + 1n) {
+    windows.push([start, start + chunk > head ? head : start + chunk]);
+  }
+
+  return { fromBlock, toBlock: head, windows, degraded };
+}

package/src/cli/spend-policy.ts

@@ -0,0 +1,139 @@
+import { formatUsdc } from "./amounts.js";
+import { CliError } from "./errors.js";
+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 function assertWithinSpendPolicy(
+  policy: PrivySpendPolicy,
+  spend: RequestedSpend,
+): void {
+  const over: string[] = [];
+  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: ServerMandateCaps,
+  spend: RequestedSpend,
+): void {
+  const over: string[] = [];
+  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.",
+    },
+  );
+}

package/src/cli/status.ts

@@ -0,0 +1,381 @@
+import type { CheckpointProof, StreamV2 } from "@absol-labs/sdk";
+
+import { formatDuration, formatUsdc } from "./amounts.js";
+import {
+  attesterDisclosure,
+  operatorAttestsOwnDelivery,
+  readAttesterSet,
+  type AttesterSet,
+} from "./attesters.js";
+import { describeError } from "./errors.js";
+import {
+  describeEscapeHatch,
+  escapeHatchWindow,
+  formatTimestamp,
+  readChainNow,
+  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 function settlementCoverage(
+  stream: Pick<StreamV2, "closedAt" | "expiresAt">,
+  latestCheckpointCheckedAt: number | null,
+  nowSeconds: number,
+): SettlementCoverage {
+  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),
+  };
+}
+
+/**
+ * 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 async function readStreamReport(
+  read: CliReadClient,
+  streamId: `0x${string}`,
+  nowSeconds: number,
+): Promise<StreamReport> {
+  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: CheckpointProof | null = null;
+  let proofUnavailable: string | null = null;
+  try {
+    proof = await read.checkpointProof(streamId);
+  } catch (error) {
+    proofUnavailable = describeError(error);
+  }
+
+  let claimable: bigint | null = null;
+  let reclaimable: bigint | null = null;
+  if (proof !== null) {
+    [claimable, reclaimable] = await Promise.all([
+      read.claimableForV2(streamId, proof.cumulativeAmount),
+      read.reclaimableForV2(streamId, proof.cumulativeAmount),
+    ]);
+  }
+
+  let protocolFeeBps: number | null = null;
+  try {
+    protocolFeeBps = await read.protocolFeeBps();
+  } catch {
+    protocolFeeBps = null;
+  }
+
+  let escapeHatch: EscapeHatchWindow | null = null;
+  try {
+    escapeHatch = escapeHatchWindow(
+      stream,
+      await read.escapeGraceSeconds(),
+      now.seconds,
+    );
+  } catch {
+    escapeHatch = null;
+  }
+
+  let latestCheckpointCheckedAt: number | null = 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: StreamReport): unknown {
+  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: StreamReport,
+): (readonly [string, string])[] {
+  const { stream, proof } = report;
+  const rows: (readonly [string, string])[] = [
+    [
+      "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: SettlementCoverage): string {
+  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: number, nowSeconds: number): string {
+  const remaining = expiresAt - nowSeconds;
+  const suffix =
+    remaining > 0
+      ? `in ${formatDuration(remaining)}`
+      : `${formatDuration(-remaining)} ago`;
+  return `${formatTimestamp(expiresAt)} — ${suffix}`;
+}

package/src/cli/timeout.ts

@@ -0,0 +1,64 @@
+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<T>(
+  operation: () => Promise<T>,
+  label: string,
+  timeoutMs: number = READ_TIMEOUT_MS,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  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<never>((_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);
+  }
+}

package/src/cli/version.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+
+/**
+ * The published version of this package, read from its own manifest.
+ *
+ * Kept in its own module because both the runner (`--version`) and the MCP
+ * config printer need it, and the printer is a command the runner imports — so
+ * reading it from `run.ts` would be a cycle.
+ *
+ * Falls back rather than throwing: a CLI that cannot state its version should
+ * still run.
+ */
+export function packageVersion(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require("../../package.json") as { version?: string };
+    return manifest.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}