@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/src/cli/privy.ts

@@ -0,0 +1,398 @@
+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 { PRIVY_BROKER_CHAIN_ID } from "../wallet/privy-session-broker.js";
+import { defaultNetwork } from "../network.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: PRIVY_BROKER_CHAIN_ID,
+    });
+  } catch (error) {
+    throw configError(
+      `the Privy wallet could not be prepared: ${describe(error)}`,
+      `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are on the broker's network only (${defaultNetwork().name}, chain ${PRIVY_BROKER_CHAIN_ID}).`,
+    );
+  }
+}
+
+/**
+ * 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/reclaimability.ts

@@ -0,0 +1,154 @@
+import type { StreamV2 } from "@absol-labs/sdk";
+
+import { formatDuration } from "./amounts.js";
+import { formatTimestamp, readChainNow } from "./escape-hatch.js";
+import { settlementCoverage } from "./status.js";
+import type { CliReadClient } from "./deps.js";
+
+/**
+ * Why a proof-based reclaim cannot go through right now, read from chain state
+ * rather than decoded out of a revert.
+ *
+ * `metrik reclaim` used to learn this only by sending the simulation and
+ * reading what came back. That works exactly as well as the endpoint's revert
+ * data does, and on the public Base Sepolia RPC it frequently does not work at
+ * all: an already-reclaimed stream, a stream that is still running, and a
+ * stream whose stop time is not checkpointed yet ALL came back as
+ *
+ *     reclaim simulation failed: Execution reverted for an unknown reason.
+ *
+ * Three different situations, three completely different next actions — you
+ * already have the money / close it first / wait ~20 seconds — and one message
+ * that distinguishes none of them. Worse, the retry loop keys off the same
+ * undecoded revert, so the wait that this command advertises never engaged.
+ *
+ * Every one of these conditions is a pure function of state the CLI already
+ * reads elsewhere (`getStreamV2`, `latestCheckpointCheckedAt`, the chain clock,
+ * and {@link settlementCoverage}, which `metrik status` has always used to
+ * decide the same question). So the condition is named from that state, before
+ * a transaction is built, the way `reclaim-unverified` has always named
+ * "already reclaimed". No revert data required.
+ */
+export type ReclaimBlocker =
+  /** `AlreadyReclaimed()` / `NothingToReclaim()`: the money is already back. */
+  | { readonly kind: "reclaimed" }
+  /** `StreamNotReclaimable()`: neither closed nor expired, so the clock runs. */
+  | {
+      readonly kind: "running";
+      readonly expiresAt: number;
+      readonly secondsRemaining: number;
+    }
+  /**
+   * `SettlementWindowOpen()`: the stream has stopped but no checkpoint reaches
+   * its stop time yet. The ONLY one of the three that is a wait rather than a
+   * refusal — the oracle publishes roughly every 15-22s.
+   */
+  | {
+      readonly kind: "awaiting-checkpoint";
+      readonly stopAt: number;
+      readonly coveredUpTo: number | null;
+    };
+
+/**
+ * The blocker implied by this state, or `null` when nothing in the state blocks
+ * a reclaim. Pure, so every branch is testable without an RPC — the same reason
+ * {@link settlementCoverage} is.
+ *
+ * Order matters and follows the escrow: a reclaimed stream is terminal, a
+ * running stream cannot be reclaimed at any settlement state, and only then
+ * does checkpoint coverage decide.
+ */
+export function classifyReclaimBlocker(
+  stream: Pick<StreamV2, "status" | "closedAt" | "expiresAt" | "reclaimed">,
+  latestCheckpointCheckedAt: number | null,
+  nowSeconds: number,
+): ReclaimBlocker | null {
+  if (stream.reclaimed) return { kind: "reclaimed" };
+  if (stream.status !== "closed" && nowSeconds < stream.expiresAt) {
+    return {
+      kind: "running",
+      expiresAt: stream.expiresAt,
+      secondsRemaining: stream.expiresAt - nowSeconds,
+    };
+  }
+  const coverage = settlementCoverage(
+    stream,
+    latestCheckpointCheckedAt,
+    nowSeconds,
+  );
+  if (coverage.pending && coverage.stopAt !== null) {
+    return {
+      kind: "awaiting-checkpoint",
+      stopAt: coverage.stopAt,
+      coveredUpTo: coverage.coveredUpTo,
+    };
+  }
+  return null;
+}
+
+/**
+ * Read the state the classifier needs and name the blocker.
+ *
+ * **Fails open.** A read that does not answer returns `null` — "nothing known
+ * to block this" — never a refusal. Refusing to return a buyer's money because
+ * a load-balanced endpoint would not answer a view call is the one outcome this
+ * command must never produce; the transaction itself remains the authority.
+ */
+export async function readReclaimBlocker(
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  fallbackNowSeconds: number,
+): Promise<ReclaimBlocker | null> {
+  const stream = await read.getStreamV2(streamId).catch(() => null);
+  if (stream === null) return null;
+  const now = await readChainNow(read, fallbackNowSeconds);
+  const latestCheckpointCheckedAt = await read
+    .latestCheckpointCheckedAt()
+    .catch(() => null);
+  return classifyReclaimBlocker(stream, latestCheckpointCheckedAt, now.seconds);
+}
+
+/**
+ * The refusal for a blocker that will not clear on its own, as message + hint.
+ *
+ * `awaiting-checkpoint` has no entry here on purpose: it clears by itself, so
+ * it is narrated by {@link describeAwaitingCheckpoint} and waited out, never
+ * raised as an error.
+ */
+export function describeTerminalBlocker(
+  blocker: ReclaimBlocker,
+  streamId: `0x${string}`,
+): { readonly message: string; readonly hint: string } | null {
+  if (blocker.kind === "reclaimed") {
+    return {
+      message:
+        "this stream has already been reclaimed — there is nothing left to take back",
+      hint: `check where it went:  metrik status ${streamId}`,
+    };
+  }
+  if (blocker.kind === "running") {
+    return {
+      message: `the stream is still running, so there is nothing to reclaim yet — the meter stops at ${formatTimestamp(
+        blocker.expiresAt,
+      )}, in ${formatDuration(blocker.secondsRemaining)}`,
+      hint: `stop the clock first — \`metrik close ${streamId}\`, or re-run this command with --close-first — or wait for it to expire. (If you closed it moments ago, the RPC endpoint may not have caught up yet: re-run this command.)`,
+    };
+  }
+  return null;
+}
+
+/** The wait, named: what stopped, how far the oracle has published. */
+export function describeAwaitingCheckpoint(
+  blocker: Extract<ReclaimBlocker, { kind: "awaiting-checkpoint" }>,
+): string {
+  const covered =
+    blocker.coveredUpTo === null
+      ? "how far the oracle has published could not be read"
+      : `the oracle has published only to ${formatTimestamp(blocker.coveredUpTo)}`;
+  return `the stream stopped at ${formatTimestamp(
+    blocker.stopAt,
+  )} and ${covered}. Reclaim reverts until a checkpoint reaches the stop time — the oracle publishes roughly every 15-22s, so this waits.`;
+}

package/src/cli/run.ts

@@ -1,16 +1,27 @@
-import { assertKnownFlags, booleanFlag, parseArgs } from "./args.js";
+import {
+  assertKnownFlags,
+  booleanFlag,
+  jsonOutputRequested,
+  parseArgs,
+} from "./args.js";
 import {
   CONFIG_FLAGS,
   GLOBAL_FLAGS,
-  TESTNET_CHAIN_IDS,
+  CLI_NETWORK_POLICY,
   resolveConfig,
 } from "./config.js";
+import { describeAllowedNetworks } from "../network.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 {
+  CDP_ENV_VARS,
+  PRIVATE_KEY_ENV,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+} from "./wallet.js";
 import type { CommandSpec } from "./context.js";
 
 import { claimCommand } from "./commands/claim.js";
@@ -19,15 +30,39 @@ 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 { payCommand } from "./commands/pay.js";
 import { reclaimCommand } from "./commands/reclaim.js";
+import { refundCommand } from "./commands/refund.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";
 
+/**
+ * Every wallet source, named in the order they are resolved. Privy shipped in
+ * 0.11.0 as resolution step 3 and worked, but appeared in no user-facing text
+ * at all — so the only way to learn the CLI could use it was to read the
+ * source or the docs. An external reviewer running the published package
+ * concluded it did not exist.
+ */
+const WALLET_SOURCES =
+  `${PRIVATE_KEY_ENV}, ${CDP_ENV_VARS.join(" + ")}, ` +
+  `or ${PRIVY_WALLET_KEY_ENV} (Privy; or a broker session via ${PRIVY_SESSION_ENV_VARS.join(" + ")}).`;
+
+/**
+ * Said in the help, not only discovered at runtime. `claim` is the OPERATOR's
+ * side and a Privy broker policy allowlists BUYER actions only, so a Privy
+ * wallet cannot sign one — the broker refuses, and the client cannot raise its
+ * own ceiling. The command already warns when it runs; someone choosing a
+ * wallet needs it before that.
+ */
+const PRIVY_CLAIM_NOTE =
+  "`metrik claim` does NOT work on a Privy wallet: the broker's transaction allowlist is buyer-only. Claim with the operator's own key.";
+
 /**
  * The command surface, in the order the product loop runs:
- * discover -> open -> invoke -> watch/status -> close -> reclaim, then the
+ * discover -> open (or pay, over x402) -> invoke -> watch/status -> close ->
+ * reclaim (or refund, through an x402 seller's gasless relay), 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.
@@ -35,12 +70,14 @@ import { watchCommand } from "./commands/watch.js";
 export const COMMANDS: readonly CommandSpec[] = [
   discoverCommand,
   openCommand,
+  payCommand,
   statusCommand,
   streamsCommand,
   watchCommand,
   invokeCommand,
   closeCommand,
   reclaimCommand,
+  refundCommand,
   reclaimUnverifiedCommand,
   claimCommand,
   mcpCommand,
@@ -69,7 +106,7 @@ export async function runCli(options: RunCliOptions): Promise<number> {
   let json = false;
   try {
     const args = parseArgs(options.argv);
-    json = booleanFlag(args, "json");
+    json = jsonOutputRequested(args);
     const out = createPrinter(streams, json);
 
     // `--version` is checked before the bare-invocation help branch: `metrik
@@ -160,12 +197,13 @@ export function renderHelp(commandName?: string): string {
       ...(command.signs
         ? [
             "",
-            `Broadcasts a transaction. Requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+            `Broadcasts a transaction. Requires a wallet in the environment: ${WALLET_SOURCES}`,
+            ...(command.name === "claim" ? [PRIVY_CLAIM_NOTE] : []),
           ]
         : 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(" + ")}.`,
+              `Broadcasts nothing, but signs an off-chain EIP-712 capability, so it requires a wallet in the environment: ${WALLET_SOURCES}`,
             ]
           : []),
     ].join("\n");
@@ -194,16 +232,21 @@ export function renderHelp(commandName?: string): string {
     "  --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",
+    "Settlement flags (all default to the selected network's registry entry):",
+    "  --network  --chain-id  --rpc-url  --escrow  --usdc  --oracle-url  --registry-url",
+    "  --network takes a registry id, chain id or CAIP-2 id (env METRIK_NETWORK).",
     "",
     "Wallet (read from the environment only; never accepted as a flag):",
-    `  ${PRIVATE_KEY_ENV}  a Base Sepolia test key. Checked first.`,
+    `  ${PRIVATE_KEY_ENV}  a testnet key. Checked first.`,
     `  ${CDP_ENV_VARS.join(", ")}`,
     "    a Coinbase CDP Server Wallet v2 account. Used when no private key is set.",
+    `  ${PRIVY_WALLET_KEY_ENV}`,
+    "    a Privy wallet you provisioned, reached through a broker. Checked third.",
+    `    A broker session instead: ${PRIVY_SESSION_ENV_VARS.join(", ")}.`,
+    `    ${PRIVY_CLAIM_NOTE}`,
     "  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),`,
+    `TESTNET ONLY: this CLI refuses any chain outside the registered testnets: ${describeAllowedNetworks(CLI_NETWORK_POLICY)},`,
     "and re-checks the chain id the RPC actually serves before signing. There is no override.",
   ].join("\n");
 }