@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/commands/streams.ts

@@ -0,0 +1,344 @@
+import { BASE_SEPOLIA_ESCROW_V2 } from "@absol-labs/sdk";
+import { getAddress, isAddress } from "viem";
+
+import { integerFlag, stringFlag } from "../args.js";
+import { formatUsdc } from "../amounts.js";
+import {
+  BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
+  assertTestnetRpc,
+} from "../config.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { escrowScanRange } from "../scan-range.js";
+import { optionalCliWallet, PRIVATE_KEY_ENV } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+import type {
+  CliReadClient,
+  OpenedStream,
+  StreamOpenedQuery,
+} from "../deps.js";
+
+/** Indexed-party filters, and the `--role` values that select them. */
+const ROLES = ["buyer", "operator"] as const;
+type Role = (typeof ROLES)[number];
+
+/**
+ * How many `eth_getLogs` calls are in flight at once. The full history of the
+ * live escrow is ~106 windows x 2 role filters; firing those unbounded is how a
+ * public RPC starts answering 429, and a rate-limited window is a window this
+ * command has to report as unscanned.
+ */
+const SCAN_CONCURRENCY = 6;
+
+/**
+ * Attempts per window before it is reported as unscanned. A public RPC answers
+ * a burst of `eth_getLogs` with an occasional 429 — measured against
+ * `sepolia.base.org`, 2 of 212 windows on a full-history scan — and a transient
+ * rate-limit is NOT a window that cannot be scanned. Declaring it one would
+ * make the "this scan is incomplete" warning routine, and a warning that fires
+ * on every healthy run is a warning nobody reads on the run that matters.
+ */
+const WINDOW_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 400;
+
+export const streamsCommand: CommandSpec = {
+  name: "streams",
+  summary: "List the streams a wallet has opened, or been hired through",
+  usage:
+    "metrik streams [--address 0x…] [--role buyer|operator|any] [--limit N] [--from-block N]",
+  flags: ["address", "role", "limit", "from-block"],
+  signs: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+
+    const roleFlag = stringFlag(args, "role") ?? "any";
+    if (roleFlag !== "any" && !ROLES.includes(roleFlag as Role)) {
+      throw usageError(
+        `--role must be buyer, operator or any (got "${roleFlag}")`,
+      );
+    }
+    const roles: readonly Role[] =
+      roleFlag === "any" ? ROLES : [roleFlag as Role];
+    const limit = integerFlag(args, "limit");
+    if (limit !== undefined && limit < 1) {
+      throw usageError("--limit must be at least 1");
+    }
+
+    const address = await resolveScanAddress(context);
+    const read = deps.createReadClient(config);
+    // The same allowlist the signing paths get. This command spends nothing,
+    // but it reads a V2 stream tuple, and the V1 and V2 tuples diverge from
+    // index 5 onward — a wrong-chain read does not revert, it decodes something
+    // else into fields with the right names.
+    await assertTestnetRpc(config, () => read.getChainId());
+
+    const anchor = resolveAnchorBlock(args, config.escrow);
+    const head = await read.blockNumber();
+    const range = escrowScanRange(head, anchor.block);
+
+    // Retention canary, before the scan is believed. A node that has pruned its
+    // log index answers a range it no longer retains with a SUCCESSFUL EMPTY
+    // result (measured on Base Sepolia: one public endpoint returned 0 logs for
+    // a window where two others returned 582). This CLI talks to ONE endpoint,
+    // so it cannot recover those logs from a sibling the way a multi-provider
+    // client can — but it can refuse to call the silence "no streams".
+    const retention =
+      anchor.canary === null
+        ? null
+        : await read
+            .escrowLogCountAt(anchor.canary)
+            .then((count) => count > 0)
+            .catch(() => false);
+
+    const scan = await scanOpenedStreams(
+      read,
+      address,
+      roles,
+      range.windows,
+      deps.sleep,
+    );
+
+    const reasons: string[] = [];
+    if (range.degraded) {
+      reasons.push(
+        `the window budget could not reach block ${anchor.block} (scan starts at ${range.fromBlock})`,
+      );
+    }
+    if (scan.failedWindows > 0) {
+      reasons.push(
+        `${scan.failedWindows} of ${range.windows.length * roles.length} log queries failed after ${WINDOW_ATTEMPTS} attempts each`,
+      );
+    }
+    if (retention === false) {
+      reasons.push(
+        `${config.rpcUrl} does not serve logs for block ${anchor.canary}, so it has pruned the escrow's history and its empty windows cannot be trusted`,
+      );
+    }
+    const degraded = reasons.length > 0;
+
+    // Newest first: the stream someone is looking for is almost always the one
+    // they just opened.
+    const opened = [...scan.opened].sort((a, b) =>
+      a.blockNumber === b.blockNumber
+        ? 0
+        : a.blockNumber > b.blockNumber
+          ? -1
+          : 1,
+    );
+    const shown = limit === undefined ? opened : opened.slice(0, limit);
+
+    // One `getStream` per row. A list that cannot distinguish an active stream
+    // from a closed one is not actionable, and status is the one field the
+    // event cannot carry. The oracle's checkpoint proof is deliberately NOT
+    // fetched here — that is a per-stream HTTP call, and `metrik status` is the
+    // command that makes it.
+    const rows = await Promise.all(
+      shown.map(async (log) => {
+        const stream = await read.getStreamV2(log.streamId).catch(() => null);
+        return {
+          streamId: log.streamId,
+          role: describeRole(log, address),
+          buyer: log.buyer,
+          operator: log.operator,
+          serviceRef: log.serviceRef,
+          // V2 MUTATES `Stream.deposit` on reclaim, so the event is the only
+          // surviving record of what was originally escrowed.
+          originalDepositUsdc: log.deposit,
+          ratePerSecondUsdc: log.ratePerSecond,
+          expiresAt: log.expiresAt,
+          openedAtBlock: log.blockNumber,
+          // A read failure is reported as unread, never as a dropped row: a
+          // stream that vanishes from this list is the exact failure the whole
+          // command is built to avoid.
+          status: stream?.status ?? "unread",
+          reclaimed: stream?.reclaimed ?? null,
+        };
+      }),
+    );
+
+    out.result({
+      address,
+      role: roleFlag,
+      escrow: config.escrow,
+      fromBlock: range.fromBlock,
+      toBlock: range.toBlock,
+      windows: range.windows.length,
+      logRetentionProven: retention,
+      degraded,
+      degradedReasons: reasons,
+      found: opened.length,
+      count: rows.length,
+      streams: rows,
+    });
+
+    if (degraded) {
+      // stderr in both modes: a partial scan must reach someone piping stdout
+      // into jq just as loudly as someone reading the table.
+      out.note(
+        `warning: this scan is INCOMPLETE — ${reasons.join("; ")}. Streams may exist that are not listed below.`,
+      );
+    }
+
+    if (rows.length === 0) {
+      out.print(
+        degraded
+          ? `No streams found for ${address} in the part of the escrow's history that could be scanned. This is NOT a statement that none exist — see the warning above.`
+          : `No streams for ${address} across the escrow's full history (blocks ${range.fromBlock}-${range.toBlock}).`,
+      );
+      return;
+    }
+
+    out.print(
+      `${rows.length} stream${rows.length === 1 ? "" : "s"} for ${address}${
+        opened.length > rows.length ? ` (of ${opened.length}, limited)` : ""
+      }`,
+    );
+    for (const row of rows) {
+      out.print("");
+      out.print(`${row.streamId}  [${row.status}]`);
+      out.table([
+        ["role", row.role],
+        ["counterparty", row.role === "buyer" ? row.operator : row.buyer],
+        ["serviceRef", row.serviceRef],
+        ["escrowed", formatUsdc(row.originalDepositUsdc)],
+        ["rate", `${formatUsdc(row.ratePerSecondUsdc)} / second`],
+        ["opened at block", row.openedAtBlock.toString()],
+        [
+          "reclaimed",
+          row.reclaimed === null ? "unread" : String(row.reclaimed),
+        ],
+      ]);
+    }
+    out.print("");
+    out.print(
+      "Earned-so-far is published by the oracle, not held on the stream:  metrik status <streamId>",
+    );
+  },
+};
+
+/** Whose streams to list: an explicit `--address`, else the configured wallet. */
+async function resolveScanAddress(
+  context: CommandContext,
+): Promise<`0x${string}`> {
+  const { args, env, out } = context;
+  const explicit = stringFlag(args, "address");
+  if (explicit !== undefined) {
+    if (!isAddress(explicit)) {
+      throw usageError(`--address must be an EVM address (got "${explicit}")`);
+    }
+    return getAddress(explicit) as `0x${string}`;
+  }
+  // This command broadcasts nothing and signs nothing, so it must not demand a
+  // wallet: `--address` is enough to read anyone's streams. A configured wallet
+  // is simply the default subject.
+  const wallet = await optionalCliWallet(env, { note: out.note });
+  if (wallet === null) {
+    throw configError(
+      "metrik streams needs a wallet to know whose streams to list",
+      `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP variables).`,
+    );
+  }
+  return wallet.account.address;
+}
+
+/**
+ * Where the log scan starts, and whether a retention canary is possible there.
+ *
+ * The canary block must be one that is KNOWN to carry escrow logs, otherwise a
+ * zero from it proves nothing and every scan would report itself degraded
+ * forever. That is only true of the deploy block of the escrow we shipped the
+ * constant for — so an overridden `--escrow` or `--from-block` scans without a
+ * canary rather than with a meaningless one.
+ */
+function resolveAnchorBlock(
+  args: CommandContext["args"],
+  escrow: `0x${string}`,
+): { readonly block: bigint; readonly canary: bigint | null } {
+  const override = integerFlag(args, "from-block");
+  const isKnownEscrow =
+    escrow.toLowerCase() === BASE_SEPOLIA_ESCROW_V2.toLowerCase();
+
+  if (override !== undefined) {
+    return { block: BigInt(override), canary: null };
+  }
+  if (!isKnownEscrow) {
+    throw configError(
+      `no scan anchor is known for escrow ${escrow}`,
+      "the scan is anchored at the escrow's deploy block, and this CLI only ships that block for its default Base Sepolia escrow. Pass --from-block <deploy block> for a different escrow.",
+    );
+  }
+  return {
+    block: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
+    canary: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
+  };
+}
+
+/**
+ * Page every window for every selected role filter, bounded concurrency.
+ *
+ * A window that ERRORS is counted, not thrown: a partial list with an honest
+ * warning is more useful than no list at all, and the count is what makes the
+ * warning specific.
+ */
+async function scanOpenedStreams(
+  read: CliReadClient,
+  address: `0x${string}`,
+  roles: readonly Role[],
+  windows: readonly (readonly [bigint, bigint])[],
+  sleep: (ms: number) => Promise<void>,
+): Promise<{
+  readonly opened: readonly OpenedStream[];
+  readonly failedWindows: number;
+}> {
+  // A wallet that is BOTH buyer and operator on one stream matches two filters.
+  const byStreamId = new Map<`0x${string}`, OpenedStream>();
+  let failedWindows = 0;
+
+  const readWindow = async (
+    query: StreamOpenedQuery,
+  ): Promise<readonly OpenedStream[] | null> => {
+    for (let attempt = 1; attempt <= WINDOW_ATTEMPTS; attempt++) {
+      try {
+        return await read.streamOpenedLogs(query);
+      } catch {
+        if (attempt < WINDOW_ATTEMPTS) await sleep(RETRY_DELAY_MS * attempt);
+      }
+    }
+    return null;
+  };
+
+  const queries: StreamOpenedQuery[] = windows.flatMap(([fromBlock, toBlock]) =>
+    roles.map((role) => ({ role, address, fromBlock, toBlock })),
+  );
+  for (let index = 0; index < queries.length; index += SCAN_CONCURRENCY) {
+    const batch = queries.slice(index, index + SCAN_CONCURRENCY);
+    const settled = await Promise.all(batch.map(readWindow));
+    for (const logs of settled) {
+      if (logs === null) {
+        failedWindows++;
+        continue;
+      }
+      for (const log of logs) {
+        if (!byStreamId.has(log.streamId)) byStreamId.set(log.streamId, log);
+      }
+    }
+  }
+
+  return { opened: [...byStreamId.values()], failedWindows };
+}
+
+function describeRole(log: OpenedStream, address: `0x${string}`): string {
+  const wanted = address.toLowerCase();
+  const isBuyer = log.buyer.toLowerCase() === wanted;
+  const isOperator = log.operator.toLowerCase() === wanted;
+  if (isBuyer && isOperator) return "buyer+operator";
+  if (isBuyer) return "buyer";
+  if (isOperator) return "operator";
+  // Only reachable if the node ignored the indexed topic filter it was given.
+  throw new CliError(
+    `the RPC returned stream ${log.streamId}, which does not involve ${address}`,
+    {
+      exitCode: 4,
+      hint: "the escrow log filter was not applied by the endpoint; the result cannot be trusted.",
+    },
+  );
+}

package/src/cli/commands/watch.ts

@@ -0,0 +1,70 @@
+import { integerFlag } from "../args.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { describeError, usageError } from "../errors.js";
+import {
+  readStreamReport,
+  streamReportJson,
+  streamReportRows,
+} from "../status.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+const DEFAULT_INTERVAL_SECONDS = 15;
+
+export const watchCommand: CommandSpec = {
+  name: "watch",
+  summary:
+    "Poll a stream's verified accrual until it is closed (Ctrl-C to stop)",
+  usage:
+    "metrik watch <streamId> [--interval 15] [--max-polls N (default: unbounded)]",
+  flags: ["interval", "max-polls"],
+  signs: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, out, deps } = context;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik watch requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+    const interval = integerFlag(args, "interval") ?? DEFAULT_INTERVAL_SECONDS;
+    if (interval <= 0) {
+      throw usageError("--interval must be a positive number of seconds");
+    }
+    const maxPolls = integerFlag(args, "max-polls");
+
+    const read = deps.createReadClient(config);
+    // Same chain allowlist as the signing paths — see `status`.
+    await assertTestnetRpc(config, () => read.getChainId());
+    out.note(
+      `watching ${streamId} every ${interval}s — the oracle checkpoints roughly every 15-22s.`,
+    );
+
+    for (let poll = 0; maxPolls === undefined || poll < maxPolls; poll++) {
+      if (poll > 0) await deps.sleep(interval * 1_000);
+
+      let report;
+      try {
+        report = await readStreamReport(read, streamId, deps.nowSeconds());
+      } catch (error) {
+        // A transient RPC blip must not end a long watch.
+        out.note(`read failed, retrying: ${describeError(error)}`);
+        continue;
+      }
+
+      // `--json` streams one COMPACT JSON object per poll — JSON Lines, as the
+      // docs promise. The pretty-printed form used by the single-shot commands
+      // would put one object across ~30 lines, none of which parses on its own,
+      // which is useless to the line-at-a-time consumer this mode exists for.
+      out.resultLine(streamReportJson(report));
+      out.print(
+        `[${new Date(report.nowSeconds * 1000).toISOString()}] ${streamId}`,
+      );
+      out.table(streamReportRows(report));
+      out.print("");
+
+      if (report.stream.status === "closed") {
+        out.note("stream is closed — watch complete.");
+        return;
+      }
+    }
+  },
+};

package/src/cli/config.ts

@@ -0,0 +1,208 @@
+import {
+  BASE_SEPOLIA_ESCROW_V2,
+  BASE_SEPOLIA_USDC,
+  DEFAULT_ORACLE_BASE_URL,
+  DEFAULT_PUBLIC_REGISTRY_URL,
+} from "@absol-labs/sdk";
+import { isAddress, getAddress } from "viem";
+import { baseSepolia } from "viem/chains";
+
+import { CliError, configError, usageError } from "./errors.js";
+import { stringFlag, integerFlag, type ParsedArgs } from "./args.js";
+
+/**
+ * TESTNET ONLY — the single allowlist this CLI will settle against.
+ *
+ * Metrik's escrow moves real USDC the moment it is pointed at a mainnet chain,
+ * and this CLI signs with a raw private key read from the environment. So the
+ * chain is an allowlist, not a default: any other chain id is refused outright,
+ * with no override flag. There is deliberately no `--allow-mainnet` — an escape
+ * hatch that re-enables real funds would defeat the guarantee, and a mainnet
+ * deployment is not something a flag can conjure (there is none).
+ *
+ * The allowlist is enforced TWICE: once against the configured/declared chain
+ * id, and again against the chain id the RPC endpoint actually reports before
+ * any fund-moving command signs anything (see `assertTestnetRpc`). The second
+ * check is what stops `--chain-id 84532 --rpc-url <a mainnet RPC>`.
+ */
+export const TESTNET_CHAIN_IDS: readonly number[] = [baseSepolia.id];
+
+/**
+ * The block `BASE_SEPOLIA_ESCROW_V2` was deployed at — the anchor of every
+ * escrow log scan, because the contract has no history before it.
+ *
+ * Verified against Base Sepolia on 2026-09-17: `eth_getLogs` for this single
+ * block returns 6 escrow logs (the deployment's own events). History is
+ * immutable, so that is a stable known answer forever, which is what lets the
+ * same block serve as the log-retention canary in `metrik streams`.
+ *
+ * It is tied to that ONE address. A run pointed at a different `--escrow` has
+ * no anchor and must be given `--from-block`, rather than silently scanning
+ * from a block that means nothing for it.
+ */
+export const BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK = 45_892_018n;
+
+export interface CliConfig {
+  readonly chain: typeof baseSepolia;
+  readonly chainId: number;
+  readonly rpcUrl: string;
+  readonly escrow: `0x${string}`;
+  readonly usdc: `0x${string}`;
+  readonly oracleBaseUrl: string;
+  readonly registryUrl: string;
+}
+
+/**
+ * Resolves settlement configuration from flags, then env, then the baked-in
+ * Base Sepolia defaults — so `metrik discover` works with nothing configured at
+ * all, while every value stays overridable.
+ */
+export function resolveConfig(
+  args: ParsedArgs,
+  env: NodeJS.ProcessEnv,
+): CliConfig {
+  const chainId =
+    integerFlag(args, "chain-id") ??
+    parseEnvChainId(env.METRIK_AGENT_CHAIN_ID) ??
+    baseSepolia.id;
+  assertTestnetChainId(chainId, "the configured chain id");
+
+  const rpcUrl =
+    stringFlag(args, "rpc-url") ??
+    env.METRIK_AGENT_RPC_URL ??
+    baseSepolia.rpcUrls.default.http[0];
+  if (rpcUrl === undefined || !isHttpUrl(rpcUrl)) {
+    throw configError(
+      `RPC URL must be an http(s) URL (got "${rpcUrl ?? "undefined"}")`,
+      "set --rpc-url or METRIK_AGENT_RPC_URL.",
+    );
+  }
+
+  return {
+    chain: baseSepolia,
+    chainId,
+    rpcUrl,
+    escrow: resolveAddress(
+      stringFlag(args, "escrow") ?? env.METRIK_AGENT_ESCROW,
+      BASE_SEPOLIA_ESCROW_V2,
+      "escrow",
+    ),
+    usdc: resolveAddress(
+      stringFlag(args, "usdc") ?? env.METRIK_AGENT_USDC,
+      BASE_SEPOLIA_USDC,
+      "usdc",
+    ),
+    oracleBaseUrl: resolveHttpUrl(
+      stringFlag(args, "oracle-url") ?? env.METRIK_AGENT_ORACLE_URL,
+      DEFAULT_ORACLE_BASE_URL,
+      "oracle-url",
+    ),
+    registryUrl: resolveHttpUrl(
+      stringFlag(args, "registry-url") ?? env.METRIK_AGENT_REGISTRY_URL,
+      DEFAULT_PUBLIC_REGISTRY_URL,
+      "registry-url",
+    ),
+  };
+}
+
+/** Flags every command accepts for settlement configuration. */
+export const CONFIG_FLAGS: readonly string[] = [
+  "chain-id",
+  "rpc-url",
+  "escrow",
+  "usdc",
+  "oracle-url",
+  "registry-url",
+];
+
+/** Flags every command accepts for output shape. */
+export const GLOBAL_FLAGS: readonly string[] = ["json", "help"];
+
+export function assertTestnetChainId(chainId: number, source: string): void {
+  if (TESTNET_CHAIN_IDS.includes(chainId)) return;
+  throw configError(
+    `refusing to run against chain ${chainId}: ${source} is not a supported testnet`,
+    `this CLI signs with a raw private key and settles real value, so it is testnet-only. Supported: ${TESTNET_CHAIN_IDS.join(
+      ", ",
+    )} (Base Sepolia). There is no override flag.`,
+  );
+}
+
+/**
+ * Second half of the testnet guard: the chain the RPC ACTUALLY serves. Called
+ * before any command that can move funds, because a declared chain id is just a
+ * number the caller typed — the endpoint is the thing that settles.
+ */
+export async function assertTestnetRpc(
+  config: CliConfig,
+  readChainId: () => Promise<number>,
+): Promise<void> {
+  let observed: number;
+  try {
+    observed = await readChainId();
+  } catch (error) {
+    throw new CliError(`could not read the chain id from ${config.rpcUrl}`, {
+      exitCode: 3,
+      hint: "the RPC endpoint must be reachable before a fund-moving command runs.",
+      cause: error,
+    });
+  }
+  assertTestnetChainId(observed, `the RPC endpoint ${config.rpcUrl}`);
+  if (observed !== config.chainId) {
+    throw configError(
+      `RPC chain id ${observed} does not match the configured chain id ${config.chainId}`,
+      "point --rpc-url at the configured chain, or fix --chain-id.",
+    );
+  }
+}
+
+function parseEnvChainId(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw.length === 0) return undefined;
+  if (!/^\d+$/.test(raw)) {
+    throw configError(
+      `METRIK_AGENT_CHAIN_ID must be a positive integer (got "${raw}")`,
+    );
+  }
+  return Number(raw);
+}
+
+function resolveAddress(
+  candidate: string | undefined,
+  fallback: `0x${string}`,
+  label: string,
+): `0x${string}` {
+  if (candidate === undefined || candidate.length === 0) return fallback;
+  if (!isAddress(candidate)) {
+    throw configError(`--${label} must be an EVM address (got "${candidate}")`);
+  }
+  return getAddress(candidate) as `0x${string}`;
+}
+
+function resolveHttpUrl(
+  candidate: string | undefined,
+  fallback: string,
+  label: string,
+): string {
+  if (candidate === undefined || candidate.length === 0) return fallback;
+  if (!isHttpUrl(candidate)) {
+    throw configError(`--${label} must be an http(s) URL (got "${candidate}")`);
+  }
+  return candidate.replace(/\/+$/, "");
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** Parses a `0x`-prefixed 32-byte hex id (stream id / serviceRef). */
+export function parseBytes32(value: string, label: string): `0x${string}` {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+    throw usageError(`${label} must be a 0x-prefixed 32-byte hex value`);
+  }
+  return value.toLowerCase() as `0x${string}`;
+}

package/src/cli/context.ts

@@ -0,0 +1,30 @@
+import type { ParsedArgs } from "./args.js";
+import type { CliConfig } from "./config.js";
+import type { CliDependencies } from "./deps.js";
+import type { Printer } from "./output.js";
+
+/** Everything a command needs, assembled once by the runner. */
+export interface CommandContext {
+  readonly args: ParsedArgs;
+  readonly config: CliConfig;
+  readonly env: NodeJS.ProcessEnv;
+  readonly out: Printer;
+  readonly deps: CliDependencies;
+}
+
+export interface CommandSpec {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage: string;
+  /** Command-specific flags, on top of the global + config flags. */
+  readonly flags: readonly string[];
+  /** True when the command broadcasts a transaction that can move funds. */
+  readonly signs: boolean;
+  /**
+   * True when the command needs `METRIK_AGENT_PRIVATE_KEY` even though it
+   * broadcasts nothing — `invoke` signs an off-chain capability. Defaults to
+   * `signs`, since everything that broadcasts obviously needs a key.
+   */
+  readonly requiresKey?: boolean;
+  readonly run: (context: CommandContext) => Promise<void>;
+}