page-agent-sdk 1.1.2 → 1.1.4

package/README.md

@@ -40,9 +40,13 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
 | 📰 **CMS ops** | "Prefix these products with 'Limited', mark under ¥100 red" | JSONPath filter + sandbox script batch edit |
 | 🖥 **Ops console** | "Raise A's threshold to 30%, turn off switch B" | Whitelist + human-confirm to edit config, read-back verify |
 | 🤖 **AI-native assistant** | "Change this chart's legend to bars" | Conversational ops on product data, no UI needed |
+| 🔬 **Research agent** | "Compare 3 solutions and recommend one" | Parallel subagents investigate each, return only conclusions |
+| 🧩 **Headless / server-side** | "Run the agent in Node.js" | `ui:false` + `storage:'memory'`, drive via `sdk.send` |
 
 > `examples/nested-demo` is a full low-code example: nested block tree + human confirm + one-click rollback.
 
+**Full end-to-end scenarios with copy-paste code** (9 cases: low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP) live in the bundled Agent Skill at `skills/page-agent-sdk-integrate/references/use-cases.md` (also shipped in the npm package). See [Skills for AI tools](#skills-for-ai-tools-for-integrators) below to install the skill.
+
 ## 30-second quickstart
 
 ```bash

package/README.zh-CN.md

@@ -40,9 +40,13 @@
 | 📰 **CMS 运营** | 「这批商品标题加『限时』前缀、低于 100 元的标红」 | JSONPath 筛选 + 沙箱脚本批量改 |
 | 🖥 **运维配置台** | 「A 实验阈值调到 30%、关掉 B 开关」 | 白名单 + 人工确认改配置，写后读回校验 |
 | 🤖 **AI 原生助手** | 「把这张看板的图例改成柱状」 | 对话操作产品自有数据，免做 UI |
+| 🔬 **调研 agent** | 「对比 3 个方案，推荐哪个」 | 并行子 agent 各调研一个，只回结论 |
+| 🧩 **Headless / 服务端** | 「在 Node.js 里跑 agent」 | `ui:false` + `storage:'memory'`，用 `sdk.send` 驱动 |
 
 > 仓库 `examples/nested-demo` 即低代码场景完整示例：嵌套区块树 + 人工确认 + 一键回退。
 
+**完整端到端场景（含可复制代码，共 9 例：低代码搭建 / 表单设计器 / CMS 批量 / 运维配置台 / AI 原生 / 调研 / 服务端 / 多 agent / MCP）** 见随包附带的 Agent Skill：`skills/page-agent-sdk-integrate/references/use-cases.md`（npm 包内同样包含）。安装 skill 见下文[给 AI 工具使用者的 Skills](#给-ai-工具使用者的-skills集成方安装)。
+
 ## 30 秒上手
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "type": "module",
   "description": "框架无关的页面内 Agent JS SDK —— 以对话框形态挂载到任意网页,通过自定义 tool 读写宿主 window 属性(GET 抓文档),具备 planning/skills/虚拟工作区/快照回退/context 管理能力。Vue 打包进库,使用者无需安装 Vue。",
   "main": "./dist/page-agent-sdk.umd.cjs",

package/skills/page-agent-sdk-integrate/SKILL.md

@@ -77,9 +77,34 @@ Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_resul
 - `capabilities: { windowOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` — turn off unused built-ins to save tokens/size. `verify` is the reverse (off by default; `capabilities.verify:true` enables write-back self-check).
 - `presets.pageBuilder` / `researcher` / `minimal` — spread into `createChatSdk` for common scenarios.
 
+## Common use cases (match the user's scenario, then read [references/use-cases.md](references/use-cases.md) for full code)
+
+| Scenario | Key setup |
+|---|---|
+| **Low-code page builder** | `windowProps` = component tree; `edit_window_prop` jsonPath patches; `onEvent` → canvas refresh; `checkpoint` + `approval` |
+| **Form designer** | `windowProps` = field definitions with enum/required schemas; schema validation prevents malformed forms |
+| **CMS batch ops** | `eval_window_script` for bulk loops; `search_window_prop` to filter; `edit_window_prop` for targeted edits |
+| **Ops config console** | `approval:{tools:[set,edit]}` human-confirm; `capabilities.verify:true` write-back read; `checkpoint` |
+| **AI-native assistant** | `capabilities:{windowOps:false,fetch:false}` + custom `tools` (your product API) |
+| **Research agent** | `capabilities:{windowOps:false}`; `subagent:{allowedTools:['fetch_document']}`; `contextPreset:'conservative'` |
+| **Headless / server-side** | `ui:false` + `storage:'memory'` + `capabilities:{windowOps:false,fetch:false}`; drive via `sdk.send` |
+| **Multi-agent on one page** | same `id` + `shareContext:true` → multiple dialogs share one `AgentCore` |
+| **MCP integration** | `mcp:[{transport,url}]` remote tool servers; `@modelcontextprotocol/sdk` optional peerDep |
+
+When the user describes a scenario, map it to the row above and load `references/use-cases.md` for the matching numbered case (1→9) with copy-paste code.
+
 ## References (read as needed)
 
-- `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference (onEvent/hook/server-side/checkpoint/approval/verify/subagent/MCP)
+Detailed docs live in this skill's `references/` folder — load the one matching the user's question:
+
+- **[references/quickstart.md](references/quickstart.md)** — progressive setup from 5-line CDN to full-featured (Stages 0→6). Read when the user wants a step-by-step "from simple to complete" walkthrough.
+- **[references/options.md](references/options.md)** — every `createChatSdk` option: type, default, purpose & when to use. Read when the user asks "what does option X do" or needs to tune behavior.
+- **[references/api.md](references/api.md)** — instance methods (`mount`/`send`/`stream`/`inspect`/`switchSession`/`hook`/checkpoints), `defineTool`/`defineSkill`/`presets`, built-in window tools, and the full `SdkEvent` type table. Read when the user asks about APIs, tools, or events.
+- **[references/use-cases.md](references/use-cases.md)** — 9 end-to-end scenarios (low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP). Read when the user wants a concrete pattern for their use case.
+- **[references/advanced.md](references/advanced.md)** — detailed examples for the four extensibility surfaces: custom `defineTool` (with error handling + coexisting with windowOps), `defineSkill` (inline content + remote doc), subagents (ad-hoc `spawn_agent`/`spawn_agents` + pre-declared `subagents` → `use_<id>`), MCP (http/sse/websocket + auth + dev gotcha). Read when the user asks "how to add custom tools / skills / subagents / MCP".
+
+Project-level docs (in the repo, not bundled in this skill):
+- `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference
 - `examples/<demo>/` — runnable demos (page-demo, nested-demo, subagent-demo, mcp-demo, planner-demo, toolsets-demo, human-confirm-demo)
 - `demo/plain.html` — framework-agnostic CDN integration
 - `CLAUDE.md` — internal dev guide (architecture, conventions)

package/skills/page-agent-sdk-integrate/references/advanced.md

@@ -0,0 +1,215 @@
+# Advanced examples — custom tools, skills, subagents, MCP
+
+Detailed, copy-paste examples for the four extensibility surfaces. Read the section matching the user's need.
+
+## 1. Custom tools (`defineTool`)
+
+Custom tools extend the agent beyond built-in `windowOps`/`fetch`. Use them to expose your product's API to the AI.
+
+### Minimal
+
+```ts
+import { createChatSdk, defineTool, z } from 'page-agent-sdk'
+
+const lookupOrder = defineTool({
+  name: 'lookup_order',
+  description: '查询订单 by id',
+  schema: z.object({ orderId: z.string() }),
+  handler: async ({ orderId }) => JSON.stringify(await api.getOrder(orderId)),
+})
+```
+
+### With error handling
+
+Return structured errors via `toolError` so the AI can react:
+
+```ts
+import { defineTool, toolError, z } from 'page-agent-sdk'
+
+const updatePrice = defineTool({
+  name: 'update_price',
+  description: '更新商品价格',
+  schema: z.object({ sku: z.string(), price: z.number().positive() }),
+  handler: async ({ sku, price }) => {
+    const ok = await api.setPrice(sku, price)
+    if (!ok) return toolError({ path: sku, code: 'NOT_FOUND', message: `SKU ${sku} 不存在` })
+    return `已更新 ${sku} 价格为 ${price}`
+  },
+})
+```
+
+### Coexisting with windowOps
+
+Mix custom tools with built-in window tools:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  windowProps: [{ path: 'app.config', description: '配置', schema: z.record(z.any()) }],
+  tools: [lookupOrder, updatePrice],   // custom + built-in windowOps together
+}).mount()
+```
+
+### Pure custom-tool agent (no windowOps)
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  tools: [lookupOrder, updatePrice],
+  capabilities: { windowOps: false, fetch: false },   // drop built-ins
+}).mount()
+```
+
+## 2. Skills (`defineSkill`) — progressive disclosure
+
+Skills are **loaded on demand** by the agent (not always in context) → saves tokens. The agent sees an index of `name`+`description`, calls `load_skill` to pull the full content when needed.
+
+### Inline content skill
+
+```ts
+import { createChatSdk, defineSkill } from 'page-agent-sdk'
+
+const apiDesignSkill = defineSkill({
+  name: 'api-design',
+  description: '本项目 REST API 设计规范(何时用:设计/评审新接口)',
+  getContent: () => `
+- URL 用 kebab-case,统一 /v1 前缀
+- 列表接口必须分页(page+pageSize)
+- 错误返回 { code, message, data: null }
+- 写操作记审计日志
+`,
+})
+
+createChatSdk({ container: '#chat', llm: { ... }, skills: [apiDesignSkill] }).mount()
+```
+
+### Remote doc skill (auto-fetched + cached to vfs)
+
+```ts
+const brandSkill = defineSkill({
+  name: 'brand-guide',
+  description: '品牌视觉规范(何时用:涉及 UI/文案/配色)',
+  doc: 'https://my-wiki/brand.md',   // SDK fetches + caches to vfs; large docs stay out of context
+})
+
+createChatSdk({ container: '#chat', llm: { ... }, skills: [brandSkill] }).mount()
+```
+
+> `SkillSpec = { name, description, doc?, getContent? }`. `doc` (http(s):// or `vfs://path`) takes precedence over `getContent`. Write `description` as "what it is + when to use" so the agent knows when to load it.
+
+## 3. Subagents — ad-hoc spawn vs pre-declared
+
+Subagents run isolated sub-tasks; **only their final conclusion** returns to the main context (saves tokens). Two flavors coexist.
+
+### 3a. Ad-hoc `spawn_agent` / `spawn_agents` (default enabled)
+
+The main agent decides when to delegate via `spawn_agent` (one) / `spawn_agents` (parallel). Configure the subagent tool subset:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '多源对比时用 spawn_agents 并行委派。',
+  subagent: {
+    allowedTools: ['fetch_document', 'get_window_prop'],  // read-only subset (no spawn → no recursion)
+    maxDepth: 1,           // physical recursion cut (default 1)
+    maxParallel: 3,        // max parallel subagents in spawn_agents
+    temperature: 0.2,      // subagent temperature (default inherits main)
+  },
+}).mount()
+```
+
+User: "对比 A/B/C 三个方案" → main agent calls `spawn_agents` with 3 tasks → 3 subagents research in parallel → only conclusions return.
+
+### 3b. Pre-declared named subagents (`subagents`) — Claude-Code style
+
+Declare fixed roles; each auto-generates a `use_<id>({ task })` delegation tool. The main agent sees the tool description and knows who to delegate to:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '复杂任务委派给专家子 agent。',
+  subagents: [
+    {
+      id: 'researcher',
+      description: '调研专家:搜集资料、对比方案(只读)',
+      tools: ['fetch_document', 'get_window_prop'],   // read-only
+      temperature: 0.2,
+    },
+    {
+      id: 'reviewer',
+      description: '审查专家:检查代码/配置的安全与性能问题',
+      tools: ['get_window_prop', 'search_window_prop'],
+      systemPrompt: '你是审查专家,只报告问题不改数据。',
+      temperature: 0.1,
+    },
+  ],
+}).mount()
+```
+
+Now the main agent has `use_researcher({ task })` and `use_reviewer({ task })` tools. Each subagent inherits main config where omitted (`llm`, `maxTokens`, `skills`...).
+
+> Pre-declared = fixed roles (research/review); ad-hoc `spawn` = temporary free delegation. Both can coexist. `maxDepth` (default 1) physically cuts recursion: at depth+1 ≥ maxDepth, subagents get no spawn tools.
+
+## 4. MCP (external tool servers)
+
+Connect remote MCP servers; their tools auto-inject into the agent. `Promise.allSettled` → one server down doesn't break others.
+
+### HTTP (StreamableHTTP) — recommended
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  mcp: [
+    { transport: 'http', url: 'https://my-mcp-server/mcp', name: 'my-tools' },
+  ],
+}).mount()
+```
+
+### SSE / WebSocket
+
+```ts
+mcp: [
+  { transport: 'sse',       url: 'https://another/sse' },
+  { transport: 'websocket', url: 'wss://ws-server/mcp' },
+]
+```
+
+### With request init (auth headers)
+
+```ts
+mcp: [
+  {
+    transport: 'http', url: 'https://my-mcp/mcp',
+    requestInit: { headers: { Authorization: `Bearer ${token}` } },
+  },
+]
+```
+
+### Notes
+
+- `@modelcontextprotocol/sdk` is an **optional peerDep** — install it only if you use `mcp`. It's dynamically imported (zero cost when unused).
+- Browser supports **only remote transports** (http/sse/websocket), not stdio.
+- MCP `inputSchema` (JSON Schema) is passed directly to LangChain `tool()` — no conversion.
+- `inspect().mcp.servers` lists connected servers; each tool's `source` shows `mcp:<name>`.
+
+### Dev gotcha
+
+If you fork `vite.config.ts`, keep `optimizeDeps.include` pre-declaring the SDK sub-paths (`/client`, `/client/streamableHttp.js`, `/client/sse.js`, `/client/websocket.js`). Otherwise the **first cold visit** to an MCP page injects 0 tools (reload fixes it). The default config already has these.
+
+## 5. Combining everything
+
+```ts
+createChatSdk({
+  container: '#chat',
+  llm: { apiKey, baseUrl, model },
+  systemPrompt: '...',
+  windowProps: [{ path: 'app.data', description: '...', schema: z.record(z.any()) }],
+  tools: [lookupOrder, updatePrice],          // custom tools
+  skills: [apiDesignSkill, brandSkill],         // progressive skills
+  subagents: [{ id: 'researcher', description: '...', tools: ['fetch_document'] }],  // pre-declared
+  mcp: [{ transport: 'http', url: '...' }],     // external tools
+  capabilities: { verify: true },               // self-check
+  approval: { tools: ['set_window_prop'] },     // human confirm writes
+  checkpoint: true,                             // rollback
+}).mount()
+```

package/skills/page-agent-sdk-integrate/references/api.md

@@ -0,0 +1,119 @@
+# API reference — instance methods, tool/skill definition, window tools, events
+
+## ChatSdk instance (`createChatSdk(...)` return)
+
+| Method / field | Signature | Purpose |
+|---|---|---|
+| `mount()` | `() => Promise<void>` | Initialize & render. Await before `send` in headless. |
+| `unmount()` | `() => void` | Tear down UI, listeners, flush storage. |
+| `messages` | `AgentMessage[]` (reactive) | The conversation. Headless reads this to render. UI shares the same array (single source). |
+| `send(message)` | `(msg: string) => Promise<string>` | Send a user message (invoke mode, no stream events). Returns final content. |
+| `stream` | `(messages, onEvent, signal?) => Promise<string>` | Low-level stream. UI uses this internally; headless can call directly for streaming. |
+| `inspect()` | `() => AgentInfo` | Inspect agent: tools/skills/windowProps/middleware/todos/mcp.servers (each tool's `source`: `builtin`/`mcp:<name>`/`user`). DebugDrawer uses this. |
+| `switchSession(id?)` | `(id?: string) => Promise<string>` | Switch session context (load or create by id). Requires `storage` enabled. |
+| `hook(handler)` | `(h: SdkEventHandler) => () => void` | Runtime event subscription (multi-listener, returns unsubscribe). Complements `onEvent`. |
+| `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
+| `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
+
+## defineTool (custom tools)
+
+```ts
+import { defineTool, z } from 'page-agent-sdk'
+
+const addTool = defineTool({
+  name: 'add',
+  description: 'Add two numbers',
+  schema: z.object({ a: z.number(), b: z.number() }),
+  handler: async ({ a, b }) => `sum: ${a + b}`,
+})
+
+createChatSdk({ tools: [addTool], /* llm, ... */ }).mount()
+```
+
+`handler` receives validated args; return a string (or structured result stringified). Errors via `toolError({ path, code, message })`.
+
+## defineSkill (progressive disclosure)
+
+```ts
+import { defineSkill } from 'page-agent-sdk'
+
+const apiSkill = defineSkill({
+  name: 'api-design',
+  description: 'REST API design conventions for this project (load when designing/reviewing APIs)',
+  getContent: () => 'Use kebab-case URLs; version under /v1; ...',   // or `doc: 'https://...'` for remote
+})
+
+createChatSdk({ skills: [apiSkill], /* ... */ }).mount()
+```
+
+Skills are loaded on demand by the agent (not always in context) — saves tokens.
+
+## presets (scenario bundles)
+
+```ts
+import { createChatSdk, presets } from 'page-agent-sdk'
+
+createChatSdk({ ...presets.pageBuilder, llm, container }).mount()
+// or presets.researcher / presets.minimal
+```
+
+Spread into options for common scenarios.
+
+## Built-in window tools (auto-injected when `capabilities.windowOps`)
+
+| Tool | Purpose |
+|---|---|
+| `list_window_props` | List declared paths + descriptions |
+| `describe_window_prop` | Show a path's schema |
+| `get_window_prop` | Read a path (or ancestor/descendant sub-paths of registered props) |
+| `get_window_paths` | Batch-read multiple paths |
+| `set_window_prop` | Write a whole path (schema-validated, scoped to registry) |
+| `edit_window_prop` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON |
+| `delete_window_prop` | Delete a path |
+| `snapshot_window_prop` | Manual snapshot |
+| `list_window_snapshots` | List snapshots |
+| `restore_window_snapshot` | Restore (no id = most recent) |
+| `query_window_prop` / `search_window_prop` | JSONPath query / full-text search |
+| `eval_window_script` | Sandboxed script on data (for batch ops) |
+
+**Key rule**: `set`/`edit`/`delete` only affect **declared** `windowProps` paths. Invalid schema → structured error, no write. `edit` writes in-place (preserves Vue reactive refs).
+
+### jsonPath edit operations
+
+`edit_window_prop({ path, jsonPath, op, value })`:
+- `set` — set a sub-path
+- `remove` — remove a sub-path / array element
+- `merge` — shallow-merge an object
+- `append` — append to an array
+
+Example: `edit_window_prop({ path: 'app.items', jsonPath: '0.price', op: 'set', value: 9.9 })` — precise local edit, no full re-send.
+
+## Built-in fetch tools (`capabilities.fetch`)
+
+`fetch_document` — GET a URL, return cleaned text (HTML→markdown, truncated, offloaded to vfs if large).
+
+## SdkEvent types (for `onEvent` / `sdk.hook`)
+
+| `type` | Payload | When |
+|---|---|---|
+| `round_start` | `round` | Each agent round begins |
+| `reasoning` | `delta` | Reasoning token (models that emit it) |
+| `text` | `delta` | Streamed text delta (stream mode only) |
+| `tool_call` | `name, args` | A tool is invoked |
+| `tool_result` | `name, result, status` | Tool returns (`status`: `done`/`error`) |
+| `subagent` | `taskId, label, kind, name, args?, result?, status?` | Subagent tool progress (forwarded to UI, NOT into main LLM context) |
+| `done` | `content` | Agent round completes |
+| `window_prop_change` | `path, operation, value?` | A window prop was written (`operation`: `set`/`edit`/`delete`/`restore`) |
+| `message_update` | `count` | The `messages` array changed |
+| `error` | `message` | An error occurred (abort excluded) |
+
+`approval_request` is **NOT** forwarded via `onEvent`/`hook` (UI handles it; headless integrators use a custom approval middleware listener).
+
+## Exported building blocks (for custom UIs)
+
+- `ChatDialog`, `MessageContent`, `CodePreview` — Vue components
+- `useChat(opts)` — composable (streaming/retry/stop/regenerate logic)
+- `createAgent(options)` — the raw harness (if you bypass `createChatSdk`)
+- Middleware factories: `createApprovalMiddleware`, `createVerifyMiddleware`, `createWriteBackCheck`, `createSubagentMiddleware`, `createCheckpointMiddleware`, `createUsageHintsMiddleware`
+- Storage: `createSessionStore`, `createMemoryBackend`, `createWebStorageBackend`, `isQuotaError`
+- JSON helpers: `jpEval`, `searchJson`, `runSandboxedScript`, `toolError`, `zodError`

package/skills/page-agent-sdk-integrate/references/options.md

@@ -0,0 +1,124 @@
+# createChatSdk options — what each does & when to use
+
+Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`. Everything else is optional with sane defaults.
+
+## LLM & identity
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `llm` | `LLMConfig \| BaseChatModel` | — (required) | The model. `LLMConfig = { apiKey, baseUrl, model, temperature?, maxTokens? }` (OpenAI-compatible; DeepSeek default). Or pass any LangChain `BaseChatModel` (e.g. `ChatAnthropic`, install its peerDep). |
+| `systemPrompt` | `string` | generic page assistant | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). |
+| `id` | `string` | random + warn | Stable agent id for multi-agent isolation & persistence. **Must pass a stable value** if you use `storage` or run multiple agents on one page. |
+| `title` / `placeholder` | `string` | — | Dialog title / input placeholder (cosmetic). |
+
+## UI & mounting
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `container` | `string \| HTMLElement` | — | Where the built-in dialog mounts. Required when `ui !== false`. |
+| `ui` | `boolean \| 'default'` | `true` | `false` = headless (no built-in dialog; you build UI from `sdk.messages` + `sdk.send`). `'default'` = built-in `ChatDialog`. |
+| `streaming` | `boolean` | `true` | Stream tokens live. `false` = wait for full reply. Headless `sdk.send` always uses invoke (no stream events, but window/message/error still fire). |
+
+## window operation (the core)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `windowProps` | `WindowPropSpec[]` | `[]` | Declare writable `window` paths + zod schemas. The agent can ONLY touch declared paths; `set`/`edit` are schema-validated. **This is the key integration step.** |
+| `maxSnapshots` | `number` | 20 | Per-path snapshot stack depth for `restore_window_snapshot`. |
+| `permissions` | `PermissionRule[]` | off | Scope whitelist (first-match-wins) for fine-grained per-path/tool rules. Default off (all declared paths writable). |
+
+`WindowPropSpec = { path: string; description: string; schema?: z.ZodType }`. `description` is shown to the AI — write it clearly so the agent knows what each path means.
+
+## Tools, skills, memory
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `tools` | `Tool[]` | `[]` | Custom tools beyond built-ins. Use `defineTool({ name, description, schema, handler })`. |
+| `skills` | `SkillSpec[]` | `[]` | Progressive-disclosure skills (`defineSkill({ name, description, prompt }`) loaded on demand by the agent. |
+| `memory` | `string` | — | AGENTS.md-style persistent instructions injected into every prompt (project conventions, hard rules). |
+| `middleware` | `Middleware[]` | `[]` | Custom middleware appended after built-ins. 8 hooks: `beforeAgent`/`wrapModelCall`/`beforeModel`/`afterModel`/`wrapToolCall`/`afterAgent`/`beforeReturn` + `augmentPrompt`/`compressInput`/`tools`. For interception, instrumentation, prompt enhancement. |
+
+## Capabilities (turn built-ins on/off)
+
+`capabilities: { ... }` — default all `true` except `verify`. Set `false` to drop unused built-ins (saves tokens/size).
+
+| Flag | Off when... |
+|---|---|
+| `windowOps` | Pure research agent, no page edits (also drops window tools from subagents). |
+| `fetch` | No web fetching needed. ⚠️ turning off `windowOps` also strips subagent window tools. |
+| `planning` | Don't want `write_todos` planning. |
+| `skills` | Don't want progressive skill loading. |
+| `vfs` | No in-memory workspace; ⚠️ large tool results then truncate instead of offloading. |
+| `summarization` | No context compression; ⚠️ long sessions grow unbounded. |
+| `memory` | No persistent instructions. |
+| `subagent` | No `spawn_agent`/`spawn_agents` delegation. |
+| `verify` (reverse) | **Off by default**; `true` enables write-back self-check before the agent returns (costs tokens). |
+
+## Robustness & limits
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `maxRetries` | `number` | 2 | Model call retries on network/429/5xx (exponential backoff). 4xx & abort don't retry. |
+| `maxParallelTools` | `number` | 1 | Same-round tool concurrency. `>1` is faster but watch stateful middleware (todos counts). |
+| `maxToolRounds` | `number` | — | Cap agent tool rounds (safety against loops). |
+| `maxMemoryRounds` | `number` | 50 | In-memory dialog rounds cap; oldest compressed to a summary system message (OOM guard). `0` disables. |
+| `contextWindow` / `maxOutputTokens` | `number` | by model name | Override model context/output token limits (affects offload threshold & compression trigger). |
+| `debug` | `boolean` | `false` | Verbose logging / DebugDrawer. |
+
+## Context compression
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `contextPreset` | `'auto'\|'conservative'\|'aggressive'` | `auto` | `conservative` = save cost; `aggressive` = save context. `contextOptions` fine-tunes further. |
+| `contextOptions` | `object` | — | Detailed compression params (overrides preset). `false` disables compression. |
+| `summaryLlm` | `BaseChatModel \| LLMConfig` | main `llm` | Use a cheaper/faster model for summarization. |
+| `summaryTemperature` | `number` | 0.3 | Summary model temperature. |
+| `summaryMaxTokens` | `number` | 1024 | Summary output cap. |
+| `summaryTimeoutMs` | `number` | 15000 | On timeout, fall back to index-based summary (no failure). |
+
+## Subagent (delegation)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `subagent` | `object` | enabled | `{ enabled?, allowedTools?, systemPrompt?, temperature?, maxTokens?, skills?, llm?, maxDepth?, maxParallel? }`. `maxDepth` (1) physically cuts recursion. Subagents get a read-only tool subset (no spawn). |
+| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. |
+
+## Verify (self-check before return)
+
+`capabilities.verify: true` enables. `verify: { check?, maxAttempts?, adversarial? }`:
+- `check` omitted → default `createWriteBackCheck()` (scans all writes, reads back + schema-validates; skips legitimately-rejected writes).
+- custom `check: async ({ messages, state }) => ({ ok, feedback? })` — return **actionable** feedback.
+- `adversarial: true` → after check passes, spawn a read-only "refuter" subagent (costs extra rounds; for semantically complex cases).
+- `maxAttempts` (default 2) caps self-correction loops.
+
+## Approval (human-in-the-loop)
+
+`approval: { tools?, confirm?, ... }` — human confirms before tool execution. Default off; passing `approval` enables. Headless integrators listen for `approval_request` (NOT forwarded via `onEvent`/`hook`) to build their own confirm UI.
+
+## Checkpoint (session rollback)
+
+`checkpoint: true \| { maxCheckpoints?, auto? }` — per-round snapshot of (messages + window props + vfs + todos). `restoreLastCheckpoint()` / LLM tool `restore_last_checkpoint` / UI button. Distinct from windowOps per-path snapshots (checkpoint = whole-session rollback).
+
+## Persistence (storage)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `storage` | `'indexed'\|'session'\|'local'\|'memory'\| StorageConfig \| false` | `false` (off) | Off by default; assign to enable. Persists messages/vfs/todos/memory (NOT window snapshots). Auto-degrades to memory if backend unavailable (private mode / quota). |
+| `session` | `SessionOptions` | — | Session control (resume by id, etc.). |
+| `shareContext` | `boolean` | `false` | `true` → multiple `createChatSdk` with same `id` share one `AgentCore` (same agent, multiple dialog views on a page). |
+
+## MCP (external tools)
+
+`mcp: [{ transport: 'http'\|'sse'\|'websocket', url, name?, requestInit? }]` — connect remote MCP servers, dynamically inject their tools (`Promise.allSettled` fault-isolated). Browser only supports remote transports (no stdio). `@modelcontextprotocol/sdk` is an optional peerDep, dynamically imported only when used.
+
+## Events
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `onEvent` | `(e: SdkEvent) => void` | — | Constructor-time event subscription (single). Replaces polling for host-page reactivity. See [api.md](api.md) for event types. |
+
+Runtime subscription via `sdk.hook(handler) => () => void` (multi-listener, cancellable) — see [api.md](api.md).
+
+## vfs (in-memory workspace)
+
+`vfs: { initialFiles?, maxBytes? }` — `maxBytes` default 4MB; LRU-evicts oldest files on overflow. Tool results > 6000 chars auto-offload to vfs (only preview + `vfs_read`/`vfs_grep` reference kept). Disabling `capabilities.vfs` degrades to truncation.

package/skills/page-agent-sdk-integrate/references/quickstart.md

@@ -0,0 +1,122 @@
+# Quickstart (progressive)
+
+From the smallest working setup to a full-featured integration. Read top-down; stop wherever your needs are met.
+
+## Stage 0 — Prerequisites
+
+- An OpenAI-compatible LLM endpoint (DeepSeek works out of the box). Get an API key.
+- Page data you want the AI to edit, placed on `window` (e.g. `window.app = { ... }`).
+
+## Stage 1 — Minimal (5 lines, CDN, no build)
+
+Drop into any HTML page. The built-in dialog mounts itself.
+
+```html
+<div id="root"></div>
+<script src="https://unpkg.com/page-agent-sdk"></script>
+<script>
+  window.app = { title: 'Hello', theme: 'light' }
+  ChatSdk.createChatSdk({
+    container: '#root',
+    llm: { apiKey: 'sk-...', baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
+    systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
+    windowProps: [
+      { path: 'app.title', description: '标题', schema: ChatSdk.z.string() },
+      { path: 'app.theme', description: '主题', schema: ChatSdk.z.enum(['light','dark']) },
+    ],
+  }).mount()
+</script>
+```
+
+Talk to it: "change theme to dark" → AI calls `set_window_prop` → `window.app.theme === 'dark'`.
+
+## Stage 2 — npm + module project
+
+```bash
+npm i page-agent-sdk zod @langchain/openai @langchain/core
+```
+
+```ts
+import { createChatSdk, z } from 'page-agent-sdk'
+import 'page-agent-sdk/style.css'
+
+window.app = { title: 'Hello', theme: 'light', items: [] }
+
+const sdk = createChatSdk({
+  container: '#root',
+  llm: { apiKey: import.meta.env.VITE_AI_API_KEY, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
+  systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
+  windowProps: [
+    { path: 'app.title',  description: '标题',   schema: z.string() },
+    { path: 'app.theme',  description: '主题',   schema: z.enum(['light','dark']) },
+    { path: 'app.items',  description: '列表项', schema: z.array(z.object({ name: z.string(), price: z.number() })) },
+  ],
+}).mount()
+```
+
+## Stage 3 — React to changes (replace polling)
+
+Subscribe via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable):
+
+```ts
+const sdk = createChatSdk({
+  onEvent(e) {
+    if (e.type === 'window_prop_change') renderUI()       // host page reactive refresh
+    if (e.type === 'error') console.error(e.message)
+  },
+  // ...llm, windowProps...
+}).mount()
+
+// runtime listener (e.g. analytics), cancellable
+const off = sdk.hook((e) => { if (e.type === 'tool_call') track(e.name) })
+// off()
+```
+
+## Stage 4 — Headless (custom UI, framework-agnostic)
+
+No built-in dialog; drive the reactive `messages` array yourself.
+
+```ts
+const sdk = createChatSdk({
+  ui: false,                                  // headless
+  llm: { ... }, systemPrompt: '...', windowProps: [...],
+}).mount()
+
+// your own UI reads sdk.messages (reactive) and calls sdk.send
+await sdk.send('add a new item: name=Pen, price=3')
+```
+
+Reusable `ChatDialog` / `MessageContent` / `CodePreview` components + `useChat` composable are also exported if you want to assemble a custom UI from existing parts.
+
+## Stage 5 — Tune capabilities & safety
+
+```ts
+createChatSdk({
+  // ...llm, windowProps...
+  capabilities: { verify: true },             // write-back self-check before agent returns
+  verify: { maxAttempts: 2 },                 // auto-correct on failure (default check = write-back read + schema)
+  approval: { tools: ['set_window_prop', 'edit_window_prop'] },  // human-confirm before writes
+  checkpoint: true,                           // session-level rollback on bad edits
+  maxParallelTools: 1,                        // serial tool calls (safe for stateful middleware)
+  contextPreset: 'conservative',              // save cost on long sessions
+}).mount()
+```
+
+## Stage 6 — Persist across refresh / multi-session
+
+```ts
+createChatSdk({
+  id: 'my-page-agent',          // STABLE id (multi-agent isolation); omit = random + warn
+  storage: 'indexed',           // persist messages/vfs/todos/memory to IndexedDB
+  // ...llm, windowProps...
+}).mount()
+
+// later, switch session:
+await sdk.switchSession('session-abc')   // load or create
+```
+
+## Next
+
+- All options: see [options.md](options.md)
+- Instance API + tool/skill definition: see [api.md](api.md)
+- End-to-end scenarios: see [use-cases.md](use-cases.md)

package/skills/page-agent-sdk-integrate/references/use-cases.md

@@ -0,0 +1,200 @@
+# Use cases — end-to-end scenarios
+
+Concrete integration patterns for common scenarios. Each shows the key `windowProps` + options that matter. Adapt the LLM config to your provider.
+
+## 1. Low-code page builder
+
+A visual builder where the page is a component tree; the AI edits the tree via jsonPath patches and the canvas re-renders live.
+
+```ts
+window.page = {
+  components: [
+    { id: 'banner', type: 'banner', props: { title: 'Welcome', bg: '#1f4d3a' } },
+    { id: 'card1', type: 'card', props: { title: '新品', price: 99 } },
+  ],
+}
+
+createChatSdk({
+  container: '#chat',
+  llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat', temperature: 0.3 },
+  systemPrompt: '你是页面搭建助手。用 edit_window_prop 按 jsonPath 增量改 components,不要重传整树。',
+  windowProps: [
+    { path: 'page.components', description: '组件树',
+      schema: z.array(z.object({
+        id: z.string(), type: z.string(),
+        props: z.record(z.any()),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderCanvas() },  // canvas reactive refresh
+  checkpoint: true,                       // bad edit → one-click rollback
+  approval: { tools: ['set_window_prop', 'edit_window_prop'] },  // confirm writes
+}).mount()
+```
+
+User: "顶部 Banner 改深色、主标题加粗、加一张新品卡" → AI calls `edit_window_prop` per component.
+
+## 2. Form designer
+
+Form schema as data; AI edits field definitions, schema validation prevents malformed forms.
+
+```ts
+window.form = {
+  fields: [
+    { name: 'phone', label: '手机号', type: 'text', required: true, validation: 'none' },
+    { name: 'address', label: '地址', type: 'text', required: false, cascade: false },
+  ],
+}
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是表单设计助手。改 form.fields 的字段定义,保持 schema 合法。',
+  windowProps: [
+    { path: 'form.fields', description: '字段定义数组',
+      schema: z.array(z.object({
+        name: z.string(), label: z.string(),
+        type: z.enum(['text','number','select','date']),
+        required: z.boolean(),
+        validation: z.enum(['none','phone','email','idcard']),
+        cascade: z.boolean().optional(),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderForm() },
+}).mount()
+```
+
+User: "手机号加格式校验、地址改三级联动" → AI patches `form.fields[0].validation='phone'`, `form.fields[1].cascade=true`.
+
+## 3. CMS batch operation
+
+Bulk-edit a product list; use `eval_window_script` or `search_window_prop` + `edit_window_prop` for batch ops.
+
+```ts
+window.products = [
+  { id: 1, title: '商品A', price: 99, highlight: false },
+  { id: 2, title: '商品B', price: 150, highlight: false },
+  // ...hundreds
+]
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是运营助手。批量改 products;标题加前缀用 eval_window_script,按条件筛选用 search_window_prop。',
+  windowProps: [
+    { path: 'products', description: '商品列表',
+      schema: z.array(z.object({
+        id: z.number(), title: z.string(), price: z.number(), highlight: z.boolean(),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderTable() },
+}).mount()
+```
+
+User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_window_script` for the prefix loop + `search_window_prop` to find `<100` then `edit_window_prop` to set `highlight`.
+
+## 4. Ops config console
+
+Edit experiment thresholds / feature flags with human confirmation.
+
+```ts
+window.config = {
+  expA: { threshold: 0.5, enabled: true },
+  featureB: { enabled: false },
+}
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是运维助手。改 config 前必须经用户确认。',
+  windowProps: [
+    { path: 'config.expA', description: '实验A',
+      schema: z.object({ threshold: z.number().min(0).max(1), enabled: z.boolean() }) },
+    { path: 'config.featureB', description: 'B开关',
+      schema: z.object({ enabled: z.boolean() }) },
+  ],
+  approval: { tools: ['set_window_prop', 'edit_window_prop'] },  // human-in-the-loop
+  checkpoint: true,
+  capabilities: { verify: true },           // write-back read + schema check
+}).mount()
+```
+
+User: "A 实验阈值调到 30%、关掉 B 开关" → AI proposes writes → user confirms → verify reads back.
+
+## 5. AI-native assistant (no page data, custom tools)
+
+The agent drives your product's own API via custom tools (no windowOps).
+
+```ts
+const lookupTool = defineTool({
+  name: 'lookup_order',
+  description: '查询订单',
+  schema: z.object({ orderId: z.string() }),
+  handler: async ({ orderId }) => JSON.stringify(await api.getOrder(orderId)),
+})
+
+createChatSdk({
+  container: '#chat',
+  llm: { ... },
+  systemPrompt: '你是订单助手。用 lookup_order 查询。',
+  tools: [lookupTool],
+  capabilities: { windowOps: false, fetch: false },   // pure custom-tool agent
+}).mount()
+```
+
+## 6. Research agent (fetch + subagents, no writes)
+
+Pure research: fetch docs, parallel subagents for multi-source investigation.
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是调研助手。多源对比用 spawn_agents 并行委派。',
+  capabilities: { windowOps: false },       // read-only, no page edits
+  subagent: { allowedTools: ['fetch_document'] },
+  contextPreset: 'conservative',             // long research sessions
+}).mount()
+```
+
+## 7. Headless server-side (Node.js)
+
+Run the agent in Node (no browser). Provide `globalThis.window` only if you enable windowOps.
+
+```ts
+// node mjs
+import { createChatSdk, z } from 'page-agent-sdk'
+
+const sdk = createChatSdk({
+  ui: false,
+  storage: 'memory',
+  llm: { apiKey, baseUrl, model },
+  systemPrompt: '...',
+  capabilities: { windowOps: false, fetch: false },
+  tools: [/* your tools */],
+})
+await sdk.mount()
+const reply = await sdk.send('do something')
+console.log(reply)
+sdk.unmount()
+```
+
+## 8. Multi-agent on one page (shared context)
+
+Two dialogs backed by one agent brain.
+
+```ts
+const a = createChatSdk({ id: 'shared', container: '#dlg-a', llm: {...}, shareContext: true, windowProps }).mount()
+const b = createChatSdk({ id: 'shared', container: '#dlg-b', llm: {...}, shareContext: true, windowProps }).mount()
+// a & b share messages/agent/vfs/todos/memory — two views of one agent
+```
+
+## 9. MCP integration (external tool servers)
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  mcp: [
+    { transport: 'http', url: 'https://my-mcp-server/mcp' },
+    { transport: 'sse',  url: 'https://another/sse' },
+  ],
+  // MCP tools auto-injected; fault-isolated (one server down doesn't break others)
+}).mount()
+```
+
+> Note: `@modelcontextprotocol/sdk` is an optional peerDep — install it only if you use `mcp`. Browser supports only remote transports (http/sse/websocket), not stdio.