@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.11.0",
+  "version": "0.12.0-rc.2",
   "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",
@@ -21,7 +21,7 @@
     "metrik-mcp": "dist/mcp/stdio.js",
     "metrik-mcp-http": "dist/mcp/http-server.js",
     "metrik-gateway": "dist/gateway/server-entry.js",
-    "metrik-x402-facilitator": "dist/x402/facilitator-server-entry.js"
+    "metrik-x402-opener-facilitator": "dist/x402-opener/facilitator-entry.js"
   },
   "exports": {
     ".": {
@@ -48,9 +48,13 @@
       "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"
+    "./x402-opener": {
+      "types": "./dist/x402-opener/index.d.ts",
+      "import": "./dist/x402-opener/index.js"
+    },
+    "./x402-buyer": {
+      "types": "./dist/x402-buyer/index.d.ts",
+      "import": "./dist/x402-buyer/index.js"
     },
     "./package.json": "./package.json",
     "./*": {
@@ -81,11 +85,13 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.9.2",
-    "@absol-labs/shared": "^0.13.1",
+    "@absol-labs/sdk": "0.10.0-rc.3",
+    "@absol-labs/shared": "0.14.0-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",
     "@privy-io/node": "0.33.0",
+    "@x402/core": "2.27.0",
+    "@x402/evm": "2.27.0",
     "reflect-metadata": "^0.2.2",
     "viem": "^2.21.0",
     "zod": "^3.24.0"
@@ -96,8 +102,7 @@
     "@elizaos/core": "^1.7.2",
     "@langchain/core": "^1.2.0",
     "@reclaimprotocol/js-sdk": "^5.6.0",
-    "@reclaimprotocol/zk-fetch": "^1.0.0",
-    "x402": "^1.2.0"
+    "@reclaimprotocol/zk-fetch": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@coinbase/agentkit": {
@@ -117,9 +122,6 @@
     },
     "@reclaimprotocol/zk-fetch": {
       "optional": true
-    },
-    "x402": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -131,12 +133,11 @@
     "@reclaimprotocol/zk-fetch": "^1.0.0",
     "@swc/core": "^1.10.0",
     "@types/node": "^20.17.0",
+    "@x402/fetch": "2.27.0",
     "prettier": "^3.4.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0",
-    "x402": "1.2.0",
-    "x402-fetch": "1.2.0"
+    "vitest": "^2.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -145,7 +146,9 @@
     "mcp:stdio": "tsx src/mcp/stdio.ts",
     "mcp:http": "tsx src/mcp/http-server.ts",
     "gateway": "tsx src/gateway/server-entry.ts",
+    "x402-opener:facilitator": "tsx src/x402-opener/facilitator-entry.ts",
     "e2e:cdp": "node dist-e2e/scripts/e2e-cdp.js",
+    "e2e:x402": "node dist-e2e/scripts/e2e-x402.js",
     "e2e:hire": "tsx scripts/e2e-hire.ts",
     "l2:proof": "node scripts/l2-proof.mjs",
     "test": "vitest run",
@@ -154,7 +157,6 @@
     "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 .",
-    "x402:facilitator": "tsx src/x402/facilitator-server-entry.ts"
+    "format": "prettier --write ."
   }
 }

package/src/capability/probe-capability.ts

@@ -0,0 +1,355 @@
+import { randomBytes } from "node:crypto";
+
+import {
+  getAddress,
+  isAddress,
+  isHex,
+  recoverTypedDataAddress,
+  type Address,
+  type Hex,
+  type LocalAccount,
+} from "viem";
+import { z } from "zod";
+
+import {
+  hashInvocationPath,
+  httpMethodSchema,
+  normalizeInvocationPath,
+} from "./invocation-capability.js";
+
+/**
+ * `ProbeCapability` — the ORACLE-signed EIP-712 credential that lets the
+ * neutral verifier exercise the PAID route of a `gated` listing.
+ *
+ * ## The gap this closes
+ *
+ * A gated listing's paid route requires an `InvocationCapability` signed by the
+ * stream's BUYER (see `./invocation-capability.ts`). The oracle is not a buyer
+ * and holds no buyer key, so before this type existed the oracle could only
+ * probe a gated service's HEALTH route. "The seller earns only for intervals
+ * that verified" therefore meant "the health endpoint answered" — not "the paid
+ * route delivered". This capability is the missing credential.
+ *
+ * ## Why this is not just "give the workers a credential"
+ *
+ * Three properties, all load-bearing:
+ *
+ * 1. **No shared secret.** Authority is an EIP-712 signature by an address in
+ *    the escrow's `getOracleSigners()`. That list is PUBLICLY READABLE on-chain,
+ *    so a third-party seller performs the identical check with no credential
+ *    distribution, no registration, and nothing for either side to leak.
+ * 2. **No signing key leaves the coordinator.** The oracle coordinator mints one
+ *    fresh capability per probe and hands the encoded header to the regional
+ *    worker. A worker holds a bearer token for the coordinator and nothing else;
+ *    compromising every worker yields no ability to mint a capability.
+ * 3. **Not stream-bound.** Deliberately carries NO `streamId` and NO `buyer`.
+ *    That is what makes the same mechanism usable to probe a listing that has no
+ *    stream at all — and it is also the structural guarantee that a probe can
+ *    never consume a buyer's budget: there is no stream for it to be billed
+ *    against. Accrual is only ever produced by an oracle checkpoint keyed to a
+ *    stream; a gateway call produces none.
+ *
+ * ## What a probe is NOT
+ *
+ * A probe is verification, not delivery to a buyer. A gateway authorizing one
+ * MUST NOT meter it, settle any payment for it, or count it as a paid call.
+ * The reference gateway enforces this structurally (see
+ * `../gateway/caller-auth-gateway.ts`) and marks the upstream request with
+ * {@link PROBE_MARKER_HEADER_NAME} so a seller's own metering can exclude it.
+ *
+ * ## Honest note for third-party sellers
+ *
+ * This CHANGES what a seller's gateway must implement to get paid-route
+ * verification. A gated listing fronted by a gateway that has not adopted
+ * `ProbeCapability` stays HEALTH-ROUTE-ONLY, and the oracle reports it as
+ * unverifiable rather than passing. Adoption is the seller's choice; silence
+ * about it is not the oracle's.
+ *
+ * Kept LOCAL to `@absol-labs/agent` for the same reason as
+ * `InvocationCapability`: no contract parses it, so there is no on-chain byte
+ * compatibility requirement. Cross-repo compatibility with the oracle's minter
+ * is pinned by a shared digest test vector — see
+ * `test/probe-capability.test.ts` and the oracle's mirror of the same constant.
+ */
+
+const addressSchema = z
+  .string()
+  .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 66,
+    "must be bytes32 hex",
+  );
+const signatureSchema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 132,
+    "must be a 65-byte signature",
+  );
+
+export const probeCapabilitySchema = z.object({
+  /**
+   * The service being probed. Must match the target gateway's configured
+   * `serviceRef`. There is deliberately no `streamId` field — see the class
+   * docs.
+   */
+  serviceRef: bytes32Schema,
+  /**
+   * The minting oracle signer. Must equal the EIP-712 signer AND be a member of
+   * the escrow's on-chain `getOracleSigners()` set at verification time.
+   */
+  oracle: addressSchema,
+  /** The single HTTP method this capability authorizes. */
+  method: httpMethodSchema,
+  /** `keccak256` of the exact request path this capability authorizes. */
+  pathHash: bytes32Schema,
+  /** Single-use anti-replay nonce. */
+  nonce: bytes32Schema,
+  /** Unix seconds after which the capability is no longer valid. */
+  expiry: z.number().int().positive(),
+});
+export type ProbeCapability = z.infer<typeof probeCapabilitySchema>;
+
+export const signedProbeCapabilitySchema = probeCapabilitySchema.extend({
+  signature: signatureSchema,
+});
+export type SignedProbeCapability = z.infer<typeof signedProbeCapabilitySchema>;
+
+/**
+ * Chain-bound domain. `verifyingContract` is the `StreamEscrowV2` whose
+ * `getOracleSigners()` defines who may mint — so a capability minted for one
+ * escrow can never authorize a probe against a gateway fronting another.
+ */
+export interface ProbeCapabilityDomainInput {
+  readonly chainId: number;
+  readonly verifyingContract: Address;
+}
+
+/**
+ * Distinct from `Metrik Invocation Capability`, so a buyer's invocation
+ * signature can never be replayed as a probe (or the reverse) even though both
+ * share a chainId and verifying contract.
+ */
+export const probeCapabilityDomainName = "Metrik Probe Capability" as const;
+export const probeCapabilityDomainVersion = "1" as const;
+
+export const probeCapabilityTypedData = {
+  ProbeCapability: [
+    { name: "serviceRef", type: "bytes32" },
+    { name: "oracle", type: "address" },
+    { name: "method", type: "string" },
+    { name: "pathHash", type: "bytes32" },
+    { name: "nonce", type: "bytes32" },
+    { name: "expiry", type: "uint64" },
+  ],
+} as const;
+
+/**
+ * Default lifetime of a freshly-minted probe capability, in seconds.
+ *
+ * Shorter than the ~15-22s checkpoint cadence would race a slow upstream; much
+ * longer would widen the window in which a captured capability is replayable
+ * against a gateway with no nonce cache. 30s is one to two probe intervals.
+ */
+export const DEFAULT_PROBE_CAPABILITY_TTL_SECONDS = 30;
+
+/** Header a probe request carries the signed capability in. */
+export const PROBE_CAPABILITY_HEADER_NAME = "x-metrik-probe-capability";
+
+/**
+ * Header the gateway adds to the UPSTREAM request when it authorized a probe.
+ * Advisory: it exists so a seller's own metering/analytics can exclude
+ * verification traffic from billable usage.
+ */
+export const PROBE_MARKER_HEADER_NAME = "x-metrik-probe";
+
+export function createProbeCapabilityEip712Domain(
+  domain: ProbeCapabilityDomainInput,
+) {
+  return {
+    name: probeCapabilityDomainName,
+    version: probeCapabilityDomainVersion,
+    chainId: domain.chainId,
+    verifyingContract: getAddress(domain.verifyingContract),
+  } as const;
+}
+
+/**
+ * `keccak256` of the exact request path this capability authorizes. Shares the
+ * canonical form with `InvocationCapability` so both sides of a gateway hash
+ * paths identically.
+ */
+export function hashProbePath(path: string): Hex {
+  return hashInvocationPath(path);
+}
+
+/** Re-exported for symmetry; identical canonicalization to the invocation path. */
+export function normalizeProbePath(path: string): string {
+  return normalizeInvocationPath(path);
+}
+
+function probeCapabilityMessage(capability: ProbeCapability) {
+  const parsed = probeCapabilitySchema.parse(capability);
+  return {
+    serviceRef: parsed.serviceRef as Hex,
+    oracle: getAddress(parsed.oracle),
+    method: parsed.method,
+    pathHash: parsed.pathHash as Hex,
+    nonce: parsed.nonce as Hex,
+    expiry: BigInt(parsed.expiry),
+  };
+}
+
+export function buildProbeCapabilityTypedData(
+  capability: ProbeCapability,
+  domain: ProbeCapabilityDomainInput,
+) {
+  return {
+    domain: createProbeCapabilityEip712Domain(domain),
+    types: probeCapabilityTypedData,
+    primaryType: "ProbeCapability" as const,
+    message: probeCapabilityMessage(capability),
+  };
+}
+
+/** The minimum an oracle signer must expose to mint a probe capability. */
+export type ProbeCapabilitySigner = Pick<
+  LocalAccount,
+  "address" | "signTypedData"
+>;
+
+/** Signs a `ProbeCapability` with an oracle signer's own key. */
+export async function signProbeCapability(
+  capability: ProbeCapability,
+  domain: ProbeCapabilityDomainInput,
+  account: ProbeCapabilitySigner,
+): Promise<Hex> {
+  const typedData = buildProbeCapabilityTypedData(capability, domain);
+  return account.signTypedData(typedData);
+}
+
+/** Recovers the EIP-712 signer of a probe capability. Throws on a malformed signature. */
+export async function recoverProbeCapabilitySigner(
+  capability: ProbeCapability,
+  domain: ProbeCapabilityDomainInput,
+  signature: Hex,
+): Promise<Address> {
+  const typedData = buildProbeCapabilityTypedData(capability, domain);
+  return recoverTypedDataAddress({ ...typedData, signature });
+}
+
+/** Cryptographically random 32-byte single-use nonce. */
+export function generateProbeNonce(): Hex {
+  return `0x${randomBytes(32).toString("hex")}` as Hex;
+}
+
+export class InvalidProbeCapabilityHeaderError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "InvalidProbeCapabilityHeaderError";
+  }
+}
+
+/** Encodes a signed probe capability as an opaque, header-safe (base64url) string. */
+export function encodeProbeCapabilityHeader(
+  signed: SignedProbeCapability,
+): string {
+  const parsed = signedProbeCapabilitySchema.parse(signed);
+  const json = JSON.stringify({
+    serviceRef: parsed.serviceRef,
+    oracle: parsed.oracle,
+    method: parsed.method,
+    pathHash: parsed.pathHash,
+    nonce: parsed.nonce,
+    expiry: parsed.expiry,
+    signature: parsed.signature,
+  });
+  return Buffer.from(json, "utf8").toString("base64url");
+}
+
+/** Decodes and schema-validates a probe capability header. Fails closed on any malformation. */
+export function decodeProbeCapabilityHeader(
+  headerValue: string,
+): SignedProbeCapability {
+  let json: string;
+  try {
+    json = Buffer.from(headerValue, "base64url").toString("utf8");
+  } catch (cause) {
+    throw new InvalidProbeCapabilityHeaderError(
+      "malformed base64 probe capability header",
+      { cause },
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (cause) {
+    throw new InvalidProbeCapabilityHeaderError(
+      "malformed JSON probe capability header",
+      { cause },
+    );
+  }
+
+  const result = signedProbeCapabilitySchema.safeParse(raw);
+  if (!result.success) {
+    throw new InvalidProbeCapabilityHeaderError(
+      `invalid probe capability shape: ${result.error.message}`,
+    );
+  }
+  return result.data;
+}
+
+export interface MintProbeCapabilityOptions {
+  readonly serviceRef: Hex;
+  readonly method: ProbeCapability["method"];
+  /** The exact request path to be probed (query/fragment are stripped). */
+  readonly path: string;
+  readonly domain: ProbeCapabilityDomainInput;
+  readonly account: ProbeCapabilitySigner;
+  readonly ttlSeconds?: number;
+  /** Injectable clock (unix seconds), for tests. */
+  readonly now?: () => number;
+  /** Injectable nonce source, for tests. */
+  readonly nonce?: () => Hex;
+}
+
+/**
+ * Mint one fresh, single-use, short-lived probe capability and return its
+ * encoded header value. Called once PER PROBE PER VANTAGE by the coordinator:
+ * the gateway's replay cache is single-use, so two vantages sharing one
+ * capability would see the second rejected as a replay.
+ */
+export async function mintProbeCapabilityHeader(
+  options: MintProbeCapabilityOptions,
+): Promise<{
+  readonly headerName: string;
+  readonly headerValue: string;
+  readonly capability: SignedProbeCapability;
+}> {
+  const nowSeconds = (options.now ?? (() => Math.floor(Date.now() / 1000)))();
+  const ttl = options.ttlSeconds ?? DEFAULT_PROBE_CAPABILITY_TTL_SECONDS;
+  if (!Number.isInteger(ttl) || ttl <= 0) {
+    throw new Error("probe capability ttlSeconds must be a positive integer");
+  }
+  const capability: ProbeCapability = {
+    serviceRef: options.serviceRef,
+    oracle: getAddress(options.account.address),
+    method: options.method,
+    pathHash: hashProbePath(options.path),
+    nonce: (options.nonce ?? generateProbeNonce)(),
+    expiry: nowSeconds + ttl,
+  };
+  const signature = await signProbeCapability(
+    capability,
+    options.domain,
+    options.account,
+  );
+  const signed: SignedProbeCapability = { ...capability, signature };
+  return {
+    headerName: PROBE_CAPABILITY_HEADER_NAME,
+    headerValue: encodeProbeCapabilityHeader(signed),
+    capability: signed,
+  };
+}

package/src/cli/args.ts

@@ -117,6 +117,35 @@ export function booleanFlag(args: ParsedArgs, name: string): boolean {
   throw usageError(`--${name} takes no value (got "${value}")`);
 }
 
+/**
+ * Commands whose `--json` may ALSO carry a value: a JSON request body, as in
+ * curl's `--json '<body>'`. For them a bare `--json` (or `--json=true`) still
+ * selects JSON output, and the two can be combined
+ * (`--json '{"a":1}' --json`). Every other command keeps `--json` boolean.
+ */
+export const JSON_BODY_COMMANDS: ReadonlySet<string> = new Set(["pay"]);
+
+/** Whether `--json` OUTPUT was requested (see {@link JSON_BODY_COMMANDS}). */
+export function jsonOutputRequested(args: ParsedArgs): boolean {
+  if (args.command === null || !JSON_BODY_COMMANDS.has(args.command)) {
+    return booleanFlag(args, "json");
+  }
+  const values = args.flags.get("json") ?? [];
+  return values.some((value) => value === true || value === "true");
+}
+
+/** The `--json <body>` value(s) of a JSON-body command, if any. */
+export function jsonBodyFlag(args: ParsedArgs): string | undefined {
+  const values = (args.flags.get("json") ?? []).filter(
+    (value): value is string =>
+      typeof value === "string" && value !== "true" && value !== "false",
+  );
+  if (values.length > 1) {
+    throw usageError("--json <body> may be given only once");
+  }
+  return values[0];
+}
+
 export function integerFlag(
   args: ParsedArgs,
   name: string,