weifuwu 0.9.6 → 0.11.0

package/README.md

@@ -6,7 +6,7 @@
 
 weifuwu doesn't invent its own request/response abstraction. `Request` and `Response` are the same objects you use in `fetch()` — what you learn in the browser applies directly on the server. `ctx` is the only framework object, and it only carries what the router parsed for you (`params`, `query`).
 
-Everything follows the same `(req, ctx) => Response` contract. The Router handles HTTP routing and WebSocket. All other features — auth, validation, database, GraphQL, AI, workflow — are standalone modules you import and mount with `app.use()`.
+Everything follows the same `(req, ctx) => Response` contract. The Router handles HTTP routing and WebSocket. All other features — auth, validation, database, GraphQL, AI — are standalone modules you import and mount with `app.use()`.
 
 ## Features
 
@@ -18,8 +18,8 @@ Everything follows the same `(req, ctx) => Response` contract. The Router handle
 - **WebSocket** — `router.ws()` with upgrade middleware (auth before connect)
 - **GraphQL** — `graphql(handler)` sub-Router with GraphiQL IDE
 - **AI streaming** — `ai(handler)` sub-Router via Vercel AI SDK
-- **AI workflows** — `workflow(handler)` sub-Router — intent-to-execution pipelines with `tool()` + SSE
-- **AI Agent** — `agent()` — server-side AI agents with chat/workflow/knowledge types, OpenAI-compatible, Ollama-ready
+- **DAG workflow tool** — `runWorkflow()` — multi-step execution engine as a single AI SDK `Tool`
+- **AI Agent** — `agent()` — server-side AI agents with chat/tool-use/knowledge types, OpenAI-compatible, Ollama-ready
 - **Messaging** — `messager()` — real-time chat with channels, WebSocket, agent routing, webhook support
 - **Tenant BaaS** — `tenant()` — multi-tenant dynamic tables, auto REST + GraphQL, row-level isolation, pgvector/HNSW
 - **Redis** — `redis()` — ioredis client, `ctx.redis`, middleware
@@ -221,83 +221,247 @@ Features: MIME type detection (20+ types), ETag + If-None-Match (304), directory
 
 ## PostgreSQL
 
-Built-in PostgreSQL — zero config, zero ORM, zero migration files.
+Built-in PostgreSQL client — connection management, type-safe DDL, transactions, and module lifecycle.
 
 ```ts
 import { serve, Router, postgres } from 'weifuwu'
-import { z } from 'zod'
 
 const app = new Router()
-const pg = postgres()
+const pg = postgres()          // reads DATABASE_URL
+app.use(pg)                     // injects ctx.sql into handlers
+```
+
+### Type-safe DDL with schema builder
 
-const User = pg.table('users', {
-  id:    z.number().optional(),    // → SERIAL PRIMARY KEY
-  name:  z.string().min(1),       // → TEXT NOT NULL
-  email: z.string().email(),      // → TEXT NOT NULL
-  age:   z.number().optional(),   // → INTEGER
+Define tables declaratively with type inference — no raw SQL for common operations, no Zod needed:
+
+```ts
+import { pgTable, serial, uuid, text, integer, boolean, timestamptz, jsonb, sql } from 'weifuwu'
+
+const users = pgTable('_users', {
+  id:        serial('id').primaryKey(),
+  name:      text('name').notNull(),
+  email:     text('email').unique().notNull(),
+  age:       integer('age'),
+  active:    boolean('active').default(true),
+  createdAt: timestamptz('created_at').default(sql`NOW()`),
+  metadata:  jsonb<{ role: string }>('metadata'),
 })
+```
 
-await pg.migrate()
-// Auto-creates tables / adds missing columns via information_schema
-app.use(pg)  // injects ctx.sql into handlers
+Supports 10 column types:
+| Builder | DDL | TS Type |
+|---------|-----|---------|
+| `serial()` | `SERIAL` | `number` |
+| `uuid()` | `UUID` | `string` |
+| `text()` | `TEXT` | `string` |
+| `integer()` | `INTEGER` | `number` |
+| `boolean()` | `BOOLEAN` | `boolean` |
+| `timestamptz()` | `TIMESTAMPTZ` | `string` |
+| `jsonb<T>()` | `JSONB` | `T` |
+| `textArray()` | `TEXT[]` | `string[]` |
+| `vector(name, dims)` | `vector(N)` | `number[]` |
+
+Column constraints chainable: `.primaryKey()`, `.notNull()`, `.nullable()`, `.default(value | sql\`...\`)`, `.unique()`, `.references(table, column?, onDelete?)`.
+
+### DDL execution
+
+```ts
+await users.create()                         // CREATE TABLE IF NOT EXISTS
+await users.createIndex('email')             // CREATE INDEX
+await users.createUniqueIndex('slug')        // CREATE UNIQUE INDEX
+await users.createIndex('created_at', { desc: true })
+await users.createIndex(['a', 'b'])          // multi-column
+await users.createIndex('embedding', {       // pgvector HNSW
+  type: 'hnsw', operator: 'vector_cosine_ops',
+})
+await users.drop({ cascade: true })
 ```
 
-### 6 methods — HTTP semantics
+### Type-safe CRUD with BoundTable
+
+Two usage paths — use `pg.table()` when you have a `pg` handle, or `pgTable()` with explicit `sql`:
 
 ```ts
-User.get(1)                          // GET    /users/:id
-User.list({ name: 'a' },             // GET    /users?name=a
-  { limit: 10, offset: 0, sort: { id: 'desc' } })
-// → { rows: User[], count: number }
+// pg.table() — auto-binds sql, no need to pass it
+const users = pg.table('_users', {
+  id:        serial('id').primaryKey(),
+  name:      text('name').notNull(),
+  email:     text('email').unique(),
+  active:    boolean('active').default(true),
+  createdAt: timestamptz('created_at').default(sql`NOW()`),
+})
 
-User.create({ name: 'A', email: 'a@b.com' })           // POST   /users
-User.patch(1, { name: 'B' })                           // PATCH  /users/:id
-User.remove(1)                                          // DELETE /users/:id
+// INSERT ... RETURNING * — auto-strips serial id
+const user = await users.insert({ name: 'Alice', email: 'alice@test.com' })
+// → { id: 1, name: 'Alice', email: 'alice@test.com', active: true, ... }
+
+// SELECT ... WHERE id = ? LIMIT 1
+const found = await users.findById(1)
+
+// SELECT ... WHERE ... [ORDER BY ...] [LIMIT ...] [OFFSET ...]
+const admins = await users.find({ role: 'admin' })
+const sorted = await users.find({ active: true }, { orderBy: { name: 'asc' } })
+const page = await users.find(undefined, { limit: 10, offset: 0 })
+const filtered = await users.find({ role: 'admin' }, { orderBy: { name: 'desc' }, limit: 5 })
+
+// UPDATE ... SET ... WHERE ... RETURNING *
+const updated = await users.update({ id: 1 }, { name: 'Bob' })
+// With SQL expressions:
+await users.update({ id: 1 }, { name: 'Bob', updated_at: sql`NOW()` })
+
+// DELETE ... WHERE ... RETURNING 1
+const ok = await users.delete({ id: 1 })
+```
+
+When using `pgTable()` directly (without `pg`), pass `sql` as the first argument:
+
+```ts
+const t = pgTable('_users', { ... })
+await t.insert(ctx.sql, { name: 'Alice' })
+await t.find(ctx.sql, { role: 'admin' }, { orderBy: { name: 'asc' } })
 ```
 
-Every method validates input against your zod schema automatically. Complex queries use `ctx.sql`:
+### Complex queries use raw SQL
 
 ```ts
 app.get('/users/stats', async (req, ctx) => {
   const rows = await ctx.sql`
     SELECT u.*, count(p.id) as posts
-    FROM users u LEFT JOIN posts p ON p.user_id = u.id
+    FROM ${users} u LEFT JOIN posts p ON p.user_id = u.id
     GROUP BY u.id
   `
   return Response.json(rows)
 })
 ```
 
-### Migration-free sync
+### Transactions
 
-`pg.migrate()` queries `information_schema.columns` and only runs the DDL needed:
+```ts
+const result = await pg.transaction(async (tx) => {
+  const [user] = await tx`INSERT INTO "_users" (...) VALUES (...) RETURNING *`
+  const [wallet] = await tx`INSERT INTO "_wallets" ("user_id") VALUES (${user.id}) RETURNING *`
+  return { user, wallet }
+})
+```
 
-- **Table missing** → `CREATE TABLE IF NOT EXISTS`
-- **Column missing** → `ALTER TABLE ADD COLUMN IF NOT EXISTS`
-- **Existing** → no-op
+### Connection lifecycle
 
-Safe for production: never drops or alters existing columns. Destructive operations (rename, type change, drop) are done via `ctx.sql`.
+```ts
+const pg = postgres()                          // reads DATABASE_URL
+const pg = postgres('postgres://...')          // explicit connection
+const pg = postgres({
+  connection: 'postgres://...',
+  max: 10,                                     // pool size
+  ssl: { rejectUnauthorized: false },          // SSL options
+  idle_timeout: 30,                            // idle timeout (s)
+  connect_timeout: 10,                         // connection timeout (s)
+  closeTimeout: 5,                             // close grace period (s)
+  signal: ac.signal,                           // abort → sql.end()
+})
+await pg.close()
+```
 
-### Connection lifecycle
+### Module base class
+
+Every database module (`opencode`, `messager`, `tenant`, `agent`, `user`) extends `PgModule`:
+
+```ts
+import { PgModule } from 'weifuwu'
+
+class MyModule extends PgModule {
+  constructor(pg: PostgresClient) {
+    super(pg)   // sets this.sql = pg.sql
+  }
+  async migrate() { /* override */ }
+  // close() inherited — calls pg.close() automatically
+}
+```
+
+## Opencode
+
+AI programming assistant — chat with LLM agents that have access to filesystem tools, skills, and isolated session workspaces.
 
 ```ts
-const pg = postgres()                        // reads DATABASE_URL
-const pg = postgres('postgres://...')        // explicit connection
-const pg = postgres({ signal: ac.signal })   // abort → sql.end()
-await pg.close()                             // explicit close
+import { serve, Router, postgres, opencode } from 'weifuwu'
+
+const app = new Router()
+const pg = postgres()
+const oc = await opencode({ pg, permissions: { ... } })
+
+await oc.migrate()
+app.use('/opencode', await oc.router())
+app.ws('/opencode', oc.wsHandler())
+
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
+```
+
+### Session-isolated workspaces
+
+Each session gets its own sandbox directory — tools operate within it, files cannot escape:
+
 ```
+cwd/.sessions/opencode/1/    ← session 1's workspace
+cwd/.sessions/opencode/2/    ← session 2's workspace
+cwd/.sessions/chat/3/        ← different mount point
+```
+
+Workspaces are computed from `cwd { ctx.mountPath } { sessionId }`. The system prompt shows the session's workspace so the LLM knows where it is.
 
-### Primary keys
+### Tools
 
-| zod field | PostgreSQL |
-|-----------|-----------|
-| `id: z.number().optional()` | `SERIAL PRIMARY KEY` |
-| `id: z.string().uuid().optional()` | `UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
-| `id: z.string()` | `TEXT PRIMARY KEY` (you pass the value) |
+| Tool | Description |
+|------|-------------|
+| `bash` | Execute shell commands in the workspace |
+| `read` | Read files with offset/limit |
+| `write` | Create or overwrite files |
+| `edit` | Exact string replacements |
+| `grep` | Regex content search |
+| `glob` | Glob pattern file search |
+| `web` | Fetch URL content |
+| `question` | Ask the user for input |
+| `skill` | Load a skill on demand |
 
-## Authentication
+### Skills
 
-Built-in user management — password login, JWT, and OAuth2 Server. Zero config beyond PostgreSQL and a secret key.
+Skills are discovered from filesystem and loaded on demand via the `skill` tool — no system prompt bloat:
+
+- Project: `.opencode/skills/{name}/SKILL.md`
+- Global: `~/.config/opencode/skills/{name}/SKILL.md`
+- Also reads: `.claude/skills/`, `.agents/skills/` (project + global)
+
+```ts
+const oc = await opencode({
+  pg,
+  skills: [{ name: 'git', description: 'Git workflow', content: '...' }],
+})
+```
+
+### Permissions
+
+Control tool access per conversation:
+
+```ts
+const oc = await opencode({
+  pg,
+  permissions: {
+    bash: { allow: true },
+    read: { allow: true },
+    write: { allow: false },
+    edit: { allow: false },
+    skill: { '*': { allow: true }, 'internal-*': { allow: false } },
+  },
+})
+```
+
+### Workspace isolation
+
+```ts
+const oc = await opencode({ pg, permissions })
+// All sessions inherit the instance's workspace (default: process.cwd())
+// Sessions cannot override their workspace
+// Different mount points = different opencode() instances = isolated workspaces
+```
 
 ```ts
 import { serve, Router, postgres, user } from 'weifuwu'
@@ -570,7 +734,7 @@ await fetch('http://localhost/api/sys/tenants/invite', {
 
 ## AI Agent
 
-Server-side AI agents with OpenAI-compatible API. Built-in chat, workflow (tool-calling), and knowledge (RAG) types. Works out of the box with Ollama or any OpenAI-compatible provider.
+Server-side AI agents with OpenAI-compatible API. Built-in chat, tool-use (tool-calling), and knowledge (RAG) types. Works out of the box with Ollama or any OpenAI-compatible provider.
 
 ```ts
 import { agent } from 'weifuwu'
@@ -584,7 +748,7 @@ app.use('/api', agents.router())
 | Type | Description | Execution |
 |------|-------------|-----------|
 | `chat` | Pure conversation | `streamText()` / `generateText()` |
-| `workflow` | Tool-calling agent | `streamText({ tools })` |
+| `tool-use` | Tool-calling agent | `streamText({ tools })` |
 
 ### Knowledge (RAG)
 
@@ -721,18 +885,18 @@ app.use('/chat', ai(async (req, ctx) => {
 serve(app.handler(), { port: 3000 })
 ```
 
-## Workflow
+## runWorkflow
 
-Define business capabilities as **Tools** (`tool()`), then chain them into **workflows** for AI-driven multi-step execution. Works with or without an LLM — hand-write the workflow JSON or let AI generate it from a goal.
+Multi-step DAG execution engine — packaged as a single AI SDK `Tool`. Use it with `streamText()` or `generateText()` when the LLM needs conditional logic, loops, or multi-step tool orchestration.
 
 ```ts
-import { Router, tool, workflow } from 'weifuwu'
+import { tool, streamText } from 'ai'
+import { runWorkflow } from 'weifuwu'
 import { z } from 'zod'
 
-// 1. Define tools (business capabilities)
 const tools = {
   queryUser: tool({
-    description: 'Query user info, returns email, name',
+    description: 'Query user info',
     inputSchema: z.object({ userId: z.string() }),
     execute: async ({ userId }) => ({ id: userId, email: 'user@test.com', name: 'Test' }),
   }),
@@ -741,139 +905,57 @@ const tools = {
     inputSchema: z.object({ to: z.string(), subject: z.string() }),
     execute: async ({ to, subject }) => ({ sent: true }),
   }),
+  runWF: runWorkflow({ tools: { queryUser, sendEmail } }),
 }
 
-// 2. Mount workflow sub-router
-const app = new Router()
-app.use('/agent', workflow(() => ({ tools })))
-// POST /agent  { nodes: [...] }  →  200 { workflow: {...}, result: ... }
-
-// With SSE streaming:
-app.use('/agent-stream', workflow(() => ({ tools, stream: true })))
-// POST /agent-stream  { nodes: [...] }
-// → 200 { workflowId: "xxx", eventsUrl: "/xxx/events" }
-// GET  /agent-stream/:workflowId/events
-// → SSE: workflow-start → node-start → node-end → complete
-
-// With LLM model (generates workflow from goal):
-app.use('/agent-llm', workflow(() => ({
+// Use in any streamText call — the LLM can decide when to trigger a workflow
+const result = await streamText({
+  model,
   tools,
-  model: openai('gpt-4o'),
-})))
-// POST /agent-llm  { goal: "给用户123发欢迎邮件" }
-// ← LLM generates → executes → returns result
-```
-
-### Tool
-
-```ts
-import { tool } from 'weifuwu'
-import { z } from 'zod'
-
-const myTool = tool({
-  description: '做什么的，返回什么',
-  inputSchema: z.object({ key: z.string() }),
-  execute: async (input, ctx) => {
-    return { result: input.key }
-  },
-})
-```
-
-`ctx.onStream` 用于流式推送（如 LLM token 输出）：
-
-```ts
-const llmTool = tool({
-  description: '生成文本',
-  inputSchema: z.object({ prompt: z.string() }),
-  execute: async (input, ctx) => {
-    const stream = await openai.chat.completions.create({ ... })
-    let full = ''
-    for await (const chunk of stream) {
-      full += chunk.choices[0]?.delta?.content || ''
-      ctx.onStream?.({ type: 'llm-stream', chunk, accumulated: full })
-    }
-    return { text: full }
-  },
+  messages: [{ role: 'user', content: '查询用户123，如果存在则发送欢迎邮件' }],
 })
 ```
 
-### Core Nodes
+### Node types
 
-7 built-in node types:
+7 built-in node types for defining the execution graph:
 
 | Node | Purpose | Input |
 |------|---------|-------|
-| `call` | Call a tool or sub-workflow | `{ tool: "name", args: {...} }` or `{ function: "name", args: {...} }` |
-| `set` | Declare or assign a variable | `{ name: "x", value: 42 }` |
+| `call` | Call a registered AI SDK Tool | `{ tool: "name", args: {...} }` |
+| `set` | Assign a variable | `{ name: "x", value: 42 }` |
 | `get` | Read a variable | `{ name: "x" }` |
 | `eval` | Evaluate an expression | `{ expression: "$var.x + 1" }` |
 | `if` | Conditional branch | `{ conditions: [{ test: ..., body: [nodes] }] }` |
 | `while` | Loop | `{ condition: "$var.i < 5" }, body: [nodes]` |
 | `http` | HTTP request | `{ url: "https://...", method: "GET" }` |
 
-### Variable Reference Syntax
+### Reference syntax
 
 | Pattern | Meaning | Example |
 |---------|---------|---------|
 | `$var.x` | Variable `x` | `$var.counter` |
 | `$nodes.u.output` | Full output of node `u` | `$nodes.u.output` |
 | `$nodes.u.output.field` | Specific field | `$nodes.u.output.email` |
-| `$input.userId` | Workflow input param | `$input.userId` |
-| `42`, `true`, `"hello"` | Literal values | Passed as-is |
-
-### Engine API
-
-For programmatic use outside of Router:
-
-```ts
-import { createWorkflowEngine, createSSEManager } from 'weifuwu'
-
-const sse = createSSEManager()
-const engine = createWorkflowEngine({ tools, sseManager: sse })
+| `$input.userId` | Input param | `$input.userId` |
 
-// Sync execution
-const result = await engine.execute({ nodes: [...] })
+### LLM generation
 
-// Async execution with SSE
-engine.runAsync('wf-1', { nodes: [...] })
-```
-
-### SSE Events
+Pass a `model` to `runWorkflow` — the LLM generates the workflow JSON from a goal:
 
 ```ts
-const sse = createSSEManager()
-const stream = sse.createStream('wf-1')
+const runWF = runWorkflow({
+  tools: { queryUser, sendEmail },
+  model: openai('gpt-4o'),
+})
 
-const reader = stream.getReader()
-//   event: workflow-start   — { workflowId, goal }
-//   event: node-start       — { nodeId, tool, input }
-//   event: node-end         — { nodeId, output }
-//   event: llm-stream       — { nodeId, chunk, accumulated }
-//   event: complete         — { result, duration }
-//   event: error            — { error }
+const result = await streamText({
+  model,
+  tools: { runWF },
+})
 ```
 
-### Sub-workflows
-
-Define reusable sub-workflows in the `functions` field:
-
-```json
-{
-  "functions": {
-    "double": {
-      "inputSchema": { "type": "object", "properties": { "x": { "type": "number" } } },
-      "workflow": {
-        "nodes": [
-          { "id": "calc", "tool": "eval", "input": { "expression": "$input.x * 2" } }
-        ]
-      }
-    }
-  },
-  "nodes": [
-    { "id": "call_double", "tool": "call", "input": { "function": "double", "args": { "x": 21 } } }
-  ]
-}
-```
+The LLM calls `runWF` with a goal, and `runWorkflow` internally calls `generateText` to produce the workflow nodes, then executes them.
 
 ## React pages with tsx()
 
@@ -1074,14 +1156,12 @@ export default function NotFound() {
 ## Usage within a full app
 
 ```ts
-import { serve, Router, ai, graphql, workflow } from 'weifuwu'
-import { tsx } from 'weifuwu/tsx'
+import { serve, Router, ai, graphql } from 'weifuwu'
 
 const app = new Router()
 app.use('/', await tsx({ dir: './pages/' }))
 app.use('/chat', ai(async (req) => ({ model: openai('gpt-4o'), messages: (await req.json()).messages })))
 app.use('/graphql', graphql(() => ({ schema: `type Query { hello: String }`, resolvers: { Query: { hello: () => 'world' } } })))
-app.use('/agent', workflow(() => ({ tools: myTools, stream: true })))
 app.ws('/chat', { message(ws, _, data) { ws.send(data) } })
 
 serve(app.handler(), { websocket: app.websocketHandler() })
@@ -1214,10 +1294,25 @@ Returns `TenantModule` — `{ migrate, middleware, router, graphql, close }`.
 | `model` | env `OPENAI_MODEL` → Ollama | `LanguageModel` from ai SDK |
 | `embeddingModel` | env `OPENAI_EMBEDDING_MODEL` → Ollama | `EmbeddingModel` for knowledge RAG |
 | `embeddingDimension` | `1024` | Vector dimension for pgvector |
-| `tools` | — | Tools for workflow-type agents (ai SDK `Tool` objects) |
+| `tools` | — | Tools for tool-use agents (ai SDK `Tool` objects) |
 
 Returns `AgentModule` — `{ migrate, router, run, addKnowledge, close }`.
 
+### `opencode(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pg` | — | PostgreSQL client from `postgres()` |
+| `workspace` | `process.cwd()` | Base directory for `.sessions` |
+| `model` | `'deepseek-v4-flash'` | LLM model name |
+| `baseURL` | env `DEEPSEEK_BASE_URL` | API base URL |
+| `apiKey` | env `DEEPSEEK_API_KEY` | API key |
+| `systemPrompt` | — | Custom system prompt |
+| `skills` | `[]` | Static skill definitions |
+| `permissions` | — | Tool permission config |
+
+Returns `OpencodeModule` — `{ migrate, router, wsHandler, close }`.
+
 ### `messager(options)`
 
 | Option | Default | Description |
@@ -1278,16 +1373,17 @@ serve(app.handler(), { websocket: app.websocketHandler() })
 
 | Import | Description |
 |--------|-------------|
-| `postgres(options?)` | PostgreSQL connection + auto-migration + 6 CRUD methods |
+| `postgres(options?)` | PostgreSQL connection + DDL schema builder + transactions + module lifecycle |
 | `redis(options?)` | Redis client (ioredis) — injects `ctx.redis` |
 | `queue(options?)` | Redis-backed job queue — immediate, delayed, cron scheduling |
 | `user(options)` | Built-in authentication (password + OAuth2 Server + JWT, middleware) |
 | `tenant(options)` | Multi-tenant BaaS — dynamic tables, REST + GraphQL auto-generation, row-level isolation |
-| `agent(options)` | AI Agent — chat/workflow/knowledge, Ollama-ready, programmatic API |
+| `agent(options)` | AI Agent — chat/tool-use/knowledge, Ollama-ready, programmatic API |
 | `messager(options)` | Real-time messaging — channels, WebSocket, agent routing, webhooks |
+| `opencode(options)` | AI programming assistant — chat agents with tools, skills, permissions, isolated workspaces |
 | `graphql(handler)` | GraphQL endpoint (GET/POST + GraphiQL) |
 | `ai(handler)` | AI streaming endpoint (POST) |
-| `workflow(handler)` | Workflow engine (POST + SSE) |
+| `runWorkflow(options)` | DAG execution engine as an AI SDK `Tool` — use with `streamText()` |
 
 ### Deploy
 
@@ -1305,9 +1401,14 @@ serve(app.handler(), { websocket: app.websocketHandler() })
 | `setCookie(res, name, value, options?)` | Set cookie (returns new Response) |
 | `deleteCookie(res, name)` | Delete cookie (returns new Response) |
 | `useTsx()` | Hook returning `{ params, query, user, parsed }` from `TsxContext` |
-| `createWorkflowEngine(options)` | Programmatic workflow engine |
-| `createSSEManager()` | SSE event manager for workflows |
-| `tool(def)` | Define a workflow tool |
+| `runWorkflow(options)` | Create a DAG execution AI SDK `Tool` — `{ tools?, model?, maxSteps? }` |
+| `pgTable(name, columns)` | Type-safe table schema definition with DDL + CRUD |
+| `pg.table(name, columns)` | Pre-bound table (no `sql` parameter needed for CRUD) |
+| `serial()`, `uuid()`, `text()`, `integer()`, `boolean()`, `timestamptz()`, `jsonb()`, `textArray()`, `vector()` | Column type builders |
+| `sql(strings, ...)` | SQL expression literal for defaults and SET values (e.g. `sql\`NOW()\``) |
+| `PgModule` | Base class for database-backed modules (provides `sql`, `close()`) |
+| `BoundTable` | Table with pre-bound `sql` — returned by `pg.table()` |
+| `FindOptions` | Query options: `{ orderBy?, limit?, offset? }` for `find()` |
 
 Import `useTsx` and `TsxContext` from `'weifuwu'`.
 

package/dist/agent/migrate.d.ts

@@ -1,4 +1,4 @@
-import type { Sql } from 'postgres';
+import type { Sql } from '../vendor.ts';
 export interface MigrateOptions {
     sql: Sql<{}>;
     embeddingDimension: number;

package/dist/agent/rest.d.ts

@@ -1,4 +1,4 @@
-import type { Sql } from 'postgres';
+import type { Sql } from '../vendor.ts';
 import { Router } from '../router.ts';
 import type { RunParams } from './types.ts';
 interface RestDeps {

package/dist/agent/run.d.ts

@@ -1,5 +1,5 @@
-import type { LanguageModel, EmbeddingModel, Tool } from 'ai';
-import type { Sql } from 'postgres';
+import { type LanguageModel, type EmbeddingModel, type Tool } from 'ai';
+import type { Sql } from '../vendor.ts';
 import type { RunParams, RunResult, KnowledgeDoc } from './types.ts';
 interface RunnerDeps {
     sql: Sql<{}>;

package/dist/agent/types.d.ts

@@ -4,7 +4,7 @@ export interface AgentConfig {
     tenant_id: string | null;
     name: string;
     description: string;
-    type: 'chat' | 'workflow';
+    type: 'chat' | 'tool-use';
     model: string;
     system_prompt: string;
     owner_id: number;
@@ -36,7 +36,7 @@ export type RunResult = {
     stream: ReadableStream<Uint8Array>;
 };
 export interface AgentOptions {
-    pg: any;
+    pg: import('../postgres/types.ts').PostgresClient;
     model?: LanguageModel;
     embeddingModel?: EmbeddingModel;
     embeddingDimension?: number;

package/dist/ai/workflow.d.ts

@@ -0,0 +1,14 @@
+import type { LanguageModel } from 'ai';
+export declare function runWorkflow(opts?: {
+    tools?: Record<string, any>;
+    model?: LanguageModel;
+    maxSteps?: number;
+}): import("ai").Tool<{
+    goal: string;
+    nodes?: any[];
+}, {
+    result: unknown;
+    nodeOutputs: {
+        [k: string]: unknown;
+    };
+}>;