@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/progress.ts

@@ -0,0 +1,75 @@
+/**
+ * A heartbeat on stderr for commands that can take a while.
+ *
+ * A live acceptance run saw `close` take 8s once and 142s the next time, and
+ * `status` calls run past two minutes with nothing on screen. With no output at
+ * all, a slow RPC and a wedged process look identical, and the only safe reading
+ * of that ambiguity — on a command that may have already broadcast a
+ * transaction — is the expensive one: wait, or kill it and risk double-sending.
+ *
+ * So the CLI narrates. Not progress towards a known total (there isn't one), but
+ * proof of life plus elapsed time, which is what distinguishes "slow" from
+ * "stuck". stderr in BOTH modes, so `--json` stdout stays a single parseable
+ * document.
+ */
+export interface Heartbeat {
+  /** Stops the ticker. Safe to call more than once. */
+  readonly stop: () => void;
+}
+
+/** Silence before the first tick — below this, a command is simply fast. */
+export const HEARTBEAT_DELAY_MS = 8_000;
+/** Gap between ticks once it has started. */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+
+export interface HeartbeatOptions {
+  readonly delayMs?: number;
+  readonly intervalMs?: number;
+  /** Injectable for tests; defaults to the global timers. */
+  readonly setTimer?: typeof setTimeout;
+  readonly clearTimer?: typeof clearTimeout;
+  readonly now?: () => number;
+}
+
+/**
+ * Start narrating `label`. Nothing is printed unless the work outlasts
+ * `delayMs`, so a fast command is silent and a slow one is legible.
+ */
+export function startHeartbeat(
+  note: (line: string) => void,
+  label: string,
+  options: HeartbeatOptions = {},
+): Heartbeat {
+  const delayMs = options.delayMs ?? HEARTBEAT_DELAY_MS;
+  const intervalMs = options.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+  const setTimer = options.setTimer ?? setTimeout;
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  const now = options.now ?? Date.now;
+
+  const startedAt = now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+
+  const tick = (): void => {
+    if (stopped) return;
+    const elapsed = Math.round((now() - startedAt) / 1000);
+    note(
+      `… still working: ${label} (${elapsed}s elapsed). Slow RPC or oracle, not a hang — nothing is retried silently.`,
+    );
+    schedule(intervalMs);
+  };
+  const schedule = (ms: number): void => {
+    timer = setTimer(tick, ms);
+    // Never hold the process open on account of the narration.
+    (timer as { unref?: () => void }).unref?.();
+  };
+  schedule(delayMs);
+
+  return {
+    stop() {
+      stopped = true;
+      if (timer !== undefined) clearTimer(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/cli/run.ts

@@ -0,0 +1,209 @@
+import { assertKnownFlags, booleanFlag, parseArgs } from "./args.js";
+import {
+  CONFIG_FLAGS,
+  GLOBAL_FLAGS,
+  TESTNET_CHAIN_IDS,
+  resolveConfig,
+} from "./config.js";
+import { CliError, describeError, usageError } from "./errors.js";
+import { createPrinter, type CliStreams } from "./output.js";
+import { startHeartbeat } from "./progress.js";
+import { defaultCliDependencies, type CliDependencies } from "./deps.js";
+import { packageVersion } from "./version.js";
+import { CDP_ENV_VARS, PRIVATE_KEY_ENV } from "./wallet.js";
+import type { CommandSpec } from "./context.js";
+
+import { claimCommand } from "./commands/claim.js";
+import { closeCommand } from "./commands/close.js";
+import { discoverCommand } from "./commands/discover.js";
+import { invokeCommand } from "./commands/invoke.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { openCommand } from "./commands/open.js";
+import { reclaimCommand } from "./commands/reclaim.js";
+import { reclaimUnverifiedCommand } from "./commands/reclaim-unverified.js";
+import { statusCommand } from "./commands/status.js";
+import { streamsCommand } from "./commands/streams.js";
+import { watchCommand } from "./commands/watch.js";
+
+/**
+ * The command surface, in the order the product loop runs:
+ * discover -> open -> invoke -> watch/status -> close -> reclaim, then the
+ * operator's own redemption (`claim`) and the buyer's last-resort exit
+ * (`reclaim-unverified`). `streams` (which of them are mine?) sits inside that
+ * loop; `mcp` (run the same loop from an MCP host) sits after it.
+ */
+export const COMMANDS: readonly CommandSpec[] = [
+  discoverCommand,
+  openCommand,
+  statusCommand,
+  streamsCommand,
+  watchCommand,
+  invokeCommand,
+  closeCommand,
+  reclaimCommand,
+  reclaimUnverifiedCommand,
+  claimCommand,
+  mcpCommand,
+];
+
+export interface RunCliOptions {
+  readonly argv: readonly string[];
+  readonly env?: NodeJS.ProcessEnv;
+  readonly streams?: CliStreams;
+  readonly deps?: CliDependencies;
+}
+
+/**
+ * Runs one CLI invocation and returns the process exit code. Pure in its
+ * inputs: argv, env, output sinks and side-effecting dependencies are all
+ * injected, so the whole surface is testable without a key or an RPC.
+ */
+export async function runCli(options: RunCliOptions): Promise<number> {
+  const env = options.env ?? process.env;
+  const streams = options.streams ?? {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+  };
+  const deps = options.deps ?? defaultCliDependencies;
+
+  let json = false;
+  try {
+    const args = parseArgs(options.argv);
+    json = booleanFlag(args, "json");
+    const out = createPrinter(streams, json);
+
+    // `--version` is checked before the bare-invocation help branch: `metrik
+    // --version` parses to no command at all.
+    if (args.command === "version" || booleanFlag(args, "version")) {
+      streams.stdout(packageVersion());
+      return 0;
+    }
+    if (args.command === null || args.command === "help") {
+      // A misspelled TOP-LEVEL flag must fail like a misspelled per-command one
+      // does. Printing help and exiting 0 tells a script the invocation
+      // succeeded, which is how a typo goes unnoticed.
+      assertKnownFlags(args, [...GLOBAL_FLAGS, "version"]);
+      streams.stdout(renderHelp(args.positionals[0]));
+      return 0;
+    }
+
+    const command = COMMANDS.find((spec) => spec.name === args.command);
+    if (command === undefined) {
+      throw usageError(
+        `unknown command: ${args.command}`,
+        `commands: ${COMMANDS.map((spec) => spec.name).join(", ")}`,
+      );
+    }
+    if (booleanFlag(args, "help")) {
+      streams.stdout(renderHelp(command.name));
+      return 0;
+    }
+
+    assertKnownFlags(args, [
+      ...GLOBAL_FLAGS,
+      ...CONFIG_FLAGS,
+      ...command.flags,
+    ]);
+    const config = resolveConfig(args, env);
+    // Every command gets the heartbeat, in one place rather than per command:
+    // any of them can be the one waiting on a slow endpoint, and a rule with an
+    // exception is a rule someone forgets to apply to the next command.
+    const heartbeat = startHeartbeat(out.note, `metrik ${command.name}`);
+    try {
+      await command.run({ args, config, env, out, deps });
+    } finally {
+      heartbeat.stop();
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof CliError) {
+      emitFailure(streams, json, error.message, error.hint, error.exitCode);
+      return error.exitCode;
+    }
+    emitFailure(streams, json, describeError(error), undefined, 4);
+    return 4;
+  }
+}
+
+function emitFailure(
+  streams: CliStreams,
+  json: boolean,
+  message: string,
+  hint: string | undefined,
+  exitCode: number,
+): void {
+  if (json) {
+    // The failure goes to stderr even in --json mode so stdout stays either a
+    // result document or nothing at all.
+    streams.stderr(
+      JSON.stringify({ error: message, hint: hint ?? null, exitCode }),
+    );
+    return;
+  }
+  streams.stderr(`error: ${message}`);
+  if (hint !== undefined) streams.stderr(`  ${hint}`);
+}
+
+export function renderHelp(commandName?: string): string {
+  const command = COMMANDS.find((spec) => spec.name === commandName);
+  if (command !== undefined) {
+    return [
+      `metrik ${command.name} — ${command.summary}`,
+      "",
+      `Usage: ${command.usage}`,
+      "",
+      command.flags.length === 0
+        ? "Command flags: (none)"
+        : `Command flags: ${command.flags.map((flag) => `--${flag}`).join(" ")}`,
+      `Settlement flags: ${CONFIG_FLAGS.map((flag) => `--${flag}`).join(" ")}`,
+      "Output flags: --json",
+      ...(command.signs
+        ? [
+            "",
+            `Broadcasts a transaction. Requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+          ]
+        : command.requiresKey === true
+          ? [
+              "",
+              `Broadcasts nothing, but signs an off-chain EIP-712 capability, so it requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+            ]
+          : []),
+    ].join("\n");
+  }
+
+  const width = COMMANDS.reduce(
+    (max, spec) => Math.max(max, spec.name.length),
+    0,
+  );
+  return [
+    `metrik ${packageVersion()} — pay for verified delivery, metered by the second`,
+    "",
+    "You rent a verified-live endpoint BY TIME, not per call: the oracle probes it and the",
+    "meter runs on availability that verified. One request and a thousand cost the same",
+    "second, and the clock keeps running while you send none. `metrik close` stops it.",
+    "",
+    "Usage: metrik <command> [options]",
+    "",
+    "Commands:",
+    ...COMMANDS.map(
+      (spec) =>
+        `  ${spec.name.padEnd(width)}  ${spec.summary}${spec.signs ? "  [broadcasts a tx]" : spec.requiresKey === true ? "  [needs a key]" : ""}`,
+    ),
+    "",
+    "Global flags:",
+    "  --json          machine-readable output on stdout",
+    "  --help          this text, or `metrik <command> --help`",
+    "",
+    "Settlement flags (all default to Metrik's Base Sepolia deployment):",
+    "  --chain-id  --rpc-url  --escrow  --usdc  --oracle-url  --registry-url",
+    "",
+    "Wallet (read from the environment only; never accepted as a flag):",
+    `  ${PRIVATE_KEY_ENV}  a Base Sepolia test key. Checked first.`,
+    `  ${CDP_ENV_VARS.join(", ")}`,
+    "    a Coinbase CDP Server Wallet v2 account. Used when no private key is set.",
+    "  A credential on the command line lands in shell history; these never are.",
+    "",
+    `TESTNET ONLY: this CLI refuses any chain outside ${TESTNET_CHAIN_IDS.join(", ")} (Base Sepolia),`,
+    "and re-checks the chain id the RPC actually serves before signing. There is no override.",
+  ].join("\n");
+}

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