@absol-labs/agent 0.9.1 → 0.11.0

package/src/cli/wallet.ts

@@ -0,0 +1,372 @@
+import { privateKeyToAccount } from "viem/accounts";
+import type { Account, LocalAccount, Transport } from "viem";
+
+import type { AutonomousWalletCredentialStore } from "../wallet/autonomous-wallet.js";
+import { resolveAgentWallet } from "../wallet/provider.js";
+import { configError } from "./errors.js";
+import {
+  PRIVY_ENV_VARS,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+  resolvePrivyCliWallet,
+  type PrivyCliWalletSource,
+  type PrivySpendPolicy,
+} from "./privy.js";
+
+/**
+ * The ONLY place the CLI resolves a signing wallet.
+ *
+ * There is deliberately NO `--private-key` flag, and no flag for any other
+ * credential. A secret passed on the command line lands in shell history, in
+ * `ps` output, and in any CI log that echoes the command; an environment
+ * variable does none of those. Secrets are also never echoed back: commands
+ * print the derived ADDRESS only.
+ *
+ * ## Resolution order (first match wins, checked in this order)
+ *
+ *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
+ *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
+ *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
+ *     broker, either agent-owned (`METRIK_AGENT_PRIVY_WALLET_KEY`) or a
+ *     user-owned broker session. See `./privy.ts`.
+ *
+ * The first two match `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures those surfaces the same way. The order is FIXED
+ * rather than "whichever is configured", because an environment carrying two is
+ * ambiguous about which address funds the stream — and that ambiguity is a
+ * fund-moving one. When more than one is present the earlier entry wins and
+ * `resolveCliWallet` says so on stderr rather than silently picking.
+ *
+ * ## What is different about Privy
+ *
+ * A private key and a CDP account both sign LOCALLY: `privateKeyToAccount()`
+ * and `toAccount(cdpServerAccount)` are viem local accounts, so they drop
+ * straight into the CLI's `http(rpcUrl)` transport with no other change.
+ *
+ * Privy does not. Its account is a JSON-RPC account with no `signTransaction`:
+ * it signs and broadcasts by sending `eth_sendTransaction` /
+ * `eth_signTypedData_v4` to a provider, so the wallet client's TRANSPORT must
+ * be that provider rather than a plain RPC. That is what {@link CliWallet.transport}
+ * carries, and the only reason this file knows Privy exists. The signer check
+ * below is therefore about CAPABILITY, not about locality: it refuses an
+ * account that genuinely cannot sign, and refuses a non-local account only on
+ * the paths that broadcast through `--rpc-url`.
+ *
+ * See `docs/cli.md` § Wallet.
+ */
+export const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
+
+/** Every environment variable the CDP path reads. Named in errors, never printed. */
+export const CDP_ENV_VARS = [
+  "CDP_API_KEY_ID",
+  "CDP_API_KEY_SECRET",
+  "CDP_WALLET_SECRET",
+  "METRIK_AGENT_CDP_OWNER_NAME",
+] as const;
+
+export {
+  PRIVY_ENV_VARS,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+} from "./privy.js";
+
+/**
+ * What the key is for, in the words of the command that needs it. `invoke`
+ * signs an EIP-712 invocation capability and broadcasts NOTHING; telling its
+ * caller "this command signs a transaction" was simply false.
+ */
+export type KeyPurpose = "transaction" | "capability";
+
+const PURPOSE_TEXT: Record<KeyPurpose, string> = {
+  transaction: "signs a transaction",
+  capability:
+    "signs an off-chain EIP-712 invocation capability (no transaction is broadcast)",
+};
+
+/** Which environment configured the signer, for output and for error text. */
+export type CliWalletSource = "private-key" | "cdp" | PrivyCliWalletSource;
+
+/**
+ * An account every CLI signing path can actually use.
+ *
+ * `signTypedData` is required rather than optional because it is the one
+ * capability EVERY path needs: fund-moving commands self-sign an EIP-712
+ * `SpendMandate`, and `invoke` signs an EIP-712 `InvocationCapability`. An
+ * account without it type-checks as a viem `Account` and then fails at the
+ * first signature with a `TypeError`.
+ */
+export type CliSignerAccount = Account & Pick<LocalAccount, "signTypedData">;
+
+export interface CliWallet {
+  readonly source: CliWalletSource;
+  readonly account: CliSignerAccount;
+  /**
+   * The transport fund-moving commands must broadcast through, when the wallet
+   * REQUIRES one. `undefined` means "a plain `http(--rpc-url)` is correct" —
+   * true for a local signer, false for Privy, whose provider IS the transport.
+   */
+  readonly transport?: Transport;
+  /** One line naming the signer's origin. Safe to print: no secret in it. */
+  readonly description: string;
+  /**
+   * Set when this wallet's spend ceiling is enforced where the CLI cannot reach
+   * it — i.e. by a Privy broker policy, not by a locally self-signed mandate.
+   *
+   * Its presence is the signal that the CLI should NOT self-sign a
+   * `SpendMandate` for this wallet, and should read and enforce the real
+   * ceiling instead. See `./spend-policy.ts` for why that substitution is
+   * strictly stronger than the mandate it replaces, and why re-adding the
+   * mandate "for consistency" would be a regression.
+   */
+  readonly readSpendPolicy?: () => Promise<PrivySpendPolicy>;
+}
+
+const WALLET_HINT =
+  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), configure a Coinbase CDP wallet with ` +
+  `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
+  `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;
+
+export interface ResolveCliWalletOptions {
+  readonly purpose?: KeyPurpose;
+  /**
+   * `--rpc-url`. Only the Privy paths use it at resolution time: their provider
+   * serves the wallet client's READS as well as its writes, so without this a
+   * Privy command would read from a different endpoint than `--rpc-url` names.
+   */
+  readonly rpcUrl?: string;
+  readonly note?: (line: string) => void;
+  /**
+   * Test seam, same role as `ResolveAgentWalletOptions.createCdpClient`: the
+   * credential store an agent-owned Privy wallet is read from. Unset in every
+   * real run, where the store is selected from the environment.
+   */
+  readonly store?: AutonomousWalletCredentialStore;
+  /** Test seam: the `fetch` the Privy broker is reached through. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Resolves the signing wallet, or throws an actionable configuration error.
+ *
+ * `note` receives one line when the environment is ambiguous (more than one
+ * wallet source configured). It is optional so `resolveCliWallet` stays usable
+ * from a context with no printer; commands always pass `out.note`.
+ */
+export async function resolveCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: ResolveCliWalletOptions = {},
+): Promise<CliWallet> {
+  const wallet = await optionalCliWallet(env, options);
+  if (wallet === null) {
+    throw configError(
+      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`,
+      WALLET_HINT,
+    );
+  }
+  return wallet;
+}
+
+/** True for both Privy shapes, which reach their key through a broker. */
+export function isPrivyWalletSource(
+  source: CliWalletSource,
+): source is PrivyCliWalletSource {
+  return source === "privy-autonomous" || source === "privy-session";
+}
+
+/**
+ * Whether this wallet's ceiling is enforced somewhere the CLI cannot reach.
+ *
+ * The one question every fund-moving command asks before deciding whether to
+ * self-sign a `SpendMandate`. See `./spend-policy.ts`.
+ */
+export function isPolicyEnforced(wallet: CliWallet): wallet is CliWallet & {
+  readonly readSpendPolicy: () => Promise<PrivySpendPolicy>;
+} {
+  return wallet.readSpendPolicy !== undefined;
+}
+
+/**
+ * The same resolution, but "nothing configured" is not an error. Used by
+ * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
+ * broadcast nothing and must therefore work for someone who does not yet have a
+ * funded wallet — which is exactly who a dry run is for.
+ *
+ * A wallet that is PARTIALLY configured is still an error here: "you set three
+ * of the four CDP variables" and "you configured no wallet" are different
+ * facts, and rendering the first as the second sends the reader looking in the
+ * wrong place. The same rule applies to a partial Privy setup.
+ */
+export async function optionalCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: Omit<ResolveCliWalletOptions, "purpose"> = {},
+): Promise<CliWallet | null> {
+  const privateKeyAccount = optionalCliAccount(env);
+  const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+  const privyConfigured = PRIVY_ENV_VARS.some((name) => isSet(env[name]));
+
+  if (privateKeyAccount !== null) {
+    const shadowed = [
+      ...(cdpConfigured ? ["CDP"] : []),
+      ...(privyConfigured ? ["Privy"] : []),
+    ];
+    if (shadowed.length > 0) {
+      options.note?.(
+        `warning: both ${PRIVATE_KEY_ENV} and ${shadowed.join(" and ")} wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the ${shadowed[0]} wallet.`,
+      );
+    }
+    return {
+      source: "private-key",
+      account: privateKeyAccount,
+      description: `${privateKeyAccount.address} (from ${PRIVATE_KEY_ENV})`,
+    };
+  }
+
+  if (cdpConfigured) {
+    if (privyConfigured) {
+      options.note?.(
+        "warning: both CDP and Privy wallet variables are set; using the CDP wallet. Unset the CDP variables to sign with the Privy wallet.",
+      );
+    }
+    return await resolveCdpWallet(env);
+  }
+
+  if (!privyConfigured) return null;
+
+  const privy = await resolvePrivyCliWallet(env, options);
+  // Unreachable: `privyConfigured` is exactly the condition under which
+  // `resolvePrivyCliWallet` returns non-null or throws. Kept so a future change
+  // to either predicate fails loudly here rather than as a null deref.
+  if (privy === null) return null;
+  return {
+    source: privy.source,
+    account: assertCliSigner(privy.account, privy.source),
+    transport: privy.transport,
+    description: privy.description,
+    readSpendPolicy: privy.readSpendPolicy,
+  };
+}
+
+async function resolveCdpWallet(env: NodeJS.ProcessEnv): Promise<CliWallet> {
+  const missing = CDP_ENV_VARS.filter((name) => !isSet(env[name]));
+  if (missing.length > 0) {
+    throw configError(
+      `the CDP wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`,
+      `a CDP wallet needs all of ${CDP_ENV_VARS.join(", ")}. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others and use ${PRIVATE_KEY_ENV} instead.`,
+    );
+  }
+
+  // A CDP SMART account is an ERC-4337 contract account at a DIFFERENT address
+  // from its owner EOA, and it is reached through a bundler — which this CLI
+  // does not route to: every command broadcasts through `http(--rpc-url)`. So a
+  // smart-account environment would silently sign and spend from the OWNER,
+  // while the user funded the smart account. Refuse instead.
+  if (
+    isSet(env.METRIK_AGENT_CDP_SMART_ACCOUNT_NAME) ||
+    isTruthy(env.METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT)
+  ) {
+    throw configError(
+      "the CLI cannot sign from a CDP smart account: METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT / METRIK_AGENT_CDP_SMART_ACCOUNT_NAME is set",
+      "a CDP smart account is an ERC-4337 account at a different address from its owner, reached through a bundler; this CLI broadcasts through --rpc-url and would spend from the OWNER address instead. Unset those two variables to use the owner account directly, or use the SDK's account-abstraction path.",
+    );
+  }
+
+  const ownerName = env.METRIK_AGENT_CDP_OWNER_NAME as string;
+  let account: Account;
+  try {
+    const resolved = await resolveAgentWallet({
+      cdp: {
+        apiKeyId: env.CDP_API_KEY_ID as string,
+        apiKeySecret: env.CDP_API_KEY_SECRET as string,
+        walletSecret: env.CDP_WALLET_SECRET as string,
+        ownerName,
+      },
+    });
+    account = resolved.account;
+  } catch (error) {
+    // Reaching CDP is a network call against an authenticated API, so this is
+    // where a wrong key, a revoked key or an outage surfaces. Say which wallet
+    // failed; the underlying message carries the rest.
+    throw configError(
+      `could not resolve the CDP wallet "${ownerName}"`,
+      `check ${CDP_ENV_VARS.join(", ")}, and that '@coinbase/cdp-sdk' (an optional peer dependency) is installed. Underlying error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return {
+    source: "cdp",
+    account: assertCliSigner(account, "cdp"),
+    description: `${account.address} (CDP account "${ownerName}")`,
+  };
+}
+
+/**
+ * The raw `METRIK_AGENT_PRIVATE_KEY` read, kept separate so the wallet-source
+ * precedence above reads as one list rather than as nested conditionals.
+ */
+export function optionalCliAccount(
+  env: NodeJS.ProcessEnv,
+): LocalAccount | null {
+  const raw = env[PRIVATE_KEY_ENV];
+  if (raw === undefined || raw.length === 0) return null;
+  if (!/^0x[0-9a-fA-F]{64}$/.test(raw)) {
+    throw configError(
+      `${PRIVATE_KEY_ENV} must be a 0x-prefixed 32-byte hex private key`,
+    );
+  }
+  return privateKeyToAccount(raw as `0x${string}`);
+}
+
+/**
+ * Whether this wallet source broadcasts through the CLI's own
+ * `http(--rpc-url)` transport, and therefore needs an account that can produce
+ * a signed raw transaction by itself.
+ */
+function broadcastsLocally(source: CliWalletSource): boolean {
+  return source === "private-key" || source === "cdp";
+}
+
+/**
+ * Refuses an account that genuinely cannot sign — and nothing else.
+ *
+ * Two distinct capabilities are checked, because two distinct things fail:
+ *
+ *  - `signTypedData` is needed by EVERY command. Fund-moving commands self-sign
+ *    an EIP-712 `SpendMandate`; `invoke` signs an EIP-712
+ *    `InvocationCapability`. Without it the run dies at the first signature
+ *    with a `TypeError` from inside viem.
+ *  - A LOCAL account is needed only where the CLI broadcasts through
+ *    `http(--rpc-url)`, which cannot sign. A Privy account is deliberately NOT
+ *    local: its provider is the transport and performs `eth_sendTransaction`
+ *    itself, so demanding locality there would reject a wallet that works.
+ *
+ * The earlier version of this guard collapsed both into "must be local", which
+ * is why Privy was refused. Deleting the guard outright was not the fix: it
+ * exists so a broken wallet fails here, named, instead of deep inside viem.
+ */
+export function assertCliSigner(
+  account: Account,
+  source: CliWalletSource,
+): CliSignerAccount {
+  if (typeof account.signTypedData !== "function") {
+    throw configError(
+      `the ${source} wallet (${account.address}) cannot sign EIP-712 typed data`,
+      "every command signs typed data: fund-moving commands self-sign a spend mandate, and `invoke` signs an invocation capability.",
+    );
+  }
+  if (broadcastsLocally(source) && account.type !== "local") {
+    throw configError(
+      `the ${source} wallet returned a ${account.type} account, which cannot sign locally`,
+      "this wallet source broadcasts through --rpc-url, which cannot sign, so it needs a local signer.",
+    );
+  }
+  return account as CliSignerAccount;
+}
+
+function isSet(value: string | undefined): boolean {
+  return value !== undefined && value.length > 0;
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return value === "true" || value === "1";
+}

package/src/frameworks/crewai.ts

@@ -23,13 +23,24 @@ export interface CrewAiVerifiedStreamMcpConfigOptions {
   readonly cacheToolsList?: boolean;
 }
 
+/**
+ * The default launcher: the `metrik-mcp` bin this package ships.
+ *
+ * It used to be `pnpm mcp:stdio`, which only resolves INSIDE this repository —
+ * a CrewAI user who installed `@absol-labs/agent` from npm got a config that
+ * could never start. `metrik-mcp` is on `PATH` wherever the package is
+ * installed (npm/pnpm link it into `node_modules/.bin`), and `npx` resolves it
+ * with no install at all.
+ */
+export const CREWAI_DEFAULT_MCP_COMMAND = "metrik-mcp";
+
 export function createCrewAiVerifiedStreamMcpConfig(
   options: CrewAiVerifiedStreamMcpConfigOptions = {},
 ): CrewAiVerifiedStreamMcpConfig {
   return {
     transport: "stdio",
-    command: options.command ?? "pnpm",
-    args: options.args ?? ["mcp:stdio"],
+    command: options.command ?? CREWAI_DEFAULT_MCP_COMMAND,
+    args: options.args ?? [],
     env: options.env ?? {},
     allowedToolNames:
       options.allowedToolNames ?? CREWAI_VERIFIED_STREAM_TOOL_NAMES,

package/src/gateway/caller-auth-gateway.ts

@@ -1,6 +1,13 @@
 import { MetrikClient } from "@absol-labs/sdk";
 import { isAddress, isHex, type Address, type Hex } from "viem";
 
+import {
+  evaluateX402Request,
+  X402_PAYMENT_HEADER,
+  type AcceptedX402Payment,
+  type GatewayX402Mode,
+} from "./x402-mode.js";
+import type { X402PaymentRequiredBody } from "../x402/payment-requirements.js";
 import {
   CAPABILITY_HEADER_NAME,
   decodeCapabilityHeader,
@@ -69,7 +76,21 @@ export type CallerAuthDenialReason =
   | "stream-not-active"
   | "stream-expired"
   | "stream-not-funded"
-  | "stream-state-stale";
+  | "stream-state-stale"
+  /**
+   * No Metrik capability, and x402 mode is enabled: the caller may pay per call
+   * instead. Carries an x402 `402` body in
+   * {@link CallerAuthDecision.x402PaymentRequired}. Emitted ONLY when
+   * {@link CallerAuthGatewayConfig.x402} is configured — without it, a missing
+   * capability is still `missing-capability-header` / `403`, unchanged.
+   */
+  | "x402-payment-required"
+  /**
+   * The request carried BOTH a Metrik capability and an `X-PAYMENT` header.
+   * Refused rather than guessed: serving it would charge the caller through one
+   * path while they believe they paid through the other.
+   */
+  | "ambiguous-payment-mode";
 
 /**
  * Default freshness bound for on-chain stream state, in seconds. Base blocks
@@ -116,11 +137,22 @@ export interface CallerAuthDecision {
   readonly authorized: boolean;
   readonly reason?: CallerAuthDenialReason;
   /** Set only when `authorized === false`. */
-  readonly httpStatus?: 402 | 403;
-  /** Set only when `authorized === true`. */
+  readonly httpStatus?: 400 | 402 | 403;
+  /** Set only when `authorized === true` via the Metrik stream path. */
   readonly stream?: GatewayStreamView;
   /** The decoded (but not necessarily valid) capability, when one was present. */
   readonly capability?: SignedInvocationCapability;
+  /**
+   * The x402 `402` body to return verbatim. Set only with
+   * `reason === "x402-payment-required"`.
+   */
+  readonly x402PaymentRequired?: X402PaymentRequiredBody;
+  /**
+   * A verified x402 payment. Set only when `authorized === true` via the x402
+   * path. The caller MUST settle it (see `./x402-mode.ts`) — verification alone
+   * moves no money.
+   */
+  readonly x402Payment?: AcceptedX402Payment;
 }
 
 /** The minimal on-chain stream fields the gateway needs to authorize a call. */
@@ -316,6 +348,13 @@ export interface CallerAuthGatewayConfig {
   readonly nonceCache?: NonceReplayCache;
   /** Injectable clock (unix seconds), for tests. */
   readonly now?: () => number;
+  /**
+   * Optional standard-x402 mode. When set, a request with NO Metrik capability
+   * gets a real x402 `402` challenge instead of a `403`, so a caller holding
+   * only `x402-fetch` can pay per call. Leaving it unset preserves today's
+   * behaviour byte for byte.
+   */
+  readonly x402?: GatewayX402Mode;
 }
 
 export interface CallerAuthRequestInput {
@@ -341,6 +380,7 @@ export class CallerAuthGateway {
   private readonly domain: InvocationCapabilityDomainInput;
   private readonly serviceRefs: ReadonlySet<string>;
   private readonly now: () => number;
+  private readonly x402: GatewayX402Mode | undefined;
 
   constructor(config: CallerAuthGatewayConfig) {
     if (!isAddress(config.escrowAddress)) {
@@ -397,19 +437,50 @@ export class CallerAuthGateway {
       verifyingContract: config.escrowAddress,
     };
     this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+    this.x402 = config.x402;
   }
 
   async authorize(
     request: CallerAuthRequestInput,
   ): Promise<CallerAuthDecision> {
     const headerValue = lookupHeader(request.headers, this.headerName);
-    if (headerValue === undefined || headerValue.length === 0) {
+    const hasCapabilityHeader =
+      headerValue !== undefined && headerValue.length > 0;
+
+    if (this.x402 !== undefined) {
+      const paymentHeader = lookupHeader(request.headers, X402_PAYMENT_HEADER);
+      const hasPaymentHeader =
+        paymentHeader !== undefined && paymentHeader.trim().length > 0;
+
+      // Exactly one payment mode per request. See `./x402-mode.ts`.
+      if (hasCapabilityHeader && hasPaymentHeader) {
+        return deny("ambiguous-payment-mode", 400);
+      }
+      if (!hasCapabilityHeader) {
+        const evaluated = await evaluateX402Request(
+          { method: request.method, path: request.path },
+          paymentHeader,
+          this.x402,
+        );
+        if (evaluated.outcome === "accepted") {
+          return { authorized: true, x402Payment: evaluated.payment };
+        }
+        return {
+          authorized: false,
+          reason: "x402-payment-required",
+          httpStatus: 402,
+          x402PaymentRequired: evaluated.body,
+        };
+      }
+    }
+
+    if (!hasCapabilityHeader) {
       return deny("missing-capability-header", 403);
     }
 
     let capability: SignedInvocationCapability;
     try {
-      capability = decodeCapabilityHeader(headerValue);
+      capability = decodeCapabilityHeader(headerValue as string);
     } catch (error) {
       if (error instanceof InvalidCapabilityHeaderError) {
         return deny("malformed-capability-header", 403);
@@ -569,7 +640,7 @@ function freshestView(views: readonly GatewayStreamView[]): GatewayStreamView {
 
 function deny(
   reason: CallerAuthDenialReason,
-  httpStatus: 402 | 403,
+  httpStatus: 400 | 402 | 403,
   capability?: SignedInvocationCapability,
 ): CallerAuthDecision {
   return {