@absol-labs/agent 0.9.0 → 0.10.0

package/src/cli/errors.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 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;
+    } = {},
+  ) {
+    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: string, hint?: string): CliError {
+  return new CliError(message, {
+    exitCode: 2,
+    ...(hint === undefined ? {} : { hint }),
+  });
+}
+
+/** Configuration error: the environment/flags describe a target we refuse. */
+export function configError(message: string, hint?: string): CliError {
+  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: readonly RegExp[] = [
+  /^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: string): boolean {
+  return (
+    /\b[A-Z][A-Za-z0-9]*\([^)]*\)/.test(line) ||
+    /\breverted:/.test(line) ||
+    /\bpanicked with code\b/.test(line)
+  );
+}
+
+function isBoilerplate(line: string): boolean {
+  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: unknown): string {
+  if (error instanceof Error) {
+    const chain: string[] = [];
+    for (let current: unknown = 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: readonly string[],
+): readonly string[] {
+  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: readonly (readonly [RegExp, string])[] = [
+  [/\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: string): string {
+  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: string, reason: string) => {
+      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();
+}

package/src/cli/escape-hatch.ts

@@ -0,0 +1,92 @@
+import type { StreamV2 } from "@absol-labs/sdk";
+
+import { formatDuration } from "./amounts.js";
+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 function escapeHatchWindow(
+  stream: Pick<StreamV2, "expiresAt">,
+  graceSeconds: number,
+  nowSeconds: number,
+): EscapeHatchWindow {
+  const readyAt = stream.expiresAt + graceSeconds;
+  const secondsRemaining = readyAt - nowSeconds;
+  return {
+    graceSeconds,
+    readyAt,
+    ready: secondsRemaining <= 0,
+    secondsRemaining: secondsRemaining > 0 ? secondsRemaining : 0,
+  };
+}
+
+/** `2026-09-17T09:15:00.000Z (1789…)`, or `-` for an unset timestamp. */
+export function formatTimestamp(seconds: number): string {
+  if (seconds <= 0) return "-";
+  return `${new Date(seconds * 1000).toISOString()} (${seconds})`;
+}
+
+/** One line describing where the escape hatch stands, for humans. */
+export function describeEscapeHatch(window: EscapeHatchWindow): string {
+  return window.ready
+    ? `open since ${formatTimestamp(window.readyAt)}`
+    : `opens ${formatTimestamp(window.readyAt)} — in ${formatDuration(
+        window.secondsRemaining,
+      )}`;
+}
+
+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 async function readChainNow(
+  read: Pick<CliReadClient, "latestBlockTimestamp">,
+  fallbackSeconds: number,
+): Promise<ChainNow> {
+  try {
+    const seconds = await read.latestBlockTimestamp();
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return { seconds, source: "chain" };
+    }
+  } catch {
+    // fall through to the caller's clock
+  }
+  return { seconds: fallbackSeconds, source: "local" };
+}

package/src/cli/index.ts

@@ -0,0 +1,27 @@
+export { runCli, renderHelp, COMMANDS, type RunCliOptions } from "./run.js";
+export { parseArgs, type ParsedArgs } from "./args.js";
+export {
+  TESTNET_CHAIN_IDS,
+  assertTestnetChainId,
+  assertTestnetRpc,
+  resolveConfig,
+  type CliConfig,
+} from "./config.js";
+export { CliError, describeError } from "./errors.js";
+export {
+  defaultCliDependencies,
+  type CliDependencies,
+  type CliReadClient,
+  type CliWriteClient,
+  type OpenedStream,
+  type StreamOpenedQuery,
+} from "./deps.js";
+export {
+  CDP_ENV_VARS,
+  PRIVATE_KEY_ENV,
+  optionalCliWallet,
+  resolveCliWallet,
+  type CliWallet,
+  type CliWalletSource,
+} from "./wallet.js";
+export type { CommandContext, CommandSpec } from "./context.js";

package/src/cli/listings.ts

@@ -0,0 +1,77 @@
+import { RegistryUnavailableError } from "../discovery/registry.js";
+
+import { CliError } from "./errors.js";
+import type { CommandContext } from "./context.js";
+import type { ServiceListing } from "./deps.js";
+
+/**
+ * Finds the verified listing for a `serviceRef`.
+ *
+ * The registry is an untrusted transport: `discoverServices` re-derives every
+ * `serviceRef` from the signed record and recovers the operator signature, so a
+ * compromised registry can neither invent an operator to pay nor redirect an
+ * invocation URL. That verification is the reason the CLI routes through
+ * discovery instead of taking a `--url`.
+ */
+export async function resolveListing(
+  context: CommandContext,
+  serviceRef: `0x${string}`,
+  options: { readonly required: boolean },
+): Promise<ServiceListing | null> {
+  const { config, out, deps } = context;
+  let services;
+  try {
+    services = (
+      await deps.discover({
+        registryUrl: config.registryUrl,
+        logger: { warn: (...parts) => out.note(parts.map(String).join(" ")) },
+      })
+    ).services;
+  } catch (error) {
+    if (error instanceof RegistryUnavailableError && !options.required) {
+      out.note(
+        `warning: the registry at ${config.registryUrl} is unreachable; continuing without a verified listing.`,
+      );
+      return null;
+    }
+    throw new CliError(
+      `the service registry at ${config.registryUrl} could not be read`,
+      { exitCode: 4, cause: error },
+    );
+  }
+
+  const wanted = serviceRef.toLowerCase();
+  const match = services.find(
+    (service) => service.serviceRef.toLowerCase() === wanted,
+  );
+  if (match === undefined) {
+    if (!options.required) return null;
+    throw new CliError(
+      `no verified listing in the registry matches serviceRef ${serviceRef}`,
+      {
+        exitCode: 4,
+        hint: "run `metrik discover` to see what is listed. A listing that fails signature verification is dropped, so it will not appear here.",
+      },
+    );
+  }
+  if (match.accessUrl === null) {
+    if (!options.required) return null;
+    throw new CliError(
+      `listing ${serviceRef} carries no signed invocation URL`,
+      {
+        exitCode: 4,
+        hint: "the CLI refuses to call an origin that the operator did not sign.",
+      },
+    );
+  }
+
+  return {
+    serviceRef: match.serviceRef,
+    operator: match.operator,
+    publicUrl: match.publicUrl,
+    access: match.access,
+    accessUrl: match.accessUrl,
+    signed: match.signed,
+    category: match.category,
+  };
+}

package/src/cli/mandate.ts

@@ -0,0 +1,126 @@
+import type { Account } from "viem";
+
+import {
+  parseServerMandateCapsEnv,
+  signServerMandate,
+  DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+  type ServerMandateCaps,
+} from "../mandates/env.js";
+import type { SignedSpendMandate } from "../mandates/mandate.js";
+
+/**
+ * Spend mandates in the CLI.
+ *
+ * Every fund-moving path in this package goes through `checkMandate()` — that is
+ * a golden rule of the agent layer, and the CLI is not exempt. The CLI's twist
+ * is that the person typing the command IS the mandate owner: they hold the key
+ * and they just stated the exact spend on the command line. So the mandate is
+ * self-signed from the same wallet that funds the stream, exactly as the MCP
+ * server does (`signServerMandate`).
+ *
+ * Two sources, in priority order:
+ *
+ *  1. `METRIK_AGENT_MANDATE_*` in the environment — an explicit standing ceiling.
+ *     If the requested hire exceeds it, `checkMandate` DENIES it. This is the
+ *     path to use when a CLI runs unattended under a policy.
+ *  2. No env caps configured — the mandate is sized to exactly this hire and
+ *     scoped to exactly this operator. It authorizes the command that was typed
+ *     and nothing wider.
+ *
+ * Neither path is an unbounded mandate.
+ */
+export interface RequestedSpend {
+  readonly operator: `0x${string}`;
+  readonly budgetUsdc: bigint;
+  readonly ratePerSecondUsdc: bigint;
+  readonly durationSeconds: number;
+}
+
+export interface CliMandate {
+  readonly signed: SignedSpendMandate;
+  /** Where the caps came from, for the human-readable output. */
+  readonly source: "env" | "request";
+}
+
+/**
+ * The caps this hire would be authorized under, WITHOUT signing anything. Split
+ * out so `open --dry-run` can report the mandate it would use even when there is
+ * no key to sign it with.
+ */
+export function cliMandateCaps(
+  request: RequestedSpend,
+  env: NodeJS.ProcessEnv,
+): { readonly caps: ServerMandateCaps; readonly source: "env" | "request" } {
+  const envCaps = parseServerMandateCapsEnv(env);
+  if (envCaps !== null) return { caps: envCaps, source: "env" };
+  return {
+    caps: {
+      maxPerStreamUsdc: request.budgetUsdc,
+      maxTotalUsdc: request.budgetUsdc,
+      maxRatePerSecondUsdc: request.ratePerSecondUsdc,
+      maxDurationSeconds: request.durationSeconds,
+      allowedOperators: [request.operator],
+      ttlSeconds: DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+    },
+    source: "request",
+  };
+}
+
+export async function signCliMandate(
+  account: Account,
+  request: RequestedSpend,
+  options: { readonly chainId: number; readonly env: NodeJS.ProcessEnv },
+): Promise<CliMandate> {
+  const { caps, source } = cliMandateCaps(request, options.env);
+  const signed = await signServerMandate(account, caps, {
+    chainId: options.chainId,
+  });
+  return { signed, source };
+}
+
+/**
+ * The operator's claim is not a SPEND: it redeems value the stream already
+ * earned under an oracle-verified checkpoint, and the escrow pays it to the
+ * stream's operator and nobody else. But `checkMandate()` gates every
+ * fund-moving path in this package without exception, so the claim carries a
+ * mandate too. The caps below are placeholders that satisfy the schema against a
+ * zero-valued request; the real gate is the escrow's own `NotOperator()`.
+ */
+export async function signClaimMandate(
+  account: Account,
+  chainId: number,
+): Promise<SignedSpendMandate> {
+  return await signPlaceholderMandate(account, chainId);
+}
+
+/**
+ * Close and reclaim are BUYER-RECOVERY actions: they stop payment or return
+ * unspent funds to the buyer, and `VerifiedStreamAgentClient` authorizes them on
+ * the mandate owner's signature alone — never on caps or expiry, so a lapsed
+ * mandate can never strand a buyer's own money. The caps below are therefore
+ * placeholders that satisfy the schema; they gate nothing.
+ */
+export async function signRecoveryMandate(
+  account: Account,
+  chainId: number,
+): Promise<SignedSpendMandate> {
+  return await signPlaceholderMandate(account, chainId);
+}
+
+async function signPlaceholderMandate(
+  account: Account,
+  chainId: number,
+): Promise<SignedSpendMandate> {
+  return await signServerMandate(
+    account,
+    {
+      maxPerStreamUsdc: 1n,
+      maxTotalUsdc: 1n,
+      maxRatePerSecondUsdc: 1n,
+      maxDurationSeconds: 1,
+      allowedOperators: [],
+      ttlSeconds: DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+    },
+    { chainId },
+  );
+}

package/src/cli/output.ts

@@ -0,0 +1,63 @@
+/**
+ * Output shape. Human-readable by default; `--json` emits one JSON object on
+ * stdout per command so a script can pipe it into `jq` without parsing prose.
+ *
+ * Warnings and progress go to stderr in BOTH modes, so `--json` stdout stays a
+ * single parseable document even when discovery drops a row or a reclaim
+ * retries.
+ */
+export interface CliStreams {
+  readonly stdout: (line: string) => void;
+  readonly stderr: (line: string) => void;
+}
+
+export interface Printer extends CliStreams {
+  readonly json: boolean;
+  /** Human-readable body. Suppressed entirely in `--json` mode. */
+  readonly print: (line: string) => void;
+  /** Key/value block, aligned. Suppressed in `--json` mode. */
+  readonly table: (rows: readonly (readonly [string, string])[]) => void;
+  /** Progress / warnings. Always stderr, always shown. */
+  readonly note: (line: string) => void;
+  /** The machine-readable result. Emitted only in `--json` mode. */
+  readonly result: (value: unknown) => void;
+  /**
+   * One COMPACT JSON object on a single stdout line — JSON Lines. Used by
+   * commands that emit a record per tick (`watch`), where every line must parse
+   * standalone so a consumer can react as each one lands. `result` is the
+   * pretty-printed single-document form and is wrong for a stream: a multi-line
+   * object means not one of its lines parses on its own.
+   */
+  readonly resultLine: (value: unknown) => void;
+}
+
+export function createPrinter(streams: CliStreams, json: boolean): Printer {
+  return {
+    ...streams,
+    json,
+    print(line) {
+      if (!json) streams.stdout(line);
+    },
+    table(rows) {
+      if (json) return;
+      const width = rows.reduce((max, [key]) => Math.max(max, key.length), 0);
+      for (const [key, value] of rows) {
+        streams.stdout(`  ${key.padEnd(width)}  ${value}`);
+      }
+    },
+    note(line) {
+      streams.stderr(line);
+    },
+    result(value) {
+      if (json) streams.stdout(JSON.stringify(value, jsonReplacer, 2));
+    },
+    resultLine(value) {
+      if (json) streams.stdout(JSON.stringify(value, jsonReplacer));
+    },
+  };
+}
+
+/** bigints are the natural amount type here; JSON has no bigint. */
+function jsonReplacer(_key: string, value: unknown): unknown {
+  return typeof value === "bigint" ? value.toString() : value;
+}

package/src/cli/preflight.ts

@@ -0,0 +1,88 @@
+import { formatUsdc } from "./amounts.js";
+import { CliError } from "./errors.js";
+import type { CliReadClient } from "./deps.js";
+
+/** Where a Base Sepolia test wallet gets its gas. */
+export const BASE_SEPOLIA_FAUCET_URL =
+  "https://www.alchemy.com/faucets/base-sepolia";
+
+/** Where a Base Sepolia test wallet gets the USDC it escrows. */
+export const CIRCLE_USDC_FAUCET_URL = "https://faucet.circle.com";
+
+/**
+ * Refuse to broadcast from a wallet that cannot pay for gas.
+ *
+ * Without this, the first thing an unfunded wallet sees is the node's own
+ * phrasing — `USDC approve transaction failed: Execution reverted with reason:
+ * gas required exceeds allowance (0)` — which reads like a USDC allowance
+ * problem and sends the reader looking at approvals. The actual fact is "this
+ * address holds no ETH", and it is knowable with one read before anything is
+ * signed.
+ *
+ * Deliberately only a ZERO check, not an estimate: predicting the gas a hire
+ * will cost means simulating it, and a wallet with a little ETH that still runs
+ * short should get the real revert rather than a guess from this CLI.
+ */
+export async function assertCanPayGas(
+  read: CliReadClient,
+  address: `0x${string}`,
+): Promise<void> {
+  let balance: bigint;
+  try {
+    balance = await read.nativeBalance(address);
+  } catch {
+    // A balance read is a courtesy, not a gate. If the RPC will not answer it,
+    // let the command proceed and fail with the real error.
+    return;
+  }
+  if (balance > 0n) return;
+
+  throw new CliError(
+    `wallet ${address} has 0 ETH on Base Sepolia, so it cannot pay for gas`,
+    {
+      exitCode: 3,
+      hint: `fund it at ${BASE_SEPOLIA_FAUCET_URL}, then re-run. (Gas is ETH; the stream itself is escrowed in USDC, which is a separate balance.)`,
+    },
+  );
+}
+
+/**
+ * Refuse to broadcast a hire the wallet cannot fund.
+ *
+ * The sibling of `assertCanPayGas`, for the OTHER balance. Gas is ETH and the
+ * deposit is USDC: they are separate balances on separate tokens, so a wallet
+ * that passes the gas check can still hold no USDC at all. Without this the
+ * `open` path sends the USDC approval FIRST — which succeeds, because approving
+ * an amount you do not hold is legal — and then reverts inside `transferFrom`,
+ * having already spent gas to learn something that was one `balanceOf` away.
+ *
+ * Deliberately NOT an allowance check. The CLI's own open path grants the
+ * bounded approval it needs (`approveTxHash` in the result), so a missing
+ * allowance is a step of the command, not a precondition for it; gating on it
+ * would refuse a hire that was about to work. Balance is the fact the CLI
+ * cannot fix for you.
+ */
+export async function assertCanFundStream(
+  read: CliReadClient,
+  address: `0x${string}`,
+  budgetUsdc: bigint,
+): Promise<void> {
+  let balance: bigint;
+  try {
+    balance = await read.usdcBalance(address);
+  } catch {
+    // Same courtesy rule as the gas check: an RPC that will not answer a
+    // balance read must not become this command's failure mode. Proceed and let
+    // the real error surface.
+    return;
+  }
+  if (balance >= budgetUsdc) return;
+
+  throw new CliError(
+    `wallet ${address} holds ${formatUsdc(balance)} but --budget is ${formatUsdc(budgetUsdc)}`,
+    {
+      exitCode: 3,
+      hint: `the deposit is escrowed in USDC — fund the wallet at ${CIRCLE_USDC_FAUCET_URL} (Base Sepolia), then re-run. (Gas is a separate ETH balance.)`,
+    },
+  );
+}