@absol-labs/agent 0.9.1 → 0.11.0

package/src/cli/privy.ts

@@ -0,0 +1,396 @@
+import {
+  custom,
+  isAddress,
+  getAddress,
+  type Account,
+  type Transport,
+} from "viem";
+
+import {
+  AutonomousWalletError,
+  EncryptedFileCredentialStore,
+  HttpAutonomousWalletBroker,
+  METRIK_AUTONOMOUS_WALLET_BROKER_URL,
+  METRIK_WALLET_ENCRYPTION_KEY_ENV,
+  createAutonomousWalletProvider,
+  createDefaultAutonomousWalletStore,
+  type AutonomousWalletCredentialStore,
+  type AutonomousWalletRecord,
+} from "../wallet/autonomous-wallet.js";
+import { createPrivySessionProvider } from "../wallet/privy-session-provider.js";
+import {
+  createPrivyEmbeddedAccount,
+  type PrivyEip1193Provider,
+} from "../wallet/provider.js";
+import { configError } from "./errors.js";
+
+/**
+ * The CLI's two Privy wallet shapes.
+ *
+ * Privy differs from the private-key and CDP paths in ONE structural way: the
+ * account it yields has no local `signTransaction`. It signs and broadcasts by
+ * sending `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so the
+ * viem wallet client's TRANSPORT must be that provider rather than a plain HTTP
+ * RPC. That is the whole difference, and it is what `transport` below carries.
+ *
+ * Neither shape puts a wallet key on this machine. The signing key lives at
+ * Privy; the broker holds the Privy authorization key. What the CLI holds is
+ * either a short-lived session token (`session`) or a P-256 authorization key
+ * in the host credential store (`autonomous`) — a key that authorizes a
+ * policy-bounded request, not a key that can move funds by itself.
+ */
+export type PrivyCliWalletSource = "privy-autonomous" | "privy-session";
+
+/** The store key naming the agent-owned wallet in the host credential store. */
+export const PRIVY_WALLET_KEY_ENV = "METRIK_AGENT_PRIVY_WALLET_KEY";
+/** Broker base URL. Optional for `autonomous`, REQUIRED for `session`. */
+export const PRIVY_BROKER_URL_ENV = "METRIK_AGENT_PRIVY_BROKER_URL";
+/** A scoped session token minted by the broker's `POST /v1/sessions`. */
+export const PRIVY_SESSION_TOKEN_ENV = "METRIK_AGENT_PRIVY_SESSION_TOKEN";
+/** The embedded wallet address the session is bound to. */
+export const PRIVY_ADDRESS_ENV = "METRIK_AGENT_PRIVY_ADDRESS";
+/** The PUBLIC Privy app id. Not a secret — the broker serves it at `/v1/config`. */
+export const PRIVY_APP_ID_ENV = "METRIK_AGENT_PRIVY_APP_ID";
+
+/** Every variable either Privy shape reads. Named in errors, never printed. */
+export const PRIVY_ENV_VARS = [
+  PRIVY_WALLET_KEY_ENV,
+  PRIVY_BROKER_URL_ENV,
+  PRIVY_SESSION_TOKEN_ENV,
+  PRIVY_ADDRESS_ENV,
+  PRIVY_APP_ID_ENV,
+] as const;
+
+/** The variables the user-owned session shape needs, all of them. */
+export const PRIVY_SESSION_ENV_VARS = [
+  PRIVY_BROKER_URL_ENV,
+  PRIVY_SESSION_TOKEN_ENV,
+  PRIVY_ADDRESS_ENV,
+  PRIVY_APP_ID_ENV,
+] as const;
+
+/**
+ * The spend ceiling a broker enforces server-side, read from `GET /v1/config`.
+ *
+ * These are the SAME numbers the broker checks `openStream` against
+ * (`deposit <= maxTotalUsdc`, `ratePerSecond <= maxRatePerSecondUsdc`,
+ * `duration <= maxDurationSeconds`), which is why the CLI can use them to
+ * refuse an over-ceiling hire locally instead of paying gas to learn a knowable
+ * fact. It reads them rather than hardcoding them: the ceiling belongs to the
+ * broker, and a copy in this file would be a second source of truth that goes
+ * stale silently.
+ */
+export interface PrivySpendPolicy {
+  readonly brokerUrl: string;
+  readonly chainId: number;
+  readonly maxTotalUsdc: bigint;
+  readonly maxRatePerSecondUsdc: bigint;
+  readonly maxDurationSeconds: number;
+}
+
+/** Reads a broker's public policy. No credential is sent; nothing secret is served. */
+export async function fetchPrivySpendPolicy(
+  brokerUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<PrivySpendPolicy> {
+  const base = brokerUrl.replace(/\/$/, "");
+  const response = await fetchImpl(`${base}/v1/config`, {
+    headers: { accept: "application/json" },
+  }).catch((error: unknown) => {
+    throw configError(
+      `the Privy broker at ${base} did not answer its public policy`,
+      `${describe(error)} The CLI reads GET /v1/config to know the ceiling your wallet is capped at; without it, it cannot tell you before broadcasting whether a hire fits.`,
+    );
+  });
+  const body = (await response.json().catch(() => null)) as Record<
+    string,
+    unknown
+  > | null;
+  if (!response.ok || body === null) {
+    throw configError(
+      `the Privy broker at ${base} rejected the public policy read (${response.status})`,
+    );
+  }
+  const chainId = Number(body.chainId);
+  const maxTotalUsdc = asBigint(body.maxTotalUsdcAtomic);
+  const maxRatePerSecondUsdc = asBigint(body.maxRatePerSecondAtomic);
+  const maxDurationSeconds = Number(body.maxDurationSeconds);
+  if (
+    !Number.isSafeInteger(chainId) ||
+    maxTotalUsdc === null ||
+    maxRatePerSecondUsdc === null ||
+    !Number.isSafeInteger(maxDurationSeconds)
+  ) {
+    throw configError(
+      `the Privy broker at ${base} returned a policy this CLI cannot read`,
+      "expected chainId, maxTotalUsdcAtomic, maxRatePerSecondAtomic and maxDurationSeconds.",
+    );
+  }
+  return {
+    brokerUrl: base,
+    chainId,
+    maxTotalUsdc,
+    maxRatePerSecondUsdc,
+    maxDurationSeconds,
+  };
+}
+
+function asBigint(value: unknown): bigint | null {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value))
+    return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return null;
+}
+
+export interface ResolvedPrivyCliWallet {
+  readonly source: PrivyCliWalletSource;
+  /** A JSON-RPC account: `signTypedData` works, `signTransaction` does not exist. */
+  readonly account: Account;
+  /** The provider-as-transport. Without this every write goes to a plain RPC and fails. */
+  readonly transport: Transport;
+  /** One line naming the wallet's origin. Safe to print: no credential in it. */
+  readonly description: string;
+  /** Reads the broker ceiling this wallet is capped at. Bound to its broker URL. */
+  readonly readSpendPolicy: () => Promise<PrivySpendPolicy>;
+}
+
+export interface ResolvePrivyCliWalletOptions {
+  /** `--rpc-url`, so a Privy wallet's READS use the same endpoint as everything else. */
+  readonly rpcUrl?: string;
+  readonly note?: (line: string) => void;
+  /** Test seam. Defaults to the real credential store selected from `env`. */
+  readonly store?: AutonomousWalletCredentialStore;
+  /** Test seam for the broker HTTP contract. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Resolves a Privy wallet from the environment, or `null` when no Privy
+ * variable is set at all.
+ *
+ * A PARTIALLY configured Privy setup is an error, not a `null` — "you set the
+ * session token but not the address" and "you configured no Privy wallet" are
+ * different facts, and rendering the first as the second sends the reader
+ * looking in the wrong place. This mirrors the CDP path exactly.
+ */
+export async function resolvePrivyCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: ResolvePrivyCliWalletOptions = {},
+): Promise<ResolvedPrivyCliWallet | null> {
+  const walletKey = read(env, PRIVY_WALLET_KEY_ENV);
+  const brokerUrl = read(env, PRIVY_BROKER_URL_ENV);
+  const sessionToken = read(env, PRIVY_SESSION_TOKEN_ENV);
+  const address = read(env, PRIVY_ADDRESS_ENV);
+  const appId = read(env, PRIVY_APP_ID_ENV);
+
+  if (
+    walletKey === null &&
+    brokerUrl === null &&
+    sessionToken === null &&
+    address === null &&
+    appId === null
+  ) {
+    return null;
+  }
+
+  if (walletKey !== null) {
+    if (sessionToken !== null) {
+      options.note?.(
+        `warning: both ${PRIVY_WALLET_KEY_ENV} and ${PRIVY_SESSION_TOKEN_ENV} are set; using the agent-owned wallet named by ${PRIVY_WALLET_KEY_ENV}. Unset it to sign with the session token.`,
+      );
+    }
+    return await resolveAutonomous(walletKey, brokerUrl, env, options);
+  }
+
+  const missing = PRIVY_SESSION_ENV_VARS.filter(
+    (name) => read(env, name) === null,
+  );
+  if (missing.length > 0) {
+    throw configError(
+      `the Privy wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`,
+      `a Privy wallet is configured one of two ways: set ${PRIVY_WALLET_KEY_ENV} to the store key of an agent-owned wallet you provisioned with provisionMetrikAutonomousWallet(), or set all of ${PRIVY_SESSION_ENV_VARS.join(", ")} for a broker session. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others to use a different wallet.`,
+    );
+  }
+
+  return resolveSession({
+    brokerUrl: brokerUrl as string,
+    sessionToken: sessionToken as string,
+    address: address as string,
+    appId: appId as string,
+    ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+    ...(options.fetchImpl === undefined
+      ? {}
+      : { fetchImpl: options.fetchImpl }),
+  });
+}
+
+async function resolveAutonomous(
+  walletKey: string,
+  brokerUrlOverride: string | null,
+  env: NodeJS.ProcessEnv,
+  options: ResolvePrivyCliWalletOptions,
+): Promise<ResolvedPrivyCliWallet> {
+  const store = options.store ?? selectCredentialStore(env);
+  let record: AutonomousWalletRecord | null;
+  try {
+    record = await store.load(walletKey);
+  } catch (error) {
+    throw configError(
+      `could not read the agent-owned Privy wallet "${walletKey}" from the credential store`,
+      `${describe(error)} On a headless host the OS credential store is often unavailable; set ${METRIK_WALLET_ENCRYPTION_KEY_ENV} to use the encrypted-file store instead.`,
+    );
+  }
+  if (record === null) {
+    throw configError(
+      `no agent-owned Privy wallet is stored under the key "${walletKey}"`,
+      `the CLI never provisions a wallet on your behalf — a fund-moving command is the wrong place to mint one. Provision it once with provisionMetrikAutonomousWallet({ storeKey: "${walletKey}" }) (see docs/autonomous-privy-wallet.md), then re-run this command.`,
+    );
+  }
+  if (record.walletId === undefined || record.address === undefined) {
+    throw configError(
+      `the agent-owned Privy wallet "${walletKey}" was never finished provisioning`,
+      "the local key exists but the broker never returned a wallet id and address. Re-run provisionMetrikAutonomousWallet() with the same store key — it retries with the same key and idempotency nonce.",
+    );
+  }
+
+  const brokerUrl = brokerUrlOverride ?? record.brokerUrl;
+  if (brokerUrlOverride !== null && brokerUrlOverride !== record.brokerUrl) {
+    options.note?.(
+      `note: ${PRIVY_BROKER_URL_ENV} (${brokerUrlOverride}) overrides the broker this wallet was provisioned against (${record.brokerUrl}); only a broker holding this wallet's Privy authorization key can authorize it.`,
+    );
+  }
+
+  let broker: HttpAutonomousWalletBroker;
+  try {
+    broker = new HttpAutonomousWalletBroker(brokerUrl, {
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+    });
+  } catch (error) {
+    throw configError(
+      `the autonomous wallet broker URL is not usable: ${describe(error)}`,
+      `set ${PRIVY_BROKER_URL_ENV} to an HTTPS broker you control (the default is ${METRIK_AUTONOMOUS_WALLET_BROKER_URL}).`,
+    );
+  }
+
+  const provider = createAutonomousWalletProvider({
+    wallet: record,
+    broker,
+    ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+    ...(options.fetchImpl === undefined
+      ? {}
+      : { fetchImpl: options.fetchImpl }),
+  });
+  const account = await embeddedAccount(provider, record.appId, record.address);
+
+  return {
+    source: "privy-autonomous",
+    account,
+    transport: custom(provider),
+    description: `${record.address} (agent-owned Privy wallet "${walletKey}" via ${brokerUrl})`,
+    readSpendPolicy: async () =>
+      await fetchPrivySpendPolicy(
+        brokerUrl,
+        options.fetchImpl ?? globalThis.fetch.bind(globalThis),
+      ),
+  };
+}
+
+function resolveSession(input: {
+  readonly brokerUrl: string;
+  readonly sessionToken: string;
+  readonly address: string;
+  readonly appId: string;
+  readonly rpcUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+}): Promise<ResolvedPrivyCliWallet> {
+  if (!isAddress(input.address)) {
+    throw configError(
+      `${PRIVY_ADDRESS_ENV} must be a 0x-prefixed 20-byte address`,
+    );
+  }
+  const address = getAddress(input.address);
+  let provider: PrivyEip1193Provider;
+  try {
+    provider = createPrivySessionProvider({
+      brokerUrl: input.brokerUrl,
+      sessionToken: input.sessionToken,
+      address,
+      ...(input.rpcUrl === undefined ? {} : { rpcUrl: input.rpcUrl }),
+      ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+    });
+  } catch (error) {
+    throw configError(
+      `the Privy session broker URL is not usable: ${describe(error)}`,
+      `set ${PRIVY_BROKER_URL_ENV} to the HTTPS broker that minted ${PRIVY_SESSION_TOKEN_ENV}. A session token is only valid against the broker that issued it.`,
+    );
+  }
+  return embeddedAccount(provider, input.appId, address).then((account) => ({
+    source: "privy-session" as const,
+    account,
+    transport: custom(provider),
+    description: `${address} (Privy broker session via ${input.brokerUrl})`,
+    readSpendPolicy: async () =>
+      await fetchPrivySpendPolicy(
+        input.brokerUrl,
+        input.fetchImpl ?? globalThis.fetch.bind(globalThis),
+      ),
+  }));
+}
+
+/**
+ * Wraps a provider in the package's existing Privy EOA adapter.
+ *
+ * Both CLI providers answer `eth_chainId` and `eth_accounts` locally, so the
+ * adapter's session assertion is a pure local consistency check here — no
+ * network call happens while the wallet is being resolved.
+ */
+async function embeddedAccount(
+  provider: PrivyEip1193Provider,
+  appId: string,
+  address: `0x${string}`,
+): Promise<Account> {
+  try {
+    return await createPrivyEmbeddedAccount({
+      appId,
+      address,
+      provider,
+      chainId: 84532,
+    });
+  } catch (error) {
+    throw configError(
+      `the Privy wallet could not be prepared: ${describe(error)}`,
+      `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are Base Sepolia (84532) only.`,
+    );
+  }
+}
+
+/**
+ * The credential store the autonomous wallet was provisioned into.
+ *
+ * Selection mirrors `provisionMetrikAutonomousWallet`'s documented options:
+ * setting `METRIK_WALLET_ENCRYPTION_KEY` means the encrypted-file store (the
+ * durable option for a headless host), otherwise the host OS store. Picking a
+ * different store than provisioning used simply finds no record, and the
+ * "no wallet is stored under this key" error above says so.
+ */
+function selectCredentialStore(
+  env: NodeJS.ProcessEnv,
+): AutonomousWalletCredentialStore {
+  if (read(env, METRIK_WALLET_ENCRYPTION_KEY_ENV) !== null) {
+    return new EncryptedFileCredentialStore({ env });
+  }
+  return createDefaultAutonomousWalletStore();
+}
+
+function read(env: NodeJS.ProcessEnv, name: string): string | null {
+  const value = env[name];
+  return value === undefined || value.length === 0 ? null : value;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof AutonomousWalletError) return error.message;
+  return error instanceof Error ? error.message : String(error);
+}

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