page-agent-sdk 4.20.0 → 4.22.0

package/package.json

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

@@ -157,6 +157,33 @@ export interface QuoteAnchor {
 }
 export declare function captureSelectionQuote(doc: { getSelection?(): { isCollapsed?: boolean; anchorNode?: Node | null; toString(): string } | null; title?: string; location?: { href?: string }; querySelectorAll?: (selector: string) => ArrayLike<Element> }): MessageQuote | null;
 
+/** 逐行 diff 行类型(content-proposals;lineDiff 产出;skip 行由宿主渲染折叠产生,本函数不产出) */
+export interface DiffRow {
+  type: 'same' | 'add' | 'del';
+  text: string;
+}
+/** 内容提案增量操作(判别联合;字面锚点纪律:find/anchor 须在当前内容唯一命中) */
+export type ProposalOp = { op: 'replace'; find: string; with: string } | { op: 'insertAfter'; anchor: string; text: string } | { op: 'insertBefore'; anchor: string; text: string } | { op: 'append'; text: string };
+/** 逐行 diff(公共前后缀修剪 + 中段 LCS;中段超 4e6 格回退整块替换)。宿主评审面板渲染/预演用 */
+export declare function lineDiff(oldText: string, newText: string): { rows: DiffRow[]; stats: { added: number; removed: number } };
+/** 顺序应用增量 ops(原子:任一失败整批拒,错误指名第几个 op 与命中数);测试缝/预演用 */
+export declare function applyProposalOps(base: string, ops: ProposalOp[]): { ok: true; content: string } | { ok: false; error: string };
+/** 内容指纹(FNV-1a → base36;提案基底锚定用;非密码学) */
+export declare function hashContent(text: string): string;
+/** 字面锚点命中数(锚为空串按 0 计) */
+export declare function countOccurrences(haystack: string, needle: string): number;
+/** 送达评审面板的提案(content-proposals;SDK 已校验基底/应用 ops/算 diff,宿主渲染面板 + 裁决) */
+export interface ReviewableProposal {
+  id: string;
+  summary: string;
+  label?: string;
+  baseHash: string;
+  baseContent: string;
+  content: string;
+  diff: { rows: DiffRow[]; stats: { added: number; removed: number } };
+  createdAt: number;
+}
+
 export interface AgentConfig {
   model: string;
   temperature?: number;
@@ -220,7 +247,9 @@ export type SdkEvent =
   | { type: 'error'; message: string; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown }
   | { type: 'context_trimmed'; dropped: { round: number; user: unknown; assistant: unknown[]; steps: unknown[] }[]; vfsResults: Record<string, string>; summary: string; reason: string }
   | { type: 'focus_chip_click'; path: string; label?: string }
-  | { type: 'focus_change'; focuses: Focus[] };
+  | { type: 'focus_change'; focuses: Focus[] }
+  | { type: 'proposal_pending'; id: string; summary: string; added: number; removed: number }
+  | { type: 'proposal_resolved'; id: string; outcome: 'applied' | 'discarded'; summary: string };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -420,6 +449,10 @@ export interface AgentInfo {
   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 };
+  /** content-proposals 反射(4.22+;配置存在才出现):pending 轻投影 + 会话累计 + 最近裁决 */
+  proposals?: { pending: Array<{ id: string; summary: string; createdAt: number; added: number; removed: number }>; applied: number; discarded: number; lastResolved: { id: string; outcome: 'applied' | 'discarded'; summary: string; detail?: string; at: number } | null };
   /** A9 收口门禁会话累计(stage → { retries 回灌, exhausted 耗尽放行 };page_assertion_gate 键存在性 = domInspect 装配反射) */
   gates?: Record<string, { retries: number; exhausted: number }>;
   /** A9 最近一次 system 段构成(段名/字节/超预算 drop 标记;集成方 augmentSystem/pageContext 段被 drop 时可观察) */
@@ -1064,10 +1097,52 @@ 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;
+  /**
+   * 内容提案-评审-应用通道(4.22+,配置即开关;不配置 = 零注册零开销):数据槽之外内容的受控修改 ——
+   * 模型零写权限,propose_content 只送提案(非阻塞),diff 评审与写回在宿主侧由用户显式完成。
+   * sdk.resolveProposal(id, 'applied'|'discarded') 裁决回传 → 事件 + 下轮结局告知
+   */
+  proposals?: ProposalsConfig;
   /** 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;
+}
+/** 内容提案通道配置(content-proposals,4.22+) */
+export interface ProposalsConfig {
+  /** 读通道:返回当前内容(SDK 计算 hash;null = 当前无可编辑对象,工具内如实报) */
+  read: () => Promise<{ content: string; label?: string } | null> | { content: string; label?: string } | null;
+  /** 评审回调:SDK 已完成基底校验/ops 应用/diff 计算;宿主渲染面板。返回字符串回灌模型(非阻塞:勿等待用户裁决) */
+  onProposal: (p: ReviewableProposal) => string | Promise<string>;
+  /** 提案工具名(默认 'propose_content') */
+  toolName?: string;
+  /** 读工具名(默认 'read_content') */
+  readToolName?: string;
+  /** 内容是什么(进工具 description) */
+  contentKind?: string;
+  /** 在审提案上限(默认 1:新提案替换最旧在审,留痕) */
+  maxPending?: number;
+}
 /** Dialog UI config (grouped form, recommended) */
 export interface DialogConfig {
   title?: string;
@@ -1177,6 +1252,10 @@ export interface ChatSdk {
   clearQuote(): void;
   /** S2 宿主变更通知:SPA 换文/路由切换/tab 切换后调用 —— 流内页面读结果(read_page/dom_search/dom_info/get_dom/take_screenshot)置过期占位,并注入一次性「重读当前页面」提示段(下一 invoke 的 system,pin 段跨压缩,轮末清除);幂等可重复调 */
   notifyHostChange(opts?: { reason?: string }): void;
+  /** content-proposals(4.22+):宿主裁决回传 → 出队 + proposal_resolved 事件 + 下轮结局注入;false = id 未知/已裁决 */
+  resolveProposal(id: string, outcome: 'applied' | 'discarded', detail?: string): boolean;
+  /** content-proposals:只读状态投射(未配置恒 null) */
+  readonly proposals: { pending: Array<{ id: string; summary: string; createdAt: number; added: number; removed: number }>; applied: number; discarded: number; lastResolved: { id: string; outcome: 'applied' | 'discarded'; summary: string; detail?: string; at: number } | null } | null;
   /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 主数据 + vfs + todos);需开启 checkpoint,无可用返回 false */
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */

package/types/index.d.ts

@@ -165,6 +165,33 @@ export interface QuoteAnchor {
 }
 export declare function captureSelectionQuote(doc: { getSelection?(): { isCollapsed?: boolean; anchorNode?: Node | null; toString(): string } | null; title?: string; location?: { href?: string }; querySelectorAll?: (selector: string) => ArrayLike<Element> }): MessageQuote | null;
 
+/** 逐行 diff 行类型(content-proposals;lineDiff 产出;skip 行由宿主渲染折叠产生,本函数不产出) */
+export interface DiffRow {
+  type: 'same' | 'add' | 'del';
+  text: string;
+}
+/** 内容提案增量操作(判别联合;字面锚点纪律:find/anchor 须在当前内容唯一命中) */
+export type ProposalOp = { op: 'replace'; find: string; with: string } | { op: 'insertAfter'; anchor: string; text: string } | { op: 'insertBefore'; anchor: string; text: string } | { op: 'append'; text: string };
+/** 逐行 diff(公共前后缀修剪 + 中段 LCS;中段超 4e6 格回退整块替换)。宿主评审面板渲染/预演用 */
+export declare function lineDiff(oldText: string, newText: string): { rows: DiffRow[]; stats: { added: number; removed: number } };
+/** 顺序应用增量 ops(原子:任一失败整批拒,错误指名第几个 op 与命中数);测试缝/预演用 */
+export declare function applyProposalOps(base: string, ops: ProposalOp[]): { ok: true; content: string } | { ok: false; error: string };
+/** 内容指纹(FNV-1a → base36;提案基底锚定用;非密码学) */
+export declare function hashContent(text: string): string;
+/** 字面锚点命中数(锚为空串按 0 计) */
+export declare function countOccurrences(haystack: string, needle: string): number;
+/** 送达评审面板的提案(content-proposals;SDK 已校验基底/应用 ops/算 diff,宿主渲染面板 + 裁决) */
+export interface ReviewableProposal {
+  id: string;
+  summary: string;
+  label?: string;
+  baseHash: string;
+  baseContent: string;
+  content: string;
+  diff: { rows: DiffRow[]; stats: { added: number; removed: number } };
+  createdAt: number;
+}
+
 export interface AgentMessage {
   role: 'user' | 'assistant' | 'system';
   content: string;
@@ -224,7 +251,9 @@ export type SdkEvent =
   | { type: 'error'; message: string; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown }
   | { type: 'context_trimmed'; dropped: { round: number; user: unknown; assistant: unknown[]; steps: unknown[] }[]; vfsResults: Record<string, string>; summary: string; reason: string }
   | { type: 'focus_chip_click'; path: string; label?: string }
-  | { type: 'focus_change'; focuses: Focus[] };
+  | { type: 'focus_change'; focuses: Focus[] }
+  | { type: 'proposal_pending'; id: string; summary: string; added: number; removed: number }
+  | { type: 'proposal_resolved'; id: string; outcome: 'applied' | 'discarded'; summary: string };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -729,6 +758,10 @@ export interface AgentInfo {
   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 };
+  /** content-proposals 反射(4.22+;配置存在才出现):pending 轻投影 + 会话累计 + 最近裁决 */
+  proposals?: { pending: Array<{ id: string; summary: string; createdAt: number; added: number; removed: number }>; applied: number; discarded: number; lastResolved: { id: string; outcome: 'applied' | 'discarded'; summary: string; detail?: string; at: number } | null };
   /** A9 收口门禁会话累计(stage → { retries 回灌, exhausted 耗尽放行 };page_assertion_gate 键存在性 = domInspect 装配反射) */
   gates?: Record<string, { retries: number; exhausted: number }>;
   /** A9 最近一次 system 段构成(段名/字节/超预算 drop 标记;集成方 augmentSystem/pageContext 段被 drop 时可观察) */
@@ -1432,6 +1465,20 @@ 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;
+  /**
+   * 内容提案-评审-应用通道(4.22+,配置即开关;不配置 = 零注册零开销):数据槽之外内容的受控修改 ——
+   * 模型零写权限,propose_content 只送提案(非阻塞),diff 评审与写回在宿主侧由用户显式完成。
+   * sdk.resolveProposal(id, 'applied'|'discarded') 裁决回传 → 事件 + 下轮结局告知
+   */
+  proposals?: ProposalsConfig;
 }
 
 /** Dialog UI config (grouped form, recommended) */
@@ -1484,6 +1531,34 @@ 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;
+}
+/** 内容提案通道配置(content-proposals,4.22+) */
+export interface ProposalsConfig {
+  /** 读通道:返回当前内容(SDK 计算 hash;null = 当前无可编辑对象,工具内如实报) */
+  read: () => Promise<{ content: string; label?: string } | null> | { content: string; label?: string } | null;
+  /** 评审回调:SDK 已完成基底校验/ops 应用/diff 计算;宿主渲染面板。返回字符串回灌模型(非阻塞:勿等待用户裁决) */
+  onProposal: (p: ReviewableProposal) => string | Promise<string>;
+  /** 提案工具名(默认 'propose_content') */
+  toolName?: string;
+  /** 读工具名(默认 'read_content') */
+  readToolName?: string;
+  /** 内容是什么(进工具 description) */
+  contentKind?: string;
+  /** 在审提案上限(默认 1:新提案替换最旧在审,留痕) */
+  maxPending?: number;
+}
 export interface I18nOptions {
   /** 语言:'zh-CN'(默认)/'en-US';切换内置文案包(聊天面 + Debug 抽屉 + Skill 面板 + 代码预览);
    *  formatTime(12h/24h)/autoTitle/默认 systemPrompt 跟随(en → 英文版身份 + "Respond in English" 锚,
@@ -1593,6 +1668,10 @@ export interface ChatSdk {
   clearQuote(): void;
   /** S2 宿主变更通知:SPA 换文/路由切换/tab 切换后调用 —— 流内页面读结果(read_page/dom_search/dom_info/get_dom/take_screenshot)置过期占位,并注入一次性「重读当前页面」提示段(下一 invoke 的 system,pin 段跨压缩,轮末清除);幂等可重复调 */
   notifyHostChange(opts?: { reason?: string }): void;
+  /** content-proposals(4.22+):宿主裁决回传 → 出队 + proposal_resolved 事件 + 下轮结局注入;false = id 未知/已裁决 */
+  resolveProposal(id: string, outcome: 'applied' | 'discarded', detail?: string): boolean;
+  /** content-proposals:只读状态投射(未配置恒 null) */
+  readonly proposals: { pending: Array<{ id: string; summary: string; createdAt: number; added: number; removed: number }>; applied: number; discarded: number; lastResolved: { id: string; outcome: 'applied' | 'discarded'; summary: string; detail?: string; at: number } | null } | null;
   /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 主数据 + vfs + todos);需开启 checkpoint,无可用返回 false */
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */