aixyz 0.0.1 → 0.1.2

package/accepts.ts

@@ -0,0 +1,12 @@
+export type Accepts = AcceptsX402 | AcceptsFree;
+
+export type AcceptsX402 = {
+  scheme: "exact";
+  price: string;
+  network?: string;
+  payTo?: string;
+};
+
+export type AcceptsFree = {
+  scheme: "free";
+};

package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+require("@aixyz/cli/bin");

package/config.ts

@@ -0,0 +1 @@
+export * from "@aixyz/config";

package/facilitator/coinbase.ts

@@ -0,0 +1,387 @@
+import { FacilitatorConfig } from "@x402/core/http";
+import { SignJWT, importPKCS8, importJWK, JWTPayload } from "jose";
+import { getRandomValues } from "crypto";
+
+const COINBASE_FACILITATOR_BASE_URL = "https://api.cdp.coinbase.com";
+const COINBASE_FACILITATOR_V2_ROUTE = "/platform/v2/x402";
+
+const X402_SDK_VERSION = "2.1.0";
+const CDP_SDK_VERSION = "1.29.0";
+
+/**
+ * Creates an authorization header for a request to the Coinbase API.
+ *
+ * @param apiKeyId - The api key ID
+ * @param apiKeySecret - The api key secret
+ * @param requestMethod - The method for the request (e.g. 'POST')
+ * @param requestHost - The host for the request (e.g. 'https://x402.org/facilitator')
+ * @param requestPath - The path for the request (e.g. '/verify')
+ * @returns The authorization header string
+ */
+export async function createAuthHeader(
+  apiKeyId: string,
+  apiKeySecret: string,
+  requestMethod: string,
+  requestHost: string,
+  requestPath: string,
+) {
+  const jwt = await generateJwt({
+    apiKeyId,
+    apiKeySecret,
+    requestMethod,
+    requestHost,
+    requestPath,
+  });
+  return `Bearer ${jwt}`;
+}
+
+/**
+ * Creates a correlation header for a request to the Coinbase API.
+ *
+ * @returns The correlation header string
+ */
+export function createCorrelationHeader(): string {
+  const data: Record<string, string> = {
+    sdk_version: CDP_SDK_VERSION,
+    sdk_language: "typescript",
+    source: "x402",
+    source_version: X402_SDK_VERSION,
+  };
+  return Object.keys(data)
+    .map((key) => `${key}=${encodeURIComponent(data[key])}`)
+    .join(",");
+}
+
+/**
+ * Creates a CDP auth header for the facilitator service
+ *
+ * @param apiKeyId - The CDP API key ID
+ * @param apiKeySecret - The CDP API key secret
+ * @returns A function that returns the auth headers
+ */
+export function createCdpAuthHeaders(apiKeyId?: string, apiKeySecret?: string): FacilitatorConfig["createAuthHeaders"] {
+  const requestHost = COINBASE_FACILITATOR_BASE_URL.replace("https://", "");
+
+  return async () => {
+    apiKeyId = apiKeyId ?? process.env.CDP_API_KEY_ID;
+    apiKeySecret = apiKeySecret ?? process.env.CDP_API_KEY_SECRET;
+
+    const headers = {
+      verify: {
+        "Correlation-Context": createCorrelationHeader(),
+      } as Record<string, string>,
+      settle: {
+        "Correlation-Context": createCorrelationHeader(),
+      } as Record<string, string>,
+      supported: {
+        "Correlation-Context": createCorrelationHeader(),
+      } as Record<string, string>,
+      list: {
+        "Correlation-Context": createCorrelationHeader(),
+      },
+    };
+
+    if (apiKeyId && apiKeySecret) {
+      headers.verify.Authorization = await createAuthHeader(
+        apiKeyId,
+        apiKeySecret,
+        "POST",
+        requestHost,
+        `${COINBASE_FACILITATOR_V2_ROUTE}/verify`,
+      );
+      headers.settle.Authorization = await createAuthHeader(
+        apiKeyId,
+        apiKeySecret,
+        "POST",
+        requestHost,
+        `${COINBASE_FACILITATOR_V2_ROUTE}/settle`,
+      );
+      headers.supported.Authorization = await createAuthHeader(
+        apiKeyId,
+        apiKeySecret,
+        "GET",
+        requestHost,
+        `${COINBASE_FACILITATOR_V2_ROUTE}/supported`,
+      );
+    }
+
+    return headers;
+  };
+}
+
+/**
+ * Creates a facilitator config for the Coinbase X402 facilitator
+ *
+ * @param apiKeyId - The CDP API key ID
+ * @param apiKeySecret - The CDP API key secret
+ * @returns A facilitator config
+ */
+function createFacilitatorConfig(apiKeyId?: string, apiKeySecret?: string): FacilitatorConfig {
+  return {
+    url: `${COINBASE_FACILITATOR_BASE_URL}${COINBASE_FACILITATOR_V2_ROUTE}`,
+    createAuthHeaders: createCdpAuthHeaders(apiKeyId, apiKeySecret),
+  };
+}
+
+/**
+ * JwtOptions contains configuration for JWT generation.
+ *
+ * This interface holds all necessary parameters for generating a JWT token
+ * for authenticating with Coinbase's REST APIs. It supports both EC (ES256)
+ * and Ed25519 (EdDSA) keys.
+ */
+export interface JwtOptions {
+  /**
+   * The API key ID
+   *
+   * Examples:
+   *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   */
+  apiKeyId: string;
+
+  /**
+   * The API key secret
+   *
+   * Examples:
+   *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+   *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+   */
+  apiKeySecret: string;
+
+  /**
+   * The HTTP method for the request (e.g. 'GET', 'POST'), or null for JWTs intended for websocket connections
+   */
+  requestMethod?: string | null;
+
+  /**
+   * The host for the request (e.g. 'api.cdp.coinbase.com'), or null for JWTs intended for websocket connections
+   */
+  requestHost?: string | null;
+
+  /**
+   * The path for the request (e.g. '/platform/v1/wallets'), or null for JWTs intended for websocket connections
+   */
+  requestPath?: string | null;
+
+  /**
+   * Optional expiration time in seconds (defaults to 120)
+   */
+  expiresIn?: number;
+
+  /**
+   * Optional audience claim for the JWT
+   */
+  audience?: string[];
+}
+
+/**
+ * Generates a JWT (also known as a Bearer token) for authenticating with Coinbase's REST APIs.
+ * Supports both EC (ES256) and Ed25519 (EdDSA) keys. Also supports JWTs meant for
+ * websocket connections by allowing requestMethod, requestHost, and requestPath to all be
+ * null, in which case the 'uris' claim is omitted from the JWT.
+ *
+ * @param options - The configuration options for generating the JWT
+ * @returns The generated JWT (Bearer token) string
+ * @throws {Error} If required parameters are missing, invalid, or if JWT signing fails
+ */
+export async function generateJwt(options: JwtOptions): Promise<string> {
+  // Validate required parameters
+  if (!options.apiKeyId) {
+    throw new Error("Key name is required");
+  }
+  if (!options.apiKeySecret) {
+    throw new Error("Private key is required");
+  }
+
+  // Check if we have a REST API request or a websocket connection
+  const hasAllRequestParams = Boolean(options.requestMethod && options.requestHost && options.requestPath);
+  const hasNoRequestParams =
+    (options.requestMethod === undefined || options.requestMethod === null) &&
+    (options.requestHost === undefined || options.requestHost === null) &&
+    (options.requestPath === undefined || options.requestPath === null);
+
+  // Ensure we either have all request parameters or none (for websocket)
+  if (!hasAllRequestParams && !hasNoRequestParams) {
+    throw new Error(
+      "Either all request details (method, host, path) must be provided, or all must be null for JWTs intended for websocket connections",
+    );
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const expiresIn = options.expiresIn || 120; // Default to 120 seconds if not specified
+
+  // Prepare the JWT payload
+  const claims: JWTPayload = {
+    sub: options.apiKeyId,
+    iss: "cdp",
+    aud: options.audience,
+  };
+
+  // Add the uris claim only for REST API requests
+  if (hasAllRequestParams) {
+    claims.uris = [`${options.requestMethod} ${options.requestHost}${options.requestPath}`];
+  }
+
+  // Generate random nonce for the header
+  const randomNonce = nonce();
+
+  // Determine if we're using EC or Edwards key based on the key format
+  if (await isValidECKey(options.apiKeySecret)) {
+    return await buildECJWT(options.apiKeySecret, options.apiKeyId, claims, now, expiresIn, randomNonce);
+  } else if (isValidEd25519Key(options.apiKeySecret)) {
+    return await buildEdwardsJWT(options.apiKeySecret, options.apiKeyId, claims, now, expiresIn, randomNonce);
+  } else {
+    throw new UserInputValidationError("Invalid key format - must be either PEM EC key or base64 Ed25519 key");
+  }
+}
+
+/**
+ * Builds a JWT using an EC key.
+ *
+ * @param privateKey - The EC private key in PEM format
+ * @param keyName - The key name/ID
+ * @param claims - The JWT claims
+ * @param now - Current timestamp in seconds
+ * @param expiresIn - Number of seconds until the token expires
+ * @param nonce - Random nonce for the JWT header
+ * @returns A JWT token signed with an EC key
+ * @throws {Error} If key conversion, import, or signing fails
+ */
+async function buildECJWT(
+  privateKey: string,
+  keyName: string,
+  claims: JWTPayload,
+  now: number,
+  expiresIn: number,
+  nonce: string,
+): Promise<string> {
+  try {
+    // Import the key directly with jose
+    const ecKey = await importPKCS8(privateKey, "ES256");
+
+    // Sign and return the JWT
+    return await new SignJWT(claims)
+      .setProtectedHeader({ alg: "ES256", kid: keyName, typ: "JWT", nonce })
+      .setIssuedAt(Math.floor(now))
+      .setNotBefore(Math.floor(now))
+      .setExpirationTime(Math.floor(now + expiresIn))
+      .sign(ecKey);
+  } catch (error) {
+    throw new Error(`Failed to generate EC JWT: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Builds a JWT using an Ed25519 key.
+ *
+ * @param privateKey - The Ed25519 private key in base64 format
+ * @param keyName - The key name/ID
+ * @param claims - The JWT claims
+ * @param now - Current timestamp in seconds
+ * @param expiresIn - Number of seconds until the token expires
+ * @param nonce - Random nonce for the JWT header
+ * @returns A JWT token using an Ed25519 key
+ * @throws {Error} If key parsing, import, or signing fails
+ */
+async function buildEdwardsJWT(
+  privateKey: string,
+  keyName: string,
+  claims: JWTPayload,
+  now: number,
+  expiresIn: number,
+  nonce: string,
+): Promise<string> {
+  try {
+    // Decode the base64 key (expecting 64 bytes: 32 for seed + 32 for public key)
+    const decoded = Buffer.from(privateKey, "base64");
+    if (decoded.length !== 64) {
+      throw new UserInputValidationError("Invalid Ed25519 key length");
+    }
+
+    const seed = decoded.subarray(0, 32);
+    const publicKey = decoded.subarray(32);
+
+    // Create JWK from the key components
+    const jwk = {
+      kty: "OKP",
+      crv: "Ed25519",
+      d: seed.toString("base64url"),
+      x: publicKey.toString("base64url"),
+    };
+
+    // Import the key for signing
+    const key = await importJWK(jwk, "EdDSA");
+
+    // Sign and return the JWT
+    return await new SignJWT(claims)
+      .setProtectedHeader({ alg: "EdDSA", kid: keyName, typ: "JWT", nonce })
+      .setIssuedAt(Math.floor(now))
+      .setNotBefore(Math.floor(now))
+      .setExpirationTime(Math.floor(now + expiresIn))
+      .sign(key);
+  } catch (error) {
+    throw new Error(`Failed to generate Ed25519 JWT: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * UserInputValidationError is thrown when validation of a user-supplied input fails.
+ */
+export class UserInputValidationError extends Error {
+  /**
+   * Initializes a new UserInputValidationError instance.
+   *
+   * @param message - The user input validation error message.
+   */
+  constructor(message: string) {
+    super(message);
+    this.name = "UserInputValidationError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, UserInputValidationError);
+    }
+  }
+}
+/**
+ * Determines if a string could be a valid Ed25519 key
+ *
+ * @param str - The string to test
+ * @returns True if the string could be a valid Ed25519 key, false otherwise
+ */
+function isValidEd25519Key(str: string): boolean {
+  try {
+    const decoded = Buffer.from(str, "base64");
+    return decoded.length === 64;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determines if a string is a valid EC private key in PEM format
+ *
+ * @param str - The string to test
+ * @returns True if the string is a valid EC private key in PEM format
+ */
+async function isValidECKey(str: string): Promise<boolean> {
+  try {
+    // Try to import the key with jose - if it works, it's a valid EC key
+    await importPKCS8(str, "ES256");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generates a random nonce for the JWT.
+ *
+ * @returns {string} The generated nonce.
+ */
+function nonce(): string {
+  const bytes = new Uint8Array(16);
+  getRandomValues(bytes);
+  return Buffer.from(bytes).toString("hex");
+}
+
+export const facilitator = createFacilitatorConfig();

package/facilitator/index.ts

@@ -0,0 +1,12 @@
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { facilitator } from "./coinbase";
+
+export function getFacilitatorClient() {
+  if (process.env.CDP_API_KEY_ID) {
+    return new HTTPFacilitatorClient(facilitator);
+  }
+
+  return new HTTPFacilitatorClient({
+    url: process.env.X402_FACILITATOR_URL || "https://www.x402.org/facilitator",
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aixyz",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "AI agent framework for building autonomous agents with X402 and ERC-8004 support.",
   "keywords": [
     "ai",
@@ -21,41 +21,34 @@
   },
   "license": "MIT",
   "author": "AgentlyHQ",
-  "type": "commonjs",
-  "bin": {
-    "aixyz": "dist/cli/bin.js"
-  },
+  "type": "module",
+  "bin": "bin.js",
   "files": [
-    "dist"
+    "**/*.ts"
   ],
-  "scripts": {
-    "build": "bun build cli/bin.ts --outdir ./dist/cli --target bun",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.10",
+    "@aixyz/cli": "workspace:*",
+    "@aixyz/config": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@next/env": "^16.1.6",
-    "@x402/core": "^2.2.0",
-    "@x402/evm": "^2.2.0",
-    "@x402/express": "^2.2.0",
+    "@x402/core": "^2.3.1",
+    "@x402/evm": "^2.3.1",
+    "@x402/express": "^2.3.0",
+    "@x402/mcp": "^2.3.0",
     "commander": "^13.0.0",
     "express": "^5.2.1",
     "jose": "^5.10.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/express": "^5.0.6",
     "ai": "^6"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1",
     "ai": "^6"
   },
   "peerDependenciesMeta": {
-    "@modelcontextprotocol/sdk": {
-      "optional": true
-    },
     "ai": {
       "optional": true
     }

package/server/adapters/a2a.ts

@@ -0,0 +1,118 @@
+import { randomUUID } from "node:crypto";
+import {
+  AgentExecutor,
+  DefaultRequestHandler,
+  ExecutionEventBus,
+  InMemoryTaskStore,
+  RequestContext,
+  TaskStore,
+} from "@a2a-js/sdk/server";
+import { AgentCard, Message, TextPart } from "@a2a-js/sdk";
+import type { ToolLoopAgent, ToolSet } from "ai";
+import { getAixyzConfig } from "../../config";
+import { AixyzServer } from "../index";
+import { agentCardHandler, jsonRpcHandler, UserBuilder } from "@a2a-js/sdk/server/express";
+import { Accepts } from "../../accepts";
+
+export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements AgentExecutor {
+  constructor(private agent: ToolLoopAgent<never, TOOLS>) {}
+
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+    try {
+      // Extract the user's message text
+      const userMessage = requestContext.userMessage;
+      const textParts = userMessage.parts.filter((part): part is TextPart => part.kind === "text");
+      const prompt = textParts.map((part) => part.text).join("\n");
+
+      // TODO(@fuxingloh): supporting streaming later
+      const result = await this.agent.generate({ prompt });
+      const responseMessage: Message = {
+        kind: "message",
+        messageId: randomUUID(),
+        role: "agent",
+        parts: [{ kind: "text", text: result.text }],
+        contextId: requestContext.contextId,
+      };
+
+      eventBus.publish(responseMessage);
+      eventBus.finished();
+    } catch (error) {
+      // Handle errors by publishing an error message
+      const errorMessage: Message = {
+        kind: "message",
+        messageId: randomUUID(),
+        role: "agent",
+        parts: [
+          {
+            kind: "text",
+            text: `Error: ${error instanceof Error ? error.message : "An unknown error occurred"}`,
+          },
+        ],
+        contextId: requestContext.contextId,
+      };
+
+      eventBus.publish(errorMessage);
+      eventBus.finished();
+    }
+  }
+
+  async cancelTask(_taskId: string, eventBus: ExecutionEventBus): Promise<void> {
+    // TODO(@fuxingloh): The ToolLoopAgent doesn't support cancellation, so we just finish
+    eventBus.finished();
+  }
+}
+
+export function getAgentCard(): AgentCard {
+  const config = getAixyzConfig();
+  return {
+    name: config.name,
+    description: config.description,
+    protocolVersion: "0.3.0",
+    version: config.version,
+    url: new URL("/agent", config.url).toString(),
+    capabilities: {
+      streaming: false,
+      pushNotifications: false,
+    },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/plain"],
+    skills: config.skills,
+  };
+}
+
+export function useA2A<TOOLS extends ToolSet = ToolSet>(
+  app: AixyzServer,
+  exports: {
+    default: ToolLoopAgent<never, TOOLS>;
+    accepts?: Accepts;
+  },
+  taskStore: TaskStore = new InMemoryTaskStore(),
+): void {
+  if (!exports.accepts) {
+    // TODO(@fuxingloh): right now we just don't register the agent if accepts is not provided,
+    //  but it might be a better idea to do it in aixyz-cli (aixyz-pack).
+    return;
+  }
+
+  const agentExecutor = new ToolLoopAgentExecutor(exports.default);
+  const requestHandler = new DefaultRequestHandler(getAgentCard(), taskStore, agentExecutor);
+
+  app.express.use(
+    "/.well-known/agent-card.json",
+    agentCardHandler({
+      agentCardProvider: requestHandler,
+    }),
+  );
+
+  if (exports.accepts.scheme === "exact") {
+    app.withX402("POST /agent", exports.accepts);
+  }
+
+  app.express.use(
+    "/agent",
+    jsonRpcHandler({
+      requestHandler,
+      userBuilder: UserBuilder.noAuthentication,
+    }),
+  );
+}

package/server/adapters/mcp.ts

@@ -0,0 +1,100 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Tool } from "ai";
+import express from "express";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { AixyzServer } from "../index";
+import { createPaymentWrapper } from "@x402/mcp";
+import { Accepts, AcceptsX402 } from "../../accepts";
+
+export class AixyzMCP {
+  private registeredTools: Array<{
+    name: string;
+    config: any;
+    handler: any;
+  }> = [];
+
+  constructor(private app: AixyzServer) {}
+
+  private createServer(): McpServer {
+    const server = new McpServer({
+      name: this.app.config.name,
+      version: this.app.config.version,
+    });
+    for (const { name, config, handler } of this.registeredTools) {
+      server.registerTool(name, config, handler);
+    }
+    return server;
+  }
+
+  public async connect() {
+    this.app.express.post("/mcp", express.json(), async (req, res) => {
+      const server = this.createServer();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      });
+
+      await server.connect(transport);
+      await transport.handleRequest(req as unknown as IncomingMessage, res as unknown as ServerResponse, req.body);
+
+      const cleanup = () => {
+        transport.close();
+        server.close();
+      };
+      res.on("finish", cleanup);
+      res.on("close", cleanup);
+    });
+  }
+
+  private async withPayment(accepts: AcceptsX402) {
+    const payments = await this.app.withPaymentRequirements(accepts);
+    return createPaymentWrapper(this.app, {
+      accepts: payments,
+    });
+  }
+
+  async register(
+    name: string,
+    exports: {
+      default: Tool;
+      accepts?: Accepts;
+    },
+  ) {
+    if (!exports.accepts) {
+      // TODO(@fuxingloh): right now we just don't register the agent if accepts is not provided,
+      //  but it might be a better idea to do it in aixyz-cli (aixyz-pack).
+      return;
+    }
+
+    const tool = exports.default;
+    if (!tool.execute) {
+      throw new Error(`Tool "${name}" has no execute function`);
+    }
+
+    // TODO(@fuxingloh): add ext-app support:
+    //  import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+
+    const execute = tool.execute;
+    const config = {
+      description: tool.description,
+      ...(tool.inputSchema && "shape" in tool.inputSchema ? { inputSchema: tool.inputSchema.shape } : {}),
+    };
+
+    const handler = async (args: Record<string, unknown>) => {
+      try {
+        const result = await execute(args, { toolCallId: name, messages: [] });
+        const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return { content: [{ type: "text" as const, text }] };
+      } catch (error) {
+        const text = error instanceof Error ? error.message : "An unknown error occurred";
+        return { content: [{ type: "text" as const, text: `Error: ${text}` }], isError: true };
+      }
+    };
+
+    this.registeredTools.push({
+      name,
+      config,
+      handler: exports.accepts.scheme === "exact" ? (await this.withPayment(exports.accepts))(handler) : handler,
+    });
+  }
+}