aixyz 0.27.1 → 0.29.0

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

@@ -0,0 +1,105 @@
+---
+title: "aixyz/config"
+description: "Agent configuration types and runtime config access"
+---
+
+Provides the `AixyzConfig` type and functions to access your agent's configuration at runtime.
+
+```typescript
+import type { AixyzConfig, AixyzConfigRuntime } from "aixyz/config";
+import { getAixyzConfig, getAixyzConfigRuntime } from "aixyz/config";
+```
+
+## Types
+
+### `AixyzConfig`
+
+The full configuration object parsed from `aixyz.config.ts`:
+
+```typescript
+type AixyzConfig = {
+  name: string;
+  description: string;
+  version: string;
+  url?: string;
+  x402: {
+    payTo: string;
+    network: string; // CAIP-2 chain ID
+  };
+  build?: {
+    output?: "standalone" | "vercel";
+    includes?: string | string[];
+    excludes?: string | string[];
+  };
+  skills?: Skill[];
+};
+```
+
+### `AixyzConfigRuntime`
+
+The subset of config safe to access at runtime (excludes `x402` and `build`):
+
+```typescript
+type AixyzConfigRuntime = {
+  name: string;
+  description: string;
+  version: string;
+  url: string;
+  skills: Skill[];
+};
+```
+
+## Functions
+
+### `getAixyzConfig()`
+
+Returns the full parsed config. Intended for build-time and CLI use.
+
+```typescript
+const config = getAixyzConfig();
+console.log(config.x402.payTo);
+```
+
+### `getAixyzConfigRuntime()`
+
+Returns the runtime-safe subset of the config. Use this in your server code.
+
+```typescript
+const config = getAixyzConfigRuntime();
+console.log(config.name, config.version);
+```
+
+## Under the hood: materialization
+
+When you run `aixyz build` or `aixyz dev`, the config is **materialized** into the bundle at build time. This means `getAixyzConfig()` and `getAixyzConfigRuntime()` don't read from the filesystem at runtime — they return a pre-computed JSON object that was inlined during the build.
+
+The `AixyzConfigPlugin` in the CLI:
+
+1. Reads and validates your `aixyz.config.ts` at build time
+2. Resolves environment variables (e.g. `VERCEL_URL` for the `url` field)
+3. Replaces the `aixyz/config` module in the bundle with a static JSON literal:
+
+```typescript
+// What your code imports:
+import { getAixyzConfig } from "aixyz/config";
+
+// What ends up in the bundle:
+const config = { name: "my-agent", description: "..." /* ... */ };
+export function getAixyzConfig() {
+  return config;
+}
+export function getAixyzConfigRuntime() {
+  return config;
+}
+```
+
+This means:
+
+- **No filesystem access** at runtime — the config is baked into the bundle
+- **Environment variables are resolved at build time** — changing `VERCEL_URL` after build has no effect on the config
+- The bundle is fully self-contained and portable
+
+<Info>
+  You don't need to call these functions directly in most cases. The auto-generated server, `A2APlugin`, and `MCPPlugin`
+  all read from the materialized config automatically.
+</Info>

package/docs/api-reference/aixyz-model-fake.mdx

@@ -0,0 +1,111 @@
+---
+title: "aixyz/model/fake"
+description: "Deterministic fake language model for testing and development"
+---
+
+A drop-in `LanguageModelV3` implementation that maps user messages through a transform function — no API key, no network calls, fully deterministic.
+
+```typescript
+import { fake, type Prompt } from "aixyz/model";
+```
+
+## `fake(transform)`
+
+Creates a fake language model conforming to the Vercel AI SDK `LanguageModelV3` specification. The returned model can be passed directly to `ToolLoopAgent` or any AI SDK function that accepts a `LanguageModel`.
+
+```typescript
+function fake(transform: (lastMessage: string, prompt: Prompt) => string): LanguageModelV3;
+```
+
+### Parameters
+
+| Parameter   | Type                                              | Description                                                                                                |
+| ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `transform` | `(lastMessage: string, prompt: Prompt) => string` | Function that receives the last user message text and the full prompt, and returns the model output string |
+
+The `transform` function receives two arguments:
+
+- **`lastMessage`** — the text content of the most recent user message (empty string if none)
+- **`prompt`** — the full `LanguageModelV3Prompt` conversation history, useful for tracking turn count or prior context
+
+### Return value
+
+A `LanguageModelV3` object with:
+
+- `specificationVersion: "v3"`
+- `provider: "aixyz/fake"`
+- `modelId: "aixyz/fake"`
+- `doGenerate()` and `doStream()` that call your transform and report zero token usage
+
+### Examples
+
+Simple echo:
+
+```typescript
+import { fake } from "aixyz/model";
+
+const model = fake((input) => `You said: ${input}`);
+```
+
+Using full prompt context:
+
+```typescript
+import { fake } from "aixyz/model";
+
+const model = fake((input, prompt) => {
+  const turn = prompt.filter((m) => m.role === "user").length;
+  return `Turn ${turn}: ${input}`;
+});
+```
+
+Wiring into an agent:
+
+```typescript title="app/agent.ts"
+import { fake } from "aixyz/model";
+import { ToolLoopAgent } from "ai";
+
+export const model = fake((input) => `Echo: ${input}`);
+
+export default new ToolLoopAgent({
+  model,
+  instructions: "You echo back whatever the user says.",
+});
+```
+
+## `Prompt`
+
+Type alias for `LanguageModelV3Prompt` from `@ai-sdk/provider`. This is an array of messages where each message has a `role` and `content`:
+
+```typescript
+import type { Prompt } from "aixyz/model";
+```
+
+Use this type when you need to reference the prompt shape in your transform function or tests:
+
+```typescript
+import { fake, type Prompt } from "aixyz/model";
+
+const model = fake((_input: string, prompt: Prompt) => {
+  return `${prompt.length} messages in history`;
+});
+```
+
+## Testing with `fake()`
+
+The fake model makes every test deterministic and CI-safe. Export the model from your agent file so tests can call `doGenerate()` directly:
+
+```typescript title="app/agent.test.ts"
+import { describe, expect, test } from "bun:test";
+import { model } from "./agent";
+import type { Prompt } from "aixyz/model";
+
+describe("agent (fake model)", () => {
+  test("echoes the user message", async () => {
+    const prompt: Prompt = [{ role: "user", content: [{ type: "text", text: "hello" }] }];
+    const result = await model.doGenerate({ prompt });
+    expect(result.content).toEqual([{ type: "text", text: "Echo: hello" }]);
+  });
+});
+```
+
+See the [Testing guide](/getting-started/testing#fully-offline-tests-with-fake) and the [Fake Model Agent template](/templates/advanced/fake-llm) for complete examples.

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

@@ -0,0 +1,106 @@
+---
+title: "aixyz/app"
+description: "The core application class built on web-standard Request/Response"
+---
+
+`AixyzApp` is a framework-agnostic server that manages route registration, middleware chaining, and optional x402 payment gating via a `PaymentGateway`. It uses web-standard `Request`/`Response` — no Express dependency.
+
+```typescript
+import { AixyzApp } from "aixyz/app";
+```
+
+## Constructor
+
+```typescript
+new AixyzApp(options?: AixyzAppOptions)
+```
+
+| Parameter              | Type                                       | Default | Description                     |
+| ---------------------- | ------------------------------------------ | ------- | ------------------------------- |
+| `options.facilitators` | `FacilitatorClient \| FacilitatorClient[]` | —       | Payment verification service(s) |
+
+When `facilitators` is provided, a `PaymentGateway` is created and x402 payment verification is enabled for routes that declare a `payment` option.
+
+After constructing, register plugins with `await server.withPlugin(...)`, then call `await server.initialize()` to finalize payment routes.
+
+## Properties
+
+| Property  | Type                          | Description                                          |
+| --------- | ----------------------------- | ---------------------------------------------------- |
+| `routes`  | `Map<string, RouteEntry>`     | Registered routes, keyed by `"METHOD /path"`         |
+| `payment` | `PaymentGateway \| undefined` | Payment gateway (present when facilitators provided) |
+
+## Methods
+
+### `route(method, path, handler, options?)`
+
+Register a route with an optional x402 payment requirement:
+
+```typescript
+server.route("POST", "/agent", handler, {
+  payment: { scheme: "exact", price: "$0.005" },
+});
+```
+
+| Parameter         | Type           | Description                                           |
+| ----------------- | -------------- | ----------------------------------------------------- |
+| `method`          | `HttpMethod`   | HTTP method (GET, POST, etc.)                         |
+| `path`            | `string`       | Route path                                            |
+| `handler`         | `RouteHandler` | `(request: Request) => Response \| Promise<Response>` |
+| `options.payment` | `AcceptsX402`  | Optional payment configuration                        |
+
+### `fetch(request)`
+
+Dispatch a web-standard `Request` through payment verification, middleware chain, and route handler:
+
+```typescript
+const response = await server.fetch(new Request("http://localhost/agent", { method: "POST" }));
+```
+
+### `use(middleware)`
+
+Append a middleware to the chain. Middlewares run in registration order before the route handler:
+
+```typescript
+server.use(async (request, next) => {
+  const response = await next();
+  return new Response(await response.text(), {
+    status: response.status,
+    headers: { ...Object.fromEntries(response.headers), "x-custom": "value" },
+  });
+});
+```
+
+### `withPlugin(plugin)`
+
+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());
+```
+
+### `initialize()`
+
+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();
+```
+
+## Example
+
+```typescript title="app/server.ts"
+import { AixyzApp } from "aixyz/app";
+import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
+import { A2APlugin } from "aixyz/app/plugins/a2a";
+import * as agent from "./agent";
+
+const server = new AixyzApp();
+
+await server.withPlugin(new IndexPagePlugin());
+await server.withPlugin(new A2APlugin([{ exports: agent }]));
+
+await server.initialize();
+
+export default server;
+```

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

@@ -0,0 +1,90 @@
+---
+title: "experimental_StripePaymentIntentPlugin"
+description: "Add Stripe PaymentIntent-based payments to your agent server"
+---
+
+Adds Stripe PaymentIntent creation and validation to an `AixyzApp`, providing an alternative payment method alongside [x402](/protocols/x402).
+
+```typescript
+import { experimental_StripePaymentIntentPlugin } from "@aixyz/stripe";
+```
+
+<Warning>This API is experimental and may change significantly in future releases.</Warning>
+
+## Installation
+
+```bash
+bun add @aixyz/stripe
+```
+
+## Usage
+
+```typescript
+await server.withPlugin(new experimental_StripePaymentIntentPlugin());
+```
+
+## Environment Variables
+
+| Variable             | Required | Default | Description                    |
+| -------------------- | -------- | ------- | ------------------------------ |
+| `STRIPE_SECRET_KEY`  | Yes      | —       | Stripe secret key              |
+| `STRIPE_PRICE_CENTS` | No       | `100`   | Price per request in USD cents |
+
+If `STRIPE_SECRET_KEY` is not set, the function is a no-op — no endpoints or middleware are registered.
+
+## Registered Endpoints
+
+### `POST /stripe/create-payment-intent`
+
+Creates a new Stripe PaymentIntent for the configured price.
+
+**Response:**
+
+```json
+{
+  "clientSecret": "pi_xxx_secret_xxx",
+  "paymentIntentId": "pi_xxx"
+}
+```
+
+## Payment Middleware
+
+After registering the `experimental_StripePaymentIntentPlugin`, the server checks incoming requests for the `x-stripe-payment-intent-id` header:
+
+1. If the header is present, it validates the PaymentIntent:
+   - Status must be `succeeded`
+   - Amount must meet the configured `STRIPE_PRICE_CENTS`
+   - Payment must not have been already consumed
+2. Valid payments are marked as consumed (one-time use) and the request proceeds
+3. Invalid payments return `402 Payment Required`
+4. If no header is present, the request falls through to x402 middleware
+
+## Usage
+
+Use in a [custom server](/api-reference/agent) (`app/server.ts`):
+
+```typescript title="app/server.ts"
+import { AixyzApp } from "aixyz/app";
+import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
+import { A2APlugin } from "aixyz/app/plugins/a2a";
+import { experimental_StripePaymentIntentPlugin } from "@aixyz/stripe";
+import * as agent from "./agent";
+
+const server = new AixyzApp();
+
+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([{ exports: agent }]));
+
+await server.initialize();
+
+export default server;
+```
+
+<Note>
+  Register the `experimental_StripePaymentIntentPlugin` **before** A2A or MCP plugins so the Stripe middleware runs
+  first. If a valid Stripe payment is found, x402 verification is skipped.
+</Note>

package/docs/api-reference/tools.mdx

@@ -0,0 +1,40 @@
+---
+title: "tools/[name].ts"
+description: "Auto-discovered tool definitions for A2A and MCP"
+---
+
+Each `.ts` file in `app/tools/` is auto-discovered and registered as a tool on both A2A and MCP endpoints.
+
+```typescript title="app/tools/weather.ts"
+import { tool } from "ai";
+import { z } from "zod";
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = {
+  scheme: "exact",
+  price: "$0.0001",
+};
+
+export default tool({
+  description: "Get current weather conditions for a city.",
+  inputSchema: z.object({
+    location: z.string().describe("City name"),
+  }),
+  execute: async ({ location }) => {
+    // your implementation
+  },
+});
+```
+
+## Exports
+
+| Export    | Type      | Required | Description                                   |
+| --------- | --------- | -------- | --------------------------------------------- |
+| `default` | `tool()`  | Yes      | The tool instance                             |
+| `accepts` | `Accepts` | No       | Payment config — gates the tool on MCP `/mcp` |
+
+## Conventions
+
+- **Auto-discovered** — All `.ts` files in `app/tools/` are registered automatically
+- **Ignored files** — Files starting with `_` (e.g., `_helpers.ts`) are skipped
+- **Naming** — The tool is registered with the filename as its name (e.g., `weather.ts` → `weather`)

package/docs/api-reference/unstable-with-index-page.mdx

@@ -0,0 +1,57 @@
+---
+title: "IndexPagePlugin"
+description: "Add a human-readable text page to your agent server"
+---
+
+Adds a human-readable plain text page to your `AixyzApp` showing agent name, description, version, and skills.
+
+```typescript
+import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
+
+await server.withPlugin(new IndexPagePlugin());
+```
+
+## Behavior
+
+Registers a `GET` handler at the given path that responds with `text/plain` content:
+
+```
+My Agent
+========
+
+Description: A helpful travel agent
+Version: 0.1.0
+
+Skills:
+
+1. Search Flights
+   ID: search-flights
+   Description: Search for flights between airports
+   Tags: travel, flights
+   Examples:
+   - Find flights from SFO to LAX
+```
+
+The output includes:
+
+- Agent **name** and a separator line
+- **Description** and **version** from config
+- **Skills** list with IDs, descriptions, tags, and examples (if configured)
+
+## Usage
+
+The auto-generated server registers the `IndexPagePlugin` automatically at `"/"`. In a custom server, register it explicitly:
+
+```typescript title="app/server.ts"
+import { AixyzApp } from "aixyz/app";
+import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
+
+const server = new AixyzApp();
+
+// Mount at root (default)
+await server.withPlugin(new IndexPagePlugin());
+
+await server.initialize();
+
+export default server;
+```

package/docs/config/aixyz-config.mdx

@@ -0,0 +1,92 @@
+---
+title: "aixyz.config.ts"
+description: "Complete reference for the aixyz configuration file"
+---
+
+Every aixyz project requires an `aixyz.config.ts` at the project root. This file defines your agent's identity, payment settings, and skills. It is validated at build time using Zod schemas.
+
+## Full Example
+
+```typescript title="aixyz.config.ts"
+import type { AixyzConfig } from "aixyz/config";
+
+const config: AixyzConfig = {
+  name: "Weather Agent",
+  description: "Get current weather for any location worldwide.",
+  version: "0.1.0",
+  url: "https://my-agent.vercel.app",
+  x402: {
+    payTo: "0x...",
+    network: "eip155:8453",
+  },
+  skills: [
+    {
+      id: "get-weather",
+      name: "Get Weather",
+      description: "Get current weather conditions for any city",
+      tags: ["weather"],
+      examples: ["What's the weather in Tokyo?"],
+    },
+  ],
+};
+
+export default config;
+```
+
+## Config Fields
+
+| Field          | Type           | Required | Description                              |
+| -------------- | -------------- | -------- | ---------------------------------------- |
+| `name`         | `string`       | Yes      | Agent display name                       |
+| `description`  | `string`       | Yes      | What the agent does                      |
+| `version`      | `string`       | Yes      | Semver version                           |
+| `url`          | `string`       | No       | Agent base URL (auto-detected on Vercel) |
+| `x402`         | `object`       | Yes      | Payment configuration                    |
+| `x402.payTo`   | `string`       | Yes      | EVM address to receive payments          |
+| `x402.network` | `string`       | Yes      | CAIP-2 chain ID (e.g., `eip155:8453`)    |
+| `skills`       | `AgentSkill[]` | Yes      | Skills exposed in the A2A agent card     |
+
+### `AgentSkill`
+
+| Field         | Type       | Required | Description             |
+| ------------- | ---------- | -------- | ----------------------- |
+| `id`          | `string`   | Yes      | Unique skill identifier |
+| `name`        | `string`   | Yes      | Skill display name      |
+| `description` | `string`   | Yes      | What the skill does     |
+| `tags`        | `string[]` | Yes      | Categorization tags     |
+| `examples`    | `string[]` | No       | Example prompts         |
+| `inputModes`  | `string[]` | No       | Input MIME types        |
+| `outputModes` | `string[]` | No       | Output MIME types       |
+
+## URL Resolution
+
+If `url` is omitted, it is auto-detected in the following order:
+
+1. `https://${VERCEL_PROJECT_PRODUCTION_URL}/` (when `VERCEL_ENV` is `"production"`)
+2. `https://${VERCEL_URL}/` (Vercel preview/other environments)
+3. `http://localhost:${PORT}/` (fallback, default port 3000)
+
+## Payment Networks
+
+| Network      | CAIP-2 ID      |
+| ------------ | -------------- |
+| Base         | `eip155:8453`  |
+| Base Sepolia | `eip155:84532` |
+| Ethereum     | `eip155:1`     |
+
+Switch networks per environment:
+
+```typescript title="aixyz.config.ts"
+x402: {
+  payTo: "0x...",
+  network: process.env.NODE_ENV === "production" ? "eip155:8453" : "eip155:84532",
+},
+```
+
+## Build-Time vs Runtime
+
+At build time, the `AixyzConfigPlugin` resolves the full config and materializes a runtime-safe subset into the bundle. This means:
+
+- `import config from "aixyz/config"` works at runtime without the config file
+- Environment variables referenced in the config are baked in at build time
+- The config file itself is not included in the output bundle

package/docs/config/environment-variables.mdx

@@ -0,0 +1,77 @@
+---
+title: "Environment Variables"
+description: "Configure your agent with .env files and environment variables"
+---
+
+## `.env` Files
+
+aixyz loads environment variables from `.env` files in the following order (later files take precedence):
+
+1. `.env` — Shared defaults
+2. `.env.local` — Local overrides (gitignored)
+3. `.env.$(NODE_ENV)` — e.g., `.env.production`
+4. `.env.$(NODE_ENV).local` — e.g., `.env.production.local`
+
+This matches the loading order used by Next.js.
+
+<Note>`.env.local` is always gitignored. Use it for API keys and secrets during development.</Note>
+
+## Common Variables
+
+| Variable               | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `OPENAI_API_KEY`       | OpenAI API key                                         |
+| `X402_PAY_TO`          | Default payment recipient address                      |
+| `X402_NETWORK`         | Default payment network                                |
+| `X402_FACILITATOR_URL` | Custom x402 facilitator URL                            |
+| `CDP_API_KEY_ID`       | Coinbase CDP key ID (switches to Coinbase facilitator) |
+| `CDP_API_KEY_SECRET`   | Coinbase CDP key secret                                |
+| `STRIPE_SECRET_KEY`    | Experimental Stripe adapter                            |
+| `STRIPE_PRICE_CENTS`   | Stripe price in cents (default: 100)                   |
+
+## Using in Config
+
+Reference environment variables directly in `aixyz.config.ts`:
+
+```typescript title="aixyz.config.ts"
+import type { AixyzConfig } from "aixyz/config";
+
+const config: AixyzConfig = {
+  name: "My Agent",
+  description: "...",
+  version: "0.1.0",
+  x402: {
+    payTo: process.env.X402_PAY_TO!,
+    network: process.env.X402_NETWORK!,
+  },
+  skills: [],
+};
+
+export default config;
+```
+
+## Testing Environment
+
+For tests, `loadEnv` from `aixyz/test` loads `.env.test.local` (where your `OPENAI_API_KEY` lives for tests). `.env.local` is ignored during testing:
+
+```typescript
+import { loadEnv } from "aixyz/test";
+
+describe("tests", () => {
+  loadEnv();
+  // process.env.OPENAI_API_KEY is now available
+});
+```
+
+## Built-in Environment Variables
+
+The CLI automatically sets these environment variables based on the command:
+
+| Variable    | `aixyz dev`     | `aixyz build`  | Description                                                                  |
+| ----------- | --------------- | -------------- | ---------------------------------------------------------------------------- |
+| `NODE_ENV`  | `"development"` | `"production"` | Standard Node.js environment indicator, for compatibility with node packages |
+| `AIXYZ_ENV` | `"development"` | `"production"` | aixyz-specific environment indicator, mirrors `NODE_ENV`                     |
+
+## Build-Time Resolution
+
+Environment variables referenced in `aixyz.config.ts` are resolved and baked into the bundle at build time. The config file itself is not included in the output — only the resolved values.