aixyz 0.34.0 → 0.35.0

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;
+}

package/app/plugins/session/memory.ts

@@ -0,0 +1,206 @@
+import type { SessionStore, SetOptions, ListOptions, ListResult } from "./index";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface InMemorySessionStoreOptions {
+  /** Maximum number of entries across all payers. Default: 10 000. */
+  maxEntries?: number;
+  /** Time-to-live in milliseconds (sliding window). 0 = no expiry. Default: 3 600 000 (1 h). */
+  ttlMs?: number;
+}
+
+interface Entry {
+  value: string;
+  payer: string;
+  key: string;
+  expiresAt: number; // 0 = never expires
+  ttlMs: number; // effective TTL used when refreshing on get(); 0 = no expiry
+}
+
+// ── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Production-ready in-memory {@link SessionStore} with LRU eviction and
+ * optional TTL.
+ *
+ * - **LRU eviction** — backed by `Map` insertion-order. When `maxEntries`
+ *   is reached, the least-recently-used entry is evicted.
+ * - **Sliding-window TTL** — `get()` refreshes the expiry timer.
+ *   Expired entries are lazily removed on read; no background timers.
+ * - **OOM-safe** — `maxEntries` is a hard cap. Memory usage is bounded
+ *   regardless of TTL or access patterns.
+ */
+export class InMemorySessionStore implements SessionStore {
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+
+  /** Flat LRU map. Key = `${payer}:${key}`. Insertion order = access order. */
+  private readonly entries = new Map<string, Entry>();
+  /** Secondary index: payer → set of composite keys (for efficient `list`). */
+  private readonly payerIndex = new Map<string, Set<string>>();
+
+  constructor(options?: InMemorySessionStoreOptions) {
+    this.maxEntries = options?.maxEntries ?? 10_000;
+    this.ttlMs = options?.ttlMs ?? 3_600_000;
+    if (this.maxEntries < 1) throw new Error("maxEntries must be >= 1");
+    if (this.ttlMs < 0) throw new Error("ttlMs must be >= 0");
+  }
+
+  async get(payer: string, key: string): Promise<string | undefined> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return undefined;
+
+    if (this.isExpired(entry)) {
+      this.removeEntry(ck, entry);
+      return undefined;
+    }
+
+    // LRU touch: move to end + refresh TTL using the entry's own TTL
+    this.entries.delete(ck);
+    entry.expiresAt = this.expiryFor(entry.ttlMs);
+    this.entries.set(ck, entry);
+
+    return entry.value;
+  }
+
+  async set(payer: string, key: string, value: string, options?: SetOptions): Promise<void> {
+    const ck = compositeKey(payer, key);
+
+    // If overwriting, remove first so re-insert lands at the end.
+    const existing = this.entries.get(ck);
+    if (existing) {
+      this.entries.delete(ck);
+    }
+
+    // Evict LRU entry if at capacity.
+    if (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) {
+        const oldestEntry = this.entries.get(oldest.value)!;
+        this.removeEntry(oldest.value, oldestEntry);
+      }
+    }
+
+    const effectiveTtl = options?.ttlMs ?? this.ttlMs;
+    const entry: Entry = { value, payer, key, expiresAt: this.expiryFor(effectiveTtl), ttlMs: effectiveTtl };
+    this.entries.set(ck, entry);
+
+    // Update payer index.
+    let idx = this.payerIndex.get(payer);
+    if (!idx) {
+      idx = new Set();
+      this.payerIndex.set(payer, idx);
+    }
+    idx.add(ck);
+  }
+
+  async delete(payer: string, key: string): Promise<boolean> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return false;
+    this.removeEntry(ck, entry);
+    return true;
+  }
+
+  async list(payer: string, options?: ListOptions): Promise<ListResult> {
+    const idx = this.payerIndex.get(payer);
+    if (!idx) return { entries: {} };
+
+    const prefix = options?.prefix;
+    const limit = options?.limit && options.limit > 0 ? options.limit : Infinity;
+    const keysOnly = options?.keysOnly ?? false;
+    const cursor = options?.cursor;
+
+    const result: Record<string, string> = {};
+    let count = 0;
+    let pastCursor = !cursor;
+    let lastCk: string | undefined;
+    let hasMore = false;
+
+    for (const ck of idx) {
+      const entry = this.entries.get(ck);
+      if (!entry) {
+        idx.delete(ck);
+        continue;
+      }
+      if (this.isExpired(entry)) {
+        this.removeEntry(ck, entry);
+        continue;
+      }
+
+      // Skip until we pass the cursor position.
+      if (!pastCursor) {
+        if (ck === cursor) pastCursor = true;
+        continue;
+      }
+
+      // Apply prefix filter.
+      if (prefix && !entry.key.startsWith(prefix)) continue;
+
+      if (count >= limit) {
+        hasMore = true;
+        break;
+      }
+
+      result[entry.key] = keysOnly ? "" : entry.value;
+      lastCk = ck;
+      count++;
+    }
+
+    if (idx.size === 0) this.payerIndex.delete(payer);
+    return { entries: result, cursor: hasMore ? lastCk : undefined };
+  }
+
+  async getMany(payer: string, keys: string[]): Promise<Record<string, string | undefined>> {
+    const result: Record<string, string | undefined> = {};
+    for (const key of keys) {
+      result[key] = await this.get(payer, key);
+    }
+    return result;
+  }
+
+  async setMany(payer: string, entries: Record<string, string>, options?: SetOptions): Promise<void> {
+    for (const [key, value] of Object.entries(entries)) {
+      await this.set(payer, key, value, options);
+    }
+  }
+
+  async deleteMany(payer: string, keys: string[]): Promise<number> {
+    let count = 0;
+    for (const key of keys) {
+      if (await this.delete(payer, key)) count++;
+    }
+    return count;
+  }
+
+  async close(): Promise<void> {
+    this.entries.clear();
+    this.payerIndex.clear();
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────
+
+  private removeEntry(ck: string, entry: Entry): void {
+    this.entries.delete(ck);
+    const idx = this.payerIndex.get(entry.payer);
+    if (idx) {
+      idx.delete(ck);
+      if (idx.size === 0) this.payerIndex.delete(entry.payer);
+    }
+  }
+
+  private isExpired(entry: Entry): boolean {
+    return entry.expiresAt > 0 && Date.now() > entry.expiresAt;
+  }
+
+  private expiryFor(ttlMs: number): number {
+    return ttlMs > 0 ? Date.now() + ttlMs : 0;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function compositeKey(payer: string, key: string): string {
+  return `${payer}:${key}`;
+}

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

@@ -91,12 +91,15 @@ await server.initialize();
 
 ```typescript title="app/server.ts"
 import { AixyzApp } from "aixyz/app";
+import { SessionPlugin } from "aixyz/app/plugins/session";
 import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
 import { A2APlugin } from "aixyz/app/plugins/a2a";
 import * as agent from "./agent";
 
 const server = new AixyzApp();
 
+// SessionPlugin must be registered first so its middleware runs before other plugins
+await server.withPlugin(new SessionPlugin());
 await server.withPlugin(new IndexPagePlugin());
 await server.withPlugin(new A2APlugin([{ exports: agent }]));
 

package/docs/api-reference/session-plugin.mdx

@@ -0,0 +1,192 @@
+---
+title: "SessionPlugin"
+description: "Payer-scoped key-value storage gated by x402 payment identity"
+---
+
+## Overview
+
+`SessionPlugin` provides per-payer key-value storage for aixyz agents. Each x402 signer gets an isolated session -- two different payers never see each other's data. Sessions are accessed via `getSession()` using `AsyncLocalStorage`, so tools don't need to thread payer identity through function parameters.
+
+SessionPlugin is **always registered** by the build pipeline. To use a custom storage backend, create an `app/session.ts` file.
+
+```typescript
+import { getSession, getPayer } from "aixyz/app/plugins/session";
+```
+
+## Setup
+
+SessionPlugin is auto-registered when `aixyz build` or `aixyz dev` generates the server entrypoint. No manual setup is needed for the default in-memory store.
+
+To use a custom store (Redis, database, etc.), create `app/session.ts`:
+
+```typescript title="app/session.ts"
+import { defineSessionStore, InMemorySessionStore } from "aixyz/app/plugins/session";
+
+export default defineSessionStore(new InMemorySessionStore());
+```
+
+The build pipeline detects `app/session.ts` and passes it to `SessionPlugin({ store: sessionStore })`. If no `app/session.ts` exists, the default `InMemorySessionStore` is used.
+
+## API
+
+### `getSession()`
+
+Returns the current payer-scoped `Session`, or `undefined` if no x402 payment was made for this request.
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+const session = getSession();
+if (!session) {
+  return { error: "No authenticated signer" };
+}
+
+await session.set("key", "value");
+const value = await session.get("key");
+```
+
+### `getPayer()`
+
+Shorthand for `getSession()?.payer`. Returns the x402 signer address or `undefined`.
+
+```typescript
+import { getPayer } from "aixyz/app/plugins/session";
+
+const payer = getPayer(); // "0x1234..."
+```
+
+## Session Interface
+
+All operations are scoped to the current x402 payer automatically.
+
+| Method   | Signature                                                             | Description                                   |
+| -------- | --------------------------------------------------------------------- | --------------------------------------------- |
+| `payer`  | `readonly string`                                                     | The x402 signer address                       |
+| `get`    | `(key: string) => Promise<string \| undefined>`                       | Get a value by key                            |
+| `set`    | `(key: string, value: string, options?: SetOptions) => Promise<void>` | Store a key-value pair                        |
+| `delete` | `(key: string) => Promise<boolean>`                                   | Delete a key, returns whether it existed      |
+| `list`   | `(options?: ListOptions) => Promise<ListResult>`                      | List key-value pairs with optional pagination |
+
+### `SetOptions`
+
+| Field   | Type     | Description                                                          |
+| ------- | -------- | -------------------------------------------------------------------- |
+| `ttlMs` | `number` | Per-key TTL in milliseconds. Overrides store default when supported. |
+
+### `ListOptions`
+
+| Field      | Type      | Description                                       |
+| ---------- | --------- | ------------------------------------------------- |
+| `prefix`   | `string`  | Only return keys starting with this prefix        |
+| `cursor`   | `string`  | Opaque cursor from a previous `list()` call       |
+| `limit`    | `number`  | Maximum number of entries to return               |
+| `keysOnly` | `boolean` | If true, values are omitted (all values are `""`) |
+
+### `ListResult`
+
+| Field     | Type                     | Description                                                         |
+| --------- | ------------------------ | ------------------------------------------------------------------- |
+| `entries` | `Record<string, string>` | The key-value pairs                                                 |
+| `cursor`  | `string \| undefined`    | If present, more results are available. Pass to next `list()` call. |
+
+## InMemorySessionStore
+
+The default store. Uses LRU eviction and optional sliding-window TTL.
+
+- **LRU eviction** -- when `maxEntries` is reached, the least-recently-used entry is evicted
+- **Sliding-window TTL** -- `get()` refreshes the expiry timer. Expired entries are lazily removed on read.
+- **OOM-safe** -- `maxEntries` is a hard cap across all payers
+
+```typescript
+import { InMemorySessionStore } from "aixyz/app/plugins/session";
+
+const store = new InMemorySessionStore({
+  maxEntries: 10_000, // default
+  ttlMs: 3_600_000, // 1 hour default, 0 to disable
+});
+```
+
+| Option       | Type     | Default   | Description                                      |
+| ------------ | -------- | --------- | ------------------------------------------------ |
+| `maxEntries` | `number` | `10000`   | Maximum entries across all payers. Must be >= 1. |
+| `ttlMs`      | `number` | `3600000` | Sliding-window TTL in ms. 0 disables expiry.     |
+
+## Custom Storage Backend
+
+Implement the `SessionStore` interface for Redis, a database, or any KV store:
+
+```typescript title="app/session.ts"
+import { defineSessionStore } from "aixyz/app/plugins/session";
+import type { SessionStore, ListOptions, SetOptions } from "aixyz/app/plugins/session";
+
+class RedisSessionStore implements SessionStore {
+  async get(payer: string, key: string) {
+    return (await redis.get(`${payer}:${key}`)) ?? undefined;
+  }
+  async set(payer: string, key: string, value: string, options?: SetOptions) {
+    if (options?.ttlMs) {
+      await redis.set(`${payer}:${key}`, value, "PX", options.ttlMs);
+    } else {
+      await redis.set(`${payer}:${key}`, value);
+    }
+  }
+  async delete(payer: string, key: string) {
+    return (await redis.del(`${payer}:${key}`)) > 0;
+  }
+  async list(payer: string, options?: ListOptions) {
+    // scan for keys matching payer prefix, apply options.prefix/limit/cursor
+    return {
+      entries: {
+        /* ... */
+      },
+    };
+  }
+}
+
+export default defineSessionStore(new RedisSessionStore());
+```
+
+### `SessionStore` Interface
+
+**Required methods:**
+
+| Method   | Signature                                                                            | Description             |
+| -------- | ------------------------------------------------------------------------------------ | ----------------------- |
+| `get`    | `(payer: string, key: string) => Promise<string \| undefined>`                       | Get a value             |
+| `set`    | `(payer: string, key: string, value: string, options?: SetOptions) => Promise<void>` | Store a value           |
+| `delete` | `(payer: string, key: string) => Promise<boolean>`                                   | Delete a value          |
+| `list`   | `(payer: string, options?: ListOptions) => Promise<ListResult>`                      | List values for a payer |
+
+**Optional methods:**
+
+| Method       | Signature                                                                                 | Description                 |
+| ------------ | ----------------------------------------------------------------------------------------- | --------------------------- |
+| `getMany`    | `(payer: string, keys: string[]) => Promise<Record<string, string \| undefined>>`         | Batch get                   |
+| `setMany`    | `(payer: string, entries: Record<string, string>, options?: SetOptions) => Promise<void>` | Batch set                   |
+| `deleteMany` | `(payer: string, keys: string[]) => Promise<number>`                                      | Batch delete, returns count |
+| `close`      | `() => Promise<void>`                                                                     | Release connections/timers  |
+
+## MCP Integration
+
+Sessions work automatically inside MCP tool handlers. The MCP plugin detects the session plugin and wraps tool execution with the payer context from x402 payment verification.
+
+No additional configuration is needed.
+
+## Constructor Options
+
+```typescript
+new SessionPlugin(options?: SessionPluginOptions)
+```
+
+| Option  | Type           | Default                | Description            |
+| ------- | -------------- | ---------------------- | ---------------------- |
+| `store` | `SessionStore` | `InMemorySessionStore` | Custom storage backend |
+
+<CardGroup cols={2}>
+  <Card title="x402 Payments" icon="credit-card" href="/protocols/x402">
+    Payment protocol that provides payer identity for sessions.
+  </Card>
+  <Card title="x402 Sessions Template" icon="database" href="/templates/advanced/x402-sessions">
+    Working example with session-backed content storage.
+  </Card>
+</CardGroup>

package/docs/getting-started/payments.mdx

@@ -137,3 +137,19 @@ export const facilitator = new HTTPFacilitatorClient({
 ```
 
 See the [BYO Facilitator template](/templates/advanced/with-custom-facilitator) for a working example.
+
+## Payer Identity and Sessions
+
+Every verified x402 payment identifies the payer by their wallet address. `SessionPlugin` (auto-registered by the build pipeline) gives each payer isolated key-value storage accessible via `getSession()`:
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+const session = getSession();
+if (session) {
+  await session.set("preference", "dark-mode");
+  const payer = session.payer; // "0x1234..."
+}
+```
+
+This works in both A2A agent handlers and MCP tool handlers. See [SessionPlugin](/api-reference/session-plugin) for the full API and custom store configuration.

package/docs/getting-started/project-structure.mdx

@@ -35,6 +35,11 @@ An aixyz agent is defined by a small set of files in a standard layout. Run `aix
               description: "Custom x402 facilitator",
               badge: { text: "optional override", color: "purple" },
             },
+            {
+              name: "session.ts",
+              description: "Custom session store",
+              badge: { text: "optional override", color: "purple" },
+            },
             {
               name: "erc-8004.ts",
               description: "ERC-8004 identity registration",
@@ -126,6 +131,7 @@ An aixyz agent is defined by a small set of files in a standard layout. Run `aix
 | `app/tools/*.ts`    | No       | Tool implementations, auto-discovered by the build                                |
 | `app/server.ts`     | No       | [Custom server](/api-reference/aixyz-server) — overrides auto-generation entirely |
 | `app/accepts.ts`    | No       | [Custom x402 facilitator](/api-reference/accepts) for payment verification        |
+| `app/session.ts`    | No       | [Custom session store](/api-reference/session-plugin) override for SessionPlugin  |
 | `app/erc-8004.ts`   | No       | ERC-8004 identity registration and trust config                                   |
 | `app/agent.test.ts` | No       | Agent tests using `bun:test`                                                      |
 | `app/icon.svg`      | No       | Agent icon served as a static asset                                               |
@@ -141,7 +147,8 @@ The build pipeline scans the `app/` directory to auto-generate a server:
 2. Imports `app/agent.ts` for the main agent definition (if present)
 3. Discovers all `.ts` files in `app/agents/` for sub-agents (each gets its own A2A endpoint)
 4. Discovers all `.ts` files in `app/tools/` (excluding `_` prefixed files)
-5. Wires up A2A (when agents exist), MCP (when tools exist), and x402 endpoints automatically
+5. Registers `SessionPlugin` (with custom store from `app/session.ts` if present)
+6. Wires up A2A (when agents exist), MCP (when tools exist), and x402 endpoints automatically
 
 The result is a server exposing:
 

package/docs/protocols/mcp.mdx

@@ -58,6 +58,20 @@ await server.withPlugin(
 );
 ```
 
+## Session Integration
+
+Paid MCP tools automatically get session context. When a tool is invoked with x402 payment, `getSession()` returns the payer-scoped session inside the tool handler — no additional configuration needed.
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+// Inside an MCP tool handler:
+const session = getSession();
+await session?.set("key", "value"); // stored per-payer
+```
+
+See [SessionPlugin](/api-reference/session-plugin) for the full API.
+
 ## Payment-Gated Tools
 
 Tools with `accepts.scheme === "exact"` require [x402 payment](/protocols/x402) via `@x402/mcp`. The payment wrapper is applied automatically when you provide an `accepts` configuration during registration.
@@ -81,6 +95,9 @@ await server.withPlugin(
   <Card title="Tools" icon="folder-tree" href="/api-reference/tools">
     How tools are defined in the app/ directory.
   </Card>
+  <Card title="SessionPlugin" icon="database" href="/api-reference/session-plugin">
+    Payer-scoped storage for MCP tools.
+  </Card>
   <Card title="A2A Protocol" icon="diagram-project" href="/protocols/a2a">
     Agent discovery and communication via A2A.
   </Card>

package/docs/templates/advanced/x402-sessions.mdx

@@ -0,0 +1,99 @@
+---
+title: "x402 Sessions"
+description: "Template demonstrating payer-scoped session storage with x402 payment identity"
+---
+
+<Info>**Source:** [`examples/x402-sessions`](https://github.com/AgentlyHQ/aixyz/tree/main/examples/x402-sessions)</Info>
+
+## Overview
+
+This template demonstrates `SessionPlugin` -- payer-scoped key-value storage gated by x402 payment identity. Each x402 signer gets isolated storage that persists across requests. Two different payers never see each other's data.
+
+## Project Structure
+
+```
+x402-sessions/
+├── aixyz.config.ts           # Agent metadata and skills
+├── app/
+│   ├── session.ts            # Custom session store (optional)
+│   ├── agent.ts              # Agent definition
+│   ├── accepts.ts            # Custom x402 facilitator
+│   └── tools/
+│       ├── put-content.ts    # Store content in session
+│       └── get-content.ts    # Retrieve content from session
+├── package.json
+└── vercel.json
+```
+
+## Session Store
+
+SessionPlugin is auto-registered by the build pipeline. To customize the store, create `app/session.ts`:
+
+```typescript title="app/session.ts"
+import { defineSessionStore, InMemorySessionStore } from "aixyz/app/plugins/session";
+
+// Use the built-in in-memory store. Replace with Redis, DB, etc. for production.
+export default defineSessionStore(new InMemorySessionStore());
+```
+
+If `app/session.ts` is not present, the default `InMemorySessionStore` is used automatically.
+
+## Using Sessions in Tools
+
+Tools access the session via `getSession()` -- no need to pass payer identity manually:
+
+```typescript title="app/tools/put-content.ts"
+import { tool } from "ai";
+import { z } from "zod";
+import { getSession } from "aixyz/app/plugins/session";
+import type { Accepts } from "aixyz/accepts";
+
+export default tool({
+  description: "Store a key-value pair in the current user's session",
+  inputSchema: z.object({
+    key: z.string(),
+    value: z.string().nullable(),
+  }),
+  execute: async ({ key, value }) => {
+    const session = getSession();
+    if (!session) {
+      return { success: false, error: "No authenticated signer in context" };
+    }
+
+    if (value === null) {
+      await session.delete(key);
+      return { success: true, key, deleted: true };
+    }
+
+    await session.set(key, value);
+    return { success: true, key };
+  },
+});
+
+export const accepts: Accepts = { scheme: "exact", price: "$0.01" };
+```
+
+## Skills
+
+| Skill         | Description                                     | Price  |
+| ------------- | ----------------------------------------------- | ------ |
+| `put-content` | Store key-value content in payer-scoped session | $0.01  |
+| `get-content` | Retrieve stored content from session            | $0.001 |
+
+## Running
+
+```bash
+cd examples/x402-sessions
+# create a .env file
+bun install
+bun run dev
+```
+
+<CardGroup cols={2}>
+  <Card title="SessionPlugin API" icon="plug" href="/api-reference/session-plugin">
+    Full API reference for SessionPlugin, Session, and SessionStore.
+  </Card>
+  <Card title="x402 Payments" icon="credit-card" href="/protocols/x402">
+    Payment protocol that provides payer identity for sessions.
+  </Card>
+</CardGroup>

package/docs/templates/overview.mdx

@@ -54,4 +54,7 @@ Custom server wiring, bring-your-own payment facilitator, and testing patterns.
   <Card title="Express Integration" icon="plug" href="/templates/advanced/with-express">
     Mount AixyzApp as Express middleware alongside your own routes.
   </Card>
+  <Card title="x402 Sessions" icon="database" href="/templates/advanced/x402-sessions">
+    Payer-scoped session storage with x402 payment identity.
+  </Card>
 </CardGroup>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aixyz",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Payment-native SDK for AI Agent",
   "keywords": [
     "ai",
@@ -24,6 +24,7 @@
     "./app/*": "./app/*.ts",
     "./app/adapters/*": "./app/adapters/*.ts",
     "./app/plugins/index-page": "./app/plugins/index-page/index.ts",
+    "./app/plugins/session": "./app/plugins/session/index.ts",
     "./app/plugins/*": "./app/plugins/*.ts"
   },
   "bin": "bin.js",
@@ -40,9 +41,9 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.10",
-    "@aixyz/cli": "0.34.0",
-    "@aixyz/config": "0.34.0",
-    "@aixyz/erc-8004": "0.34.0",
+    "@aixyz/cli": "0.35.0",
+    "@aixyz/config": "0.35.0",
+    "@aixyz/erc-8004": "0.35.0",
     "@kitajs/html": "^4.2.13",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@next/env": "^16.1.6",