@absol-labs/agent 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -17,6 +17,12 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "metrik": "dist/cli/bin.js",
+    "metrik-mcp": "dist/mcp/stdio.js",
+    "metrik-mcp-http": "dist/mcp/http-server.js",
+    "metrik-gateway": "dist/gateway/server-entry.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -34,6 +40,10 @@
       "types": "./dist/frameworks/langchain.d.ts",
       "import": "./dist/frameworks/langchain.js"
     },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    },
     "./crewai": {
       "types": "./dist/frameworks/crewai.d.ts",
       "import": "./dist/frameworks/crewai.js"
@@ -63,12 +73,12 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20 <21",
+    "node": ">=20.19 <25",
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.9.0",
-    "@absol-labs/shared": "^0.12.1",
+    "@absol-labs/sdk": "^0.9.2",
+    "@absol-labs/shared": "^0.13.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",
     "@privy-io/node": "0.33.0",
@@ -121,6 +131,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "build:e2e": "tsc -p tsconfig.e2e.build.json",
+    "cli": "tsx src/cli/bin.ts",
     "mcp:stdio": "tsx src/mcp/stdio.ts",
     "mcp:http": "tsx src/mcp/http-server.ts",
     "gateway": "tsx src/gateway/server-entry.ts",
@@ -129,7 +140,8 @@
     "l2:proof": "node scripts/l2-proof.mjs",
     "test": "vitest run",
     "test:package": "node scripts/test-packed-package.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit",
+    "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
     "typecheck:e2e": "tsc -p tsconfig.e2e.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",
     "format": "prettier --write ."

package/src/cli/amounts.ts

@@ -0,0 +1,102 @@
+import { formatUnits, parseUnits } from "viem";
+
+import { usageError } from "./errors.js";
+
+/** Circle USDC — 6 decimals on every deployment Metrik settles against. */
+export const USDC_DECIMALS = 6;
+
+/**
+ * How `--budget` / `--rate` are interpreted.
+ *
+ *  - `"usdc"` (default): decimal USDC, e.g. `--budget 0.27`.
+ *  - `"atomic"`: raw 6-decimal base units, e.g. `--budget 270000`.
+ *
+ * Both are offered because the two audiences count differently: a human reads
+ * USDC, while the escrow, the oracle and every `METRIK_E2E_*` fixture are in
+ * atomic units. Guessing from the magnitude of the number would be a silent
+ * 1,000,000x mistake on a fund-moving command, so the unit is explicit.
+ */
+export type AmountUnits = "usdc" | "atomic";
+
+export function parseAmountUnits(raw: string | undefined): AmountUnits {
+  if (raw === undefined || raw === "usdc") return "usdc";
+  if (raw === "atomic") return "atomic";
+  throw usageError(`--units must be "usdc" or "atomic" (got "${raw}")`);
+}
+
+/** Parses a `--budget`/`--rate` value into atomic USDC units. */
+export function parseUsdcAmount(
+  raw: string,
+  units: AmountUnits,
+  flagName: string,
+): bigint {
+  if (units === "atomic") {
+    if (!/^\d+$/.test(raw)) {
+      throw usageError(
+        `--${flagName} must be a non-negative integer of atomic USDC units (got "${raw}")`,
+      );
+    }
+    return BigInt(raw);
+  }
+
+  if (!/^\d+(\.\d+)?$/.test(raw)) {
+    throw usageError(
+      `--${flagName} must be a decimal USDC amount (got "${raw}")`,
+      "pass --units atomic to supply raw 6-decimal base units instead.",
+    );
+  }
+  const fraction = raw.split(".")[1];
+  if (fraction !== undefined && fraction.length > USDC_DECIMALS) {
+    throw usageError(
+      `--${flagName} has more precision than USDC supports (${USDC_DECIMALS} decimals): ${raw}`,
+    );
+  }
+  return parseUnits(raw, USDC_DECIMALS);
+}
+
+/** `270000n` -> `"0.27 USDC (270000 atomic)"`. */
+export function formatUsdc(atomic: bigint): string {
+  return `${formatUnits(atomic, USDC_DECIMALS)} USDC (${atomic.toString()} atomic)`;
+}
+
+/**
+ * Parses `--duration`: bare seconds, or a `s`/`m`/`h`/`d` suffix.
+ */
+export function parseDurationSeconds(raw: string): number {
+  const match = /^(\d+)([smhd]?)$/.exec(raw);
+  if (match === null) {
+    throw usageError(
+      `--duration must be seconds, optionally suffixed s/m/h/d (got "${raw}")`,
+    );
+  }
+  const value = Number(match[1]);
+  const multiplier = { "": 1, s: 1, m: 60, h: 3_600, d: 86_400 }[
+    match[2] ?? ""
+  ];
+  if (multiplier === undefined) {
+    throw usageError(`--duration has an unsupported unit: ${raw}`);
+  }
+  const seconds = value * multiplier;
+  if (!Number.isSafeInteger(seconds) || seconds <= 0) {
+    throw usageError(`--duration must be a positive number of seconds: ${raw}`);
+  }
+  return seconds;
+}
+
+/** Seconds -> a compact human duration (`3600` -> `1h`). */
+export function formatDuration(seconds: number): string {
+  if (seconds <= 0) return "0s";
+  const parts: string[] = [];
+  let remaining = seconds;
+  for (const [unit, size] of [
+    ["d", 86_400],
+    ["h", 3_600],
+    ["m", 60],
+    ["s", 1],
+  ] as const) {
+    const count = Math.floor(remaining / size);
+    if (count > 0) parts.push(`${count}${unit}`);
+    remaining -= count * size;
+  }
+  return parts.join(" ");
+}

package/src/cli/args.ts

@@ -0,0 +1,150 @@
+import { usageError } from "./errors.js";
+
+/**
+ * A deliberately small GNU-style argument parser. The CLI ships no argument
+ * parsing dependency: the surface is seven commands with a handful of flags, and
+ * the packed tarball should stay as light as the library it wraps.
+ *
+ * Supported forms: `--flag`, `--flag value`, `--flag=value`, `--no-flag`, and
+ * positional arguments. `--` ends flag parsing.
+ */
+export interface ParsedArgs {
+  readonly command: string | null;
+  readonly positionals: readonly string[];
+  /**
+   * Every occurrence of each flag, in order. Repeats are kept rather than
+   * overwritten so `--header` can be given more than once; scalar readers take
+   * the last occurrence.
+   */
+  readonly flags: ReadonlyMap<string, readonly (string | boolean)[]>;
+}
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const flags = new Map<string, (string | boolean)[]>();
+  const push = (name: string, value: string | boolean): void => {
+    const existing = flags.get(name);
+    if (existing === undefined) flags.set(name, [value]);
+    else existing.push(value);
+  };
+  let passthrough = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === undefined) continue;
+
+    if (passthrough || !token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    if (token === "--") {
+      passthrough = true;
+      continue;
+    }
+
+    const body = token.slice(2);
+    const equals = body.indexOf("=");
+    if (equals !== -1) {
+      const name = body.slice(0, equals);
+      assertFlagName(name, token);
+      push(name, body.slice(equals + 1));
+      continue;
+    }
+    assertFlagName(body, token);
+
+    if (body.startsWith("no-")) {
+      push(body.slice(3), false);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      push(body, true);
+      continue;
+    }
+    push(body, next);
+    index++;
+  }
+
+  const [command = null, ...rest] = positionals;
+  return { command, positionals: rest, flags };
+}
+
+function assertFlagName(name: string, token: string): void {
+  if (name.length === 0) {
+    throw usageError(`not a valid flag: ${token}`);
+  }
+}
+
+/** Reads a flag that must carry a string value. */
+export function stringFlag(args: ParsedArgs, name: string): string | undefined {
+  const values = args.flags.get(name);
+  if (values === undefined) return undefined;
+  const value = values[values.length - 1];
+  if (typeof value !== "string") {
+    throw usageError(`--${name} requires a value`);
+  }
+  return value;
+}
+
+/** Every occurrence of a repeatable string flag (e.g. `--header`). */
+export function stringFlags(args: ParsedArgs, name: string): string[] {
+  const values = args.flags.get(name) ?? [];
+  return values.map((value) => {
+    if (typeof value !== "string") {
+      throw usageError(`--${name} requires a value`);
+    }
+    return value;
+  });
+}
+
+export function requiredStringFlag(args: ParsedArgs, name: string): string {
+  const value = stringFlag(args, name);
+  if (value === undefined) {
+    throw usageError(`--${name} is required`);
+  }
+  return value;
+}
+
+export function booleanFlag(args: ParsedArgs, name: string): boolean {
+  const values = args.flags.get(name);
+  if (values === undefined) return false;
+  const value = values[values.length - 1];
+  if (value === undefined) return false;
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw usageError(`--${name} takes no value (got "${value}")`);
+}
+
+export function integerFlag(
+  args: ParsedArgs,
+  name: string,
+): number | undefined {
+  const raw = stringFlag(args, name);
+  if (raw === undefined) return undefined;
+  if (!/^\d+$/.test(raw)) {
+    throw usageError(`--${name} must be a non-negative integer (got "${raw}")`);
+  }
+  return Number(raw);
+}
+
+/**
+ * Rejects flags the command does not understand. A silently ignored `--budgt`
+ * on a fund-moving command is how someone spends more than they meant to.
+ */
+export function assertKnownFlags(
+  args: ParsedArgs,
+  known: readonly string[],
+): void {
+  const allowed = new Set(known);
+  const unknown = [...args.flags.keys()].filter((name) => !allowed.has(name));
+  if (unknown.length > 0) {
+    throw usageError(
+      `unknown flag${unknown.length > 1 ? "s" : ""}: ${unknown
+        .map((name) => `--${name}`)
+        .join(", ")}`,
+      `known flags: ${known.map((name) => `--${name}`).join(", ")}`,
+    );
+  }
+}

package/src/cli/attesters.ts

@@ -0,0 +1,86 @@
+import { describeError } from "./errors.js";
+import type { CliReadClient } from "./deps.js";
+
+/**
+ * Who attests, read off the escrow.
+ *
+ * Metrik's whole claim is that money moves only for delivery that a NEUTRAL
+ * verifier checked. On the live Base Sepolia deployment that neutrality is
+ * partial: `getOracleSigners()` returns three addresses, and one of them is the
+ * operator of the listings a buyer is being offered. A tool that prints
+ * "cryptographically verified" and "tier 2" without saying so is letting the
+ * buyer assume something the deployment does not provide.
+ *
+ * This is DISCLOSURE, not enforcement. The CLI does not refuse such a listing
+ * and does not score it — it states the fact and leaves the judgement to the
+ * buyer. Fixing the deployment is a deployment decision, not a CLI one.
+ */
+export interface AttesterSet {
+  /** The signer set, lowercased. `null` when the escrow would not answer. */
+  readonly signers: readonly string[] | null;
+  /** Why the set could not be read, when applicable. */
+  readonly unavailable: string | null;
+}
+
+/**
+ * Read the signer set, failing SOFT.
+ *
+ * An unreadable set must never render as "no overlap": "we checked and the
+ * operator does not attest" and "we could not check" are different facts, and
+ * conflating them would turn an outage into a false assurance. `signers: null`
+ * is carried through to every caller and printed as UNKNOWN.
+ */
+export async function readAttesterSet(
+  read: Pick<CliReadClient, "oracleSigners">,
+): Promise<AttesterSet> {
+  try {
+    const signers = await read.oracleSigners();
+    return {
+      signers: signers.map((signer) => signer.toLowerCase()),
+      unavailable: null,
+    };
+  } catch (error) {
+    return { signers: null, unavailable: describeError(error) };
+  }
+}
+
+/**
+ * Is this operator also one of the escrow's attesters?
+ *
+ * `null` means unknown (the set could not be read) and must be rendered as
+ * unknown, never as `false`.
+ */
+export function operatorAttestsOwnDelivery(
+  set: AttesterSet,
+  operator: string,
+): boolean | null {
+  if (set.signers === null) return null;
+  return set.signers.includes(operator.toLowerCase());
+}
+
+/**
+ * One factual stderr line, or `null` when there is nothing to disclose.
+ *
+ * Deliberately not alarming and deliberately not a verdict: it reports a
+ * configuration fact and what that fact means, and stops there.
+ */
+export function attesterDisclosure(
+  set: AttesterSet,
+  operator: string,
+): string | null {
+  const overlap = operatorAttestsOwnDelivery(set, operator);
+  if (overlap === null) return attesterSetUnavailableWarning(set);
+  if (!overlap) return null;
+  const total = set.signers?.length ?? 0;
+  return `warning: operator ${operator} is also one of the ${total} oracle signer${total === 1 ? "" : "s"} configured on this escrow. The party being paid is among the parties attesting that delivery happened. Verification here is not independent of the seller.`;
+}
+
+/**
+ * The one warning that belongs to the ESCROW rather than to any one listing:
+ * the signer set could not be read at all. Printed once per command, not once
+ * per row, and never as "no overlap".
+ */
+export function attesterSetUnavailableWarning(set: AttesterSet): string | null {
+  if (set.signers !== null) return null;
+  return `warning: the escrow's oracle signer set could not be read (${set.unavailable ?? "no reason given"}) — whether the operator being paid is also one of the parties attesting to its own delivery is UNKNOWN, not "no overlap".`;
+}

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from "./run.js";
+
+const exitCode = await runCli({ argv: process.argv.slice(2) });
+process.exitCode = exitCode;

package/src/cli/commands/claim.ts

@@ -0,0 +1,100 @@
+import { formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, describeError, usageError } from "../errors.js";
+import { signClaimMandate } from "../mandate.js";
+import { assertCanPayGas } from "../preflight.js";
+import { PRIVATE_KEY_ENV, resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/**
+ * The seller's side of the loop.
+ *
+ * `status` has always computed and printed an `operator claimable` row — a
+ * redeemable balance the CLI could see and could not act on. `claimWithProof` is
+ * operator-gated on-chain, so this command refuses a wallet that is not the
+ * stream's operator BEFORE it broadcasts: an address mismatch is knowable with
+ * one read, and letting it become a raw `NotOperator()` revert would cost gas to
+ * learn a fact that was already available.
+ */
+export const claimCommand: CommandSpec = {
+  name: "claim",
+  summary: "Operator: redeem what this stream has verifiably earned",
+  usage: "metrik claim <streamId>",
+  flags: [],
+  signs: true,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik claim requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+
+    const { account } = await resolveCliWallet(env, { note: out.note });
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    await assertCanPayGas(read, account.address);
+
+    const stream = await read.getStreamV2(streamId);
+    if (stream.operator.toLowerCase() !== account.address.toLowerCase()) {
+      throw new CliError(
+        `wallet ${account.address} is not the operator of this stream`,
+        {
+          exitCode: 3,
+          hint: `only ${stream.operator} can claim it — the escrow enforces this, so no other wallet can. Set ${PRIVATE_KEY_ENV} to the operator's key. (The buyer's side of this stream is \`metrik reclaim ${streamId}\`.)`,
+        },
+      );
+    }
+
+    // Accrual lives in the oracle's checkpoint proof, never in the stream tuple.
+    // No proof means no claim is possible yet, and saying that is better than
+    // paying gas for a `NothingToClaim()` revert.
+    let cumulativeAmount: bigint;
+    try {
+      cumulativeAmount = (await read.checkpointProof(streamId))
+        .cumulativeAmount;
+    } catch (error) {
+      throw new CliError(
+        "no checkpoint covers this stream yet, so there is nothing provable to claim",
+        {
+          exitCode: 4,
+          hint: `the oracle publishes roughly every 15-22s and pays only for intervals that verified; ${describeError(
+            error,
+          )}`,
+          cause: error,
+        },
+      );
+    }
+
+    const claimable = await read.claimableForV2(streamId, cumulativeAmount);
+    if (claimable === 0n) {
+      throw new CliError("this stream has nothing claimable right now", {
+        exitCode: 4,
+        hint: `everything checkpointed so far has already been claimed. See where it stands:  metrik status ${streamId}`,
+      });
+    }
+
+    const write = deps.createWriteClient(config, account);
+    const result = await write.claimStream({
+      streamId,
+      signedMandate: await signClaimMandate(account, config.chainId),
+      spentSoFarUsdc: 0n,
+      nowSeconds: deps.nowSeconds(),
+    });
+
+    out.result({
+      streamId,
+      txHash: result.txHash,
+      operator: stream.operator,
+      claimed: claimable,
+      verifiedCumulative: cumulativeAmount,
+    });
+    out.print("Claimed.");
+    out.table([
+      ["streamId", streamId],
+      ["tx", result.txHash],
+      ["operator", stream.operator],
+      ["claimed", `${formatUsdc(claimable)} (net of protocol fee)`],
+    ]);
+  },
+};

package/src/cli/commands/close.ts

@@ -0,0 +1,53 @@
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { usageError } from "../errors.js";
+import { signRecoveryMandate } from "../mandate.js";
+import { assertCanPayGas } from "../preflight.js";
+import { resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+export const closeCommand: CommandSpec = {
+  name: "close",
+  summary: "Stop the clock on a stream so the unspent budget can be reclaimed",
+  usage: "metrik close <streamId>",
+  flags: [],
+  signs: true,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik close requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+
+    const { account } = await resolveCliWallet(env, { note: out.note });
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    await assertCanPayGas(read, account.address);
+
+    const signedMandate = await signRecoveryMandate(account, config.chainId);
+    const write = deps.createWriteClient(config, account);
+    const result = await write.closeStream({
+      streamId,
+      signedMandate,
+      spentSoFarUsdc: 0n,
+      nowSeconds: deps.nowSeconds(),
+    });
+
+    out.result({ streamId, txHash: result.txHash, closed: true });
+    out.print("Stream closed.");
+    out.table([
+      ["streamId", streamId],
+      ["tx", result.txHash],
+    ]);
+    out.print("");
+    out.print(
+      `Nothing pushes money back. Reclaim what was never earned:  metrik reclaim ${streamId}`,
+    );
+    out.print(
+      "That reclaim reverts until the oracle publishes a checkpoint covering the stop time, so it waits and retries for you — leave it running.",
+    );
+    out.print(
+      `Next time:  metrik reclaim <streamId> --close-first  does this close and that reclaim in one command.`,
+    );
+  },
+};