aixyz 0.20.0 → 0.22.0

package/accepts.ts

@@ -6,6 +6,7 @@ export type Accepts = AcceptsX402 | AcceptsFree;
 export type AcceptsX402 = {
   scheme: "exact";
   price: string;
+  // TODO(kevin): update type to Network (`string:string`)
   network?: string;
   payTo?: string;
 };

package/app/adapters/express.ts

@@ -0,0 +1,129 @@
+import type { IncomingMessage } from "node:http";
+import type { AixyzApp } from "../index";
+
+/** Minimal request shape compatible with both Node's IncomingMessage and Express's Request. */
+interface NodeRequest {
+  headers: IncomingMessage["headers"];
+  url?: string;
+  method?: string;
+}
+
+/** Minimal response shape compatible with both Node's ServerResponse and Express's Response. */
+interface NodeResponse {
+  writeHead(statusCode: number, headers?: Record<string, string>): this;
+  write(chunk: unknown): boolean;
+  end(): this;
+}
+
+/**
+ * Converts an {@link AixyzApp} into Express-compatible middleware.
+ *
+ * This adapter bridges the web-standard `Request`/`Response` API used by
+ * `AixyzApp` with Express's Node-style `(req, res, next)` middleware signature.
+ * Incoming Express requests are converted to web-standard `Request` objects,
+ * routed through `app.fetch()`, and the resulting `Response` is streamed back
+ * to the Express response. If the `AixyzApp` does not match the request
+ * (404), control is passed to the next Express middleware via `next()`.
+ *
+ * The returned middleware handles all AixyzApp concerns — A2A, MCP, x402
+ * payment verification, and any registered plugins — so you can mount it
+ * alongside your own Express routes without conflict.
+ *
+ * **Important:** Do not apply `express.json()` or other body-parsing middleware
+ * before this middleware, as it needs access to the raw request body stream.
+ *
+ * @param app - A fully initialized {@link AixyzApp} instance (call
+ *   `app.initialize()` before passing it here).
+ * @returns An async Express middleware function `(req, res, next) => void`.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { AixyzApp } from "aixyz/app";
+ * import { toExpressMiddleware } from "aixyz/app/adapters/express";
+ * import { A2APlugin } from "aixyz/app/plugins/a2a";
+ * import { MCPPlugin } from "aixyz/app/plugins/mcp";
+ * import * as agent from "./agent";
+ * import * as myTool from "./tools/my-tool";
+ *
+ * const app = new AixyzApp();
+ * await app.withPlugin(new A2APlugin(agent));
+ * await app.withPlugin(new MCPPlugin([{ name: "myTool", exports: myTool }]));
+ * await app.initialize();
+ *
+ * const server = express();
+ *
+ * // Your own Express routes
+ * server.get("/health", (_req, res) => res.json({ status: "ok" }));
+ *
+ * // Mount AixyzApp (handles /agent, /mcp, /.well-known/agent-card.json, etc.)
+ * server.use(toExpressMiddleware(app));
+ *
+ * server.listen(3000);
+ * ```
+ */
+export function toExpressMiddleware(app: AixyzApp) {
+  return async (req: NodeRequest, res: NodeResponse, next: (err?: unknown) => void) => {
+    try {
+      const request = toWebRequest(req);
+      const response = await app.fetch(request);
+
+      // Let Express handle unmatched routes
+      if (response.status === 404) {
+        return next();
+      }
+
+      await writeResponse(response, res);
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+function toWebRequest(req: NodeRequest): Request {
+  const protocol = (req.headers["x-forwarded-proto"] as string) || "http";
+  const host = req.headers.host || "localhost";
+  const url = `${protocol}://${host}${req.url || "/"}`;
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(key, v);
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  const method = (req.method || "GET").toUpperCase();
+  const hasBody = method !== "GET" && method !== "HEAD";
+
+  return new Request(url, {
+    method,
+    headers,
+    body: hasBody ? (req as unknown as ReadableStream) : undefined,
+    // @ts-expect-error -- Node 18+ supports duplex on RequestInit
+    duplex: hasBody ? "half" : undefined,
+  });
+}
+
+async function writeResponse(response: Response, res: NodeResponse): Promise<void> {
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+
+  if (!response.body) {
+    res.end();
+    return;
+  }
+
+  const reader = response.body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+    res.end();
+  }
+}

package/app/index.ts

@@ -0,0 +1,138 @@
+import type { AcceptsX402 } from "../accepts";
+import type { FacilitatorClient } from "@x402/core/server";
+import { type HttpMethod, type RouteHandler, type Middleware, type RouteEntry } from "./types";
+import { PaymentGateway } from "./payment/payment";
+import { Network } from "@x402/core/types";
+import { getAixyzConfig } from "@aixyz/config";
+import { BasePlugin } from "./plugin";
+
+export { BasePlugin };
+export type { HttpMethod, RouteHandler, Middleware, RouteEntry };
+
+export interface AixyzAppOptions {
+  facilitators?: FacilitatorClient | FacilitatorClient[];
+}
+
+/**
+ * Framework-agnostic route and middleware registry with optional x402 payment gating.
+ * Call `fetch()` to dispatch a web-standard Request through payment verification, middleware, and route handler.
+ */
+export class AixyzApp {
+  readonly routes = new Map<string, RouteEntry>();
+  readonly payment?: PaymentGateway;
+  private middlewares: Middleware[] = [];
+  private plugins: BasePlugin[] = [];
+  private readonly poweredByHeader: boolean;
+
+  constructor(options?: AixyzAppOptions) {
+    // TODO(future): getAiXyzConfig will be materialized.
+    //  this is internal, we control it so it's fine for us to use—but we changing it in the future.
+    const config = getAixyzConfig();
+    this.poweredByHeader = config.build.poweredByHeader;
+
+    if (options?.facilitators) {
+      this.payment = new PaymentGateway(options.facilitators, config);
+      this.payment.register((config.x402.network as Network) ?? "eip155:8453");
+    }
+  }
+
+  /** Initialize payment gateway and plugins. Must be called after all routes are registered. */
+  async initialize(): Promise<void> {
+    if (this.payment) {
+      // Register payment routes with the gateway before initializing
+      for (const [, entry] of this.routes) {
+        if (entry.payment) {
+          this.payment.addRoute(entry.method, entry.path, entry.payment);
+        }
+      }
+      await this.payment.initialize();
+    }
+
+    for (const plugin of this.plugins) {
+      await plugin.initialize?.(this);
+    }
+  }
+
+  /** Register a plugin. Calls plugin.register(this) and returns this for chaining. */
+  async withPlugin<B extends BasePlugin>(plugin: B): Promise<this> {
+    this.plugins.push(plugin);
+    await plugin.register(this);
+    return this;
+  }
+
+  /** Returns the canonical lookup key for a route (e.g. "POST /agent"). */
+  getRouteKey(method: HttpMethod, path: string) {
+    return `${method} ${path}`;
+  }
+
+  /** Register a route with an optional x402 payment requirement. */
+  route(method: HttpMethod, path: string, handler: RouteHandler, options?: { payment?: AcceptsX402 }): void {
+    const key = this.getRouteKey(method, path);
+    this.routes.set(key, {
+      method,
+      path,
+      handler,
+      payment: options?.payment,
+    });
+  }
+
+  /** Append a middleware to the chain. Middlewares run in registration order before the route handler. */
+  use(middleware: Middleware): void {
+    this.middlewares.push(middleware);
+  }
+
+  /** Returns the registered middlewares (read-only access for adapters). */
+  getMiddlewares(): Middleware[] {
+    return this.middlewares;
+  }
+
+  /** Dispatch a web-standard Request through payment verification, middleware, and route handler. */
+  fetch = async (request: Request): Promise<Response> => {
+    const response = await this.dispatch(request);
+    if (this.poweredByHeader) {
+      response.headers.set("X-Powered-By", "aixyz");
+    }
+    return response;
+  };
+
+  private dispatch = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const key = this.getRouteKey(request.method as HttpMethod, url.pathname);
+    const entry = this.routes.get(key);
+
+    if (!entry) {
+      return new Response("Not Found", { status: 404 });
+    }
+
+    if (entry.payment && this.payment) {
+      const rejection = await this.payment.verify(request);
+      if (rejection) return rejection;
+    }
+
+    let index = 0;
+    const middlewares = this.middlewares;
+    const handler = entry.handler;
+
+    const next = async (): Promise<Response> => {
+      if (index < middlewares.length) {
+        const mw = middlewares[index++];
+        return mw(request, next);
+      }
+      return handler(request);
+    };
+
+    const response = await next();
+
+    if (entry.payment && this.payment) {
+      const settlementResult = await this.payment.settle(request);
+      if (settlementResult?.success) {
+        const paymentResultHeader = settlementResult.headers["PAYMENT-RESPONSE"];
+        const cloned = new Response(response.body, response);
+        cloned.headers.set("PAYMENT-RESPONSE", paymentResultHeader);
+        return cloned;
+      }
+    }
+
+    return response;
+  };
+}

package/app/payment/payment.ts

@@ -0,0 +1,157 @@
+import { FacilitatorClient, ProcessSettleResultResponse, x402ResourceServer } from "@x402/core/server";
+import {
+  x402HTTPResourceServer,
+  type HTTPAdapter,
+  type HTTPRequestContext,
+  type RoutesConfig,
+  type RouteConfig,
+  type HTTPResponseInstructions,
+} from "@x402/core/http";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import type { AcceptsX402 } from "../../accepts";
+import { Network, PaymentPayload, PaymentRequirements } from "@x402/core/types";
+import { AixyzConfig } from "@aixyz/config";
+
+/**
+ * Converts a web-standard Request into the x402 HTTPAdapter interface.
+ */
+function toHTTPAdapter(request: Request): HTTPAdapter {
+  const url = new URL(request.url);
+  return {
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+    getMethod: () => request.method,
+    getPath: () => url.pathname,
+    getUrl: () => request.url,
+    getAcceptHeader: () => request.headers.get("accept") ?? "",
+    getUserAgent: () => request.headers.get("user-agent") ?? "",
+    getQueryParams: () => Object.fromEntries(url.searchParams),
+    getQueryParam: (name) => url.searchParams.get(name) ?? undefined,
+  };
+}
+
+/**
+ * Converts x402 HTTPResponseInstructions into a web-standard Response.
+ */
+function toResponse(instructions: HTTPResponseInstructions): Response {
+  const headers = new Headers(instructions.headers);
+  let body: string | undefined;
+  if (instructions.body != null) {
+    body = instructions.isHtml ? String(instructions.body) : JSON.stringify(instructions.body);
+  }
+  if (body && !headers.has("content-type")) {
+    headers.set("content-type", instructions.isHtml ? "text/html" : "application/json");
+  }
+  return new Response(body, { status: instructions.status, headers });
+}
+
+interface PaymentContext {
+  paymentPayload: PaymentPayload;
+  paymentRequirements: PaymentRequirements;
+  declaredExtensions?: Record<string, unknown>;
+}
+
+/**
+ * Thin wrapper around x402HTTPResourceServer
+ */
+export class PaymentGateway {
+  readonly resourceServer: x402ResourceServer;
+  private httpServer?: x402HTTPResourceServer;
+  private readonly config: AixyzConfig;
+  private readonly pendingRoutes = new Map<string, RouteConfig>();
+  private readonly verifiedPayments = new WeakMap<Request, PaymentContext>();
+
+  constructor(facilitators: FacilitatorClient | FacilitatorClient[], config: AixyzConfig) {
+    this.resourceServer = new x402ResourceServer(facilitators);
+    this.config = config;
+  }
+
+  /** Register an EVM payment scheme for the given network (e.g. Base mainnet). */
+  register(network: Network) {
+    this.resourceServer.register(network, new ExactEvmScheme());
+  }
+
+  /** Returns the canonical lookup key for a payment route (e.g. "POST /agent"). */
+  getRouteKey(method: string, path: string) {
+    return `${method.toUpperCase()} ${path}`;
+  }
+
+  /**
+   * Add a payment-gated route. Must be called before initialize().
+   */
+  addRoute(method: string, path: string, accepts: AcceptsX402): void {
+    const pattern = this.getRouteKey(method, path);
+    this.pendingRoutes.set(pattern, {
+      accepts: {
+        scheme: accepts.scheme,
+        payTo: accepts.payTo ?? this.config.x402.payTo,
+        price: accepts.price,
+        network: (accepts.network as Network) ?? (this.config.x402.network as Network),
+      },
+    });
+  }
+
+  /**
+   * Initialize the payment gateway. Builds the x402HTTPResourceServer from registered routes.
+   * Must be called after all routes are added.
+   */
+  async initialize(): Promise<void> {
+    const routes: RoutesConfig =
+      this.pendingRoutes.size > 0 ? Object.fromEntries(this.pendingRoutes) : { "* /*": { accepts: [] } };
+    this.httpServer = new x402HTTPResourceServer(this.resourceServer, routes);
+    await this.httpServer.initialize();
+  }
+
+  /**
+   * Verify payment for a request. Returns a 402 Response if payment is required/invalid,
+   * or null if the request is authorized to proceed.
+   */
+  async verify(request: Request): Promise<Response | null> {
+    if (!this.httpServer) {
+      throw new Error("PaymentGateway not initialized. Call initialize() first.");
+    }
+
+    const adapter = toHTTPAdapter(request);
+    const context: HTTPRequestContext = {
+      adapter,
+      path: adapter.getPath(),
+      method: adapter.getMethod(),
+      paymentHeader: adapter.getHeader("payment-signature") || adapter.getHeader("PAYMENT-SIGNATURE"),
+    };
+
+    const result = await this.httpServer.processHTTPRequest(context);
+
+    switch (result.type) {
+      case "no-payment-required":
+        return null;
+
+      case "payment-verified":
+        this.verifiedPayments.set(request, {
+          paymentPayload: result.paymentPayload,
+          paymentRequirements: result.paymentRequirements,
+          declaredExtensions: result.declaredExtensions,
+        });
+        return null;
+
+      case "payment-error":
+        return toResponse(result.response);
+    }
+  }
+
+  /**
+   * Settle a previously verified payment. Call after the handler responds successfully.
+   * Returns settlement headers to merge into the response, or null if nothing to settle.
+   */
+  async settle(request: Request): Promise<ProcessSettleResultResponse | null> {
+    const ctx = this.verifiedPayments.get(request);
+    if (!ctx || !this.httpServer) return null;
+    this.verifiedPayments.delete(request);
+
+    const result = await this.httpServer.processSettlement(
+      ctx.paymentPayload,
+      ctx.paymentRequirements,
+      ctx.declaredExtensions,
+    );
+
+    return result;
+  }
+}

package/app/plugin.ts

@@ -0,0 +1,7 @@
+import type { AixyzApp } from "./index";
+
+export abstract class BasePlugin {
+  abstract readonly name: string;
+  abstract register(app: AixyzApp): void | Promise<void>;
+  initialize?(app: AixyzApp): void | Promise<void>;
+}

package/{server/adapters → app/plugins}/a2a.ts

@@ -4,28 +4,30 @@ import {
   DefaultRequestHandler,
   ExecutionEventBus,
   InMemoryTaskStore,
+  JsonRpcTransportHandler,
   RequestContext,
   TaskStore,
 } from "@a2a-js/sdk/server";
 import { AgentCard, Message, Task, TaskArtifactUpdateEvent, TaskStatusUpdateEvent, TextPart } from "@a2a-js/sdk";
 import type { ToolLoopAgent, ToolSet } from "ai";
 import { getAixyzConfigRuntime } from "../../config";
-import { AixyzServer } from "../index";
-import { agentCardHandler, jsonRpcHandler, UserBuilder } from "@a2a-js/sdk/server/express";
+import { BasePlugin } from "../plugin";
+import type { AixyzApp } from "../index";
 import { Accepts, AcceptsScheme } from "../../accepts";
 
+/**
+ * Wraps a Vercel AI SDK ToolLoopAgent into the A2A AgentExecutor interface.
+ * Streams text chunks as artifact updates and publishes task lifecycle events.
+ */
 export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements AgentExecutor {
   constructor(private agent: ToolLoopAgent<never, TOOLS>) {}
 
   async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
     const { taskId, contextId, userMessage, task } = requestContext;
     try {
-      // Extract the user's message text
       const textParts = userMessage.parts.filter((part): part is TextPart => part.kind === "text");
       const prompt = textParts.map((part) => part.text).join("\n");
 
-      // Publish the initial Task object if one does not exist yet — required by ResultManager
-      // before any TaskArtifactUpdateEvent can be processed.
       if (!task) {
         const initialTask: Task = {
           kind: "task",
@@ -37,7 +39,6 @@ export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements A
         eventBus.publish(initialTask);
       }
 
-      // Signal that the agent is working
       const workingUpdate: TaskStatusUpdateEvent = {
         kind: "status-update",
         taskId,
@@ -47,7 +48,6 @@ export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements A
       };
       eventBus.publish(workingUpdate);
 
-      // Stream the response and publish artifact chunks as they arrive
       const result = await this.agent.stream({ prompt });
       const artifactId = randomUUID();
       let firstChunk = true;
@@ -69,7 +69,6 @@ export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements A
         }
       }
 
-      // Publish the final completed status
       const completedUpdate: TaskStatusUpdateEvent = {
         kind: "status-update",
         taskId,
@@ -80,7 +79,6 @@ export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements A
       eventBus.publish(completedUpdate);
       eventBus.finished();
     } catch (error) {
-      // Handle errors by publishing an error message
       const errorMessage: Message = {
         kind: "message",
         messageId: randomUUID(),
@@ -93,18 +91,17 @@ export class ToolLoopAgentExecutor<TOOLS extends ToolSet = ToolSet> implements A
         ],
         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();
   }
 }
 
+/** Build an A2A AgentCard from the runtime config, pointing to the given agent endpoint path. */
 export function getAgentCard(agentPath = "/agent"): AgentCard {
   const config = getAixyzConfigRuntime();
   return {
@@ -113,58 +110,73 @@ export function getAgentCard(agentPath = "/agent"): AgentCard {
     protocolVersion: "0.3.0",
     version: config.version,
     url: new URL(agentPath, config.url).toString(),
-    capabilities: {
-      streaming: true,
-      pushNotifications: false,
-    },
+    capabilities: { streaming: true, 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;
-  },
-  prefix?: string,
-  taskStore: TaskStore = new InMemoryTaskStore(),
-): void {
-  if (exports.accepts) {
-    // TODO(@fuxingloh): validation should be done at build stage
-    AcceptsScheme.parse(exports.accepts);
-  } else {
-    // 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;
+/**
+ * A2A protocol plugin. Registers the well-known agent card endpoint
+ * and a JSON-RPC endpoint that delegates to the given ToolLoopAgent.
+ * Routes are only registered if the agent exports a valid `accepts` payment config.
+ */
+export class A2APlugin<TOOLS extends ToolSet = ToolSet> extends BasePlugin {
+  readonly name = "a2a";
+
+  constructor(
+    private exports: { default: ToolLoopAgent<never, TOOLS>; accepts?: Accepts },
+    private prefix?: string,
+    private taskStore: TaskStore = new InMemoryTaskStore(),
+  ) {
+    super();
   }
 
-  const agentPath: `/${string}` = prefix ? `/${prefix}/agent` : "/agent";
-  const wellKnownPath: `/${string}` = prefix
-    ? `/${prefix}/.well-known/agent-card.json`
-    : "/.well-known/agent-card.json";
-
-  const agentExecutor = new ToolLoopAgentExecutor(exports.default);
-  const requestHandler = new DefaultRequestHandler(getAgentCard(agentPath), taskStore, agentExecutor);
+  register(app: AixyzApp): void {
+    if (this.exports.accepts) {
+      AcceptsScheme.parse(this.exports.accepts);
+    } else {
+      return;
+    }
 
-  app.express.use(
-    wellKnownPath,
-    agentCardHandler({
-      agentCardProvider: requestHandler,
-    }),
-  );
+    const agentPath: `/${string}` = this.prefix ? `/${this.prefix}/agent` : "/agent";
+    const wellKnownPath: `/${string}` = this.prefix
+      ? `/${this.prefix}/.well-known/agent-card.json`
+      : "/.well-known/agent-card.json";
+
+    const agentExecutor = new ToolLoopAgentExecutor(this.exports.default);
+    const requestHandler = new DefaultRequestHandler(getAgentCard(agentPath), this.taskStore, agentExecutor);
+    const jsonRpcTransport = new JsonRpcTransportHandler(requestHandler);
+
+    // Agent card — pure web-standard handler
+    app.route("GET", wellKnownPath, async () => {
+      const card = await requestHandler.getAgentCard();
+      return Response.json(card);
+    });
+
+    // JSON-RPC endpoint — pure web-standard handler using JsonRpcTransportHandler
+    app.route(
+      "POST",
+      agentPath,
+      async (request: Request) => {
+        const body = await request.json();
+        const result = await jsonRpcTransport.handle(body);
+
+        // If result is an AsyncGenerator (streaming), collect all chunks
+        if (Symbol.asyncIterator in Object(result)) {
+          const chunks: unknown[] = [];
+          for await (const chunk of result as AsyncGenerator) {
+            chunks.push(chunk);
+          }
+          return Response.json(chunks[chunks.length - 1]);
+        }
 
-  if (exports.accepts.scheme === "exact") {
-    app.withX402Exact(`POST ${agentPath}`, exports.accepts);
+        return Response.json(result);
+      },
+      {
+        payment: this.exports.accepts.scheme === "exact" ? this.exports.accepts : undefined,
+      },
+    );
   }
-
-  app.express.use(
-    agentPath,
-    jsonRpcHandler({
-      requestHandler,
-      userBuilder: UserBuilder.noAuthentication,
-    }),
-  );
 }