@absol-labs/agent 0.1.0

package/src/frameworks/langchain.ts

@@ -0,0 +1,325 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { isAddress, isHex } from "viem";
+import { z } from "zod/v3";
+
+import {
+  discoverServices as defaultDiscoverServices,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
+import {
+  type MandateAuthorizedStreamActionInput,
+  type ReclaimAuthorizedStreamInput,
+  type ReclaimVerifiedStreamResult,
+  type StreamProofTransactionResult,
+  type StreamStatusView,
+  type VerifiedStreamAgentOpener,
+} from "../sdk/client.js";
+
+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 decimalStringSchema = z.preprocess(
+  (value) =>
+    typeof value === "bigint" || typeof value === "number"
+      ? value.toString()
+      : value,
+  z.string().regex(/^(0|[1-9]\d*)$/, "must be a base-10 integer string"),
+);
+
+const spendMandateInputSchema = z.object({
+  maxPerStreamUsdc: decimalStringSchema,
+  maxTotalUsdc: decimalStringSchema,
+  maxRatePerSecondUsdc: decimalStringSchema,
+  maxDurationSeconds: z.number().int().positive(),
+  allowedOperators: z.array(addressSchema).optional(),
+  expiresAt: z.number().int().positive(),
+});
+
+const signedSpendMandateInputSchema = z.object({
+  mandateId: bytes32Schema,
+  owner: addressSchema,
+  chainId: z.number().int().positive(),
+  issuedAt: z.number().int().nonnegative(),
+  mandate: spendMandateInputSchema,
+  signature: z
+    .string()
+    .refine(
+      (value) => isHex(value, { strict: true }) && value.length === 132,
+      "must be a 65-byte signature",
+    ),
+});
+
+const hireToolSchema = z.object({
+  operator: addressSchema,
+  serviceRef: bytes32Schema,
+  budgetUsdc: decimalStringSchema,
+  ratePerSecondUsdc: decimalStringSchema,
+  maxDurationSeconds: z.number().int().positive(),
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+const streamStatusToolSchema = z.object({
+  streamId: bytes32Schema,
+});
+
+const reclaimToolSchema = z.object({
+  streamId: bytes32Schema,
+  closeFirst: z.boolean().optional(),
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+const closeToolSchema = z.object({
+  streamId: bytes32Schema,
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+const discoverToolSchema = z.object({
+  category: z.string().min(1).optional(),
+  limit: z.number().int().positive().optional(),
+});
+
+export interface LangChainMandateStateResolver {
+  getSpentSoFarUsdc(owner: `0x${string}`): Promise<bigint>;
+  getRevokedMandateIds(owner: `0x${string}`): Promise<readonly `0x${string}`[]>;
+}
+
+export interface LangChainVerifiedStreamClient extends Pick<
+  VerifiedStreamAgentOpener,
+  "openVerifiedStream"
+> {
+  getStreamStatus(streamId: `0x${string}`): Promise<StreamStatusView>;
+  reclaimStream(
+    input: ReclaimAuthorizedStreamInput,
+  ): Promise<ReclaimVerifiedStreamResult>;
+  closeStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
+}
+
+export interface LangChainVerifiedStreamToolsOptions {
+  readonly agentClient: LangChainVerifiedStreamClient;
+  readonly mandateStateResolver?: Partial<LangChainMandateStateResolver>;
+  readonly now?: () => number;
+  /**
+   * Discovery driver for the `discover_services` tool. Defaults to the live
+   * registry-backed `discoverServices`; tests inject a double.
+   */
+  readonly discoverServices?: (
+    opts?: DiscoverServicesOptions,
+  ) => Promise<ServiceListing[]>;
+}
+
+export interface LangChainVerifiedStreamTools {
+  readonly discover: DynamicStructuredTool<any, any, any, any, any, string>;
+  readonly hire: DynamicStructuredTool<any, any, any, any, any, string>;
+  readonly status: DynamicStructuredTool<any, any, any, any, any, string>;
+  readonly reclaim: DynamicStructuredTool<any, any, any, any, any, string>;
+  readonly close: DynamicStructuredTool<any, any, any, any, any, string>;
+}
+
+const DEFAULT_MANDATE_STATE_RESOLVER: LangChainMandateStateResolver = {
+  getSpentSoFarUsdc: async () => 0n,
+  getRevokedMandateIds: async () => [],
+};
+
+export function createLangChainVerifiedStreamTools(
+  options: LangChainVerifiedStreamToolsOptions,
+): LangChainVerifiedStreamTools {
+  const resolver = {
+    ...DEFAULT_MANDATE_STATE_RESOLVER,
+    ...options.mandateStateResolver,
+  } satisfies LangChainMandateStateResolver;
+  const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+  const discoverImpl = options.discoverServices ?? defaultDiscoverServices;
+
+  const discover: DynamicStructuredTool<any, any, any, any, any, string> =
+    new DynamicStructuredTool({
+      name: "discover_services",
+      description:
+        "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is verified — the entry point before hire_verified_service.",
+      schema: discoverToolSchema as any,
+      func: async (input: z.infer<typeof discoverToolSchema>) => {
+        const listings = await discoverImpl({
+          ...(input.category === undefined ? {} : { category: input.category }),
+          ...(input.limit === undefined ? {} : { limit: input.limit }),
+        });
+        return { services: listings };
+      },
+    }) as DynamicStructuredTool<any, any, any, any, any, string>;
+
+  const hire: DynamicStructuredTool<any, any, any, any, any, string> =
+    new DynamicStructuredTool({
+      name: "hire_verified_service",
+      description:
+        "Open a verified payment stream with a signed mandate and hard budget limits.",
+      schema: hireToolSchema as any,
+      func: async (input: z.infer<typeof hireToolSchema>) => {
+        const signedMandate = parseSignedMandateInput(input.signedMandate);
+        const nowSeconds = now();
+        const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(
+          signedMandate.owner as `0x${string}`,
+        );
+        const revokedMandateIds = await resolver.getRevokedMandateIds(
+          signedMandate.owner as `0x${string}`,
+        );
+        const decision = await checkMandate(
+          signedMandate,
+          {
+            operator: input.operator as `0x${string}`,
+            budgetUsdc: BigInt(input.budgetUsdc),
+            ratePerSecondUsdc: BigInt(input.ratePerSecondUsdc),
+            maxDurationSeconds: input.maxDurationSeconds,
+          },
+          spentSoFarUsdc,
+          {
+            nowSeconds,
+            revokedMandateIds,
+          },
+        );
+        if (!decision.allowed) {
+          throw new Error(`mandate denied: ${decision.reason ?? "unknown"}`);
+        }
+
+        const result = await options.agentClient.openVerifiedStream({
+          operator: input.operator as `0x${string}`,
+          serviceRef: input.serviceRef as `0x${string}`,
+          budgetUsdc: BigInt(input.budgetUsdc),
+          ratePerSecondUsdc: BigInt(input.ratePerSecondUsdc),
+          maxDurationSeconds: input.maxDurationSeconds,
+          signedMandate,
+          spentSoFarUsdc,
+          nowSeconds,
+          revokedMandateIds,
+        });
+
+        return {
+          streamId: result.streamId,
+          txHash: result.txHash,
+          approveTxHash: result.approveTxHash,
+          handle: result.handle,
+        };
+      },
+    }) as DynamicStructuredTool<any, any, any, any, any, string>;
+
+  const status: DynamicStructuredTool<any, any, any, any, any, string> =
+    new DynamicStructuredTool({
+      name: "check_stream_status",
+      description:
+        "Read the current stream status and whether the agent should stop work.",
+      schema: streamStatusToolSchema as any,
+      func: async ({ streamId }: z.infer<typeof streamStatusToolSchema>) => {
+        const result = await options.agentClient.getStreamStatus(
+          streamId as `0x${string}`,
+        );
+        return serializeStreamStatus(result, streamId as `0x${string}`);
+      },
+    }) as DynamicStructuredTool<any, any, any, any, any, string>;
+
+  const reclaim: DynamicStructuredTool<any, any, any, any, any, string> =
+    new DynamicStructuredTool({
+      name: "reclaim_unspent",
+      description:
+        "Close and/or reclaim an existing stream under the same signed mandate controls.",
+      schema: reclaimToolSchema as any,
+      func: async (input: z.infer<typeof reclaimToolSchema>) => {
+        const signedMandate = parseSignedMandateInput(input.signedMandate);
+        const nowSeconds = now();
+        const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(
+          signedMandate.owner as `0x${string}`,
+        );
+        const revokedMandateIds = await resolver.getRevokedMandateIds(
+          signedMandate.owner as `0x${string}`,
+        );
+        const result = await options.agentClient.reclaimStream({
+          streamId: input.streamId as `0x${string}`,
+          signedMandate,
+          spentSoFarUsdc,
+          nowSeconds,
+          revokedMandateIds,
+          ...(input.closeFirst === undefined
+            ? {}
+            : { closeFirst: input.closeFirst }),
+        });
+
+        return {
+          closeTxHash: result.closeResult?.txHash ?? null,
+          reclaimTxHash: result.reclaimResult.txHash,
+        };
+      },
+    }) as DynamicStructuredTool<any, any, any, any, any, string>;
+
+  const close: DynamicStructuredTool<any, any, any, any, any, string> =
+    new DynamicStructuredTool({
+      name: "close_stream",
+      description:
+        "Close an existing stream, finalizing accrual and halting further payment, under the same signed mandate controls.",
+      schema: closeToolSchema as any,
+      func: async (input: z.infer<typeof closeToolSchema>) => {
+        const signedMandate = parseSignedMandateInput(input.signedMandate);
+        const nowSeconds = now();
+        const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(
+          signedMandate.owner as `0x${string}`,
+        );
+        const revokedMandateIds = await resolver.getRevokedMandateIds(
+          signedMandate.owner as `0x${string}`,
+        );
+        const result = await options.agentClient.closeStream({
+          streamId: input.streamId as `0x${string}`,
+          signedMandate,
+          spentSoFarUsdc,
+          nowSeconds,
+          revokedMandateIds,
+        });
+
+        return { closeTxHash: result.txHash };
+      },
+    }) as DynamicStructuredTool<any, any, any, any, any, string>;
+
+  return { discover, hire, status, reclaim, close };
+}
+
+function parseSignedMandateInput(
+  value: z.input<typeof signedSpendMandateInputSchema>,
+): SignedSpendMandate {
+  const parsed = signedSpendMandateInputSchema.parse(value);
+  return {
+    ...parsed,
+    mandateId: parsed.mandateId as `0x${string}`,
+    owner: parsed.owner as `0x${string}`,
+    signature: parsed.signature as `0x${string}`,
+    mandate: {
+      ...parsed.mandate,
+      maxPerStreamUsdc: BigInt(parsed.mandate.maxPerStreamUsdc),
+      maxTotalUsdc: BigInt(parsed.mandate.maxTotalUsdc),
+      maxRatePerSecondUsdc: BigInt(parsed.mandate.maxRatePerSecondUsdc),
+    },
+  };
+}
+
+function serializeStreamStatus(
+  result: StreamStatusView,
+  streamId: `0x${string}`,
+) {
+  return {
+    streamId,
+    shouldStop: result.stream.status !== "active",
+    stream: {
+      ...result.stream,
+      deposit: result.stream.deposit.toString(),
+      ratePerSecond: result.stream.ratePerSecond.toString(),
+      accrued: result.stream.accrued.toString(),
+      claimed: result.stream.claimed.toString(),
+      lastSequence: result.stream.lastSequence.toString(),
+    },
+    claimable: result.claimable.toString(),
+    reclaimable: result.reclaimable.toString(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+export {
+  createSpendMandateTypedData,
+  spendMandateSchema,
+  signedSpendMandateSchema,
+  checkMandate,
+  checkMandatePolicy,
+  verifySignedMandate,
+  verifyMandateOwnerSignature,
+  spendMandateDomain,
+  spendMandateTypedData,
+  type SpendMandate,
+  type SignedSpendMandate,
+  type HireRequest,
+  type MandateDecision,
+  type MandateVerificationContext,
+} from "./mandates/mandate.js";
+
+export {
+  DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+  ServerMandateConfigError,
+  parseServerMandateCapsEnv,
+  signServerMandate,
+  type ServerMandateCaps,
+  type SignServerMandateOptions,
+} from "./mandates/env.js";
+
+export {
+  VerifiedStreamX402Facilitator,
+  DeliveryProofUnavailableError,
+  X402PayloadError,
+  SettlementTargetMismatchError,
+  X402_SCHEME,
+  encodeX402PayloadHeader,
+  parseX402ChallengeJson,
+  parseX402PayloadHeader,
+  verifiedStreamRequirementsSchema,
+  x402StreamChallengeSchema,
+  x402OpenPayloadSchema,
+  type X402ConsumedHttpsResponseProofInput,
+  type X402Facilitator,
+  type X402OpenPayload,
+  type X402StreamChallenge,
+  type VerifiedStreamFacilitatorOptions,
+  type VerifiedStreamRequirements,
+} from "./x402/facilitator.js";
+
+export {
+  DEFAULT_METRIK_REGISTRY_URL,
+  discoverServices,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "./discovery/registry.js";
+
+export {
+  METRIK_MCP_TOOLS,
+  STREAMPROOF_MCP_TOOLS,
+  FileStreamRegistry,
+  InMemoryStreamRegistry,
+  createVerifiedStreamMcpServer,
+  createVerifiedStreamMcpServerFromEnv,
+  createVerifiedStreamMcpServerOptionsFromEnv,
+  parseMetrikAgentEnv,
+  startVerifiedStreamMcpServerStdio,
+  type McpToolSpec,
+  type ParsedMetrikAgentEnv,
+  type StoredStreamRecord,
+  type StreamRegistry,
+  type VerifiedStreamMcpClient,
+  type VerifiedStreamMcpServerOptions,
+  type VerifiedStreamMcpServerRuntime,
+} from "./mcp/server.js";
+
+export {
+  StaticTenantResolver,
+  createHostedMcpHttpServer,
+  createHostedMcpTenants,
+  parseHostedMcpServerConfig,
+  startHostedMcpHttpServerFromEnv,
+  type HostedMcpHttpServer,
+  type HostedMcpHttpServerOptions,
+  type HostedMcpServerConfig,
+  type HostedMcpTenant,
+  type HostedMcpTenantConfig,
+  type TenantResolver,
+} from "./mcp/http.js";
+
+export {
+  MandateDeniedError,
+  VerifiedStreamAgentClient,
+  type AgentSdkClient,
+  type AgentSdkClientFactory,
+  type MandateAuthorizedStreamActionInput,
+  type OpenVerifiedStreamInput,
+  type ReclaimAuthorizedStreamInput,
+  type ReclaimVerifiedStreamOptions,
+  type ReclaimVerifiedStreamResult,
+  type StreamStatusView,
+  type VerifiedStreamAgentOpener,
+} from "./sdk/client.js";
+
+export {
+  AgentWalletConfigError,
+  createWalletBackedAgentClient,
+  parseAgentWalletEnv,
+  resolveAgentWallet,
+  type AgentWalletInput,
+  type CdpClientLike,
+  type CdpWalletConfig,
+  type ResolvedAgentWallet,
+  type WalletBackedAgentClient,
+} from "./wallet/provider.js";
+
+export {
+  ReclaimConsumerProofService,
+  ResponseProofUnavailableError,
+  ResponseProofVerificationError,
+  createReclaimConsumerProofServiceFromEnv,
+  parseReclaimProofEnv,
+  type ConsumerDeliveryProofService,
+  type DeliveryProofBinding,
+  type HttpsResponseMatch,
+  type HttpsResponseRedaction,
+  type ParsedReclaimProofEnv,
+  type ProveConsumedHttpsResponseInput,
+  type ReclaimClientLike,
+  type ReclaimProof,
+  type ReclaimProofServiceConfig,
+  type VerifiedConsumedHttpsResponseProof,
+  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";