aixyz 0.28.0 → 0.29.0

package/README.md

@@ -137,7 +137,7 @@ const server = new AixyzApp();
 await server.withPlugin(new IndexPagePlugin());
 
 // A2A: agent discovery + JSON-RPC endpoint
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 
 // MCP: expose tools to MCP clients
 await server.withPlugin(

package/app/adapters/express.ts

@@ -47,7 +47,7 @@ interface NodeResponse {
  * import * as myTool from "./tools/my-tool";
  *
  * const app = new AixyzApp();
- * await app.withPlugin(new A2APlugin(agent));
+ * await app.withPlugin(new A2APlugin([{ exports: agent }]));
  * await app.withPlugin(new MCPPlugin([{ name: "myTool", exports: myTool }]));
  * await app.initialize();
  *

package/app/index.ts

@@ -5,12 +5,13 @@ import { PaymentGateway } from "./payment/payment";
 import { Network } from "@x402/core/types";
 import { getAixyzConfig } from "@aixyz/config";
 import { loadEnvConfig } from "@next/env";
-import { BasePlugin } from "./plugin";
+import { BasePlugin, type RegisterContext, type InitializeContext } from "./plugin";
 
 // Load .env and .env.production files at runtime (local files are excluded at build time).
 loadEnvConfig(process.cwd());
 
 export { BasePlugin };
+export type { RegisterContext, InitializeContext };
 export type { HttpMethod, RouteHandler, Middleware, RouteEntry };
 
 export interface AixyzAppOptions {
@@ -52,15 +53,32 @@ export class AixyzApp {
       await this.payment.initialize();
     }
 
+    const ctx: InitializeContext = {
+      routes: this.routes,
+      getPlugin: <T extends BasePlugin>(name: string) => this.getPlugin<T>(name),
+      payment: this.payment,
+    };
     for (const plugin of this.plugins) {
-      await plugin.initialize?.(this);
+      await plugin.initialize?.(ctx);
     }
   }
 
-  /** Register a plugin. Calls plugin.register(this) and returns this for chaining. */
+  /** Register a plugin with a scoped RegisterContext that auto-tracks registered routes. */
   async withPlugin<B extends BasePlugin>(plugin: B): Promise<this> {
     this.plugins.push(plugin);
-    await plugin.register(this);
+    // clear registered routes for this plugin before registration, in case of hot reload or multiple registrations
+    plugin.registeredRoutes.clear();
+
+    const ctx: RegisterContext = {
+      route: (method, path, handler, options) => {
+        this.route(method, path, handler, options);
+        const key = this.getRouteKey(method, path);
+        const entry = this.routes.get(key);
+        if (entry) plugin.registeredRoutes.set(key, entry);
+      },
+      use: (mw) => this.use(mw),
+    };
+    await plugin.register?.(ctx);
     return this;
   }
 

package/app/plugin.ts

@@ -1,7 +1,82 @@
-import type { AixyzApp } from "./index";
+import type { HttpMethod, RouteHandler, RouteEntry, Middleware } from "./types";
+import type { AcceptsX402 } from "../accepts";
+import type { PaymentGateway } from "./payment/payment";
 
+/**
+ * Scoped context passed to {@link BasePlugin.register}.
+ *
+ * Intentionally narrow — plugins can only register routes and middleware during
+ * the registration phase. Every `route()` call is automatically tracked in
+ * {@link BasePlugin.registeredRoutes}, so plugins never need to track their own routes.
+ *
+ * This follows the Rollup/Vite plugin context pattern: plugins receive a scoped
+ * interface rather than the full application instance.
+ */
+export interface RegisterContext {
+  /** Register a route on the application. Automatically tracked in `plugin.registeredRoutes`. */
+  route(method: HttpMethod, path: string, handler: RouteHandler, options?: { payment?: AcceptsX402 }): void;
+  /** Append a middleware to the application's middleware chain. */
+  use(middleware: Middleware): void;
+}
+
+/**
+ * Context passed to {@link BasePlugin.initialize}.
+ *
+ * Available after all plugins have registered their routes. Provides read access
+ * to the full route table, other plugins, and the payment gateway — enabling
+ * cross-plugin discovery and late-binding concerns like payment wrapper setup.
+ *
+ * Route registration should happen in `register()`, not `initialize()`.
+ */
+export interface InitializeContext {
+  /** Read-only view of all registered routes across all plugins. */
+  readonly routes: ReadonlyMap<string, RouteEntry>;
+  /** Find a registered plugin by name. Returns `undefined` if not found. */
+  getPlugin<T extends BasePlugin>(name: string): Readonly<T> | undefined;
+  /** Payment gateway instance, if x402 payment is configured. */
+  readonly payment?: PaymentGateway;
+}
+
+/**
+ * Base class for all aixyz plugins.
+ *
+ * Plugins extend `BasePlugin` and implement one or both lifecycle hooks:
+ *
+ * - **`register(ctx)`** — Called by {@link AixyzApp.withPlugin}. Use `ctx.route()` and
+ *   `ctx.use()` to register routes and middleware. Routes registered here are
+ *   automatically tracked in {@link registeredRoutes}.
+ *
+ * - **`initialize(ctx)`** — Called by {@link AixyzApp.initialize} after all plugins
+ *   have registered. Use `ctx.routes`, `ctx.getPlugin()`, and `ctx.payment` for
+ *   cross-plugin discovery and late-binding (e.g., payment wrappers, UI generation).
+ *
+ * Both hooks are optional — a plugin may implement only `register` (most common),
+ * only `initialize`, or both.
+ *
+ * @example
+ * ```ts
+ * class MyPlugin extends BasePlugin {
+ *   readonly name = "my-plugin";
+ *
+ *   register(ctx: RegisterContext) {
+ *     ctx.route("GET", "/health", () => Response.json({ ok: true }));
+ *   }
+ * }
+ * ```
+ */
 export abstract class BasePlugin {
+  /** Unique identifier for this plugin. Used by {@link InitializeContext.getPlugin} for discovery. */
   abstract readonly name: string;
-  abstract register(app: AixyzApp): void | Promise<void>;
-  initialize?(app: AixyzApp): void | Promise<void>;
+
+  /**
+   * Routes registered by this plugin during {@link register}.
+   * Populated automatically by the framework — plugins do not need to manage this.
+   */
+  readonly registeredRoutes = new Map<string, RouteEntry>();
+
+  /** Register routes and middleware. Called once by {@link AixyzApp.withPlugin}. */
+  register?(ctx: RegisterContext): void | Promise<void>;
+
+  /** Late initialization after all plugins have registered. Called once by {@link AixyzApp.initialize}. */
+  initialize?(ctx: InitializeContext): void | Promise<void>;
 }

package/app/plugins/a2a.ts

@@ -12,8 +12,7 @@ import { AgentCard, Message, Task, TaskArtifactUpdateEvent, TaskStatusUpdateEven
 import type { ToolLoopAgent, ToolSet } from "ai";
 import { z } from "zod";
 import { getAixyzConfigRuntime } from "../../config";
-import { BasePlugin } from "../plugin";
-import type { AixyzApp } from "../index";
+import { BasePlugin, type RegisterContext } from "../plugin";
 import { Accepts, AcceptsScheme } from "../../accepts";
 
 export const CapabilitiesSchema = z.object({
@@ -24,6 +23,13 @@ export const CapabilitiesSchema = z.object({
 
 export type Capabilities = z.infer<typeof CapabilitiesSchema>;
 
+export interface A2AAgentEntry {
+  name?: string;
+  exports: { default: ToolLoopAgent; accepts?: Accepts; capabilities?: Capabilities };
+  /** Optional task store override. Defaults to a per-agent InMemoryTaskStore for isolation. */
+  taskStore?: TaskStore;
+}
+
 const DEFAULT_CAPABILITIES: Capabilities = { streaming: true, pushNotifications: false };
 
 /**
@@ -148,52 +154,56 @@ export function getAgentCard(agentPath = "/agent", capabilities?: Capabilities):
 }
 
 /**
- * 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.
+ * A2A protocol plugin. Registers well-known agent card endpoints
+ * and JSON-RPC endpoints for one or more agents.
+ * Routes are only registered for agents that export a valid `accepts` payment config.
  */
-export class A2APlugin<TOOLS extends ToolSet = ToolSet> extends BasePlugin {
+export class A2APlugin extends BasePlugin {
   readonly name = "a2a";
 
-  constructor(
-    private exports: { default: ToolLoopAgent<never, TOOLS>; accepts?: Accepts; capabilities?: Capabilities },
-    private prefix?: string,
-    private taskStore: TaskStore = new InMemoryTaskStore(),
-  ) {
+  constructor(private agents: A2AAgentEntry[]) {
     super();
   }
 
-  register(app: AixyzApp): void {
-    if (this.exports.accepts) {
-      AcceptsScheme.parse(this.exports.accepts);
+  register(ctx: RegisterContext): void {
+    for (const entry of this.agents) {
+      this.registerAgent(ctx, entry);
+    }
+  }
+
+  private registerAgent(ctx: RegisterContext, entry: A2AAgentEntry): void {
+    if (entry.exports.accepts) {
+      const result = AcceptsScheme.safeParse(entry.exports.accepts);
+      if (!result.success) {
+        const id = entry.name ?? "root";
+        throw new Error(`Invalid accepts config for agent "${id}": ${result.error.message}`);
+      }
     } else {
       return;
     }
 
-    const parsed = this.exports.capabilities ? CapabilitiesSchema.safeParse(this.exports.capabilities) : undefined;
+    const parsed = entry.exports.capabilities ? CapabilitiesSchema.safeParse(entry.exports.capabilities) : undefined;
     const capabilities = parsed?.success ? { ...DEFAULT_CAPABILITIES, ...parsed.data } : DEFAULT_CAPABILITIES;
 
-    const agentPath: `/${string}` = this.prefix ? `/${this.prefix}/agent` : "/agent";
-    const wellKnownPath: `/${string}` = this.prefix
-      ? `/${this.prefix}/.well-known/agent-card.json`
+    const prefix = entry.name;
+    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(this.exports.default, capabilities.streaming ?? true);
-    const requestHandler = new DefaultRequestHandler(
-      getAgentCard(agentPath, capabilities),
-      this.taskStore,
-      agentExecutor,
-    );
+    const taskStore = entry.taskStore ?? new InMemoryTaskStore();
+    const agentExecutor = new ToolLoopAgentExecutor(entry.exports.default, capabilities.streaming ?? true);
+    const requestHandler = new DefaultRequestHandler(getAgentCard(agentPath, capabilities), taskStore, agentExecutor);
     const jsonRpcTransport = new JsonRpcTransportHandler(requestHandler);
 
     // Agent card — pure web-standard handler
-    app.route("GET", wellKnownPath, async () => {
+    ctx.route("GET", wellKnownPath, async () => {
       const card = await requestHandler.getAgentCard();
       return Response.json(card);
     });
 
     // JSON-RPC endpoint — pure web-standard handler using JsonRpcTransportHandler
-    app.route(
+    ctx.route(
       "POST",
       agentPath,
       async (request: Request) => {
@@ -240,7 +250,7 @@ export class A2APlugin<TOOLS extends ToolSet = ToolSet> extends BasePlugin {
         return Response.json(result);
       },
       {
-        payment: this.exports.accepts.scheme === "exact" ? this.exports.accepts : undefined,
+        payment: entry.exports.accepts.scheme === "exact" ? entry.exports.accepts : undefined,
       },
     );
   }

package/app/plugins/erc-8004.ts

@@ -6,8 +6,7 @@ import {
   ERC8004_REGISTRATION_TYPE,
   ServiceSchema,
 } from "@aixyz/erc-8004/schemas/registration";
-import { BasePlugin } from "../plugin";
-import type { AixyzApp } from "../index";
+import { BasePlugin, type RegisterContext } from "../plugin";
 
 /**
  * Build an ERC-8004 agent registration file by merging user-provided data with
@@ -49,7 +48,7 @@ export function getAgentRegistrationFile(
   return withDefault.parse(data);
 }
 
-/** ERC-8004 identity plugin. Registers `/.well-known/erc-8004.json` and `/_aixyz/erc-8004.json` routes. */
+/** ERC-8004 identity plugin. Registers the `/_aixyz/erc-8004.json` route. */
 export class ERC8004Plugin extends BasePlugin {
   readonly name = "erc-8004";
 
@@ -57,10 +56,9 @@ export class ERC8004Plugin extends BasePlugin {
     super();
   }
 
-  register(app: AixyzApp): void {
+  register(ctx: RegisterContext): void {
     const file = getAgentRegistrationFile(this.exports.default, this.exports.options);
 
-    app.route("GET", "/.well-known/erc-8004.json", () => Response.json(file));
-    app.route("GET", "/_aixyz/erc-8004.json", () => Response.json(file));
+    ctx.route("GET", "/_aixyz/erc-8004.json", () => Response.json(file));
   }
 }

package/app/plugins/index-page/index.ts

@@ -1,7 +1,6 @@
 import { getAixyzConfigRuntime } from "@aixyz/config";
 import { z } from "zod";
-import { BasePlugin } from "../../plugin";
-import type { AixyzApp } from "../../index";
+import { BasePlugin, type RegisterContext, type InitializeContext } from "../../plugin";
 import type { MCPPlugin } from "../mcp";
 import { renderHtml } from "./html";
 
@@ -111,14 +110,14 @@ export class IndexPagePlugin extends BasePlugin {
     super();
   }
 
-  register(app: AixyzApp): void {
+  register(ctx: RegisterContext): void {
     const config = getAixyzConfigRuntime();
     if (!this.path.startsWith("/")) {
       throw new Error(`Invalid path: ${this.path}. Path must start with "/"`);
     }
 
     // Default to serve markdown, else explicitly asked for HTML (which browsers do by default)
-    app.route("GET", this.path, (request: Request) => {
+    ctx.route("GET", this.path, (request: Request) => {
       if (prefersHtml(request)) {
         return new Response(renderHtml(config, this.protocols), {
           headers: { "Content-Type": "text/html; charset=utf-8", Vary: "Accept" },
@@ -130,11 +129,11 @@ export class IndexPagePlugin extends BasePlugin {
     });
   }
 
-  initialize(app: AixyzApp): void {
+  initialize(ctx: InitializeContext): void {
     const entrypoints: Entrypoint[] = [];
 
     // Detect A2A agents from routes (POST */agent pattern)
-    for (const [key, entry] of app.routes) {
+    for (const [key, entry] of ctx.routes) {
       if (key.startsWith("POST ") && entry.path.endsWith("/agent")) {
         const prefix = entry.path.slice(1, -"/agent".length); // e.g. "" or "foo"
         const name = prefix || "agent";
@@ -148,7 +147,7 @@ export class IndexPagePlugin extends BasePlugin {
     }
 
     // Detect MCP tools from MCPPlugin
-    const mcpPlugin = app.getPlugin<MCPPlugin>("mcp");
+    const mcpPlugin = ctx.getPlugin<MCPPlugin>("mcp");
     if (mcpPlugin?.registeredTools) {
       for (const tool of mcpPlugin.registeredTools) {
         let inputSchema: Record<string, unknown> | undefined;

package/app/plugins/mcp.ts

@@ -2,8 +2,7 @@ import { type Tool } from "ai";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { createPaymentWrapper } from "@x402/mcp";
-import { BasePlugin } from "../plugin";
-import type { AixyzApp } from "../index";
+import { BasePlugin, type RegisterContext, type InitializeContext } from "../plugin";
 import type { Accepts } from "../../accepts";
 import { AcceptsScheme } from "../../accepts";
 import { getAixyzConfig, getAixyzConfigRuntime } from "../../config";
@@ -53,7 +52,7 @@ export class MCPPlugin extends BasePlugin {
     return mcpServer;
   }
 
-  async register(app: AixyzApp): Promise<void> {
+  async register(ctx: RegisterContext): Promise<void> {
     for (const t of this.tools) {
       if (t.exports.accepts) {
         AcceptsScheme.parse(t.exports.accepts);
@@ -74,16 +73,16 @@ export class MCPPlugin extends BasePlugin {
       return transport.handleRequest(request);
     };
 
-    app.route("POST", "/mcp", mcpHandler);
-    app.route("GET", "/mcp", mcpHandler);
-    app.route("DELETE", "/mcp", mcpHandler);
+    ctx.route("POST", "/mcp", mcpHandler);
+    ctx.route("GET", "/mcp", mcpHandler);
+    ctx.route("DELETE", "/mcp", mcpHandler);
   }
 
-  async initialize(app: AixyzApp): Promise<void> {
-    if (!app.payment) return;
+  async initialize(ctx: InitializeContext): Promise<void> {
+    if (!ctx.payment) return;
 
     const config = getAixyzConfig();
-    const resourceServer = app.payment.resourceServer;
+    const resourceServer = ctx.payment.resourceServer;
 
     for (const { name, accepts } of this.registeredTools) {
       if (accepts?.scheme !== "exact") continue;

package/docs/api-reference/aixyz-server.mdx

@@ -73,7 +73,7 @@ server.use(async (request, next) => {
 
 ### `withPlugin(plugin)`
 
-Register a plugin. Calls `plugin.register(this)` and returns `this` for chaining:
+Register a plugin. Creates a scoped `RegisterContext` that auto-tracks routes in `plugin.registeredRoutes`, calls `plugin.register(ctx)`, and returns `this` for chaining:
 
 ```typescript
 await server.withPlugin(new IndexPagePlugin());
@@ -81,7 +81,7 @@ await server.withPlugin(new IndexPagePlugin());
 
 ### `initialize()`
 
-Initialize payment gateway. Must be called after all routes are registered:
+Initialize payment gateway and plugins. Passes an `InitializeContext` with read access to all routes, registered plugins, and payment gateway. Must be called after all plugins are registered:
 
 ```typescript
 await server.initialize();
@@ -98,7 +98,7 @@ import * as agent from "./agent";
 const server = new AixyzApp();
 
 await server.withPlugin(new IndexPagePlugin());
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 
 await server.initialize();
 

package/docs/api-reference/experimental-stripe-payment-intent-plugin.mdx

@@ -77,7 +77,7 @@ await server.withPlugin(new IndexPagePlugin());
 // Register Stripe before other plugins so the Stripe middleware runs first
 await server.withPlugin(new experimental_StripePaymentIntentPlugin());
 
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 
 await server.initialize();
 

package/docs/getting-started/agent-and-tools.mdx

@@ -176,7 +176,7 @@ import * as lookup from "./tools/lookup";
 const server = new AixyzApp();
 
 await server.withPlugin(new IndexPagePlugin());
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 await server.withPlugin(
   new MCPPlugin([
     {

package/docs/protocols/a2a.mdx

@@ -94,7 +94,7 @@ import { A2APlugin } from "aixyz/app/plugins/a2a";
 
 // agentExports is `import * as agent from "./agent"`
 // reads `default` (the ToolLoopAgent), `accepts` (payment config), and `capabilities`
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 ```
 
 This registers:
@@ -104,18 +104,22 @@ This registers:
 
 ### Sub-Agent Routing
 
-Pass an optional `prefix` argument to mount a sub-agent under its own path:
+Pass multiple entries with a `name` to mount sub-agents under their own paths:
 
 ```typescript title="app/server.ts"
 import * as research from "./agents/research";
 import * as implement from "./agents/implement";
 
-await server.withPlugin(new A2APlugin(agent)); // → /agent
-await server.withPlugin(new A2APlugin(research, "research")); // → /research/agent
-await server.withPlugin(new A2APlugin(implement, "implement")); // → /implement/agent
+await server.withPlugin(
+  new A2APlugin([
+    { exports: agent }, // → /agent
+    { name: "research", exports: research }, // → /research/agent
+    { name: "implement", exports: implement }, // → /implement/agent
+  ]),
+);
 ```
 
-Each sub-agent gets its own agent card at `/{prefix}/.well-known/agent-card.json` and its own JSON-RPC endpoint at `/{prefix}/agent`. When using `app/agents/`, the build pipeline generates these calls automatically.
+Each sub-agent gets its own agent card at `/{name}/.well-known/agent-card.json` and its own JSON-RPC endpoint at `/{name}/agent`. When using `app/agents/`, the build pipeline generates these calls automatically.
 
 ## Payment Integration
 

package/docs/protocols/erc-8004.mdx

@@ -33,7 +33,6 @@ export default metadata;
 When this file exists, the build pipeline automatically exposes two endpoints:
 
 - `GET /_aixyz/erc-8004.json`
-- `GET /.well-known/erc-8004.json`
 
 These serve the full agent registration file, merging defaults from `aixyz.config.ts` (name, description, image, services).
 

package/docs/templates/advanced/with-custom-server.mdx

@@ -42,7 +42,7 @@ import lookup from "./tools/lookup";
 const server = new AixyzApp();
 
 await server.withPlugin(new IndexPagePlugin());
-await server.withPlugin(new A2APlugin(agent));
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
 await server.withPlugin(
   new MCPPlugin([
     {

package/docs/templates/advanced/with-express.mdx

@@ -47,7 +47,7 @@ import * as premiumTemperature from "./tools/premium-temperature";
 // 1. Create AixyzApp with plugins
 const app = new AixyzApp(facilitator ? { facilitators: facilitator } : undefined);
 await app.withPlugin(new IndexPagePlugin());
-await app.withPlugin(new A2APlugin(agent));
+await app.withPlugin(new A2APlugin([{ exports: agent }]));
 await app.withPlugin(
   new MCPPlugin([
     { name: "convertTemperature", exports: convertTemperature },

package/examples/with-express/app/server.ts

@@ -13,7 +13,7 @@ import * as premiumTemperature from "./tools/premium-temperature";
 // 1. Create AixyzApp with plugins
 const app = new AixyzApp(facilitator ? { facilitators: facilitator } : undefined);
 await app.withPlugin(new IndexPagePlugin());
-await app.withPlugin(new A2APlugin(agent));
+await app.withPlugin(new A2APlugin([{ exports: agent }]));
 await app.withPlugin(
   new MCPPlugin([
     { name: "convertTemperature", exports: convertTemperature },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aixyz",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Payment-native SDK for AI Agent",
   "keywords": [
     "ai",
@@ -40,9 +40,9 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.10",
-    "@aixyz/cli": "0.28.0",
-    "@aixyz/config": "0.28.0",
-    "@aixyz/erc-8004": "0.28.0",
+    "@aixyz/cli": "0.29.0",
+    "@aixyz/config": "0.29.0",
+    "@aixyz/erc-8004": "0.29.0",
     "@kitajs/html": "^4.2.13",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@next/env": "^16.1.6",