page-agent-sdk 4.26.1 → 4.27.0

package/package.json

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

@@ -249,7 +249,8 @@ export type SdkEvent =
   | { type: 'focus_chip_click'; path: string; label?: string }
   | { 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 };
+  | { type: 'proposal_resolved'; id: string; outcome: 'applied' | 'discarded'; summary: string }
+  | { type: 'action_resolved'; name: string; outcome: 'applied' | 'discarded'; detail?: string };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -983,6 +984,8 @@ export interface ActionDef {
   run: (args: Record<string, unknown>) => unknown | Promise<unknown>;
   /** 可选参数 schema(ZodObject);不传 = 无参 tool */
   params?: any;
+  /** params 的别名:与 defineTool 的 schema 同名同义(消除两入口命名分叉);两者同给时 params 优先 */
+  schema?: any;
   /** 标记本 action 读取宿主态(4.20+):旧工具结果随 `sdk.notifyHostChange()` 替换为过期占位(修前仅 read_page 等五个内置页面读工具享受,action 仅靠 reason 文案口头告知);页面断言门禁的「页面依据」计数也计入。不标记 = 现行为零变化 */
   readsHostState?: boolean;
   /** 标记本 action 的效果延迟到用户确认才生效(提案类,4.20+):调用成功 ≠ 已写入 → 零工具门禁事实清单对此类调用注记「待用户确认后才生效」,防模型收口「已修改完成」;等效写计数不含此类。不标记 = 现行为零变化 */
@@ -1280,6 +1283,10 @@ export interface ChatSdk {
   revokeApprovalGrants(): void;
   /** content-proposals(4.22+):宿主裁决回传 → 出队 + proposal_resolved 事件 + 下轮结局注入;false = id 未知/已裁决 */
   resolveProposal(id: string, outcome: 'applied' | 'discarded', detail?: string): boolean;
+  /** deferredWrite 动作裁决回传(action-resolve-outcome):结局入队 → 下一轮一次性系统段 + action_resolved 事件 + debugLogs(action_resolved)。
+   *  名字键:同名字不同结局 = 新裁决覆盖旧笔;相同结局重报 / 未标记 deferredWrite / 未知名 → false(幂等)。
+   *  detail 自由文本随行(如「3 条候选:采纳 2」);裁决到达不打断在途轮;未送达的裁决随 switchSession/resetSession 清空 */
+  resolveAction(name: 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 */

package/types/index.d.ts

@@ -253,7 +253,8 @@ export type SdkEvent =
   | { type: 'focus_chip_click'; path: string; label?: string }
   | { 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 };
+  | { type: 'proposal_resolved'; id: string; outcome: 'applied' | 'discarded'; summary: string }
+  | { type: 'action_resolved'; name: string; outcome: 'applied' | 'discarded'; detail?: string };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -1353,6 +1354,8 @@ export interface ActionDef {
   run: (args: Record<string, unknown>) => unknown | Promise<unknown>;
   /** 可选参数 schema(ZodObject);不传 = 无参 tool */
   params?: any;
+  /** params 的别名:与 defineTool 的 schema 同名同义(消除两入口命名分叉);两者同给时 params 优先 */
+  schema?: any;
   /** 标记本 action 读取宿主态(4.20+):旧工具结果随 `sdk.notifyHostChange()` 替换为过期占位(修前仅 read_page 等五个内置页面读工具享受,action 仅靠 reason 文案口头告知);页面断言门禁的「页面依据」计数也计入。不标记 = 现行为零变化 */
   readsHostState?: boolean;
   /** 标记本 action 的效果延迟到用户确认才生效(提案类,4.20+):调用成功 ≠ 已写入 → 零工具门禁事实清单对此类调用注记「待用户确认后才生效」,防模型收口「已修改完成」;等效写计数不含此类。不标记 = 现行为零变化 */
@@ -1706,6 +1709,10 @@ export interface ChatSdk {
   revokeApprovalGrants(): void;
   /** content-proposals(4.22+):宿主裁决回传 → 出队 + proposal_resolved 事件 + 下轮结局注入;false = id 未知/已裁决 */
   resolveProposal(id: string, outcome: 'applied' | 'discarded', detail?: string): boolean;
+  /** deferredWrite 动作裁决回传(action-resolve-outcome):结局入队 → 下一轮一次性系统段 + action_resolved 事件 + debugLogs(action_resolved)。
+   *  名字键:同名字不同结局 = 新裁决覆盖旧笔;相同结局重报 / 未标记 deferredWrite / 未知名 → false(幂等)。
+   *  detail 自由文本随行(如「3 条候选:采纳 2」);裁决到达不打断在途轮;未送达的裁决随 switchSession/resetSession 清空 */
+  resolveAction(name: 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 */