@absol-labs/agent 0.9.0 → 0.10.0

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";
+  }
+}