@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/wallet.ts

@@ -0,0 +1,241 @@
+import { privateKeyToAccount } from "viem/accounts";
+import type { Account, LocalAccount } from "viem";
+
+import { resolveAgentWallet } from "../wallet/provider.js";
+import { configError } from "./errors.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()`.
+ *
+ * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures every surface the same way. It is checked in a
+ * FIXED order rather than "whichever is configured", because an environment
+ * carrying both is ambiguous about which address funds the stream — and that
+ * ambiguity is a fund-moving one. When both are present the private key wins
+ * and `resolveCliWallet` says so on stderr rather than silently picking.
+ *
+ * ## Why CDP is wired and Privy is not
+ *
+ * CDP is the only wallet path in this package with live CI evidence
+ * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
+ * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
+ * viem local account, so it drops straight into the CLI's existing
+ * `http(rpcUrl)` transport with no other change.
+ *
+ * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
+ * account with no `signTransaction`: they sign and broadcast by sending
+ * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
+ * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
+ * that into the CLI is not a matter of reading three more variables — it
+ * changes the transport for every fund-moving command, and `metrik invoke`
+ * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
+ * `assertLocalSigner` below therefore REFUSES a non-local account with that
+ * fact, instead of accepting one and failing later inside viem. 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;
+
+/**
+ * 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";
+
+export interface CliWallet {
+  readonly source: CliWalletSource;
+  /**
+   * A LOCAL signer. Every CLI path either broadcasts through `http(rpcUrl)`
+   * (which cannot sign) or signs EIP-712 off-chain, so a signer that delegates
+   * to a remote provider is refused at resolution rather than mid-command.
+   */
+  readonly account: LocalAccount;
+  /** One line naming the signer's origin. Safe to print: no secret in it. */
+  readonly description: string;
+}
+
+const WALLET_HINT =
+  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), or configure a Coinbase CDP wallet with ` +
+  `${CDP_ENV_VARS.join(", ")}. Both are read from the environment only — never pass a credential as a command-line flag.`;
+
+/**
+ * Resolves the signing wallet, or throws an actionable configuration error.
+ *
+ * `note` receives one line when the environment is ambiguous (both wallet
+ * sources 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: {
+    readonly purpose?: KeyPurpose;
+    readonly note?: (line: string) => void;
+  } = {},
+): Promise<CliWallet> {
+  const wallet = await optionalCliWallet(env, options);
+  if (wallet === null) {
+    throw configError(
+      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: neither ${PRIVATE_KEY_ENV} nor the CDP variables are set`,
+      WALLET_HINT,
+    );
+  }
+  return wallet;
+}
+
+/**
+ * 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.
+ */
+export async function optionalCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: { readonly note?: (line: string) => void } = {},
+): Promise<CliWallet | null> {
+  const privateKeyAccount = optionalCliAccount(env);
+  const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+
+  if (privateKeyAccount !== null) {
+    if (cdpConfigured) {
+      options.note?.(
+        `warning: both ${PRIVATE_KEY_ENV} and CDP wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the CDP wallet.`,
+      );
+    }
+    return {
+      source: "private-key",
+      account: privateKeyAccount,
+      description: `${privateKeyAccount.address} (from ${PRIVATE_KEY_ENV})`,
+    };
+  }
+
+  if (!cdpConfigured) return null;
+
+  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: assertLocalSigner(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}`);
+}
+
+/**
+ * Every CLI signing path needs a LOCAL signer: fund-moving commands broadcast
+ * through `http(--rpc-url)`, which cannot sign, and `invoke` needs a
+ * `LocalAccount` to sign the EIP-712 capability. A JSON-RPC account (Privy's
+ * adapters) would type-check as an `Account` and then fail somewhere inside
+ * viem with a message about a missing method, so it is rejected here with the
+ * actual reason.
+ */
+function assertLocalSigner(
+  account: Account,
+  source: CliWalletSource,
+): LocalAccount {
+  if (account.type === "local") return account;
+  throw configError(
+    `the ${source} wallet returned a ${account.type} account, which cannot sign locally`,
+    "the CLI broadcasts through --rpc-url and signs EIP-712 capabilities in-process, so it needs a local signer.",
+  );
+}
+
+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/server-entry.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startCallerAuthGatewayServerFromEnv } from "./http-server.js";
 
 /**

package/src/mcp/http-server.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startHostedMcpHttpServerFromEnv } from "./http.js";
 
 /**

package/src/mcp/server.ts

@@ -799,10 +799,34 @@ export function createVerifiedStreamMcpServer(
   };
 }
 
+/** One readable line per invalid or missing environment variable. */
+function describeEnvIssues(error: z.ZodError): string {
+  const seen = new Set<string>();
+  for (const issue of error.issues) {
+    const name = issue.path.join(".");
+    seen.add(
+      issue.code === "invalid_type" && issue.received === "undefined"
+        ? `${name} is not set`
+        : `${name} is invalid (${issue.message})`,
+    );
+  }
+  return [...seen].join("; ");
+}
+
 export function parseMetrikAgentEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): ParsedMetrikAgentEnv {
-  const parsed = metrikAgentEnvSchema.parse(env);
+  const result = metrikAgentEnvSchema.safeParse(env);
+  if (!result.success) {
+    // `.parse()` threw a ZodError whose message is a JSON array of issue
+    // objects. `metrik-mcp` is started by an MCP host and fails closed on stdio,
+    // so that array was the ONLY thing an operator ever saw — a correct failure
+    // rendered as noise. Name the variables instead.
+    throw new Error(
+      `metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP/Privy variables). METRIK_AGENT_CHAIN_ID defaults to Base Sepolia (${baseSepolia.id}).`,
+    );
+  }
+  const parsed = result.data;
   const chainId = Number(parsed.METRIK_AGENT_CHAIN_ID ?? baseSepolia.id);
   if (!Number.isInteger(chainId) || chainId <= 0) {
     throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");

package/src/mcp/stdio.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startVerifiedStreamMcpServerStdio } from "./server.js";
 
 startVerifiedStreamMcpServerStdio().catch((error) => {

package/src/sdk/client.ts

@@ -89,6 +89,16 @@ export interface AgentSdkClient {
   claim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   close(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   reclaim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  /**
+   * The BUYER's no-proof escape hatch. Every other buyer path to the money
+   * (`reclaim` -> `reclaimWithProof`) needs a Merkle proof fetched from the
+   * oracle, so it is only as available as the oracle is. `reclaimUnverified`
+   * takes no proof, no quorum and no guardian — it is the path that exists
+   * precisely for the case where that dependency has failed.
+   */
+  reclaimUnverified(
+    streamId: `0x${string}`,
+  ): Promise<StreamProofTransactionResult>;
 }
 
 export type AgentSdkClientFactory = (
@@ -201,7 +211,29 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
   }
 
   /**
-   * Authorizes a BUYER-RECOVERY action (close / reclaim). These only return
+   * Buyer-only escape hatch: reclaim WITHOUT a checkpoint proof, available only
+   * once `block.timestamp >= expiresAt + escapeGraceSeconds` on the escrow.
+   *
+   * Authorized exactly like `close` / `reclaim` — on the mandate owner's
+   * signature alone (see {@link authorizeBuyerRecovery}) — because it only
+   * returns the buyer's own unspent escrow. It is a SEPARATE method rather than
+   * an option on {@link reclaimStream} because it is not an alternative route to
+   * the same outcome: `reclaimUnverified` pays the buyer
+   * `deposit - claimedCumulative` and permanently forfeits every operator
+   * voucher that was earned but not yet redeemed on-chain.
+   *
+   * Takes no `closeFirst`: the escrow gates this path on `expiresAt`, never on
+   * `closedAt`, so closing first would buy nothing but a second gas fee.
+   */
+  async reclaimUnverifiedStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    await this.authorizeBuyerRecovery(input);
+    return await this.sdkClient.reclaimUnverified(input.streamId);
+  }
+
+  /**
+   * Authorizes a BUYER-RECOVERY action (close / reclaim / reclaimUnverified). These only return
    * unspent funds to the buyer or stop payment, so they are authorized on
    * mandate-owner signature ALONE — never gated by expiry, revocation, or caps,
    * which would otherwise let a lapsed mandate strand the buyer's own funds.