page-agent-sdk 2.18.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.18.0",
+  "version": "2.19.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 {
@@ -158,6 +159,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; }
 
@@ -477,7 +480,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; 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[];
@@ -669,6 +672,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 +786,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;