@absol-labs/agent 0.1.0 → 0.3.1

package/src/frameworks/agentkit.ts

@@ -132,11 +132,6 @@ export interface MetrikMandateStateResolver {
   getRevokedMandateIds(owner: `0x${string}`): Promise<readonly `0x${string}`[]>;
 }
 
-const DEFAULT_MANDATE_STATE_RESOLVER: MetrikMandateStateResolver = {
-  getSpentSoFarUsdc: async () => 0n,
-  getRevokedMandateIds: async () => [],
-};
-
 /**
  * The subset of the Metrik SDK the action provider drives. `VerifiedStreamAgentClient`
  * satisfies this structurally; tests inject a lightweight double so the provider
@@ -205,6 +200,21 @@ export class MetrikActionProviderConfigError extends Error {
   }
 }
 
+/**
+ * Raised when a hire cannot be authorized because a fund-safety mandate control
+ * (the cumulative-cap accounting or the revocation state) cannot be POSITIVELY
+ * verified — no resolver wired, or a wired resolver threw/returned garbage. The
+ * provider denies the hire (fail-closed, buyer-favoring) rather than proceeding
+ * on an unverified "0 spent / none revoked" assumption (the B6 fix). Buyer
+ * recovery (close / reclaim) is NEVER blocked by this — it is signature-only.
+ */
+export class MetrikSpendControlUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MetrikSpendControlUnavailableError";
+  }
+}
+
 /**
  * Coinbase AgentKit action provider that lets any AgentKit-based agent hire and
  * pay third-party services through Metrik's verified USDC escrow. Every action
@@ -214,7 +224,10 @@ export class MetrikActionProviderConfigError extends Error {
 export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   readonly #client: MetrikAgentKitClient;
   readonly #signedMandate: SignedSpendMandate;
-  readonly #resolver: MetrikMandateStateResolver;
+  // Stored as the raw partial the caller supplied. A missing method means the
+  // corresponding fund-safety control cannot be verified, so the HIRE path fails
+  // CLOSED (see `#resolveSpendControls`). Buyer recovery never reads this.
+  readonly #resolver: Partial<MetrikMandateStateResolver>;
   readonly #now: () => number;
   readonly #chainId: number;
   readonly #discover: (
@@ -234,23 +247,24 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
 
     this.#client = resolveClient(config);
     this.#signedMandate = config.signedMandate;
-    this.#resolver = {
-      ...DEFAULT_MANDATE_STATE_RESOLVER,
-      ...config.mandateStateResolver,
-    };
+    this.#resolver = { ...config.mandateStateResolver };
     // Fail-loud on the two mandate controls that require external state. The
     // action provider holds no stream registry, so without a wired resolver the
-    // cumulative cap (maxTotalUsdc) and revocation are not enforced. Warn once.
+    // cumulative cap (maxTotalUsdc) and revocation cannot be verified — and every
+    // mandate carries a positive maxTotalUsdc, so a missing spent resolver can
+    // NEVER verify the cap. `hire_verified_service` therefore fails CLOSED
+    // (denies) until both are wired; warn once so the reason is visible at deploy
+    // time. Buyer recovery (close / reclaim) stays available regardless.
     if (config.mandateStateResolver?.getSpentSoFarUsdc === undefined) {
       warnAgentKitOnce(
         "agentkit-spent",
-        "[metrik] AgentKit provider: no getSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) is NOT enforced across hires (per-stream/rate/duration/operator/expiry still are).",
+        "[metrik] AgentKit provider: no getSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so hire_verified_service will DENY every hire (fail-closed) until a resolver is wired.",
       );
     }
     if (config.mandateStateResolver?.getRevokedMandateIds === undefined) {
       warnAgentKitOnce(
         "agentkit-revocation",
-        "[metrik] AgentKit provider: no getRevokedMandateIds wired — revoked mandates will NOT be rejected until you wire a revocation store.",
+        "[metrik] AgentKit provider: no getRevokedMandateIds wired — revocation state cannot be verified, so hire_verified_service will DENY every hire (fail-closed) until a resolver is wired.",
       );
     }
     this.#now = config.now ?? (() => Math.floor(Date.now() / 1000));
@@ -299,10 +313,10 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
 
     const owner = this.#signedMandate.owner as `0x${string}`;
     const nowSeconds = this.#now();
-    const [spentSoFarUsdc, revokedMandateIds] = await Promise.all([
-      this.#resolver.getSpentSoFarUsdc(owner),
-      this.#resolver.getRevokedMandateIds(owner),
-    ]);
+    // FAIL-CLOSED fund safety (B6): deny the hire unless BOTH the cumulative-cap
+    // accounting and the revocation state are positively verified.
+    const { spentSoFarUsdc, revokedMandateIds } =
+      await this.#resolveSpendControls(owner);
 
     const operator = args.operator as `0x${string}`;
     const serviceRef = args.serviceRef as `0x${string}`;
@@ -386,7 +400,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     this.#assertWalletNetwork(walletProvider);
 
     const result = await this.#client.reclaimStream(
-      await this.#authorizedStreamAction(args.streamId as `0x${string}`, {
+      this.#authorizedStreamAction(args.streamId as `0x${string}`, {
         ...(args.closeFirst === undefined
           ? {}
           : { closeFirst: args.closeFirst }),
@@ -413,7 +427,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     this.#assertWalletNetwork(walletProvider);
 
     const result = await this.#client.closeStream(
-      await this.#authorizedStreamAction(args.streamId as `0x${string}`, {}),
+      this.#authorizedStreamAction(args.streamId as `0x${string}`, {}),
     );
     return `Closed stream ${args.streamId}. tx=${result.txHash}`;
   }
@@ -435,22 +449,79 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     }
   }
 
-  async #authorizedStreamAction<TExtra extends object>(
+  /**
+   * FAIL-CLOSED resolution of the two fund-safety controls for the HIRE path.
+   * Every mandate carries a positive `maxTotalUsdc`, so a missing spent resolver
+   * can never verify the cap; a missing revocation resolver can never verify
+   * revocation. A resolver that throws (state store down) or returns garbage is
+   * likewise treated as "cannot verify" → deny. Never a silent fail-open to
+   * `{ 0n, [] }`.
+   */
+  async #resolveSpendControls(owner: `0x${string}`): Promise<{
+    spentSoFarUsdc: bigint;
+    revokedMandateIds: readonly `0x${string}`[];
+  }> {
+    const getSpentSoFarUsdc = this.#resolver.getSpentSoFarUsdc;
+    const getRevokedMandateIds = this.#resolver.getRevokedMandateIds;
+    if (getSpentSoFarUsdc === undefined) {
+      throw new MetrikSpendControlUnavailableError(
+        "cannot hire verified service: no getSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified (fail-closed)",
+      );
+    }
+    if (getRevokedMandateIds === undefined) {
+      throw new MetrikSpendControlUnavailableError(
+        "cannot hire verified service: no getRevokedMandateIds wired — mandate revocation state cannot be verified (fail-closed)",
+      );
+    }
+
+    let spentSoFarUsdc: bigint;
+    try {
+      spentSoFarUsdc = await getSpentSoFarUsdc(owner);
+    } catch (error) {
+      throw new MetrikSpendControlUnavailableError(
+        `cannot verify mandate cumulative cap (maxTotalUsdc): ${asErrorMessage(error)} (fail-closed)`,
+      );
+    }
+    if (typeof spentSoFarUsdc !== "bigint" || spentSoFarUsdc < 0n) {
+      throw new MetrikSpendControlUnavailableError(
+        "cannot verify mandate cumulative cap (maxTotalUsdc): resolver returned an invalid spent-so-far value (fail-closed)",
+      );
+    }
+
+    let revokedMandateIds: readonly `0x${string}`[];
+    try {
+      revokedMandateIds = await getRevokedMandateIds(owner);
+    } catch (error) {
+      throw new MetrikSpendControlUnavailableError(
+        `cannot verify mandate revocation state: ${asErrorMessage(error)} (fail-closed)`,
+      );
+    }
+    if (!Array.isArray(revokedMandateIds)) {
+      throw new MetrikSpendControlUnavailableError(
+        "cannot verify mandate revocation state: resolver returned a non-array value (fail-closed)",
+      );
+    }
+
+    return { spentSoFarUsdc, revokedMandateIds };
+  }
+
+  /**
+   * Context for a BUYER-RECOVERY action (close / reclaim). These are authorized
+   * on the mandate owner's signature ALONE (see `authorizeBuyerRecovery` in the
+   * SDK client) and must NEVER be blocked by missing or failing spend-control
+   * state — otherwise a lapsed resolver could strand the buyer's own funds. The
+   * spent/revoked fields are ignored downstream, so we pass safe neutral values.
+   */
+  #authorizedStreamAction<TExtra extends object>(
     streamId: `0x${string}`,
     extra: TExtra,
-  ): Promise<MandateAuthorizedStreamActionInput & TExtra> {
-    const owner = this.#signedMandate.owner as `0x${string}`;
-    const nowSeconds = this.#now();
-    const [spentSoFarUsdc, revokedMandateIds] = await Promise.all([
-      this.#resolver.getSpentSoFarUsdc(owner),
-      this.#resolver.getRevokedMandateIds(owner),
-    ]);
+  ): MandateAuthorizedStreamActionInput & TExtra {
     return {
       streamId,
       signedMandate: this.#signedMandate,
-      spentSoFarUsdc,
-      nowSeconds,
-      revokedMandateIds,
+      spentSoFarUsdc: 0n,
+      nowSeconds: this.#now(),
+      revokedMandateIds: [],
       ...extra,
     };
   }
@@ -520,6 +591,10 @@ function resolveClient(
   );
 }
 
+function asErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 const USDC_DECIMALS = 6n;
 const USDC_SCALE = 10n ** USDC_DECIMALS;
 

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   VerifiedStreamX402Facilitator,
   DeliveryProofUnavailableError,
   X402PayloadError,
+  X402SpendControlUnavailableError,
   SettlementTargetMismatchError,
   X402_SCHEME,
   encodeX402PayloadHeader,
@@ -46,6 +47,8 @@ export {
 
 export {
   DEFAULT_METRIK_REGISTRY_URL,
+  DEMO_SEED_LISTING,
+  DEMO_SEED_SERVICE_REF,
   discoverServices,
   type DiscoverServicesOptions,
   type ServiceListing,
@@ -129,51 +132,13 @@ export {
   type VerifyProofFn,
 } from "./zktls/reclaim.js";
 
-export {
-  createLangChainVerifiedStreamTools,
-  type LangChainMandateStateResolver,
-  type LangChainVerifiedStreamClient,
-  type LangChainVerifiedStreamTools,
-  type LangChainVerifiedStreamToolsOptions,
-} from "./frameworks/langchain.js";
-
-export {
-  METRIK_ELIZA_ACTION_NAMES,
-  METRIK_ELIZA_SETTLEMENT_CHAIN_ID,
-  createMetrikElizaPlugin,
-  createMetrikElizaContent,
-  metrikElizaPlugin,
-  // Deprecated aliases retained for backward compatibility.
-  createElizaVerifiedStreamContent,
-  createElizaVerifiedStreamPlugin,
-  type MetrikElizaActionInputs,
-  type MetrikElizaActionName,
-  type MetrikElizaClient,
-  type MetrikElizaMandateStateResolver,
-  type MetrikElizaPluginOptions,
-} from "./frameworks/eliza.js";
-
-export {
-  CREWAI_VERIFIED_STREAM_TOOL_NAMES,
-  createCrewAiVerifiedStreamMcpConfig,
-  renderCrewAiVerifiedStreamPythonExample,
-  type CrewAiVerifiedStreamMcpConfig,
-  type CrewAiVerifiedStreamMcpConfigOptions,
-} from "./frameworks/crewai.js";
-
-export {
-  METRIK_BASE_SEPOLIA_CHAIN_ID,
-  MetrikActionProvider,
-  MetrikActionProviderConfigError,
-  metrikActionProvider,
-  createMetrikAgentKit,
-  discoverServicesSchema,
-  hireVerifiedServiceSchema,
-  checkStreamStatusSchema,
-  reclaimUnspentSchema,
-  closeStreamSchema,
-  type CreateMetrikAgentKitOptions,
-  type MetrikActionProviderConfig,
-  type MetrikAgentKitClient,
-  type MetrikMandateStateResolver,
-} from "./frameworks/agentkit.js";
+// Framework adapters are NOT re-exported from this top-level barrel on purpose.
+// Some of them (notably the Coinbase AgentKit adapter) pull heavy optional
+// dependency graphs, so importing "@absol-labs/agent" must stay light and load
+// only the core (SDK client, spend mandates, MCP server, x402, discovery,
+// wallet, zkTLS). Import an adapter from its own subpath when you need it:
+//
+//   import { createMetrikAgentKit } from "@absol-labs/agent/agentkit";
+//   import { metrikElizaPlugin } from "@absol-labs/agent/eliza";
+//   import { createLangChainVerifiedStreamTools } from "@absol-labs/agent/langchain";
+//   import { createCrewAiVerifiedStreamMcpConfig } from "@absol-labs/agent/crewai";

package/src/mcp/server.ts

@@ -188,7 +188,7 @@ export const METRIK_MCP_TOOLS: readonly McpToolSpec[] = [
   {
     name: "prove_https_response",
     description:
-      "Generate a zkTLS proof of the exact HTTPS response consumed for a tracked stream. This is an L4 delivery signal and must be cross-checked with oracle/L1 evidence.",
+      "Generate a zkTLS proof of the exact HTTPS response consumed for a tracked stream. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence.",
     movesFunds: false,
   },
 ] as const;

package/src/x402/facilitator.ts

@@ -130,17 +130,37 @@ export class DeliveryProofUnavailableError extends Error {
   }
 }
 
+/**
+ * Raised when a spend cannot be authorized because a fund-safety mandate control
+ * (the cumulative-cap accounting or the revocation state) cannot be POSITIVELY
+ * verified — no resolver wired, or a wired resolver threw/returned garbage. The
+ * facilitator denies the open in this case (fail-closed, buyer-favoring) rather
+ * than proceeding on an unverified assumption of "0 spent / none revoked".
+ */
+export class X402SpendControlUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "X402SpendControlUnavailableError";
+  }
+}
+
 export class VerifiedStreamX402Facilitator implements X402Facilitator {
   private readonly agentClient: VerifiedStreamAgentOpener;
   private readonly deliveryProofs: ConsumerDeliveryProofService | undefined;
   private readonly sdkConfig: StreamProofClientConfig;
   private readonly nowSeconds: () => number;
-  private readonly resolveSpentSoFarUsdc: (
-    signedMandate: SignedSpendMandate,
-  ) => bigint | Promise<bigint>;
-  private readonly resolveRevokedMandateIds: (
-    signedMandate: SignedSpendMandate,
-  ) => Iterable<`0x${string}`> | Promise<Iterable<`0x${string}`>>;
+  // Left `undefined` when the caller wired no resolver. A missing resolver means
+  // the corresponding fund-safety control cannot be positively verified, so
+  // `open()` fails CLOSED rather than defaulting to a fail-open "0 spent / none
+  // revoked" assumption (the B6 fix).
+  private readonly resolveSpentSoFarUsdc:
+    | ((signedMandate: SignedSpendMandate) => bigint | Promise<bigint>)
+    | undefined;
+  private readonly resolveRevokedMandateIds:
+    | ((
+        signedMandate: SignedSpendMandate,
+      ) => Iterable<`0x${string}`> | Promise<Iterable<`0x${string}`>>)
+    | undefined;
 
   constructor(options: VerifiedStreamFacilitatorOptions) {
     this.sdkConfig = options.sdkConfig;
@@ -150,24 +170,25 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     this.deliveryProofs = options.deliveryProofs;
     this.nowSeconds =
       options.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
-    this.resolveSpentSoFarUsdc = options.resolveSpentSoFarUsdc ?? (() => 0n);
-    this.resolveRevokedMandateIds =
-      options.resolveRevokedMandateIds ?? (() => []);
+    this.resolveSpentSoFarUsdc = options.resolveSpentSoFarUsdc;
+    this.resolveRevokedMandateIds = options.resolveRevokedMandateIds;
 
     // Fail-loud on the two mandate controls that require external state. This
-    // facilitator is stateless (no stream registry), so it cannot enforce the
-    // cumulative-cap or revocation without a wired resolver. Warn once so a
-    // deployment never silently ships with maxTotalUsdc / revocation disabled.
+    // facilitator is stateless (no stream registry), so without a wired resolver
+    // it cannot verify the cumulative cap (maxTotalUsdc) or revocation — and
+    // every mandate carries a positive maxTotalUsdc, so a missing spent resolver
+    // can NEVER verify the cap. `open()` therefore fails CLOSED (denies) until
+    // both resolvers are wired; warn once so the reason is visible at deploy time.
     if (options.resolveSpentSoFarUsdc === undefined) {
       warnFacilitatorOnce(
         "x402-spent",
-        "[metrik] x402 facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) is NOT enforced across streams (per-stream/rate/duration/operator/expiry still are).",
+        "[metrik] x402 facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
     if (options.resolveRevokedMandateIds === undefined) {
       warnFacilitatorOnce(
         "x402-revocation",
-        "[metrik] x402 facilitator: no resolveRevokedMandateIds wired — revoked mandates will NOT be rejected until you wire a revocation store.",
+        "[metrik] x402 facilitator: no resolveRevokedMandateIds wired — revocation state cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
   }
@@ -182,12 +203,61 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     const payload = parseX402PayloadHeader(payloadHeader);
     assertSettlementTarget(payload.challenge.requirements, this.sdkConfig);
 
-    const spentSoFarUsdc = await this.resolveSpentSoFarUsdc(
-      payload.signedMandate,
-    );
-    const revokedMandateIds = await this.resolveRevokedMandateIds(
-      payload.signedMandate,
-    );
+    // FAIL-CLOSED fund safety (B6). Both the cumulative-cap accounting and the
+    // revocation state must be POSITIVELY verified before any spend. A missing
+    // resolver, a resolver that throws (state store down), or a resolver that
+    // returns a non-bigint/negative spend is treated as "state cannot be
+    // verified" and DENIES the open — never a silent fail-open to 0/none.
+    if (this.resolveSpentSoFarUsdc === undefined) {
+      throw new X402SpendControlUnavailableError(
+        "cannot open verified stream: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified (fail-closed)",
+      );
+    }
+    if (this.resolveRevokedMandateIds === undefined) {
+      throw new X402SpendControlUnavailableError(
+        "cannot open verified stream: no resolveRevokedMandateIds wired — mandate revocation state cannot be verified (fail-closed)",
+      );
+    }
+
+    let spentSoFarUsdc: bigint;
+    try {
+      spentSoFarUsdc = await this.resolveSpentSoFarUsdc(payload.signedMandate);
+    } catch (error) {
+      throw new X402SpendControlUnavailableError(
+        `cannot verify mandate cumulative cap (maxTotalUsdc): ${
+          error instanceof Error ? error.message : String(error)
+        } (fail-closed)`,
+      );
+    }
+    if (typeof spentSoFarUsdc !== "bigint" || spentSoFarUsdc < 0n) {
+      throw new X402SpendControlUnavailableError(
+        "cannot verify mandate cumulative cap (maxTotalUsdc): resolver returned an invalid spent-so-far value (fail-closed)",
+      );
+    }
+
+    let revokedMandateIds: Iterable<`0x${string}`>;
+    try {
+      revokedMandateIds = await this.resolveRevokedMandateIds(
+        payload.signedMandate,
+      );
+    } catch (error) {
+      throw new X402SpendControlUnavailableError(
+        `cannot verify mandate revocation state: ${
+          error instanceof Error ? error.message : String(error)
+        } (fail-closed)`,
+      );
+    }
+    if (
+      revokedMandateIds === null ||
+      revokedMandateIds === undefined ||
+      typeof (revokedMandateIds as { [Symbol.iterator]?: unknown })[
+        Symbol.iterator
+      ] !== "function"
+    ) {
+      throw new X402SpendControlUnavailableError(
+        "cannot verify mandate revocation state: resolver returned a non-iterable value (fail-closed)",
+      );
+    }
 
     const result = await this.agentClient.openVerifiedStream({
       operator: payload.challenge.requirements.operator as `0x${string}`,

package/src/zktls/reclaim.ts

@@ -346,7 +346,7 @@ function buildRequestContext(
   return {
     contextAddress: binding.owner,
     contextMessage: JSON.stringify({
-      kind: "metrik-l4-http-response/v1",
+      kind: "metrik-l2-http-response/v1",
       streamId: binding.streamId ?? null,
       operator: binding.operator ?? null,
       serviceRef: binding.serviceRef ?? null,