aixyz 0.27.0 → 0.28.0

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.

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. Calls `plugin.register(this)` and returns `this` for chaining:
+
+```typescript
+await server.withPlugin(new IndexPagePlugin());
+```
+
+### `initialize()`
+
+Initialize payment gateway. Must be called after all routes 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(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(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`)