@absol-labs/agent 0.10.0 → 0.11.0

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@absol-labs/agent",
-  "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.",
+  "version": "0.11.0",
+  "description": "Metrik agent layer: verified-streaming USDC payments metered by delivery, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
   "keywords": [
     "metrik",
-    "x402",
     "mcp",
     "ai-agents",
     "spend-mandate",
@@ -21,7 +20,8 @@
     "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"
+    "metrik-gateway": "dist/gateway/server-entry.js",
+    "metrik-x402-facilitator": "dist/x402/facilitator-server-entry.js"
   },
   "exports": {
     ".": {
@@ -48,6 +48,10 @@
       "types": "./dist/frameworks/crewai.d.ts",
       "import": "./dist/frameworks/crewai.js"
     },
+    "./x402-facilitator": {
+      "types": "./dist/x402/facilitator-server.d.ts",
+      "import": "./dist/x402/facilitator-server.js"
+    },
     "./package.json": "./package.json",
     "./*": {
       "types": "./dist/*.d.ts",
@@ -92,7 +96,8 @@
     "@elizaos/core": "^1.7.2",
     "@langchain/core": "^1.2.0",
     "@reclaimprotocol/js-sdk": "^5.6.0",
-    "@reclaimprotocol/zk-fetch": "^1.0.0"
+    "@reclaimprotocol/zk-fetch": "^1.0.0",
+    "x402": "^1.2.0"
   },
   "peerDependenciesMeta": {
     "@coinbase/agentkit": {
@@ -112,6 +117,9 @@
     },
     "@reclaimprotocol/zk-fetch": {
       "optional": true
+    },
+    "x402": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -126,7 +134,9 @@
     "prettier": "^3.4.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^2.1.0",
+    "x402": "1.2.0",
+    "x402-fetch": "1.2.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -144,6 +154,7 @@
     "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 ."
+    "format": "prettier --write .",
+    "x402:facilitator": "tsx src/x402/facilitator-server-entry.ts"
   }
 }

package/src/capability/invocation-capability.ts

@@ -172,11 +172,27 @@ export function buildInvocationCapabilityTypedData(
   };
 }
 
+/**
+ * The minimum an account must expose to sign a capability: its address, and
+ * EIP-712 signing.
+ *
+ * Deliberately narrower than viem's `LocalAccount`. Every wallet this package
+ * resolves signs typed data — a raw key, a CDP server account via `toAccount()`,
+ * a Privy embedded EOA — but only the raw-key one is a `LocalAccount` by TYPE.
+ * Demanding the full interface would have meant the MCP server could only ever
+ * invoke with a raw key, which is the wallet an MCP host is least likely to be
+ * configured with. Widening a parameter type breaks no existing caller.
+ */
+export type InvocationCapabilitySigner = Pick<
+  LocalAccount,
+  "address" | "signTypedData"
+>;
+
 /** Signs an `InvocationCapability` with the buyer's own wallet. */
 export async function signInvocationCapability(
   capability: InvocationCapability,
   domain: InvocationCapabilityDomainInput,
-  account: LocalAccount,
+  account: InvocationCapabilitySigner,
 ): Promise<Hex> {
   const typedData = buildInvocationCapabilityTypedData(capability, domain);
   return account.signTypedData(typedData);

package/src/cli/commands/claim.ts

@@ -3,7 +3,12 @@ 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 { writeClientOptions } from "../deps.js";
+import {
+  isPolicyEnforced,
+  PRIVATE_KEY_ENV,
+  resolveCliWallet,
+} from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
 /**
@@ -30,7 +35,21 @@ export const claimCommand: CommandSpec = {
     }
     const streamId = parseBytes32(streamIdArg, "<streamId>");
 
-    const { account } = await resolveCliWallet(env, { note: out.note });
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    const { account } = wallet;
+    if (isPolicyEnforced(wallet)) {
+      // Said plainly rather than discovered mid-command. `claim` is the
+      // OPERATOR's side, and a Privy broker policy allowlists the BUYER
+      // actions only (openStream, close, reclaim, reclaimUnverified, and a
+      // bounded USDC approval). That is a property of an operator using a
+      // buyer-scoped wallet, not a defect in this command.
+      out.note(
+        "warning: this wallet's broker policy allowlists buyer actions only, so it will refuse to sign an operator claim. Claim with the operator's own key.",
+      );
+    }
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
     await assertCanPayGas(read, account.address);
@@ -74,10 +93,17 @@ export const claimCommand: CommandSpec = {
       });
     }
 
-    const write = deps.createWriteClient(config, account);
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
     const result = await write.claimStream({
       streamId,
-      signedMandate: await signClaimMandate(account, config.chainId),
+      // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
+      signedMandate: isPolicyEnforced(wallet)
+        ? null
+        : await signClaimMandate(account, config.chainId),
       spentSoFarUsdc: 0n,
       nowSeconds: deps.nowSeconds(),
     });

package/src/cli/commands/close.ts

@@ -2,7 +2,8 @@ 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 { writeClientOptions } from "../deps.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 
 export const closeCommand: CommandSpec = {
@@ -19,13 +20,28 @@ export const closeCommand: CommandSpec = {
     }
     const streamId = parseBytes32(streamIdArg, "<streamId>");
 
-    const { account } = await resolveCliWallet(env, { note: out.note });
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    const { account } = wallet;
     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);
+    // A policy-enforced wallet signs no mandate of its own: this is a
+    // buyer-recovery action, the escrow gates it on the buyer address and the
+    // broker gates it again on `stream.buyer == wallet`. A locally self-signed
+    // placeholder would add nothing and the broker would refuse to sign it.
+    // See `../spend-policy.ts`.
+    const signedMandate = isPolicyEnforced(wallet)
+      ? null
+      : await signRecoveryMandate(account, config.chainId);
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
     const result = await write.closeStream({
       streamId,
       signedMandate,

package/src/cli/commands/invoke.ts

@@ -61,6 +61,7 @@ export const invokeCommand: CommandSpec = {
     const { account } = await resolveCliWallet(env, {
       purpose: "capability",
       note: out.note,
+      rpcUrl: config.rpcUrl,
     });
     const read = deps.createReadClient(config);
     // No transaction is signed here — but the capability is bound to

package/src/cli/commands/open.ts

@@ -8,10 +8,17 @@ import {
   parseUsdcAmount,
 } from "../amounts.js";
 import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { writeClientOptions } from "../deps.js";
 import { CliError, configError } from "../errors.js";
+import type { PrivySpendPolicy } from "../privy.js";
+import {
+  assertWithinOperatorCaps,
+  assertWithinSpendPolicy,
+} from "../spend-policy.js";
 import { cliMandateCaps, signCliMandate } from "../mandate.js";
 import { assertCanFundStream, assertCanPayGas } from "../preflight.js";
 import {
+  isPolicyEnforced,
   optionalCliWallet,
   resolveCliWallet,
   PRIVATE_KEY_ENV,
@@ -74,8 +81,8 @@ export const openCommand: CommandSpec = {
     // the intended call and says which parts (allowance, simulation, mandate
     // signature) could not be produced, rather than inventing them.
     const wallet = dryRun
-      ? await optionalCliWallet(env, { note: out.note })
-      : await resolveCliWallet(env, { note: out.note });
+      ? await optionalCliWallet(env, { note: out.note, rpcUrl: config.rpcUrl })
+      : await resolveCliWallet(env, { note: out.note, rpcUrl: config.rpcUrl });
     const account = wallet?.account ?? null;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
@@ -101,16 +108,41 @@ export const openCommand: CommandSpec = {
     }
 
     const spend = { operator, budgetUsdc, ratePerSecondUsdc, durationSeconds };
+    const mandateCaps = cliMandateCaps(spend, env);
+
+    // A policy-enforced wallet (Privy) is capped by its broker, not by a
+    // mandate this process signs for itself. Read the REAL ceiling and hold it
+    // to that instead — see `../spend-policy.ts` for why that substitution is
+    // the stronger of the two, and why re-adding the self-signed mandate here
+    // would both weaken it and break the wallet outright.
+    const policy: PrivySpendPolicy | null =
+      wallet !== null && isPolicyEnforced(wallet)
+        ? await wallet.readSpendPolicy()
+        : null;
+    if (policy !== null && !dryRun) {
+      assertWithinSpendPolicy(policy, spend);
+      // The operator's own standing ceiling still applies, and may be TIGHTER
+      // than the broker's. Enforced here because no mandate is signed to carry
+      // it — "policy-enforced" retires the self-signed mandate, not the caps
+      // the operator deliberately configured.
+      if (mandateCaps.source === "env") {
+        assertWithinOperatorCaps(mandateCaps.caps, spend);
+      }
+    }
+
     const mandate =
-      account === null
+      account === null || policy !== null
         ? null
         : await signCliMandate(account, spend, {
             chainId: config.chainId,
             env,
           });
-    const mandateCaps = cliMandateCaps(spend, env);
 
-    const write = deps.createWriteClient(config, account);
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
     const hire = {
       operator,
       serviceRef,
@@ -145,6 +177,19 @@ export const openCommand: CommandSpec = {
         durationSeconds,
         mandateSource: mandateCaps.source,
         mandateSigned: mandate !== null,
+        spendPolicy:
+          policy === null
+            ? null
+            : {
+                brokerUrl: policy.brokerUrl,
+                maxTotalUsdc: policy.maxTotalUsdc,
+                maxRatePerSecondUsdc: policy.maxRatePerSecondUsdc,
+                maxDurationSeconds: policy.maxDurationSeconds,
+                fits:
+                  budgetUsdc <= policy.maxTotalUsdc &&
+                  ratePerSecondUsdc <= policy.maxRatePerSecondUsdc &&
+                  durationSeconds <= policy.maxDurationSeconds,
+              },
         to: preview.to,
         data: preview.data,
         chainId: preview.chainId,
@@ -180,10 +225,28 @@ export const openCommand: CommandSpec = {
         ["duration", formatDuration(durationSeconds)],
         [
           "mandate",
-          mandate === null
-            ? `not signed (no wallet); caps would come from ${mandateCaps.source}`
-            : `self-signed, caps from ${mandateCaps.source}`,
+          mandate !== null
+            ? `self-signed, caps from ${mandateCaps.source}`
+            : policy !== null
+              ? "not signed — this wallet's ceiling is enforced by its broker, which is stronger"
+              : `not signed (no wallet); caps would come from ${mandateCaps.source}`,
         ],
+        ...(policy === null
+          ? []
+          : ([
+              [
+                "spend policy",
+                `${formatUsdc(policy.maxTotalUsdc)} total, ${policy.maxRatePerSecondUsdc} atomic/second, ${formatDuration(policy.maxDurationSeconds)} max — enforced by ${policy.brokerUrl}`,
+              ],
+              [
+                "fits policy",
+                budgetUsdc <= policy.maxTotalUsdc &&
+                ratePerSecondUsdc <= policy.maxRatePerSecondUsdc &&
+                durationSeconds <= policy.maxDurationSeconds
+                  ? "yes"
+                  : "NO — a real open would be refused before broadcasting",
+              ],
+            ] as [string, string][])),
         ["escrow", preview.to],
         [
           "usdc balance",
@@ -219,7 +282,7 @@ export const openCommand: CommandSpec = {
     );
     // Unreachable without a wallet: `resolveCliWallet` above throws when the
     // command is not a dry run. The narrowing keeps that a type-level fact.
-    if (account === null || mandate === null) {
+    if (account === null) {
       throw configError(
         "this command signs a transaction and needs a wallet, and none was resolved",
       );
@@ -233,7 +296,10 @@ export const openCommand: CommandSpec = {
         budgetUsdc,
         ratePerSecondUsdc,
         maxDurationSeconds: durationSeconds,
-        signedMandate: mandate.signed,
+        // `null` for a policy-enforced wallet: the ceiling was checked against
+        // the broker's own policy above, and the broker checks it again on the
+        // transaction it signs.
+        signedMandate: mandate === null ? null : mandate.signed,
         spentSoFarUsdc: 0n,
         nowSeconds: deps.nowSeconds(),
       });

package/src/cli/commands/reclaim-unverified.ts

@@ -10,7 +10,8 @@ import {
 } from "../escape-hatch.js";
 import { signRecoveryMandate } from "../mandate.js";
 import { assertCanPayGas } from "../preflight.js";
-import { resolveCliWallet } from "../wallet.js";
+import { writeClientOptions } from "../deps.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient } from "../deps.js";
 
@@ -80,7 +81,11 @@ export const reclaimUnverifiedCommand: CommandSpec = {
       );
     }
 
-    const { account } = await resolveCliWallet(env, { note: out.note });
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
     await assertCanPayGas(read, account.address);
@@ -120,10 +125,17 @@ export const reclaimUnverifiedCommand: CommandSpec = {
     );
     out.note("");
 
-    const write = deps.createWriteClient(config, account);
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
     const result = await write.reclaimUnverifiedStream({
       streamId,
-      signedMandate: await signRecoveryMandate(account, config.chainId),
+      // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
+      signedMandate: isPolicyEnforced(wallet)
+        ? null
+        : await signRecoveryMandate(account, config.chainId),
       spentSoFarUsdc: 0n,
       nowSeconds: deps.nowSeconds(),
     });

package/src/cli/commands/reclaim.ts

@@ -11,7 +11,8 @@ import {
 } from "../escape-hatch.js";
 import { signRecoveryMandate } from "../mandate.js";
 import { assertCanPayGas } from "../preflight.js";
-import { resolveCliWallet } from "../wallet.js";
+import { writeClientOptions } from "../deps.js";
+import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient, CliWriteClient } from "../deps.js";
 import type {
@@ -48,12 +49,28 @@ export const reclaimCommand: CommandSpec = {
     if (attempts < 1) throw usageError("--attempts must be at least 1");
     if (interval < 1) throw usageError("--interval must be at least 1 second");
 
-    const { account } = await resolveCliWallet(env, { note: out.note });
+    const wallet = await resolveCliWallet(env, {
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
     await assertCanPayGas(read, account.address);
 
-    const write = deps.createWriteClient(config, account);
+    const write = deps.createWriteClient(
+      config,
+      account,
+      writeClientOptions(wallet),
+    );
+
+    // A policy-enforced wallet (Privy) signs no mandate of its own: these are
+    // buyer-recovery actions, gated by the escrow on the buyer address and by
+    // the broker on `stream.buyer == wallet`. See `../spend-policy.ts`.
+    const recoveryMandate = async () =>
+      isPolicyEnforced(wallet)
+        ? null
+        : await signRecoveryMandate(account, config.chainId);
 
     // `--close-first` is TWO transactions, and the second one only simulates
     // successfully against post-close state. Sequencing them inside a single SDK
@@ -75,7 +92,7 @@ export const reclaimCommand: CommandSpec = {
       } else {
         closeResult = await closeBeforeReclaim(write, {
           streamId,
-          signedMandate: await signRecoveryMandate(account, config.chainId),
+          signedMandate: await recoveryMandate(),
           spentSoFarUsdc: 0n,
           nowSeconds: deps.nowSeconds(),
         });
@@ -97,7 +114,7 @@ export const reclaimCommand: CommandSpec = {
       write,
       async () => ({
         streamId,
-        signedMandate: await signRecoveryMandate(account, config.chainId),
+        signedMandate: await recoveryMandate(),
         spentSoFarUsdc: 0n,
         nowSeconds: deps.nowSeconds(),
       }),

package/src/cli/commands/streams.ts

@@ -234,7 +234,7 @@ async function resolveScanAddress(
   if (wallet === null) {
     throw configError(
       "metrik streams needs a wallet to know whose streams to list",
-      `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP variables).`,
+      `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP or Privy variables).`,
     );
   }
   return wallet.account.address;