page-agent-sdk 4.19.2 → 4.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "4.19.2",
+  "version": "4.21.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

@@ -413,13 +413,15 @@ export interface AgentInfo {
   /** 方案确认留痕(save-and-plan-gates 3c:RHC 带 options 的方案被点选;undefined=本会话无已确认方案) */
   planConfirmation?: PlanConfirmationRecord;
   /** 宿主动作元信息(actions 注册;集成方 save_draft/publish 等) */
-  actions?: Record<string, { description: string; hasParams: boolean }>;
+  actions?: Record<string, { description: string; hasParams: boolean; readsHostState?: boolean; deferredWrite?: boolean }>;
   /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
   workingMemory?: WorkingMemory;
   /** 写驱动过期读失效会话累计(stale-read-invalidation;写后旧 read/query/search 结果被替换为占位的次数) */
   staleReadsInvalidated?: number;
   /** S2 宿主变更失效会话累计(host-integration-contract;notifyHostChange 触发的页面读占位替换次数,与写驱动分列) */
   hostReadsInvalidated?: number;
+  /** hostWatch 装配反射(4.21+;配置存在才出现):enabled=false = 服务端/headless 特性探测全缺(合法 no-op);autoNotified = 自动报案会话累计 */
+  hostWatch?: { enabled: boolean; url: boolean; pushState: boolean; title: boolean; autoNotified: number };
   /** A9 收口门禁会话累计(stage → { retries 回灌, exhausted 耗尽放行 };page_assertion_gate 键存在性 = domInspect 装配反射) */
   gates?: Record<string, { retries: number; exhausted: number }>;
   /** A9 最近一次 system 段构成(段名/字节/超预算 drop 标记;集成方 augmentSystem/pageContext 段被 drop 时可观察) */
@@ -926,6 +928,10 @@ export interface ActionDef {
   run: (args: Record<string, unknown>) => unknown | Promise<unknown>;
   /** 可选参数 schema(ZodObject);不传 = 无参 tool */
   params?: any;
+  /** 标记本 action 读取宿主态(4.20+):旧工具结果随 `sdk.notifyHostChange()` 替换为过期占位(修前仅 read_page 等五个内置页面读工具享受,action 仅靠 reason 文案口头告知);页面断言门禁的「页面依据」计数也计入。不标记 = 现行为零变化 */
+  readsHostState?: boolean;
+  /** 标记本 action 的效果延迟到用户确认才生效(提案类,4.20+):调用成功 ≠ 已写入 → 零工具门禁事实清单对此类调用注记「待用户确认后才生效」,防模型收口「已修改完成」;等效写计数不含此类。不标记 = 现行为零变化 */
+  deferredWrite?: boolean;
 }
 /** actions 配置:动作名 → 定义(动作名即 tool 名,须合法标识符) */
 export type ActionMap = Record<string, ActionDef>;
@@ -1060,10 +1066,31 @@ export interface ChatSdkOptions {
   onEvent?: SdkEventHandler;
   /** 流式输出(默认 true);false 时等整段回复再显示 */
   streaming?: boolean;
+  /**
+   * 宿主导航自动报案(4.21+,配置即开关):监听 URL/title 变化自动触发 notifyHostChange 全链路
+   * (流内页面读占位失效 + 一次性重读提示段)—— 把「防线靠宿主记得调」变「防线自动」。
+   * `true` = { url: true };细配见 HostWatchConfig。服务端/headless(无 window)逐 API 特性探测
+   * 静默降级 no-op(合法形态,inspect().hostWatch.enabled=false 可确认)。
+   * 另:dom_edit/dom_restore 落地成功后既有页面读自动失效(默认开,与本选项无关)
+   */
+  hostWatch?: boolean | HostWatchConfig;
   /** Dialog UI config (title/placeholder/drawer/drawerWidth/drawerHidden/inputRows/onClose grouped) */
   dialog?: DialogConfig;
 }
 
+/** hostWatch 细配(4.21+):各项独立降级,缺失依赖只关该项不弃整个 watcher */
+export interface HostWatchConfig {
+  /** 原生 hashchange + popstate(默认项,零 patch;hash 路由文档站主场景) */
+  url?: boolean;
+  /** patch history.pushState/replaceState(hashless SPA 路由;链式保留 + unmount 还原;opt-in) */
+  pushState?: boolean;
+  /** 观察 document.title(不改 URL 的换文站;噪声较高故 opt-in;配 debounceMs 消化) */
+  title?: boolean;
+  /** 去抖窗口 ms(默认 300:路由切换常伴 hash+title 连发,窗口内合并为一次报案,url 类优先) */
+  debounceMs?: number;
+  /** 宿主自定义忽略(如自家 #section 纯锚点):返回 true 不报案 */
+  ignore?: (e: { kind: 'hash' | 'pop' | 'push' | 'title'; from: string; to: string }) => boolean;
+}
 /** Dialog UI config (grouped form, recommended) */
 export interface DialogConfig {
   title?: string;
@@ -1496,7 +1523,7 @@ export declare const getDomTool: any;
 export declare function domToStructure(node: Element | null, opts: { depth: number; attrs?: string[]; includeText?: boolean }): DomNode | null;
 /** 把集成方注册的 actions 转成命名 tool 数组(每个 action 一个 tool) */
 export declare function actionsToTools(actions: ActionMap): any[];
-export declare function actionsToInspectInfo(actions: ActionMap): Record<string, { description: string; hasParams: boolean }>;
+export declare function actionsToInspectInfo(actions: ActionMap): Record<string, { description: string; hasParams: boolean; readsHostState: boolean; deferredWrite: boolean }>;
 export interface DomNode { tag: string; attrs: Record<string, string>; text?: string; children?: DomNode[]; childCount?: number }
 export interface DomReadOptions { depth: number; attrs?: string[]; includeText?: boolean }
 
@@ -1599,6 +1626,10 @@ export interface CreateAgentOptions {
    * 传入(仅页面问答形态装配 —— 数据槽场景「页面上已改成…」误伤路径从结构上切断);false/缺省 = 门禁层不进判定。
    */
   pageAssertionGate?: boolean;
+  /** 有效页面读集扩展(action-host-semantics,4.20):宿主标记 readsHostState 的 action 名 —— 进页面断言门禁「页面依据」计数;缺省 = 仅默认五工具 */
+  pageReadTools?: Set<string>;
+  /** 延迟生效写 action 名集(action-host-semantics,4.20):零工具门禁事实清单对其调用注记「待用户确认后才生效」;缺省 = 清单与现行为逐字节一致 */
+  deferredWriteTools?: Set<string>;
   /** LLM 运行时切换回调(setLlm 后触发,供重解析模型能力 contextWindow/maxOutputTokens) */
   onLlmChange?: (newLlm: import('@langchain/core/language_models/chat_models').BaseChatModel) => void;
   /** 显式声明主模型是否多模态识图(声明 > 查表 > 缺省 false) */

package/types/index.d.ts

@@ -722,13 +722,15 @@ export interface AgentInfo {
   /** 方案确认留痕(save-and-plan-gates 3c:RHC 带 options 的方案被点选;undefined=本会话无已确认方案) */
   planConfirmation?: PlanConfirmationRecord;
   /** 宿主动作元信息(actions 注册;集成方 save_draft/publish 等) */
-  actions?: Record<string, { description: string; hasParams: boolean }>;
+  actions?: Record<string, { description: string; hasParams: boolean; readsHostState?: boolean; deferredWrite?: boolean }>;
   /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
   workingMemory?: WorkingMemory;
   /** 写驱动过期读失效会话累计(stale-read-invalidation;写后旧 read/query/search 结果被替换为占位的次数) */
   staleReadsInvalidated?: number;
   /** S2 宿主变更失效会话累计(host-integration-contract;notifyHostChange 触发的页面读占位替换次数,与写驱动分列) */
   hostReadsInvalidated?: number;
+  /** hostWatch 装配反射(4.21+;配置存在才出现):enabled=false = 服务端/headless 特性探测全缺(合法 no-op);autoNotified = 自动报案会话累计 */
+  hostWatch?: { enabled: boolean; url: boolean; pushState: boolean; title: boolean; autoNotified: number };
   /** A9 收口门禁会话累计(stage → { retries 回灌, exhausted 耗尽放行 };page_assertion_gate 键存在性 = domInspect 装配反射) */
   gates?: Record<string, { retries: number; exhausted: number }>;
   /** A9 最近一次 system 段构成(段名/字节/超预算 drop 标记;集成方 augmentSystem/pageContext 段被 drop 时可观察) */
@@ -1286,6 +1288,10 @@ export interface ActionDef {
   run: (args: Record<string, unknown>) => unknown | Promise<unknown>;
   /** 可选参数 schema(ZodObject);不传 = 无参 tool */
   params?: any;
+  /** 标记本 action 读取宿主态(4.20+):旧工具结果随 `sdk.notifyHostChange()` 替换为过期占位(修前仅 read_page 等五个内置页面读工具享受,action 仅靠 reason 文案口头告知);页面断言门禁的「页面依据」计数也计入。不标记 = 现行为零变化 */
+  readsHostState?: boolean;
+  /** 标记本 action 的效果延迟到用户确认才生效(提案类,4.20+):调用成功 ≠ 已写入 → 零工具门禁事实清单对此类调用注记「待用户确认后才生效」,防模型收口「已修改完成」;等效写计数不含此类。不标记 = 现行为零变化 */
+  deferredWrite?: boolean;
 }
 /** actions 配置:动作名 → 定义(动作名即 tool 名,须合法标识符) */
 export type ActionMap = Record<string, ActionDef>;
@@ -1428,6 +1434,14 @@ export interface ChatSdkOptions {
   dialog?: DialogConfig;
   /** 国际化:locale 切语言 + messages 键级覆盖文案(3.22+;UI 文案包 + 默认 systemPrompt/autoTitle 语言;原 dialog.locale/dialog.messages 两键合并至此) */
   i18n?: I18nOptions;
+  /**
+   * 宿主导航自动报案(4.21+,配置即开关):监听 URL/title 变化自动触发 notifyHostChange 全链路
+   * (流内页面读占位失效 + 一次性重读提示段)—— 把「防线靠宿主记得调」变「防线自动」。
+   * `true` = { url: true };细配见 HostWatchConfig。服务端/headless(无 window)逐 API 特性探测
+   * 静默降级 no-op(合法形态,inspect().hostWatch.enabled=false 可确认)。
+   * 另:dom_edit/dom_restore 落地成功后既有页面读自动失效(默认开,与本选项无关)
+   */
+  hostWatch?: boolean | HostWatchConfig;
 }
 
 /** Dialog UI config (grouped form, recommended) */
@@ -1480,6 +1494,19 @@ export interface QuickActionItem {
  * 国际化配置(顶层 i18n;3.22 起,原 dialog.locale/dialog.messages 两键移入此处合并)。
  * 不放 dialog 组:locale 除 UI 文案包外还驱动默认 systemPrompt 语言与 autoTitle 标题语言(agent 层)。
  */
+/** hostWatch 细配(4.21+):各项独立降级,缺失依赖只关该项不弃整个 watcher */
+export interface HostWatchConfig {
+  /** 原生 hashchange + popstate(默认项,零 patch;hash 路由文档站主场景) */
+  url?: boolean;
+  /** patch history.pushState/replaceState(hashless SPA 路由;链式保留 + unmount 还原;opt-in) */
+  pushState?: boolean;
+  /** 观察 document.title(不改 URL 的换文站;噪声较高故 opt-in;配 debounceMs 消化) */
+  title?: boolean;
+  /** 去抖窗口 ms(默认 300:路由切换常伴 hash+title 连发,窗口内合并为一次报案,url 类优先) */
+  debounceMs?: number;
+  /** 宿主自定义忽略(如自家 #section 纯锚点):返回 true 不报案 */
+  ignore?: (e: { kind: 'hash' | 'pop' | 'push' | 'title'; from: string; to: string }) => boolean;
+}
 export interface I18nOptions {
   /** 语言:'zh-CN'(默认)/'en-US';切换内置文案包(聊天面 + Debug 抽屉 + Skill 面板 + 代码预览);
    *  formatTime(12h/24h)/autoTitle/默认 systemPrompt 跟随(en → 英文版身份 + "Respond in English" 锚,
@@ -1925,7 +1952,7 @@ export declare const getDomTool: any;
 export declare function domToStructure(node: Element | null, opts: { depth: number; attrs?: string[]; includeText?: boolean }): DomNode | null;
 /** 把集成方注册的 actions 转成命名 tool 数组(每个 action 一个 tool) */
 export declare function actionsToTools(actions: ActionMap): any[];
-export declare function actionsToInspectInfo(actions: ActionMap): Record<string, { description: string; hasParams: boolean }>;
+export declare function actionsToInspectInfo(actions: ActionMap): Record<string, { description: string; hasParams: boolean; readsHostState: boolean; deferredWrite: boolean }>;
 export interface DomNode { tag: string; attrs: Record<string, string>; text?: string; children?: DomNode[]; childCount?: number }
 export interface DomReadOptions { depth: number; attrs?: string[]; includeText?: boolean }
 
@@ -2028,6 +2055,10 @@ export interface CreateAgentOptions {
    * 传入(仅页面问答形态装配 —— 数据槽场景「页面上已改成…」误伤路径从结构上切断);false/缺省 = 门禁层不进判定。
    */
   pageAssertionGate?: boolean;
+  /** 有效页面读集扩展(action-host-semantics,4.20):宿主标记 readsHostState 的 action 名 —— 进页面断言门禁「页面依据」计数;缺省 = 仅默认五工具 */
+  pageReadTools?: Set<string>;
+  /** 延迟生效写 action 名集(action-host-semantics,4.20):零工具门禁事实清单对其调用注记「待用户确认后才生效」;缺省 = 清单与现行为逐字节一致 */
+  deferredWriteTools?: Set<string>;
   /** LLM 运行时切换回调(setLlm 后触发,供重解析模型能力 contextWindow/maxOutputTokens) */
   onLlmChange?: (newLlm: import('@langchain/core/language_models/chat_models').BaseChatModel) => void;
   /** 显式声明主模型是否多模态识图(声明 > 查表 > 缺省 false) */