aixyz 0.34.0 → 0.36.0

package/README.md

@@ -137,6 +137,7 @@ That's it. Run `bun run dev` and aixyz auto-generates the server, wires up A2A +
 | [`sub-agents`](./examples/sub-agents/)                           | Multiple A2A endpoints from one deployment      |
 | [`with-tests`](./examples/with-tests/)                           | Agent with test examples                        |
 | [`fake-llm`](./examples/fake-llm/)                               | Fully deterministic testing with `fake()` model |
+| [`with-vercel-blob`](./examples/with-vercel-blob/)               | MCP-only txt storage using Vercel Blob          |
 
 ## CLI
 

package/app/index.ts

@@ -5,7 +5,7 @@ import { type HttpMethod, type RouteHandler, type Middleware, type RouteEntry, t
 import { PaymentGateway } from "./payment/payment";
 import { getAixyzConfig } from "@aixyz/config";
 import { loadEnvConfig } from "@next/env";
-import { BasePlugin, type RegisterContext, type InitializeContext } from "./plugin";
+import { BasePlugin, type RegisterContext, type InitializeContext, type PaymentHookContext } from "./plugin";
 
 // Load .env and .env.production files at runtime (local files are excluded at build time).
 loadEnvConfig(process.cwd());
@@ -68,6 +68,35 @@ export class AixyzApp {
     // clear registered routes for this plugin before registration, in case of hot reload or multiple registrations
     plugin.registeredRoutes.clear();
 
+    const paymentHooks: PaymentHookContext | undefined = this.payment
+      ? {
+          onBeforeVerify: (h) => {
+            this.payment!.onBeforeVerify(h);
+            return paymentHooks!;
+          },
+          onAfterVerify: (h) => {
+            this.payment!.onAfterVerify(h);
+            return paymentHooks!;
+          },
+          onVerifyFailure: (h) => {
+            this.payment!.onVerifyFailure(h);
+            return paymentHooks!;
+          },
+          onBeforeSettle: (h) => {
+            this.payment!.onBeforeSettle(h);
+            return paymentHooks!;
+          },
+          onAfterSettle: (h) => {
+            this.payment!.onAfterSettle(h);
+            return paymentHooks!;
+          },
+          onSettleFailure: (h) => {
+            this.payment!.onSettleFailure(h);
+            return paymentHooks!;
+          },
+        }
+      : undefined;
+
     const ctx: RegisterContext = {
       route: (method, path, handler, options) => {
         this.route(method, path, handler, options);
@@ -76,6 +105,7 @@ export class AixyzApp {
         if (entry) plugin.registeredRoutes.set(key, entry);
       },
       use: (mw) => this.use(mw),
+      paymentHooks,
     };
     await plugin.register?.(ctx);
     return this;

package/app/payment/payment.ts

@@ -10,9 +10,54 @@ import {
 import { ExactEvmScheme } from "@x402/evm/exact/server";
 import type { AcceptsX402, AcceptsX402Multi } from "../../accepts";
 import { normalizeAcceptsX402 } from "../../accepts";
-import { Network, PaymentPayload, PaymentRequirements } from "@x402/core/types";
+import { Network, PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse } from "@x402/core/types";
 import { AixyzConfig } from "@aixyz/config";
 
+// ── x402 Lifecycle Hook Types ──────────────────────────────────────────
+// These mirror x402ResourceServer's hook signatures but are defined here
+// because x402/core does not export them publicly.
+
+export interface VerifyContext {
+  paymentPayload: PaymentPayload;
+  requirements: PaymentRequirements;
+}
+
+export interface VerifyResultContext extends VerifyContext {
+  result: VerifyResponse;
+}
+
+export interface VerifyFailureContext extends VerifyContext {
+  error: Error;
+}
+
+export interface SettleContext {
+  paymentPayload: PaymentPayload;
+  requirements: PaymentRequirements;
+}
+
+export interface SettleResultContext extends SettleContext {
+  result: SettleResponse;
+}
+
+export interface SettleFailureContext extends SettleContext {
+  error: Error;
+}
+
+export type BeforeVerifyHook = (
+  context: VerifyContext,
+) => Promise<void | { abort: true; reason: string; message?: string }>;
+export type AfterVerifyHook = (context: VerifyResultContext) => Promise<void>;
+export type OnVerifyFailureHook = (
+  context: VerifyFailureContext,
+) => Promise<void | { recovered: true; result: VerifyResponse }>;
+export type BeforeSettleHook = (
+  context: SettleContext,
+) => Promise<void | { abort: true; reason: string; message?: string }>;
+export type AfterSettleHook = (context: SettleResultContext) => Promise<void>;
+export type OnSettleFailureHook = (
+  context: SettleFailureContext,
+) => Promise<void | { recovered: true; result: SettleResponse }>;
+
 /**
  * Converts a web-standard Request into the x402 HTTPAdapter interface.
  */
@@ -45,10 +90,12 @@ function toResponse(instructions: HTTPResponseInstructions): Response {
   return new Response(body, { status: instructions.status, headers });
 }
 
-interface PaymentContext {
+export interface PaymentContext {
   paymentPayload: PaymentPayload;
   paymentRequirements: PaymentRequirements;
   declaredExtensions?: Record<string, unknown>;
+  /** The payer's address, captured from x402 verification. */
+  payer?: string;
 }
 
 /**
@@ -60,10 +107,22 @@ export class PaymentGateway {
   private readonly config: AixyzConfig;
   private readonly pendingRoutes = new Map<string, RouteConfig>();
   private readonly verifiedPayments = new WeakMap<Request, PaymentContext>();
+  /**
+   * Temporary map to capture payer address from the afterVerify hook.
+   * Keyed by PaymentPayload reference (same object flows through the verify pipeline).
+   */
+  private readonly pendingPayers = new WeakMap<PaymentPayload, string>();
 
   constructor(facilitators: FacilitatorClient | FacilitatorClient[], config: AixyzConfig) {
     this.resourceServer = new x402ResourceServer(facilitators);
     this.config = config;
+
+    // Capture payer address from verification so it can be exposed to handlers.
+    this.onAfterVerify(async (context) => {
+      if (context.result.payer) {
+        this.pendingPayers.set(context.paymentPayload, context.result.payer);
+      }
+    });
   }
 
   /** Register an EVM payment scheme for the given network (e.g. Base mainnet). */
@@ -145,13 +204,16 @@ export class PaymentGateway {
       case "no-payment-required":
         return null;
 
-      case "payment-verified":
+      case "payment-verified": {
+        const payer = this.pendingPayers.get(result.paymentPayload);
         this.verifiedPayments.set(request, {
           paymentPayload: result.paymentPayload,
           paymentRequirements: result.paymentRequirements,
           declaredExtensions: result.declaredExtensions,
+          payer,
         });
         return null;
+      }
 
       case "payment-error":
         return toResponse(result.response);
@@ -175,4 +237,58 @@ export class PaymentGateway {
 
     return result;
   }
+
+  /**
+   * Get the payer's address for a verified payment request.
+   * Available after `verify()` succeeds and before `settle()` is called.
+   */
+  getPayer(request: Request): string | undefined {
+    return this.verifiedPayments.get(request)?.payer;
+  }
+
+  /**
+   * Get the full payment context for a verified payment request.
+   * Available after `verify()` succeeds and before `settle()` is called.
+   */
+  getPaymentContext(request: Request): Readonly<PaymentContext> | undefined {
+    return this.verifiedPayments.get(request);
+  }
+
+  // ── x402 Lifecycle Hooks ───────────────────────────────────────────
+
+  /** Register a hook to run before payment verification. Return `{ abort: true, reason }` to reject. */
+  onBeforeVerify(hook: BeforeVerifyHook): this {
+    this.resourceServer.onBeforeVerify(hook);
+    return this;
+  }
+
+  /** Register a hook to run after successful payment verification. */
+  onAfterVerify(hook: AfterVerifyHook): this {
+    this.resourceServer.onAfterVerify(hook);
+    return this;
+  }
+
+  /** Register a hook to run when payment verification fails. Return `{ recovered: true, result }` to recover. */
+  onVerifyFailure(hook: OnVerifyFailureHook): this {
+    this.resourceServer.onVerifyFailure(hook);
+    return this;
+  }
+
+  /** Register a hook to run before payment settlement. Return `{ abort: true, reason }` to reject. */
+  onBeforeSettle(hook: BeforeSettleHook): this {
+    this.resourceServer.onBeforeSettle(hook);
+    return this;
+  }
+
+  /** Register a hook to run after successful payment settlement. */
+  onAfterSettle(hook: AfterSettleHook): this {
+    this.resourceServer.onAfterSettle(hook);
+    return this;
+  }
+
+  /** Register a hook to run when payment settlement fails. Return `{ recovered: true, result }` to recover. */
+  onSettleFailure(hook: OnSettleFailureHook): this {
+    this.resourceServer.onSettleFailure(hook);
+    return this;
+  }
 }

package/app/plugin.ts

@@ -1,5 +1,26 @@
 import type { HttpMethod, RouteHandler, RouteEntry, RouteOptions, Middleware } from "./types";
-import type { PaymentGateway } from "./payment/payment";
+import type {
+  PaymentGateway,
+  BeforeVerifyHook,
+  AfterVerifyHook,
+  OnVerifyFailureHook,
+  BeforeSettleHook,
+  AfterSettleHook,
+  OnSettleFailureHook,
+} from "./payment/payment";
+
+/**
+ * Scoped interface for registering x402 payment lifecycle hooks.
+ * Exposes only hook registration — not the full PaymentGateway.
+ */
+export interface PaymentHookContext {
+  onBeforeVerify(hook: BeforeVerifyHook): PaymentHookContext;
+  onAfterVerify(hook: AfterVerifyHook): PaymentHookContext;
+  onVerifyFailure(hook: OnVerifyFailureHook): PaymentHookContext;
+  onBeforeSettle(hook: BeforeSettleHook): PaymentHookContext;
+  onAfterSettle(hook: AfterSettleHook): PaymentHookContext;
+  onSettleFailure(hook: OnSettleFailureHook): PaymentHookContext;
+}
 
 /**
  * Scoped context passed to {@link BasePlugin.register}.
@@ -16,6 +37,8 @@ export interface RegisterContext {
   route(method: HttpMethod, path: string, handler: RouteHandler, options?: RouteOptions): void;
   /** Append a middleware to the application's middleware chain. */
   use(middleware: Middleware): void;
+  /** Register hooks on the x402 payment lifecycle. Undefined when no facilitators configured. */
+  readonly paymentHooks?: PaymentHookContext;
 }
 
 /**

package/app/plugins/a2a.ts

@@ -25,7 +25,8 @@ export type Capabilities = z.infer<typeof CapabilitiesSchema>;
 
 export interface A2AAgentEntry {
   name?: string;
-  exports: { default: ToolLoopAgent; accepts?: Accepts; capabilities?: Capabilities };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  exports: { default: ToolLoopAgent<never, any>; accepts?: Accepts; capabilities?: Capabilities };
   /** Optional task store override. Defaults to a per-agent InMemoryTaskStore for isolation. */
   taskStore?: TaskStore;
 }

package/app/plugins/mcp.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { type Tool } from "ai";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -8,6 +9,13 @@ import { AcceptsScheme, isAcceptsPaid, normalizeAcceptsX402 } from "../../accept
 import { getAixyzConfig, getAixyzConfigRuntime } from "../../config";
 import { Network } from "@x402/core/types";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
+import type { SessionPlugin } from "./session/index";
+
+/**
+ * AsyncLocalStorage to pass the MCP-level payer address from the
+ * onAfterVerify hook to the tool handler within the same async context.
+ */
+const mcpPayerStorage = new AsyncLocalStorage<{ payer?: string }>();
 
 /**
  * MCP (Model Context Protocol) plugin. Collects tools and exposes them
@@ -21,6 +29,7 @@ export class MCPPlugin extends BasePlugin {
   readonly name = "mcp";
   readonly registeredTools: Array<{ name: string; tool: Tool; accepts?: Accepts }> = [];
   private paymentWrappers = new Map<string, (handler: any) => any>();
+  private sessionPlugin?: SessionPlugin;
 
   constructor(private tools: Array<{ name: string; exports: { default: Tool; accepts?: Accepts } }>) {
     super();
@@ -31,22 +40,44 @@ export class MCPPlugin extends BasePlugin {
     const mcpServer = new McpServer({ name: config.name, version: config.version }, { capabilities: { tools: {} } });
 
     for (const { name, tool } of this.registeredTools) {
+      const sessionPlugin = this.sessionPlugin;
       const handler = async (args: Record<string, unknown>) => {
-        try {
-          const result = await tool.execute!(args, { toolCallId: name, messages: [] });
-          const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
-          return { content: [{ type: "text" as const, text }] };
-        } catch (error) {
-          const text = error instanceof Error ? error.message : "Unknown error";
-          return { content: [{ type: "text" as const, text: `Error: ${text}` }], isError: true };
+        const execute = async () => {
+          try {
+            const result = await tool.execute!(args, { toolCallId: name, messages: [] });
+            const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+            return { content: [{ type: "text" as const, text }] };
+          } catch (error) {
+            console.error(`[mcp] Tool "${name}" failed:`, error);
+            const text = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text" as const, text: `Error: ${text}` }], isError: true };
+          }
+        };
+
+        // If a payer was captured from MCP-level payment, run the tool
+        // within a session context so getSession() works.
+        const payer = mcpPayerStorage.getStore()?.payer;
+        if (payer && sessionPlugin) {
+          return sessionPlugin.runWithPayer(payer, execute);
         }
+        return execute();
       };
 
       const wrapper = this.paymentWrappers.get(name);
+      let registeredHandler: (args: any, extra?: any) => any;
+      if (wrapper) {
+        const wrapped = wrapper(handler);
+        // Wrap the payment wrapper call in mcpPayerStorage.run() so the
+        // onAfterVerify hook and handler share the same async context.
+        registeredHandler = (args: any, extra: any) =>
+          mcpPayerStorage.run({ payer: undefined }, () => wrapped(args, extra));
+      } else {
+        registeredHandler = handler;
+      }
       mcpServer.registerTool(
         name,
         { description: tool.description, inputSchema: tool.inputSchema as any },
-        wrapper ? wrapper(handler) : handler,
+        registeredHandler,
       );
     }
 
@@ -80,6 +111,8 @@ export class MCPPlugin extends BasePlugin {
   }
 
   async initialize(ctx: InitializeContext): Promise<void> {
+    this.sessionPlugin = ctx.getPlugin<SessionPlugin>("session");
+
     if (!ctx.payment) return;
 
     const config = getAixyzConfig();
@@ -102,6 +135,17 @@ export class MCPPlugin extends BasePlugin {
       }
     }
 
+    // Capture payer from MCP-level payment verification for session integration.
+    // This hook is global (fires for all verifications, including HTTP-level), but
+    // only writes when mcpPayerStorage has an active context — which only happens
+    // inside MCP tool calls wrapped by mcpPayerStorage.run() below.
+    ctx.payment.onAfterVerify(async (context) => {
+      const store = mcpPayerStorage.getStore();
+      if (store && context.result.payer) {
+        store.payer = context.result.payer;
+      }
+    });
+
     for (const { name, accepts } of this.registeredTools) {
       if (!accepts || !isAcceptsPaid(accepts)) continue;
 

package/app/plugins/session/index.ts

@@ -0,0 +1,193 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { BasePlugin, type RegisterContext, type InitializeContext } from "../../plugin";
+import type { PaymentGateway } from "../../payment/payment";
+import { InMemorySessionStore } from "./memory";
+
+export { InMemorySessionStore, type InMemorySessionStoreOptions } from "./memory";
+
+// ── Storage Interface ────────────────────────────────────────────────
+
+/** Options for {@link SessionStore.set} and {@link SessionStore.setMany}. */
+export interface SetOptions {
+  /** Per-key TTL in milliseconds. Overrides the store-level default when supported. */
+  ttlMs?: number;
+}
+
+/** Options for {@link SessionStore.list}. */
+export interface ListOptions {
+  /** Only return keys starting with this prefix. */
+  prefix?: string;
+  /** Opaque cursor from a previous `list()` call for pagination. */
+  cursor?: string;
+  /** Maximum number of entries to return. The store decides its own default when omitted. */
+  limit?: number;
+  /** If true, values are omitted (all values will be empty strings). */
+  keysOnly?: boolean;
+}
+
+/** Return type for {@link SessionStore.list}. */
+export interface ListResult {
+  entries: Record<string, string>;
+  /** If present, more results are available — pass to the next `list()` call. */
+  cursor?: string;
+}
+
+/**
+ * Pluggable session storage backend.
+ * All methods are async to support external stores (Redis, DB, KV, etc.).
+ * Operations are scoped by payer address — the x402 signer for the request.
+ */
+export interface SessionStore {
+  get(payer: string, key: string): Promise<string | undefined>;
+  set(payer: string, key: string, value: string, options?: SetOptions): Promise<void>;
+  delete(payer: string, key: string): Promise<boolean>;
+  list(payer: string, options?: ListOptions): Promise<ListResult>;
+
+  /** Retrieve multiple keys in a single call. */
+  getMany?(payer: string, keys: string[]): Promise<Record<string, string | undefined>>;
+  /** Set multiple keys in a single call. */
+  setMany?(payer: string, entries: Record<string, string>, options?: SetOptions): Promise<void>;
+  /** Delete multiple keys in a single call. Returns the number of keys actually removed. */
+  deleteMany?(payer: string, keys: string[]): Promise<number>;
+
+  /** Release resources held by the store (connections, timers, etc.). */
+  close?(): Promise<void>;
+}
+
+// ── Session Handle ───────────────────────────────────────────────────
+
+/**
+ * Payer-scoped session handle. All operations target the current
+ * x402 payer without requiring the caller to pass an address.
+ */
+export interface Session {
+  readonly payer: string;
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, options?: SetOptions): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list(options?: ListOptions): Promise<ListResult>;
+}
+
+function createSession(payer: string, store: SessionStore): Session {
+  // Normalize the payer address to lowercase so sessions are keyed consistently
+  // regardless of whether the x402 verifier returns a checksummed (EIP-55) or
+  // lowercase address. The original (possibly checksummed) address is still
+  // exposed as `session.payer` for display purposes.
+  const storedPayer = payer.toLowerCase();
+  return {
+    payer,
+    get: (key) => store.get(storedPayer, key),
+    set: (key, value, options) => store.set(storedPayer, key, value, options),
+    delete: (key) => store.delete(storedPayer, key),
+    list: (options) => store.list(storedPayer, options),
+  };
+}
+
+// ── AsyncLocalStorage API ────────────────────────────────────────────
+
+const sessionStorage = new AsyncLocalStorage<Session | undefined>();
+
+/**
+ * Get the current payer-scoped session.
+ * Returns `undefined` if no x402 payment was made for this request.
+ */
+export function getSession(): Session | undefined {
+  return sessionStorage.getStore();
+}
+
+/**
+ * Get the current x402 payer address.
+ * Shorthand for `getSession()?.payer`.
+ */
+export function getPayer(): string | undefined {
+  return sessionStorage.getStore()?.payer;
+}
+
+// ── Plugin ───────────────────────────────────────────────────────────
+
+export interface SessionPluginOptions {
+  /** Custom session store. Defaults to {@link InMemorySessionStore}. */
+  store?: SessionStore;
+}
+
+/**
+ * Session plugin for aixyz. Provides payer-scoped key-value storage
+ * gated by x402 payment identity.
+ *
+ * Register **before** other plugins so the session middleware runs first:
+ *
+ * ```ts
+ * await app.withPlugin(new SessionPlugin());
+ * await app.withPlugin(new A2APlugin([...]));
+ * ```
+ *
+ * Tools access the session via {@link getSession}:
+ *
+ * ```ts
+ * import { getSession } from "aixyz/app/plugins/session";
+ *
+ * const session = getSession();
+ * await session?.set("key", "value");
+ * ```
+ */
+export class SessionPlugin extends BasePlugin {
+  readonly name = "session";
+  readonly store: SessionStore;
+  private payment?: PaymentGateway;
+
+  constructor(options?: SessionPluginOptions) {
+    super();
+    this.store = options?.store ?? new InMemorySessionStore();
+  }
+
+  register(ctx: RegisterContext): void {
+    ctx.use(async (request, next) => {
+      const payer = this.payment?.getPayer(request);
+      if (payer) {
+        const session = createSession(payer, this.store);
+        return sessionStorage.run(session, next);
+      }
+      // Explicitly clear any inherited ALS context so that an unpaid route
+      // nested inside a paid handler's app.fetch() doesn't leak the outer session.
+      return sessionStorage.run(undefined, next);
+    });
+  }
+
+  initialize(ctx: InitializeContext): void {
+    this.payment = ctx.payment;
+  }
+
+  /**
+   * Run a function within a session context for the given payer.
+   * Used by other plugins (e.g., MCPPlugin) to set session context
+   * for tool execution when payment is handled at the protocol level.
+   *
+   * **Security note:** This method bypasses HTTP-level payment verification.
+   * Only call it with a payer address that has already been authenticated by a
+   * trusted payment mechanism (e.g., the `@x402/mcp` payment wrapper).
+   * @internal
+   */
+  runWithPayer<T>(payer: string, fn: () => T): T {
+    const session = createSession(payer, this.store);
+    return sessionStorage.run(session, fn);
+  }
+}
+
+/**
+ * Identity helper that provides full type inference for a {@link SessionStore}.
+ * Use in `app/session.ts` to get type-safe autocompletion:
+ *
+ * ```ts
+ * import { defineSessionStore } from "aixyz/app/plugins/session";
+ *
+ * export default defineSessionStore({
+ *   async get(payer, key) { ... },
+ *   async set(payer, key, value) { ... },
+ *   async delete(payer, key) { ... },
+ *   async list(payer) { ... },
+ * });
+ * ```
+ */
+export function defineSessionStore(store: SessionStore): SessionStore {
+  return store;
+}