page-agent-sdk 2.15.1 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.15.1",
+  "version": "2.17.0",
   "type": "module",
   "description": "AI agent SDK for web pages — embed a chat assistant that edits page data via schema-validated tools. A lighter, framework-agnostic alternative to CopilotKit/LangChain for in-page JSON-editing agents. Vue-bundled; works with DeepSeek, OpenAI, MCP.",
   "main": "./dist/page-agent-sdk.umd.cjs",

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

@@ -128,6 +128,35 @@ Example: `write({ value: 9.9, patch: { op: 'set', jsonPath: 'items.0.price' } })
 
 `fetch_document` — GET a URL, return cleaned text (HTML→markdown, truncated, offloaded to vfs if large).
 
+## Built-in vfs tools (`capabilities.vfs`, default on)
+
+The virtual file workspace holds tool-result offloads (>6000 chars), agent/integrator drafts, and user files. 2.16.0+ partitions it into three independent LRU pools (`large_results/*` / `drafts/*` / `userFiles`), so offloaded results can't evict drafts or user files.
+
+| Tool | Signature | Purpose |
+|---|---|---|
+| `vfs_read` | `({ path }) => string` | Read a file (path may be returned by a prior offload). |
+| `vfs_write` | `({ path, content, jsonString? }) => meta` | Write/overwrite a file. `jsonString:true` (2.16.0+) validates `content` is valid JSON before writing (invalid → `VFS_JSON_INVALID`, not written). |
+| `vfs_grep` | `({ pattern, paths? }) => matches` | Grep across workspace files. |
+| `vfs_json_read` (2.16.0+) | `({ path, jsonPath? }) => json\|string` | Read a JSON subtree from a vfs file via jsonPath (omit for the whole file). Returns `VFS_JSON_INVALID` if the file isn't valid JSON; `VFS_PATH_NOT_FOUND` if jsonPath doesn't exist. |
+| `vfs_json_patch` (2.16.0+) | `({ path, patches: [{op:'set'\|'remove'\|'merge'\|'append', jsonPath, value?}] }) => meta` | Atomic jsonPath patch inside a vfs file. Applied on a clone; any patch failure → `PATCH_FAILED`, original file unchanged. Avoids re-sending large JSON (delta only). |
+
+## Context compression presets (`contextPreset`)
+
+`contextPreset` is a one-line knob over the `summarization` middleware (ratio-based); `contextOptions` overrides individual fields.
+
+| Preset | When | Profile |
+|---|---|---|
+| `auto` (default) | General chat | window 0.4 / threshold 0.5 / recall Top-3 / LLM summary |
+| `conservative` | Big models / cost | window 0.5 / threshold 0.7 / recall Top-2 / index summary (no LLM) |
+| `aggressive` | Small models / save context | window 0.3 / threshold 0.3 / recall Top-5 |
+| `complex` (2.16.0+) | Multi-step complex tasks / large JSON / long workflows | windowRatio 0.6 / summaryThresholdRatio 0.7 / recall Top-5 / LLM summary; `preserveLastToolResults` defaults to `['describe_data','read','query_data','search_data']` |
+
+```ts
+createChatSdk({ contextPreset: 'complex', contextOptions: { recallTopK: 8 } })
+```
+
+`inspect().contextPreset` (2.16.0+) exposes the effective preset.
+
 ## SdkEvent types (for `onEvent` / `sdk.hook`)
 
 | `type` | Payload | When |

package/types/index.d.ts

@@ -75,7 +75,7 @@ export type SdkEvent =
   | { type: 'conflict'; conflict: PendingConflict }
   | { type: 'session_restored'; sessionId: string; rounds: number }
   | { type: 'usage'; round: number; usage: TokenUsage; cumulative: TokenUsage }
-  | { type: 'error'; message: string };
+  | { type: 'error'; message: string; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -135,6 +135,8 @@ export interface AgentInfo {
   tools: ToolInfo[];
   skills: SkillInfo[];
   data?: DataInfo;
+  /** 当前上下文压缩预设(默认 auto;complex 为多步复杂任务/大 JSON 场景) */
+  contextPreset: 'auto' | 'conservative' | 'aggressive' | 'complex';
   memory: string;
   middleware: string[];
   todos: { content: string; status: string }[];
@@ -464,8 +466,8 @@ export interface ChatSdkOptions {
   mcp?: McpServerConfig[];
   /** 上下文压缩配置(false 关闭;默认 LLM 摘要,失败回退索引摘要) */
   contextOptions?: any;
-  /** 上下文压缩预设档位(默认 'auto'):auto / conservative / aggressive;提供合理默认,contextOptions 细参可覆盖 */
-  contextPreset?: 'auto' | 'conservative' | 'aggressive';
+  /** 上下文压缩预设档位(默认 'auto'):auto / conservative / aggressive / complex(多步复杂任务/大 JSON);提供合理默认,contextOptions 细参可覆盖 */
+  contextPreset?: 'auto' | 'conservative' | 'aggressive' | 'complex';
   /** 摘要压缩专用 LLM(BaseChatModel 实例或 LLMConfig);不传则默认用主 agent 模型(llm) */
   summaryLlm?: any;
   /** 摘要 LLM 温度(默认 0.3) */
@@ -637,6 +639,8 @@ export declare function applyPatchToClone(clone: any, op: EditOp, jsonPath: stri
 export declare function applyPatchToLive(bind: any, op: EditOp, jsonPath: string, value: unknown): void;
 export declare function restoreLive(bind: any, snapshotVal: unknown): void;
 export declare function restoreInPlace(live: Record<string, unknown> | unknown[], snapshotVal: unknown): void;
+/** 深度差异对比(对象/数组递归,叶子差异),返回 {path, from, to}[];供 diff_data / verify 自纠 / 审计复用 */
+export declare function diffObjects(a: unknown, b: unknown, prefix?: string): { path: string; from: unknown; to: unknown }[];
 // ============ schema 白名单投影纯函数(schemaUtils,refactor-module-extraction 从 dataOps 抽离)============
 export declare function getSchemaTopKeys(schema: any): string[] | null;
 export declare function isPathAllowed(jsonPath: string, schema: any | null, allowKeys: string[] | null): boolean;
@@ -644,6 +648,33 @@ export declare function unwrapSchema(schema: any): any;
 export declare function getSchemaAtPath(schema: any, jsonPath: string): any | null;
 export declare function projectBySchemaDeep(obj: unknown, schema: any | null): unknown;
 export declare function projectBySchema(obj: unknown, allowKeys: string[] | null): unknown;
+// ============ schema 约束结构化提取(expose-schema-constraints;供 systemPrompt「可操作数据」段 / read 概览 / schema_data 工具)============
+export interface SchemaNodeDesc {
+  type: string;
+  constraints?: {
+    minLength?: number; maxLength?: number; length?: number;
+    min?: number; max?: number; int?: boolean;
+    format?: string | string[];
+    values?: readonly (string | number)[];
+    value?: unknown;
+    item?: SchemaNodeDesc;
+    shape?: Record<string, SchemaNodeDesc>;
+    anyOf?: SchemaNodeDesc[];
+    valueType?: SchemaNodeDesc;
+  };
+  optional?: boolean;
+  nullable?: boolean;
+  default?: unknown;
+  description?: string;
+}
+/** 结构化提取单个 zod 节点的约束(type + 关键约束 + optional/default/nullable;zod 4 `_def`/`_zod.def` 读取) */
+export declare function describeSchemaNode(schema: any): SchemaNodeDesc;
+/** 把标量约束格式化为括号内短串(min/max/enum/format 等;shape/item/anyOf 不渲染) */
+export declare function formatConstraints(c: NonNullable<SchemaNodeDesc['constraints']>): string;
+/** 渲染单行字段标注 `- key (Type?)[约束]: description` */
+export declare function renderSchemaHint(key: string, desc: SchemaNodeDesc): string;
+/** 渲染 schema 顶层字段约束总览(非 object fallback 根节点;供 extractSchemaHint + read 概览复用) */
+export declare function renderSchemaOverview(schema: any): string;
 // ============ 上下文索引纯函数(contextIndex,refactor-module-extraction 期二 从 useContextManager 抽离)============
 export declare const STOP_WORDS: Set<string>;
 export declare function tokenize(text: string): string[];
@@ -768,6 +799,24 @@ export declare function zodError(path: string, issues: unknown[]): string;
 export declare function jsonParseError(path: string | undefined, raw: string, err: unknown): string;
 /** 提取 zod issues 为结构化 details(每条 path/expected/received/message) */
 export declare function formatZodIssues(issues: unknown[]): unknown[];
+// ============ 统一错误模型(unify-error-model:三档 severity,各 catch 点按档路由)============
+/** 错误严重程度三档:recoverable(回灌)/ fatal(中断)/ observable(记录不中断) */
+export type ErrorSeverity = 'recoverable' | 'fatal' | 'observable';
+/** 统一错误对象(结构化,跨层传递;普通 Error 经 asAgentError 归一化) */
+export interface AgentError {
+  severity: ErrorSeverity;
+  message: string;
+  code?: string;
+  context?: unknown;
+}
+/** 错误路由:recoverable→feedback / fatal→abort / observable→log */
+export type ErrorRouting = 'feedback' | 'abort' | 'log';
+/** 路由纯函数:据 severity 决定错误如何被处理 */
+export declare function routeError(err: AgentError): ErrorRouting;
+/** 把任意错误归一化为 AgentError(已是 AgentError 不覆盖;普通 Error 用 defaultSeverity,默认 fatal) */
+export declare function asAgentError(err: unknown, defaultSeverity?: ErrorSeverity): AgentError;
+/** AgentError 便捷工厂 */
+export declare function agentError(severity: ErrorSeverity, message: string, code?: string, context?: unknown): AgentError;
 
 // === 与 src/core/index.ts 导出对齐(消费者类型完整;复杂内部类型用宽松声明,消费者主要消费工厂返回值) ===
 // 上下文压缩预设