page-agent-sdk 3.40.3 → 3.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "3.40.3",
+  "version": "3.42.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/types/headless.d.ts

@@ -328,6 +328,8 @@ export interface AgentInfo {
   actions?: Record<string, { description: string; hasParams: boolean }>;
   /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
   workingMemory?: WorkingMemory;
+  /** 写驱动过期读失效会话累计(stale-read-invalidation;写后旧 read/query/search 结果被替换为占位的次数) */
+  staleReadsInvalidated?: number;
   /** 当前上下文聚焦焦点(focus 中间件;兼容:首个;未聚焦/未开启 → undefined) */
   focus?: Focus;
   /** 全部聚焦焦点(multi-focus;空数组=未聚焦) */
@@ -490,6 +492,11 @@ export interface DataConfig {
    *  配置后 read 受保护路径返占位符(精确值不入 LLM 消息流),写侧强制(freeze 拒/verbatim 展开校验)。
    *  opt-in:未配(默认)全部行为零变化 */
   resources?: ResourceProtectSpec[];
+  /**
+   * 装配期工具白名单(main-surface-slim Phase 1):`'high'` 预设(全量减旧四件 get/set/edit/delete_data)/
+   * 具体名单(按名过滤,未装配名 warn 留痕)。不传 = 全量零回归;仅首次装配生效,运行时 setData 忽略。
+   */
+  tools?: string[] | 'high';
 }
 /** createDataOps 选项(审计回调 / 快照上限 / 乐观锁) */
 export interface DataOpsOptions {
@@ -499,6 +506,11 @@ export interface DataOpsOptions {
   onConflict?: (conflict: ConflictInfo) => Promise<ConflictResolution>;
   /** 冲突监听字段白名单(任意深度字段名):声明后仅这些字段的值变动触发自动冲突检测(位置不敏感);未声明 = 不开自动检测(仅显式 expectedHash 校验);['*'] = 全字段检测(旧 autoLock 行为) */
   conflictWatchFields?: string[];
+  /**
+   * 装配期工具白名单(main-surface-slim Phase 1):`'high'` 预设(全量减旧四件 get/set/edit/delete_data)/
+   * 具体名单(按名过滤,未装配名 warn 留痕)。不传 = 全量零回归。
+   */
+  tools?: string[] | 'high';
 }
 
 /** 数据操作控制器(运行时替换配置;createDataOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
@@ -804,7 +816,7 @@ export interface ChatSdkOptions {
   permissions?: PermissionRule[];
   /** 自定义中间件(注入到内置中间件之后;可拦截/观察模型调用、工具、prompt) */
   middleware?: any[];
-  vfs?: { initialFiles?: Record<string, string>; maxBytes?: number };
+    vfs?: { initialFiles?: Record<string, string>; maxBytes?: number; poolBytes?: { largeResults?: number; drafts?: number; userFiles?: number }; mainTools?: boolean };
   /** 每个数据对象最多保留快照数(默认 20) */
   maxSnapshots?: number;
   /** 乐观锁冲突裁决策略(默认 'ask'):ask=挂起 pendingConflict 等人工 resolveConflict;overwrite=agent 强制覆盖(宿主与 agent 争同一份数据且 agent 优先时用,冲突自动收口不挂起,无人值守场景防永挂);keep_external=自动保留外部修改(agent 收到提示重新 read)。自动裁决仍外发 conflict 事件(conflict.autoResolved 标记) */
@@ -828,6 +840,8 @@ export interface ChatSdkOptions {
   tokenBudget?: number;
   /** 单次 invoke 的 token 预算上限(opt-in,默认关):本次 agent 调用累计 total_tokens 超限 → 中断收口(observable emit + 友好文本,已完成部分保留);与 automation 全局 tokenBudget 正交 */
   roundTokenBudget?: number;
+  /** 写驱动过期读失效(stale-read-invalidation,默认 true):单次 invoke 窗口内,本批成功写之后被击中路径的旧 read/query/search 结果替换为失效占位(防模型凭旧快照答状态/用错位索引)。false = 主/子一致关闭零变化 */
+  staleReadInvalidation?: boolean;
   /** 时间预算 ms(从 agent 开始计时,超过 → 停止;需 capabilities.automation:true) */
   timeBudgetMs?: number;
   /** 无人值守错误恢复:致命错误(invoke 抛错)自动 restore_last_checkpoint + 重试次数(默认 1;防单点错误永久中断批量/长任务)。需 capabilities.automation:true */

package/types/index.d.ts

@@ -666,6 +666,8 @@ export interface AgentInfo {
   actions?: Record<string, { description: string; hasParams: boolean }>;
   /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
   workingMemory?: WorkingMemory;
+  /** 写驱动过期读失效会话累计(stale-read-invalidation;写后旧 read/query/search 结果被替换为占位的次数) */
+  staleReadsInvalidated?: number;
   /** 当前上下文聚焦焦点(focus 中间件;兼容:首个;未聚焦/未开启 → undefined) */
   focus?: Focus;
   /** 全部聚焦焦点(multi-focus;空数组=未聚焦) */
@@ -854,6 +856,11 @@ export interface DataConfig {
    *  配置后 read 受保护路径返占位符(精确值不入 LLM 消息流),写侧强制(freeze 拒/verbatim 展开校验)。
    *  opt-in:未配(默认)全部行为零变化 */
   resources?: ResourceProtectSpec[];
+  /**
+   * 装配期工具白名单(main-surface-slim Phase 1):`'high'` 预设(全量减旧四件 get/set/edit/delete_data)/
+   * 具体名单(按名过滤,未装配名 warn 留痕)。不传 = 全量零回归;仅首次装配生效,运行时 setData 忽略。
+   */
+  tools?: string[] | 'high';
 }
 /** createDataOps 选项(审计回调 / 快照上限 / 乐观锁) */
 export interface DataOpsOptions {
@@ -863,6 +870,11 @@ export interface DataOpsOptions {
   onConflict?: (conflict: ConflictInfo) => Promise<ConflictResolution>;
   /** 冲突监听字段白名单(任意深度字段名):声明后仅这些字段的值变动触发自动冲突检测(位置不敏感);未声明 = 不开自动检测(仅显式 expectedHash 校验);['*'] = 全字段检测(旧 autoLock 行为) */
   conflictWatchFields?: string[];
+  /**
+   * 装配期工具白名单(main-surface-slim Phase 1):`'high'` 预设(全量减旧四件 get/set/edit/delete_data)/
+   * 具体名单(按名过滤,未装配名 warn 留痕)。不传 = 全量零回归。
+   */
+  tools?: string[] | 'high';
 }
 
 /** 数据操作控制器(运行时替换配置;createDataOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
@@ -1193,7 +1205,7 @@ export interface ChatSdkOptions {
   permissions?: PermissionRule[];
   /** 自定义中间件(注入到内置中间件之后;可拦截/观察模型调用、工具、prompt) */
   middleware?: any[];
-  vfs?: { initialFiles?: Record<string, string>; maxBytes?: number };
+    vfs?: { initialFiles?: Record<string, string>; maxBytes?: number; poolBytes?: { largeResults?: number; drafts?: number; userFiles?: number }; mainTools?: boolean };
   /** 每个数据对象最多保留快照数(默认 20) */
   maxSnapshots?: number;
   /** 乐观锁冲突裁决策略(默认 'ask'):ask=挂起 pendingConflict 等人工 resolveConflict;overwrite=agent 强制覆盖(宿主与 agent 争同一份数据且 agent 优先时用,冲突自动收口不挂起,无人值守场景防永挂);keep_external=自动保留外部修改(agent 收到提示重新 read)。自动裁决仍外发 conflict 事件(conflict.autoResolved 标记) */
@@ -1219,6 +1231,8 @@ export interface ChatSdkOptions {
   tokenBudget?: number;
   /** 单次 invoke 的 token 预算上限(opt-in,默认关):本次 agent 调用累计 total_tokens 超限 → 中断收口(observable emit + 友好文本,已完成部分保留);与 automation 全局 tokenBudget 正交 */
   roundTokenBudget?: number;
+  /** 写驱动过期读失效(stale-read-invalidation,默认 true):单次 invoke 窗口内,本批成功写之后被击中路径的旧 read/query/search 结果替换为失效占位(防模型凭旧快照答状态/用错位索引)。false = 主/子一致关闭零变化 */
+  staleReadInvalidation?: boolean;
   /** 时间预算 ms(从 agent 开始计时,超过 → 停止;需 capabilities.automation:true) */
   timeBudgetMs?: number;
   /** 无人值守错误恢复:致命错误(invoke 抛错)自动 restore_last_checkpoint + 重试次数(默认 1;防单点错误永久中断批量/长任务)。需 capabilities.automation:true */