aixyz 0.27.1 → 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/accepts.mdx

@@ -0,0 +1,116 @@
+---
+title: "aixyz/accepts"
+description: "Payment configuration types and facilitator client for x402 gating"
+---
+
+Types and utilities for configuring x402 payment gating on agent and tool endpoints.
+
+```typescript
+import type { Accepts, AcceptsX402, AcceptsFree } from "aixyz/accepts";
+import { HTTPFacilitatorClient, facilitator } from "aixyz/accepts";
+```
+
+## Types
+
+### `Accepts`
+
+Union type for payment configuration:
+
+```typescript
+type Accepts = AcceptsX402 | AcceptsFree;
+```
+
+### `AcceptsX402`
+
+Requires x402 exact payment:
+
+```typescript
+type AcceptsX402 = {
+  scheme: "exact";
+  price: string; // USD string, e.g. "$0.005"
+  network?: string; // CAIP-2 chain ID, overrides config
+  payTo?: string; // EVM address, overrides config
+};
+```
+
+| Field     | Type     | Required | Description                                                   |
+| --------- | -------- | -------- | ------------------------------------------------------------- |
+| `scheme`  | `string` | Yes      | Must be `"exact"`                                             |
+| `price`   | `string` | Yes      | USD price string (e.g. `"$0.005"`)                            |
+| `network` | `string` | No       | CAIP-2 chain ID, overrides `x402.network` from config         |
+| `payTo`   | `string` | No       | EVM address to receive payment, overrides `x402.payTo` config |
+
+### `AcceptsFree`
+
+No payment required:
+
+```typescript
+type AcceptsFree = {
+  scheme: "free";
+};
+```
+
+## Exports
+
+### `HTTPFacilitatorClient`
+
+Client for communicating with an x402 facilitator service. Re-exported from `@x402/core/server`.
+
+```typescript
+import { HTTPFacilitatorClient } from "aixyz/accepts";
+
+const client = new HTTPFacilitatorClient({
+  url: "https://x402.use-agently.com/facilitator",
+});
+```
+
+### `facilitator`
+
+The default facilitator client used by `AixyzApp`. Points to the Agently-hosted x402 facilitator.
+
+```typescript
+import { facilitator } from "aixyz/accepts";
+```
+
+### `AcceptsScheme`
+
+Zod schema for validating `Accepts` objects at runtime:
+
+```typescript
+import { AcceptsScheme } from "aixyz/accepts";
+
+AcceptsScheme.parse({ scheme: "exact", price: "$0.005" });
+```
+
+## Usage
+
+Agents and tools declare an `accepts` export to control x402 payment gating. Endpoints without `accepts` are **not registered**.
+
+```typescript title="app/agent.ts"
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = {
+  scheme: "exact",
+  price: "$0.005",
+};
+```
+
+```typescript title="app/tools/lookup.ts"
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = {
+  scheme: "free",
+};
+```
+
+### Custom facilitator
+
+Create `app/accepts.ts` to override the default facilitator:
+
+```typescript title="app/accepts.ts"
+import { HTTPFacilitatorClient } from "aixyz/accepts";
+
+export const facilitator = new HTTPFacilitatorClient({
+  url: process.env.X402_FACILITATOR_URL ?? "https://x402.use-agently.com/facilitator",
+});
+```

package/docs/api-reference/agent.mdx

@@ -0,0 +1,63 @@
+---
+title: "agent.ts"
+description: "Define your agent with Vercel AI SDK"
+---
+
+The agent definition file. Must export a default `ToolLoopAgent` and optionally `accepts` for payment gating and `capabilities` for A2A agent card configuration.
+
+```typescript title="app/agent.ts"
+import { openai } from "@ai-sdk/openai";
+import { stepCountIs, ToolLoopAgent } from "ai";
+import type { Accepts } from "aixyz/accepts";
+import type { Capabilities } from "aixyz/app/plugins/a2a";
+import weather from "./tools/weather";
+
+export const accepts: Accepts = {
+  scheme: "exact",
+  price: "$0.005",
+};
+
+export const capabilities: Capabilities = {
+  streaming: false,
+  pushNotifications: false,
+};
+
+export default new ToolLoopAgent({
+  model: openai("gpt-4o-mini"),
+  instructions: "You are a helpful weather assistant.",
+  tools: { weather },
+  stopWhen: stepCountIs(10),
+});
+```
+
+## Exports
+
+| Export         | Type            | Required | Description                                                         |
+| -------------- | --------------- | -------- | ------------------------------------------------------------------- |
+| `default`      | `ToolLoopAgent` | Yes      | The agent instance                                                  |
+| `accepts`      | `Accepts`       | No       | Payment config — gates the A2A `/agent` route                       |
+| `capabilities` | `Capabilities`  | No       | A2A capabilities — controls streaming and push notification support |
+
+When `accepts` is exported, the `/agent` endpoint requires x402 payment. Without it, the agent is not registered on the A2A endpoint.
+
+## Capabilities
+
+The optional `capabilities` export controls the A2A agent card's `capabilities` field and the executor's behavior:
+
+```typescript
+import type { Capabilities } from "aixyz/app/plugins/a2a";
+
+export const capabilities: Capabilities = {
+  streaming: false, // default: true
+  pushNotifications: false, // default: false
+  stateTransitionHistory: false, // default: undefined
+};
+```
+
+| Field                    | Type      | Default     | Description                                          |
+| ------------------------ | --------- | ----------- | ---------------------------------------------------- |
+| `streaming`              | `boolean` | `true`      | Whether the agent streams responses via `textStream` |
+| `pushNotifications`      | `boolean` | `false`     | Whether the agent supports push notifications        |
+| `stateTransitionHistory` | `boolean` | `undefined` | Whether the agent exposes state transition history   |
+
+When `streaming` is set to `false`, the executor uses `agent.generate()` instead of `agent.stream()`, returning the full response as a single artifact rather than streaming chunks. This is useful for agents backed by models or APIs that don't support streaming.

package/docs/api-reference/agents.mdx

@@ -0,0 +1,54 @@
+---
+title: "agents/[name].ts"
+description: "Auto-discovered sub-agent definitions for multiple A2A endpoints"
+---
+
+Each `.ts` file in `app/agents/` is auto-discovered and registered as a sub-agent on its own A2A endpoint.
+
+```typescript title="app/agents/research.ts"
+import { openai } from "@ai-sdk/openai";
+import { stepCountIs, ToolLoopAgent } from "ai";
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = {
+  scheme: "exact",
+  price: "$0.005",
+};
+
+export default new ToolLoopAgent({
+  model: openai("gpt-4o-mini"),
+  instructions: "You are a research assistant specialized in finding and summarizing information.",
+  stopWhen: stepCountIs(10),
+});
+```
+
+Given the file `app/agents/research.ts`, the sub-agent is exposed at `/research/agent` with its agent card at `/research/.well-known/agent-card.json`.
+
+## Exports
+
+| Export    | Type            | Required | Description                                                 |
+| --------- | --------------- | -------- | ----------------------------------------------------------- |
+| `default` | `ToolLoopAgent` | Yes      | The agent instance                                          |
+| `accepts` | `Accepts`       | No       | Payment config — gates the sub-agent A2A endpoint with x402 |
+
+When `accepts` is exported, the sub-agent endpoint requires x402 payment. Without it, the sub-agent is not registered.
+
+## Conventions
+
+- **Auto-discovered** — All `.ts` files in `app/agents/` are registered automatically
+- **Ignored files** — Files starting with `_` (e.g., `_helpers.ts`) are skipped
+- **Routing** — The filename (without `.ts`) becomes the URL prefix (e.g., `research.ts` → `/research/agent`)
+
+## Multiple Sub-Agents
+
+You can mix `app/agent.ts` (main agent) with `app/agents/` (sub-agents) in the same project:
+
+```
+app/
+  agent.ts           # → /agent
+  agents/
+    research.ts      # → /research/agent
+    implement.ts     # → /implement/agent
+```
+
+This exposes three independent A2A endpoints from a single deployment.