weifuwu 0.31.2 → 0.32.1

package/README.md

@@ -64,7 +64,8 @@ app.get('/users/:id', (req, ctx) => {
 | `logger(opts?)` | Request logging. `format: 'short' | 'combined' | 'json'`. |
 | `upload(opts?)` | Multipart file upload via `req.formData()`. Injects `ctx.parsed`. |
 | `serveStatic(root, opts?)` | Static file handler. `cacheControl`, `index`. |
-| `trace(opts?)` | Injects `ctx.trace = { requestId, traceId, elapsed(), startTime }`. |
+| `sandbox(opts?)` | Filesystem isolation for agent operations. `baseDir`, `timeout`, `isolateBy`. |
+| `auth(opts?)` | Authentication: JWT, session cookies, API keys. Injects `ctx.user`. |
 
 ### Tracing
 
@@ -313,6 +314,113 @@ import { createBrowserRouter, hydrate, navigate } from 'weifuwu/react/client'
 
 See [examples/react-ssr/](examples/react-ssr/) for the full demo.
 
+### AI Agent
+
+> Requires `ai` (Vercel AI SDK). Install with a model provider:
+> ```bash
+> npm install ai @ai-sdk/openai
+> ```
+
+```ts
+import { agent } from 'weifuwu'
+import { openai } from '@ai-sdk/openai'
+import { tool } from 'ai'
+import { z } from 'zod'
+
+app.use(agent({
+  model: openai('gpt-4o'),
+  system: 'You are a helpful assistant.',
+  knowledge: {
+    // RAG — search a knowledge base before each response
+    search: async (query, ctx) => {
+      const { embeddings } = await embedModel.doEmbed({ values: [query] })
+      return ctx.sql`
+        SELECT content, 1 - (embedding <=> ${embeddings[0]}::vector) AS score
+        FROM docs ORDER BY embedding <=> ${embeddings[0]}::vector LIMIT 3
+      `
+    },
+  },
+  tools: {
+    getWeather: tool({
+      description: 'Get weather for a city',
+      parameters: z.object({ city: z.string() }),
+      execute: async ({ city }) => ({ temp: 22, unit: 'C' }),
+    }),
+  },
+  maxSteps: 5,
+}))
+
+app.post('/api/chat', async (req, ctx) => {
+  const { messages } = await req.json()
+  return ctx.agent.chatStreamResponse({ messages })
+})
+```
+
+**`agent()` handles:** multi-turn conversations, automatic tool-calling loops (maxSteps), knowledge retrieval (RAG) injected into the system prompt, and SSE streaming compatible with `useChat` from `@ai-sdk/react`.
+
+| Feature | Description |
+|---|---|
+| `ctx.agent.chat(prompt, opts?)` | Non-streaming chat with tool calling and RAG |
+| `ctx.agent.chatStreamResponse({ messages })` | SSE streaming response (useChat-compatible) |
+| `knowledge.search` | User-defined RAG callback — query any data source via `ctx` |
+| `tools` | Tool definitions (from `ai` package). Executed in automatic loops |
+| `agents` | Named sub-agents with different models/tools |
+| `sandbox: true` | Auto-integrate with `ctx.sandbox` for file operations |
+| `store` | Session persistence (save/load conversation history) |
+
+### Auth
+
+JWT extraction priority: `cookie` → `Authorization: Bearer` → `?access_token=`. All callbacks receive `ctx` so `ctx.sql` is directly available.
+
+```ts
+import { auth } from 'weifuwu'
+
+// JWT — cookie, header, or ?access_token=
+app.use(auth({ jwt: { secret: process.env.JWT_SECRET } }))
+
+// Session cookie — loadUser gets ctx
+app.use(auth({
+  session: {
+    secret: '...',
+    loadUser: async (data, ctx) => ctx.sql`SELECT * FROM users WHERE id = ${data.userId}`,
+  },
+}))
+
+// API key — header or ?api_key=
+app.use(auth({ apiKey: {
+  query: 'api_key',
+  validate: async (key, ctx) => ctx.sql`SELECT * FROM users WHERE api_key = ${key}`,
+} }))
+
+// ctx.user is now available
+app.get('/me', (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  return Response.json(ctx.user)
+})
+```
+
+Supports JWT (HS256 via cookie or Authorization header), signed session cookies with `loadUser` callback, and API key validation. All are optional — requests proceed without a user identity unless handlers enforce it.
+
+### Sandbox
+
+```ts
+import { sandbox } from 'weifuwu'
+
+app.use(sandbox({
+  baseDir: '/tmp/workspaces',
+  timeout: 30000,
+  isolateBy: 'user',  // one directory per ctx.user.id
+}))
+
+// ctx.sandbox provides isolated file + exec operations
+await ctx.sandbox.writeFile('hello.txt', 'world')
+const content = await ctx.sandbox.readFile('hello.txt')
+const { stdout } = await ctx.sandbox.exec('ls -la')
+await ctx.sandbox.destroy()  // clean up workspace
+```
+
+All file paths are validated — escapes (`../`) are rejected. `exec()` enforces timeout and sets `HOME` to the workspace directory. When `isolateBy: 'user'` is set, each user gets their own directory under `baseDir`.
+
 ### Types
 
 | Export | Description |
@@ -368,50 +476,35 @@ app.onError((err, req, ctx) => {
 ## Complete example
 
 ```ts
-import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, queue, HttpError } from 'weifuwu'
+import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, auth, sandbox, HttpError } from 'weifuwu'
+import { agent } from 'weifuwu/agent'
+import { react } from 'weifuwu/react'
+import { openai } from '@ai-sdk/openai'
 
 const app = new Router()
+  .use(trace())
+  .use(logger())
+  .use(cors())
+  .use(helmet())
+  .use(compress())
+  .use(postgres())
+  .use(redis())
+  .use(auth({ jwt: { secret: process.env.JWT_SECRET! } }))
+  .use(sandbox({ isolateBy: 'user' }))
+  .use(agent({
+    model: openai('gpt-4o'),
+    system: 'You are a helpful assistant.',
+    knowledge: {
+      search: async (q, ctx) => ctx.sql`...`,
+    },
+    sandbox: true,
+  }))
+  .plugin(react({ pages: { '/': './Chat.tsx' }, layout: './Layout.tsx', tailwind: {} }))
 
-// Global middleware
-app.use(trace())
-app.use(logger())
-app.use(cors())
-app.use(helmet())
-app.use(compress())
-app.use(rateLimit({ windowMs: 60_000, max: 100 }))
-
-// Database
-const sql = postgres()
-app.use(sql)
-
-// Routes
-app.get('/api/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT id, name FROM users ORDER BY id`
-  return Response.json(users)
-})
-
-app.post('/api/users', async (req, ctx) => {
-  const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name,email) VALUES (${name},${email}) RETURNING *`
-  return Response.json(user, { status: 201 })
-})
-
-app.get('/api/users/:id', async (req, ctx) => {
-  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  if (!user) throw new HttpError('Not found', 404)
-  return Response.json(user)
-})
-
-// WebSocket
-app.ws('/chat', {
-  open(ws, ctx) { ctx.ws.join('lobby') },
-  message(ws, ctx, data) { ctx.ws.sendRoom('lobby', { text: data.toString() }) },
-})
-
-// Error handling
-app.onError((err) => {
-  if (err instanceof HttpError) return Response.json({ error: err.message }, { status: err.status })
-  return Response.json({ error: 'Internal error' }, { status: 500 })
+app.post('/api/chat', async (req, ctx) => {
+  if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+  const { messages } = await req.json()
+  return ctx.agent.chatStreamResponse({ messages })
 })
 
 serve(app, { port: 3000 })
@@ -432,6 +525,7 @@ weifuwu/
 │   ├── types.ts
 │   ├── core/               ← serve, router, ws, trace, logger
 │   ├── middleware/          ← cors, helmet, compress, rate-limit, static, upload
+│   ├── ai/                  ← AI + agent middleware
 │   ├── postgres/
 │   ├── redis/
 │   ├── react/              ← react SSR (render, navigation, client)

package/dist/ai/agent.d.ts

@@ -0,0 +1,127 @@
+import type { Middleware, Context } from '../types.ts';
+import type { AiOptions } from '../ai/types.ts';
+declare module '../types.ts' {
+    interface Context {
+        /**
+         * AI agent — LLM integration with session management, tool calling,
+         * knowledge retrieval, and streaming.
+         * Injected by the `agent()` middleware.
+         */
+        agent: Agent;
+    }
+}
+export interface Agent {
+    /**
+     * Chat with the agent (non-streaming). Returns the final response
+     * after tool calls and knowledge retrieval.
+     */
+    chat(prompt: string, opts?: AgentChatOptions): Promise<AgentChatResult>;
+    /**
+     * Stream the agent's response as an SSE Response.
+     * Compatible with `useChat` from @ai-sdk/react.
+     */
+    chatStreamResponse(opts: AgentStreamOptions): Response;
+    /** The underlying language model. */
+    model: unknown;
+    /** Default system prompt. */
+    system: string | undefined;
+}
+export interface AgentChatOptions {
+    /** Override system prompt for this call. */
+    system?: string;
+    /** Chat history messages (from useChat). */
+    messages?: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    /** Override temperature. */
+    temperature?: number;
+    /** Override max tokens. */
+    maxTokens?: number;
+    /** Override max steps. */
+    maxSteps?: number;
+}
+export interface AgentStreamOptions {
+    /** User prompt or full message list. */
+    messages: Array<{
+        role: string;
+        content: string;
+        [key: string]: unknown;
+    }>;
+    /** Override system prompt. */
+    system?: string;
+}
+export type AgentChatResult = Record<string, any>;
+export interface AgentOptions extends AiOptions {
+    /**
+     * Knowledge base for RAG. Called before every chat to inject context.
+     */
+    knowledge?: {
+        /**
+         * Search for relevant documents given a user query.
+         * Results are injected into the system prompt.
+         */
+        search: (query: string, ctx: Context) => Promise<Array<{
+            content: string;
+            score?: number;
+        }>>;
+        /** Maximum results to inject (default: 3). */
+        topK?: number;
+        /** Minimum relevance score (default: 0). */
+        minScore?: number;
+    };
+    /**
+     * Named sub-agents with their own model, system prompt, and tools.
+     * Access via ctx.agent.agents[name].
+     */
+    agents?: Record<string, {
+        model?: unknown;
+        system?: string;
+        tools?: Record<string, unknown>;
+    }>;
+    /**
+     * Enable sandbox integration. When true and ctx.sandbox is available,
+     * the agent automatically uses it for file operations.
+     */
+    sandbox?: boolean;
+    /**
+     * Store for session persistence. Save/load conversation history.
+     */
+    store?: {
+        save: (sessionId: string, messages: unknown[]) => Promise<void>;
+        load: (sessionId: string) => Promise<unknown[]>;
+    };
+}
+/**
+ * AI Agent middleware — injects `ctx.agent` for LLM-powered conversations.
+ *
+ * Built on the Vercel AI SDK. Supports:
+ * - Multi-turn conversations with session history
+ * - Tool calling with automatic loops (maxSteps)
+ * - Knowledge retrieval (RAG) via `knowledge.search`
+ * - Streaming SSE responses compatible with `useChat` from @ai-sdk/react
+ * - Named sub-agents for role-based delegation
+ * - Sandbox integration
+ *
+ * @example
+ * ```ts
+ * import { agent } from 'weifuwu'
+ * import { openai } from '@ai-sdk/openai'
+ *
+ * app.use(agent({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are a helpful assistant.',
+ *   knowledge: {
+ *     search: async (query, ctx) => ctx.sql`...pgvector...`,
+ *   },
+ *   tools: { getWeather: tool({...}) },
+ * }))
+ *
+ * app.post('/api/chat', async (req, ctx) => {
+ *   const { messages } = await req.json()
+ *   return ctx.agent.chatStreamResponse({ messages })
+ * })
+ * ```
+ */
+export declare function agent(opts: AgentOptions): Middleware;

package/dist/ai/index.d.ts

@@ -0,0 +1,26 @@
+import type { Middleware } from '../types.ts';
+import type { AiOptions } from './types.ts';
+export type { AiOptions, Ai } from './types.ts';
+/**
+ * AI middleware — injects `ctx.ai` for LLM integration via the Vercel AI SDK.
+ *
+ * Requires a language model provider (e.g. `@ai-sdk/openai`, `@ai-sdk/anthropic`).
+ *
+ * @example
+ * ```ts
+ * import { ai } from 'weifuwu'
+ * import { openai } from '@ai-sdk/openai'
+ *
+ * app.use(ai({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are a helpful assistant.',
+ * }))
+ *
+ * app.post('/api/chat', async (req, ctx) => {
+ *   const { prompt } = await req.json()
+ *   const result = await ctx.ai.generateText({ prompt })
+ *   return Response.json({ text: result.text })
+ * })
+ * ```
+ */
+export declare function ai(opts: AiOptions): Middleware;

package/dist/ai/types.d.ts

@@ -0,0 +1,59 @@
+declare module '../types.ts' {
+    interface Context {
+        /** AI / LLM integration. Injected by the `ai()` middleware. */
+        ai: Ai;
+    }
+}
+export interface Ai {
+    /**
+     * Generate text (non-streaming). See `generateText` from the `ai` package.
+     *
+     * @example
+     * const { text, toolCalls, steps } = await ctx.ai.generateText({
+     *   prompt: 'What is the weather?',
+     * })
+     */
+    generateText(opts: GenerateTextParams): Promise<AiGenerateTextResult>;
+    /** The language model instance. */
+    model: unknown;
+    /** Default system prompt. */
+    system: string | undefined;
+}
+export type AiGenerateTextResult = Awaited<ReturnType<typeof import('ai').generateText<any, any, any>>>;
+export interface AiOptions {
+    /**
+     * Language model instance (from @ai-sdk/openai, @ai-sdk/anthropic, etc.).
+     *
+     * @example
+     * import { openai } from '@ai-sdk/openai'
+     * ai({ model: openai('gpt-4o') })
+     */
+    model: unknown;
+    /** System prompt added to every request. */
+    system?: string;
+    /** Tools available for tool calling. */
+    tools?: any;
+    /** Maximum agent steps for tool-calling loops (default: 1). */
+    maxSteps?: number;
+    /** Default temperature (0–2). */
+    temperature?: number;
+    /** Default max output tokens. */
+    maxTokens?: number;
+}
+export interface GenerateTextParams {
+    /** User prompt. */
+    prompt: string;
+    /** System prompt override. */
+    system?: string;
+    /** Chat history messages. */
+    messages?: Array<{
+        role: string;
+        content: string;
+    } & Record<string, any>>;
+    /** Override temperature. */
+    temperature?: number;
+    /** Override max tokens. */
+    maxTokens?: number;
+    /** Override max steps. */
+    maxSteps?: number;
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { Context, Handler, Middleware, ErrorHandler, WsContext, WebSocket } from './types.ts';
 export { HttpError } from './types.ts';
+export type { User } from './types.ts';
 export { currentTraceId, currentTrace, runWithTrace, traceElapsed, trace } from './core/trace.ts';
 export type { TraceContext, TraceInjected, TraceOptions } from './core/trace.ts';
 export { serve, DEFAULT_MAX_BODY } from './core/serve.ts';
@@ -10,10 +11,14 @@ export { logger } from './core/logger.ts';
 export type { LoggerOptions } from './core/logger.ts';
 export { cors } from './middleware/cors.ts';
 export type { CORSOptions } from './middleware/cors.ts';
+export { auth } from './middleware/auth.ts';
+export type { AuthOptions } from './middleware/auth.ts';
 export { serveStatic } from './middleware/static.ts';
 export type { ServeStaticOptions } from './middleware/static.ts';
 export { upload } from './middleware/upload.ts';
 export type { UploadOptions, UploadedFile, UploadModule } from './middleware/upload.ts';
+export { sandbox } from './middleware/sandbox.ts';
+export type { SandboxOptions, Sandbox } from './middleware/sandbox.ts';
 export { esbuildDev } from './middleware/esbuild-dev.ts';
 export type { EsbuildDevEntry, EsbuildDevOptions } from './middleware/esbuild-dev.ts';
 export { tailwindDev } from './middleware/tailwind-dev.ts';
@@ -37,3 +42,7 @@ export type { QueueOptions, QueueJob, Queue, QueueInjected } from './queue/types
 export { react, reactRouter } from './react/index.ts';
 export type { ReactOptions, RenderOptions, ReactRouterOptions, ReactAppOptions } from './react/types.ts';
 export { useServerData, ServerDataContext, Link, ErrorBoundary } from './react/index.ts';
+export { ai } from './ai/index.ts';
+export type { AiOptions, Ai } from './ai/index.ts';
+export { agent } from './ai/agent.ts';
+export type { AgentOptions, Agent } from './ai/agent.ts';

package/dist/index.js

@@ -9,7 +9,7 @@ var HttpError = class extends Error {
 };
 
 // src/core/trace.ts
-import crypto from "node:crypto";
+import crypto2 from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 var als = new AsyncLocalStorage();
 function currentTraceId() {
@@ -19,7 +19,7 @@ function currentTrace() {
   return als.getStore();
 }
 function runWithTrace(incomingTraceId, fn) {
-  const traceId = incomingTraceId || crypto.randomUUID();
+  const traceId = incomingTraceId || crypto2.randomUUID();
   const startTime = Date.now();
   return als.run({ traceId, startTime }, fn);
 }
@@ -30,7 +30,7 @@ function traceElapsed() {
 }
 function trace(options) {
   const header = options?.header ?? "X-Request-ID";
-  const gen = options?.generator ?? (() => crypto.randomUUID());
+  const gen = options?.generator ?? (() => crypto2.randomUUID());
   return async (req, ctx, next) => {
     const existing = req.headers.get(header);
     const requestId = existing ?? gen();
@@ -225,14 +225,14 @@ function serve(router, options) {
     if (!server.listening) return;
     server.close();
     server.closeIdleConnections();
-    return new Promise((resolve5) => {
+    return new Promise((resolve6) => {
       const timer = setTimeout(() => {
         server.closeAllConnections();
-        resolve5();
+        resolve6();
       }, timeoutMs);
       server.on("close", () => {
         clearTimeout(timer);
-        resolve5();
+        resolve6();
       });
     });
   }
@@ -277,7 +277,7 @@ function createHub(opts) {
       }
     });
   }
-  function join3(key, ws) {
+  function join4(key, ws) {
     if (!channels.has(key)) {
       channels.set(key, /* @__PURE__ */ new Set());
       redisSub?.subscribe(`${prefix}${key}`);
@@ -339,7 +339,7 @@ function createHub(opts) {
     redisPub = void 0;
     redisSub = null;
   }
-  return { join: join3, leave, broadcast, close };
+  return { join: join4, leave, broadcast, close };
 }
 
 // src/core/ws.ts
@@ -906,6 +906,82 @@ function cors(options) {
   };
 }
 
+// src/middleware/auth.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+function base64urlDecode(str) {
+  return Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8");
+}
+function sign(payload, secret) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+function parseCookie(cookieHeader, name) {
+  if (!cookieHeader) return null;
+  for (const c of cookieHeader.split(";")) {
+    const [key, ...rest] = c.trim().split("=");
+    if (key === name) return rest.join("=");
+  }
+  return null;
+}
+function auth(opts) {
+  return async (req, ctx, next) => {
+    if (opts.jwt) {
+      const cookie = opts.jwt.cookie ?? "token";
+      const token = parseCookie(req.headers.get("cookie"), cookie) ?? req.headers.get("authorization")?.replace(/^Bearer\s+/i, "") ?? ctx.query.access_token;
+      if (token) {
+        try {
+          const [headerB64, payloadB64, sigB64] = token.split(".");
+          const expectedSig = sign(`${headerB64}.${payloadB64}`, opts.jwt.secret);
+          const sigBuf = Buffer.from(sigB64, "base64url");
+          const expectedBuf = Buffer.from(expectedSig, "base64url");
+          if (sigBuf.length === expectedBuf.length && timingSafeEqual(sigBuf, expectedBuf)) {
+            const payload = JSON.parse(base64urlDecode(payloadB64));
+            ctx.user = {
+              id: payload.sub ?? payload.id ?? "unknown",
+              role: payload.role,
+              tenant: payload.tenant,
+              ...payload
+            };
+          }
+        } catch {
+        }
+      }
+    }
+    if (opts.session && !ctx.user) {
+      const cookie = opts.session.cookie ?? "session";
+      const raw = parseCookie(req.headers.get("cookie"), cookie);
+      if (raw) {
+        try {
+          const [dataB64, sigB64] = raw.split(".");
+          const expectedSig = sign(dataB64, opts.session.secret);
+          const sigBuf = Buffer.from(sigB64, "base64url");
+          const expectedBuf = Buffer.from(expectedSig, "base64url");
+          if (sigBuf.length === expectedBuf.length && timingSafeEqual(sigBuf, expectedBuf)) {
+            const data = JSON.parse(base64urlDecode(dataB64));
+            const user = await opts.session.loadUser(data, ctx);
+            if (user) ctx.user = user;
+          }
+        } catch {
+        }
+      }
+    }
+    if (opts.apiKey && !ctx.user) {
+      const header = opts.apiKey.header ?? "authorization";
+      const prefix = opts.apiKey.prefix ?? "Bearer ";
+      let raw = req.headers.get(header);
+      if (!raw && opts.apiKey.query) {
+        raw = ctx.query[opts.apiKey.query];
+        if (raw) raw = prefix + raw;
+      }
+      if (raw?.startsWith(prefix)) {
+        const key = raw.slice(prefix.length);
+        const user = await opts.apiKey.validate(key, ctx);
+        if (user) ctx.user = user;
+      }
+    }
+    return next(req, ctx);
+  };
+}
+
 // src/middleware/static.ts
 import { open, realpath } from "node:fs/promises";
 import { extname, resolve, normalize, sep } from "node:path";
@@ -1113,9 +1189,77 @@ function upload(options) {
   return mw;
 }
 
+// src/middleware/sandbox.ts
+import { join as join2, resolve as resolve2, normalize as normalize2 } from "node:path";
+import { mkdir as mkdir2, readFile, writeFile as writeFile2, rm } from "node:fs/promises";
+import { exec as cpExec } from "node:child_process";
+import { promisify } from "node:util";
+var runExec = promisify(cpExec);
+function sandbox(opts = {}) {
+  const base = resolve2(opts.baseDir ?? "/tmp/weifuwu-sandboxes");
+  const defaultTimeout = opts.timeout ?? 3e4;
+  return async (req, ctx, next) => {
+    let sessionId;
+    if (opts.isolateBy === "user" && ctx.user) {
+      sessionId = ctx.user.id ?? "default";
+    } else {
+      sessionId = crypto.randomUUID();
+    }
+    const workDir = join2(base, encodeURIComponent(sessionId));
+    await mkdir2(workDir, { recursive: true });
+    function safePath(p) {
+      const resolved = resolve2(workDir, normalize2(p).replace(/^[/\\]+/, ""));
+      if (!resolved.startsWith(workDir + "/") && resolved !== workDir) {
+        throw new Error(`Path escape rejected: ${p}`);
+      }
+      return resolved;
+    }
+    ctx.sandbox = {
+      workDir,
+      async readFile(path) {
+        return readFile(safePath(path), "utf-8");
+      },
+      async writeFile(path, content) {
+        const resolved = safePath(path);
+        await mkdir2(join2(resolved, ".."), { recursive: true });
+        return writeFile2(resolved, content, "utf-8");
+      },
+      async exec(cmd, execOpts) {
+        const cwd = execOpts?.cwd ? safePath(execOpts.cwd) : workDir;
+        const { stdout, stderr } = await runExec(cmd, {
+          cwd,
+          timeout: execOpts?.timeout ?? defaultTimeout,
+          env: {
+            ...process.env,
+            HOME: workDir,
+            PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin"
+          },
+          maxBuffer: 10 * 1024 * 1024
+          // 10MB
+        });
+        return { stdout, stderr };
+      },
+      async grep(pattern) {
+        const { stdout } = await runExec(
+          `grep -rn --include='*' "${pattern.replace(/"/g, '\\"')}" . 2>/dev/null || true`,
+          { cwd: workDir, timeout: 1e4 }
+        );
+        return stdout;
+      },
+      async destroy() {
+        await rm(workDir, { recursive: true, force: true });
+      }
+    };
+    try {
+      return await next(req, ctx);
+    } finally {
+    }
+  };
+}
+
 // src/middleware/esbuild-dev.ts
-import { resolve as resolve2, relative, dirname } from "node:path";
-import { stat, readFile, realpath as realpath2 } from "node:fs/promises";
+import { resolve as resolve3, relative, dirname } from "node:path";
+import { stat, readFile as readFile2, realpath as realpath2 } from "node:fs/promises";
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -1160,14 +1304,14 @@ async function collectDeps(entryPath) {
       continue;
     }
     try {
-      const content = await readFile(p, "utf-8");
+      const content = await readFile2(p, "utf-8");
       const importRe = /from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g;
       let m;
       while ((m = importRe.exec(content)) !== null) {
         const spec = m[1] ?? m[2];
         if (spec.startsWith(".") || spec.startsWith("/")) {
           const dir = dirname(p);
-          const resolved = resolve2(dir, spec);
+          const resolved = resolve3(dir, spec);
           for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", "/index.ts", "/index.tsx", "/index.js"]) {
             const candidate = resolved + ext;
             if (!visited.has(candidate)) {
@@ -1274,7 +1418,7 @@ ${entries2.join("\n")}
         format: entry.format ?? "esm",
         sourcemap: entry.sourcemap ?? false,
         splitting: entry.splitting ?? false,
-        ...entry.splitting ? { outdir: resolve2(".weifuwu-esbuild-out") } : {},
+        ...entry.splitting ? { outdir: resolve3(".weifuwu-esbuild-out") } : {},
         define: entry.define,
         loader: entry.loader,
         write: false,
@@ -1295,7 +1439,7 @@ ${entries2.join("\n")}
         }]
       };
     } else {
-      entryAbs = resolve2(entry.entry);
+      entryAbs = resolve3(entry.entry);
       buildOpts = {
         entryPoints: [entryAbs],
         bundle: entry.bundle ?? true,
@@ -1412,7 +1556,7 @@ ${entries2.join("\n")}
       }
       const { code, etag, chunks } = await compile(config);
       const depEntry = config.clientRouter?.routes ?? (config.clientRouter?.pages ? Object.values(config.clientRouter.pages)[0] : void 0) ?? config.entry;
-      const deps = await collectDeps(resolve2(depEntry));
+      const deps = await collectDeps(resolve3(depEntry));
       if (cache === "memory") {
         cacheStore.set(pathname, { code, etag, files: deps, chunks });
         if (chunks) {
@@ -1447,8 +1591,8 @@ function hashCode(s) {
 }
 
 // src/middleware/tailwind-dev.ts
-import { resolve as resolve3 } from "node:path";
-import { stat as stat2, readFile as readFile2, glob } from "node:fs/promises";
+import { resolve as resolve4 } from "node:path";
+import { stat as stat2, readFile as readFile3, glob } from "node:fs/promises";
 function escapeHtml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -1482,11 +1626,11 @@ var CLASS_CONTEXT_RE = /(?:class(?:Name)?\s*[=:]\s*["'`]([^"'`]+)["'`]|["'`]([^"
 async function extractCandidates(patterns, root) {
   const seen = /* @__PURE__ */ new Set();
   for (const pattern of patterns) {
-    const resolved = resolve3(root, pattern);
+    const resolved = resolve4(root, pattern);
     try {
       for await (const file of glob(resolved)) {
         try {
-          const content = await readFile2(file, "utf-8");
+          const content = await readFile3(file, "utf-8");
           for (const m of content.matchAll(CLASS_CONTEXT_RE)) {
             const str = m[1] ?? m[2];
             if (!str) continue;
@@ -1553,9 +1697,9 @@ ${String(err)}`;
   }
   async function compileCss(entry) {
     const compile = await getCompile();
-    const entryAbs = resolve3(entry.entry);
-    const cssSource = await readFile2(entryAbs, "utf-8");
-    const baseDir = resolve3(entry.entry, "..");
+    const entryAbs = resolve4(entry.entry);
+    const cssSource = await readFile3(entryAbs, "utf-8");
+    const baseDir = resolve4(entry.entry, "..");
     const deps = [entryAbs];
     const result = await compile(cssSource, {
       base: baseDir,
@@ -1566,7 +1710,7 @@ ${String(err)}`;
     const contentPatterns = entry.content ?? [];
     for (const src of result.sources) {
       if (!src.negated) {
-        contentPatterns.push(resolve3(src.base, src.pattern));
+        contentPatterns.push(resolve4(src.base, src.pattern));
       }
     }
     let candidates = [];
@@ -1576,7 +1720,7 @@ ${String(err)}`;
     const css = result.build(candidates);
     for (const pattern of contentPatterns) {
       try {
-        for await (const file of glob(resolve3(baseDir, pattern))) {
+        for await (const file of glob(resolve4(baseDir, pattern))) {
           if (!deps.includes(file)) deps.push(file);
         }
       } catch {
@@ -1746,10 +1890,10 @@ function addRateLimitHeaders(res, limit, remaining, reset) {
 
 // src/middleware/compress.ts
 import { constants, brotliCompress, gzip, deflate } from "node:zlib";
-import { promisify } from "node:util";
-var brotliCompressAsync = promisify(brotliCompress);
-var gzipAsync = promisify(gzip);
-var deflateAsync = promisify(deflate);
+import { promisify as promisify2 } from "node:util";
+var brotliCompressAsync = promisify2(brotliCompress);
+var gzipAsync = promisify2(gzip);
+var deflateAsync = promisify2(deflate);
 function compress(options) {
   const level = options?.level ?? 6;
   const threshold = options?.threshold ?? 1024;
@@ -2154,7 +2298,7 @@ function redis(opts) {
 }
 
 // src/queue/index.ts
-import crypto2 from "node:crypto";
+import crypto3 from "node:crypto";
 import { Redis as IORedis2 } from "ioredis";
 
 // src/queue/cron.ts
@@ -2268,7 +2412,7 @@ function queue(opts) {
     }
     if (job.schedule) {
       try {
-        await insert({ ...job, id: crypto2.randomUUID(), runAt: cronNext(job.schedule), createdAt: Date.now() });
+        await insert({ ...job, id: crypto3.randomUUID(), runAt: cronNext(job.schedule), createdAt: Date.now() });
       } catch {
       }
     }
@@ -2294,7 +2438,7 @@ function queue(opts) {
   });
   const q = mw;
   mw.add = function add(type, payload, opts2) {
-    const id = crypto2.randomUUID();
+    const id = crypto3.randomUUID();
     let runAt;
     if (opts2?.schedule) {
       try {
@@ -2412,7 +2556,7 @@ function queue(opts) {
     return r;
   };
   q.cron = function(pattern, handler) {
-    const id = "__cron_" + pattern.replace(/[^a-zA-Z0-9]/g, "_") + "_" + crypto2.randomUUID().slice(0, 8);
+    const id = "__cron_" + pattern.replace(/[^a-zA-Z0-9]/g, "_") + "_" + crypto3.randomUUID().slice(0, 8);
     q.process(id, async () => {
       await handler();
     });
@@ -2427,8 +2571,8 @@ import { createElement as createElement2 } from "react";
 import { renderToReadableStream } from "react-dom/server";
 
 // src/react/compile.ts
-import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile3 } from "node:fs/promises";
-import { resolve as resolve4, join as join2, dirname as dirname2 } from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile4 } from "node:fs/promises";
+import { resolve as resolve5, join as join3, dirname as dirname2 } from "node:path";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 var EXTERNAL_PKGS = [
@@ -2481,14 +2625,14 @@ function setReactCacheDir(dir) {
 }
 function getCacheDir() {
   if (_cacheDir) return _cacheDir;
-  _cacheDir = join2(process.cwd(), "node_modules", ".weifuwu", "react");
+  _cacheDir = join3(process.cwd(), "node_modules", ".weifuwu", "react");
   return _cacheDir;
 }
 async function loadTsxModule(entryPath) {
-  const abs = resolve4(entryPath);
+  const abs = resolve5(entryPath);
   let source;
   try {
-    source = await readFile3(abs, "utf-8");
+    source = await readFile4(abs, "utf-8");
   } catch {
     throw new Error(`Cannot read file: ${entryPath}`);
   }
@@ -2498,7 +2642,7 @@ async function loadTsxModule(entryPath) {
     return memCached.mod;
   }
   const tmpDir = getCacheDir();
-  const tmpFile = join2(tmpDir, `${sourceHash}.mjs`);
+  const tmpFile = join3(tmpDir, `${sourceHash}.mjs`);
   if (existsSync(tmpFile)) {
     try {
       const mod2 = await import(tmpFile + "?" + sourceHash);
@@ -2521,8 +2665,8 @@ async function loadTsxModule(entryPath) {
   let code = result.outputFiles[0]?.text ?? "";
   if (!code) throw new Error(`esbuild produced empty output for ${entryPath}`);
   code = rewriteImports(code);
-  await mkdir2(dirname2(tmpFile), { recursive: true });
-  await writeFile2(tmpFile, code);
+  await mkdir3(dirname2(tmpFile), { recursive: true });
+  await writeFile3(tmpFile, code);
   const mod = await import(tmpFile + "?" + sourceHash);
   memCache.set(abs, { sourceHash, mod });
   return mod;
@@ -2794,6 +2938,149 @@ function reactRouter(app, routes, opts = {}) {
 function Link({ href, children, ...props }) {
   return createElement2("a", { href, ...props }, children);
 }
+
+// src/ai/index.ts
+function ai(opts) {
+  let aiModule = null;
+  const model = opts.model;
+  async function getAi() {
+    if (!aiModule) aiModule = await import("ai");
+    return aiModule;
+  }
+  return async (_req, ctx, next) => {
+    ctx.ai = {
+      model,
+      system: opts.system,
+      async generateText(params) {
+        const { generateText } = await getAi();
+        const messages = [...params.messages ?? []];
+        const system = params.system ?? opts.system;
+        if (system) {
+          const hasSystem = messages.some((m) => m.role === "system");
+          if (!hasSystem) {
+            messages.unshift({ role: "system", content: system });
+          }
+        }
+        const baseOpts = {
+          model,
+          tools: opts.tools,
+          maxSteps: params.maxSteps ?? opts.maxSteps ?? 1,
+          temperature: params.temperature ?? opts.temperature,
+          maxTokens: params.maxTokens ?? opts.maxTokens,
+          abortSignal: _req.signal
+        };
+        if (messages.length > 0) {
+          baseOpts.messages = messages;
+        } else {
+          baseOpts.prompt = params.prompt;
+        }
+        return generateText(baseOpts);
+      }
+    };
+    return next(_req, ctx);
+  };
+}
+
+// src/ai/agent.ts
+function agent(opts) {
+  let aiModule = null;
+  async function getAi() {
+    if (!aiModule) aiModule = await import("ai");
+    return aiModule;
+  }
+  return async (req, ctx, next) => {
+    ctx.agent = {
+      model: opts.model,
+      system: opts.system,
+      async chat(prompt, chatOpts = {}) {
+        const { generateText } = await getAi();
+        let knowledgeContext = "";
+        if (opts.knowledge) {
+          try {
+            const results = await opts.knowledge.search(prompt, ctx);
+            const topK = opts.knowledge.topK ?? 3;
+            const minScore = opts.knowledge.minScore ?? 0;
+            const filtered = results.filter((r) => (r.score ?? 1) >= minScore).slice(0, topK);
+            if (filtered.length > 0) {
+              knowledgeContext = "\n\n\u53C2\u8003\u4EE5\u4E0B\u77E5\u8BC6\uFF1A\n" + filtered.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+            }
+          } catch {
+          }
+        }
+        const system = chatOpts.system ?? opts.system ?? "";
+        const messages = [...chatOpts.messages ?? []];
+        if (system) {
+          const hasSystem = messages.some((m) => m.role === "system");
+          if (!hasSystem) {
+            messages.unshift({
+              role: "system",
+              content: knowledgeContext ? system + knowledgeContext : system
+            });
+          } else if (knowledgeContext) {
+            const sysMsg = messages.find((m) => m.role === "system");
+            if (sysMsg) sysMsg.content += knowledgeContext;
+          }
+        }
+        if (prompt && !messages.some((m) => m.role === "user")) {
+          messages.push({ role: "user", content: prompt });
+        }
+        const result = await generateText({
+          model: opts.model,
+          messages,
+          tools: opts.tools,
+          maxSteps: chatOpts.maxSteps ?? opts.maxSteps ?? 1,
+          temperature: chatOpts.temperature ?? opts.temperature,
+          maxTokens: chatOpts.maxTokens ?? opts.maxTokens,
+          abortSignal: req.signal
+        });
+        return {
+          text: result.text,
+          toolCalls: result.toolCalls,
+          toolResults: result.toolResults,
+          steps: result.steps,
+          finishReason: result.finishReason,
+          usage: result.usage
+        };
+      },
+      chatStreamResponse(streamOpts) {
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+          async start(controller) {
+            try {
+              const result = await ctx.agent.chat(
+                streamOpts.messages.filter((m) => m.role === "user").pop()?.content ?? "",
+                {
+                  messages: streamOpts.messages,
+                  system: streamOpts.system
+                }
+              );
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "text", content: result.text })}
+
+`));
+              controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+              controller.close();
+            } catch (err) {
+              controller.enqueue(encoder.encode(
+                `data: ${JSON.stringify({ type: "error", error: String(err) })}
+
+`
+              ));
+              controller.close();
+            }
+          }
+        });
+        return new Response(stream, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          }
+        });
+      }
+    };
+    return next(req, ctx);
+  };
+}
 export {
   DEFAULT_MAX_BODY,
   ErrorBoundary,
@@ -2802,6 +3089,9 @@ export {
   MIGRATIONS_TABLE,
   Router,
   ServerDataContext,
+  agent,
+  ai,
+  auth,
   compress,
   cors,
   createHub,
@@ -2818,6 +3108,7 @@ export {
   reactRouter,
   redis,
   runWithTrace,
+  sandbox,
   serve,
   serveStatic,
   tailwindDev,

package/dist/middleware/auth.d.ts

@@ -0,0 +1,70 @@
+import type { Middleware, User, Context } from '../types.ts';
+export interface AuthOptions {
+    /**
+     * JWT authentication.
+     *
+     * @example
+     * auth({ jwt: { secret: process.env.JWT_SECRET } })
+     */
+    jwt?: {
+        /** HMAC secret for HS256. */
+        secret: string;
+        /** Cookie name for the token (default: 'token'). */
+        cookie?: string;
+    };
+    /**
+     * Simple session authentication via signed cookie.
+     *
+     * @example
+     * auth({ session: { secret: '...' } })
+     */
+    session?: {
+        /** Secret for HMAC cookie signing. */
+        secret: string;
+        /** Cookie name (default: 'session'). */
+        cookie?: string;
+        /** Load user from session data. `ctx` has `ctx.sql`, `ctx.redis`, etc. */
+        loadUser: (data: Record<string, unknown>, ctx: Context) => Promise<User | null> | User | null;
+    };
+    /**
+     * API key authentication via header.
+     *
+     * @example
+     * auth({ apiKey: { header: 'x-api-key', keys: ['sk-xxx'] } })
+     */
+    apiKey?: {
+        /** Header name (default: 'authorization'). */
+        header?: string;
+        /** Prefix to strip (default: 'Bearer '). */
+        prefix?: string;
+        /** Query parameter name (e.g. 'api_key'). */
+        query?: string;
+        /** Validate an API key → User or null. `ctx` has `ctx.sql`, `ctx.redis`, etc. */
+        validate: (key: string, ctx: Context) => Promise<User | null> | User | null;
+    };
+}
+/**
+ * Authentication middleware — injects `ctx.user`.
+ *
+ * Supports JWT (HS256), signed session cookies, and API keys.
+ * When no user is authenticated, requests still proceed —
+ * check `ctx.user` in your handlers to enforce auth.
+ *
+ * @example
+ * ```ts
+ * // JWT
+ * app.use(auth({ jwt: { secret: 'my-secret' } }))
+ *
+ * // Session cookie
+ * app.use(auth({
+ *   session: {
+ *     secret: '...',
+ *     loadUser: async (data, ctx) => ctx.sql`SELECT * FROM users WHERE id = ${data.userId}`,
+ *   },
+ * }))
+ *
+ * // API key
+ * app.use(auth({ apiKey: { validate: async (key, ctx) => ctx.sql`...` } }))
+ * ```
+ */
+export declare function auth(opts: AuthOptions): Middleware;

package/dist/middleware/sandbox.d.ts

@@ -0,0 +1,52 @@
+import type { Middleware } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        /** Filesystem sandbox for agent operations. Injected by sandbox(). */
+        sandbox: Sandbox;
+    }
+}
+export interface SandboxOptions {
+    /** Root directory for all workspaces (default: '/tmp/weifuwu-sandboxes'). */
+    baseDir?: string;
+    /** Default timeout for exec() in ms (default: 30000). */
+    timeout?: number;
+    /** Isolate workspaces by a ctx field. If 'user', uses ctx.user.id. */
+    isolateBy?: 'user';
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+export interface Sandbox {
+    /** The workspace directory for the current request. */
+    workDir: string;
+    /** Read a file inside the workspace. */
+    readFile(path: string): Promise<string>;
+    /** Write a file inside the workspace. Creates parent directories. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Execute a command inside the workspace. */
+    exec(cmd: string, opts?: {
+        timeout?: number;
+        cwd?: string;
+    }): Promise<ExecResult>;
+    /** Grep for a pattern inside the workspace. */
+    grep(pattern: string): Promise<string>;
+    /** Destroy the workspace (called when the session ends). */
+    destroy(): Promise<void>;
+}
+/**
+ * Filesystem sandbox middleware.
+ *
+ * Each request gets an isolated workspace directory. File and exec
+ * operations are restricted to the workspace — path escapes are rejected.
+ *
+ * @example
+ * ```ts
+ * app.use(sandbox({ baseDir: '/tmp/workspaces', isolateBy: 'user' }))
+ *
+ * // In a handler:
+ * await ctx.sandbox.writeFile('hello.txt', 'world')
+ * const content = await ctx.sandbox.readFile('hello.txt')
+ * ```
+ */
+export declare function sandbox(opts?: SandboxOptions): Middleware;

package/dist/types.d.ts

@@ -19,6 +19,13 @@ export interface WebSocket {
     removeEventListener(event: string, handler: (...args: unknown[]) => void): void;
 }
 export type { Redis, RedisOptions } from 'ioredis';
+/** User injected by auth() middleware. */
+export interface User {
+    id: string;
+    role?: string;
+    tenant?: string;
+    [key: string]: unknown;
+}
 export interface WsContext {
     /** Per-connection state object */
     state: Record<string, unknown>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.31.2",
+  "version": "0.32.1",
   "description": "Web-standard HTTP microframework for Node.js — (req, ctx) => Response",
   "exports": {
     ".": {
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@graphql-tools/schema": "^10",
+    "ai": "^7.0.14",
     "graphql": "^16",
     "ioredis": "^5.11.0",
     "postgres": "^3.4.9",