page-agent-sdk 2.18.1 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.18.1",
+  "version": "2.20.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",
@@ -52,7 +52,9 @@
     "test:types": "tsc --noEmit -p tsconfig.test.json",
     "test:size": "node tests/size-check.mjs",
     "test:browser": "playwright test",
-    "test:browser:ui": "playwright test --ui"
+    "test:browser:ui": "playwright test --ui",
+    "test:draft-real": "tsx tests/runtime/draft-real-llm.ts",
+    "test:trace-real": "tsx tests/runtime/trace-real-llm.ts"
   },
   "keywords": [
     "ai",

package/types/index.d.ts

@@ -75,7 +75,8 @@ 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; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown };
+  | { type: 'error'; message: string; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown }
+  | { type: 'trace'; spans: TraceSpan[]; metrics: TraceMetrics };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -83,6 +84,26 @@ export interface TokenUsage {
   completion_tokens?: number;
   total_tokens?: number;
 }
+/** 批处理单任务结果(sdk.batch 返回;ok=true 含 reply,ok=false 含 error) */
+export interface BatchResult {
+  /** 任务在入参数组中的下标 */
+  index: number;
+  /** 任务文本 */
+  task: string;
+  /** 成功时的 agent 回复 */
+  reply?: string;
+  /** 失败时的错误信息 */
+  error?: string;
+  /** 是否成功 */
+  ok: boolean;
+}
+/** 批处理进度回调 payload(sdk.batch 的 onProgress 每任务完成调一次) */
+export interface BatchProgress {
+  done: number;
+  total: number;
+  task: string;
+  ok: boolean;
+}
 
 export type SdkEventHandler = (event: SdkEvent) => void;
 
@@ -158,6 +179,8 @@ export interface AgentInfo {
   };
   /** 会话级 checkpoint 装载状态(未开启 → undefined) */
   checkpoints?: { enabled: boolean; auto: boolean; list: CheckpointMeta[] };
+  /** 结构化追踪(revive-observability-tracing;capabilities.tracing 开时填充,否则 undefined) */
+  trace?: { spans: TraceSpan[]; metrics: TraceMetrics };
 }
 export interface McpServerConfig { transport: 'http' | 'sse' | 'websocket'; url: string; name?: string; requestInit?: any; }
 
@@ -313,11 +336,21 @@ export interface CheckpointMeta {
   timestamp: number;
   messageCount: number;
 }
+export interface Checkpoint extends CheckpointMeta {
+  messages: AgentMessage[];
+  windowVals: Record<string, unknown>;
+  vfs: Record<string, { content: string; mimeType?: string; updatedAt: number }>;
+  todos: { id: string; content: string; status: 'pending' | 'in_progress' | 'completed' }[];
+}
 export interface CheckpointManager {
   save(label?: string): number;
   list(): CheckpointMeta[];
   restore(id?: number): boolean;
   canRestore(): boolean;
+  /** 导出栈快照(深拷贝,可序列化;供 automation 断点续跑持久化,刷新/崩溃后恢复 restoreLastCheckpoint 能力) */
+  exportStack(): Checkpoint[];
+  /** 灌入栈快照(刷新/崩溃恢复时重建 checkpoint 栈;重置 nextId 防后续 save id 冲突) */
+  importStack(cps: unknown[]): void;
 }
 export declare function createCheckpointManager(deps: any): CheckpointManager;
 export declare function createCheckpointMiddleware(mgr: CheckpointManager): any;
@@ -355,6 +388,10 @@ export interface SessionSnapshot {
   vfs: Record<string, { content: string; mimeType?: string; updatedAt: number }>;
   todos: { id: string; content: string; status: 'pending' | 'in_progress' | 'completed' }[];
   memory: string;
+  /** automation 断点续跑:checkpoint 栈快照(刷新/崩溃后恢复 restoreLastCheckpoint 能力);仅 capabilities.automation 开启时写入 */
+  checkpoints?: unknown[];
+  /** automation 断点续跑:累计 token usage(刷新后续跑预算统计连续) */
+  usage?: TokenUsage;
 }
 export type StorageEvent =
   | { type: 'degraded'; reason: string }
@@ -470,6 +507,12 @@ export interface ChatSdkOptions {
   maxPlanRevisions?: number;
   /** 模型调用失败自动重试次数(默认 2;网络/429/5xx 重试,4xx 与 abort 不重试) */
   maxRetries?: number;
+  /** token 预算上限(累计 total_tokens 超过 → 停止 agent + emit BUDGET_EXCEEDED;需 capabilities.automation:true) */
+  tokenBudget?: number;
+  /** 时间预算 ms(从 agent 开始计时,超过 → 停止;需 capabilities.automation:true) */
+  timeBudgetMs?: number;
+  /** 无人值守错误恢复:致命错误(invoke 抛错)自动 restore_last_checkpoint + 重试次数(默认 1;防单点错误永久中断批量/长任务)。需 capabilities.automation:true */
+  maxAutoRetries?: number;
   /** 同轮工具并发上限(默认 1 串行) */
   maxParallelTools?: number;
   /** 模型上下文窗口(token);顶层声明对 llm 实例场景也生效,缺省按 model 名查表。影响 offload 阈值与压缩触发 */
@@ -477,7 +520,7 @@ export interface ChatSdkOptions {
   /** 模型最大输出(token);顶层声明对 llm 实例场景也生效,缺省按 model 名查表 */
   maxOutputTokens?: number;
   /** 子 agent 委派(默认开启;{ enabled: false } 关闭) */
-  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; missionAnchor?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean; domInspect?: boolean; workingMemory?: boolean };
+  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; missionAnchor?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean; domInspect?: boolean; inspectEnv?: boolean; draftWrite?: boolean; tracing?: boolean; todoDeps?: boolean; automation?: boolean; workingMemory?: boolean };
   subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number };
   /** 预声明子 agent 列表:每个用同主配置方式声明,自动生成 use_<id> 委派工具(与 spawn_agent 共存) */
   subagents?: SubagentConfig[];
@@ -568,6 +611,12 @@ export interface ChatSdk {
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */
   listCheckpoints(): CheckpointMeta[];
+  /**
+   * 批处理(automation):逐任务跑 agent,每任务前自动 checkpoint,任务间错误隔离(单任务失败记 error 不中断整批)。
+   * 适合无人值守批量操作(批量生成/改一批页面)。不经 UI 排队(直接 invoke);返回每个任务结果(成功 reply / 失败 error)。
+   * 配合 capabilities.automation + checkpoint 使用。
+   */
+  batch(tasks: string[], onProgress?: (p: BatchProgress) => void): Promise<BatchResult[]>;
   /** 运行时订阅 SDK 事件(可多个监听器,返回取消函数);与构造时 onEvent 互补 */
   hook(handler: SdkEventHandler): () => void;
   /** 运行时替换主数据配置(如页面切换、schema 变更);立即对数据工具生效,无需重建 agent。需开启 dataOps */
@@ -669,6 +718,36 @@ export declare function defineTool(opts: {
 }): any;
 export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
 export declare function filterByToolMode(tools: any[], mode?: 'simple' | 'advanced' | 'minimal'): any[];
+/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。set_data / write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
+export declare function commitSetToBind(args: { bindRef: unknown; value: unknown; schema: any; allowKeys: string[] | null; snapshots: any[]; maxSnapshots: number; audit: (e: any) => void; dryRun?: boolean; op?: 'set' | 'draft_commit' }): { ok: true; hash: string; data: unknown } | { ok: false; error: string };
+/** 结构化追踪 span(revive-observability-tracing Phase 3) */
+export type SpanType = 'round' | 'model' | 'tool' | 'compression';
+export type SpanStatus = 'ok' | 'error' | 'timeout';
+export interface TraceSpan {
+  id: string;
+  parentId?: string;
+  name: string;
+  type: SpanType;
+  startTs: number;
+  endTs?: number;
+  durationMs?: number;
+  status: SpanStatus;
+  attributes: Record<string, unknown>;
+}
+export interface TraceMetrics {
+  rounds: number;
+  totalDurationMs: number;
+  avgRoundMs: number;
+  toolCalls: number;
+  toolFailures: number;
+  toolSuccessRate: number;
+  modelCalls: number;
+  retries: number;
+  compressions: number;
+  totalTokens?: { prompt: number; completion: number; total: number };
+}
+/** 从 TraceSpan[] 聚合 metrics(纯函数:轮次/延迟/工具成功率/重试/压缩/token) */
+export declare function getTraceMetrics(spans: TraceSpan[]): TraceMetrics;
 // ============ 通用 JSON 操作纯函数(jsonUtils,refactor-module-extraction 从 dataOps 抽离;零依赖,经 ./query subpath 按需引入)============
 export type EditOp = 'set' | 'remove' | 'merge' | 'append';
 export declare const UNSAFE_KEYS: Set<string>;
@@ -753,12 +832,20 @@ export interface SdkEvents {
   hook(handler: (e: any) => void): () => void;
 }
 export declare function createSdkEvents(onEvent?: (e: any) => void): SdkEvents;
-export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean; domInspect?: boolean } | undefined, dataOps: any[], fetchDocs: any[], dom?: any[]): any[];
+export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean; domInspect?: boolean; inspectEnv?: boolean } | undefined, dataOps: any[], fetchDocs: any[], dom?: any[], inspect?: any[]): any[];
 export declare function createUsageHintsMiddleware(caps: { planning?: boolean; dataOps?: boolean; subagent?: boolean } | undefined, hasDataOps: boolean, toolMode?: 'simple' | 'advanced' | 'minimal'): any;
 export declare const fetchDocTools: any[];
 /** DOM 读取工具 get_dom(随 capabilities.domInspect 装配,opt-in) */
 export declare const domTools: any[];
 export declare const domToolsStatic: any[];
+/** 环境探查工具 inspect_env(随 capabilities.inspectEnv 默认装配,默认开;排查 window/location/调试变量) */
+export declare const inspectTools: any[];
+/** 单个 inspect_env 工具(inspectTools 数组的元素) */
+export declare const inspectEnvTool: any;
+/** 纯函数:安全序列化任意值(跳过 function/DOM,防循环引用,截断)—— inspect_env 读 window[key] 时用 */
+export declare function safeSerialize(value: unknown, depth?: number, maxLen?: number, seen?: WeakSet<object>): unknown;
+/** 环境摘要(location/navigator/viewport/document);inspect_env 无参时返回,可传 win 注入测试 */
+export declare function getEnvSummary(win?: Window & typeof globalThis): Record<string, unknown>;
 export declare const getDomTool: any;
 /** 纯函数:DOM Element → 结构化 DomNode(可单测,与浏览器解耦) */
 export declare function domToStructure(node: Element | null, opts: { depth: number; attrs?: string[]; includeText?: boolean }): DomNode | null;