page-agent-sdk 3.47.0 → 4.1.0

package/types/index.d.ts

@@ -158,7 +158,6 @@ export type SdkEvent =
   | { 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: 'trace'; spans: TraceSpan[]; metrics: TraceMetrics }
   | { 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[] };
@@ -405,11 +404,6 @@ export interface DialogMessages {
   debugStepsBtn: string
   debugStepsCountSuffix: string      // 步 / steps(n 在前)
   debugTraceEmpty: string
-  debugMetricRounds: string
-  debugMetricTotal: string
-  debugMetricAvg: string
-  debugMetricTools: string
-  debugMetricCompressions: string
   debugCtxEmpty: string
   debugCtxOccupancy: string          // 占用 / Occupancy(title)
   debugCtxThreshold: string          // 压缩阈值 / compress threshold
@@ -451,13 +445,6 @@ export interface DialogMessages {
   debugSameAsMain: string            // (同主) / (same as main)
   debugTodosTitle: string
   debugMemoryTitle: string
-  debugPrefsTitle: string             // 用户偏好 / User preferences(preferences opt-in 小节标题)
-  debugPrefTopicColor: string         // 偏好 topic 标签:颜色 / color
-  debugPrefTopicCopy: string          // 文案 / copy
-  debugPrefTopicLayout: string        // 排版 / layout
-  debugPrefTopicInteraction: string   // 交互 / interaction
-  debugPrefTopicTech: string          // 技术 / tech
-  debugPrefTopicOther: string         // 其他 / other
   debugLastCompTitle: string
   debugTriggered: string
   debugNotTriggered: string          // ✗(未达阈值) / ✗ (below threshold)
@@ -602,6 +589,8 @@ export interface SubagentInfo {
   enabled: boolean;
   maxDepth: number;
   maxParallel: number;
+  /** 单次委派总时长毫秒(flow-robustness P1#4 反射:undefined → 默认 600000;0 = 关) */
+  timeoutMs: number;
   allowedTools: string[];
   /** 预声明子 agent 列表(动态:反映 setSubagents/addSubagent/removeSubagent 后的最新) */
   subagents?: { id: string; description: string }[];
@@ -662,8 +651,6 @@ export interface AgentInfo {
   mission?: Mission;
   /** 方案确认留痕(save-and-plan-gates 3c:RHC 带 options 的方案被点选;undefined=本会话无已确认方案) */
   planConfirmation?: PlanConfirmationRecord;
-  /** 跨会话用户偏好(preferences 中间件;updatedAt 新在前;capabilities.preferences:false → undefined) */
-  preferences?: PersistedPreference[];
   /** 宿主动作元信息(actions 注册;集成方 save_draft/publish 等) */
   actions?: Record<string, { description: string; hasParams: boolean }>;
   /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
@@ -685,8 +672,6 @@ export interface AgentInfo {
   };
   /** 会话级 checkpoint 装载状态(未开启 → undefined) */
   checkpoints?: { enabled: boolean; auto: boolean; list: CheckpointMeta[] };
-  /** 结构化追踪(revive-observability-tracing;capabilities.tracing 开时填充,否则 undefined) */
-  trace?: { spans: TraceSpan[]; metrics: TraceMetrics };
   /** 上下文构成快照(context-inspector;每轮 wrapModelCall 覆盖;capabilities.contextInspector:false → undefined) */
   context?: ContextSnapshot;
 }
@@ -870,6 +855,10 @@ export interface DataOpsOptions {
   onConflict?: (conflict: ConflictInfo) => Promise<ConflictResolution>;
   /** 冲突监听字段白名单(任意深度字段名):声明后仅这些字段的值变动触发自动冲突检测(位置不敏感);未声明 = 不开自动检测(仅显式 expectedHash 校验);['*'] = 全字段检测(旧 autoLock 行为) */
   conflictWatchFields?: string[];
+  /**
+   * 同轮工具并发上限(createAgent 透传):>1 且 conflictWatchFields 武装时启用 dataOps 闭包级并发写互锁(async mutex,单锁 bind 域)—— 同轮并发双写不再「双双过旧基线、后者静默覆盖前者」;串行/未武装直通 no-op 零行为变化
+   */
+  maxParallelTools?: number;
 }
 
 /** 数据操作控制器(运行时替换配置;createDataOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
@@ -935,11 +924,11 @@ export interface SkillRefSpec {
   doc?: string;
   getContent?: () => string | Promise<string>;
 }
-/** skill 执行钩子:code(内联 JS)/url(远程,仅 sandbox)二选一;context 默认 sandbox,host 需 skillHostScript */
+/** skill 执行钩子:code(内联 JS)/url(远程,仅 sandbox)二选一;context 默认 sandbox(host 已随 4.1.0 移除,残值落 sandbox 执行) */
 export interface SkillExecSpec {
   code?: string;
   url?: string;
-  context?: 'sandbox' | 'host';
+  context?: 'sandbox';
   inject?: 'append' | 'prepend';
 }
 /** skill 附带工具工厂(返回单个/数组工具,可异步;ctx.signal 运行时中止信号) */
@@ -950,6 +939,8 @@ export type SkillToolFactory = () => any | any[] | Promise<any | any[]>;
 export interface VerifyCheckContext {
   messages: any[];
   state: any;
+  /** 结构化日志(debugLogs;render-check 类环境降级留痕用,可缺省) */
+  log?: (type: string, data: unknown) => void;
 }
 export interface VerifyCheckResult {
   ok: boolean;
@@ -984,8 +975,10 @@ export interface ApprovalOptions {
   tools?: string[];
   /** 自定义判定(优先于 tools);返回 true 需确认 */
   confirm?: (name: string, args: any) => boolean;
-  /** 超时毫秒(用户未响应自动拒绝);0 = 不超时(默认) */
+  /** 超时毫秒(无响应自动拒绝);SDK 装配层默认 30000(响应方调事件的 hold() 接管后不限时);显式 Infinity/负数 = 不超时 */
   timeoutMs?: number;
+  /** 超时自动拒的留痕回调(abort/用户先收口不触发) */
+  onAutoReject?: (info: { toolName: string; waitedMs: number }) => void;
   /** 是否装载 request_human_confirmation 主动确认工具(传 approval 时默认 true;false 关闭) */
   humanConfirmTool?: boolean;
 }
@@ -998,14 +991,14 @@ export interface PlanConfirmationRecord {
   choice: string;
   viaOptions: true;
 }
-export declare function createHumanConfirmMiddleware(onResolved?: (record: PlanConfirmationRecord) => void): any;
-export declare const HUMAN_CONFIRM_TOOL_NAME: string;
-/** 大批量变更门禁(bulk-change-guard):量纲 = 现有组件节点数;默认关,须配 approval 才装配 */
-export interface BulkGuardOptions {
-  threshold?: number;
+/** humanConfirm 中间件可选项:timeoutMs 无响应自动拒(超时视同拒绝);onAutoReject 超时留痕回调 */
+export interface HumanConfirmOptions {
   timeoutMs?: number;
-  mode?: 'confirm' | 'observe';
+  onAutoReject?: (info: { toolName: string; waitedMs: number }) => void;
 }
+export declare function createHumanConfirmMiddleware(onResolved?: (record: PlanConfirmationRecord) => void, opts?: HumanConfirmOptions): any;
+export declare const HUMAN_CONFIRM_TOOL_NAME: string;
+/** 写触达量纲结果(原 bulk-change-guard 量纲;bulkGuard 已于 4.1.0 移除,函数为 delegateNudge 依赖保留) */
 export interface WriteScaleResult {
   count: number;
   scopes: string[];
@@ -1013,19 +1006,6 @@ export interface WriteScaleResult {
 }
 /** 度量单次写调用触达的现有组件节点数(纯函数:同组件多 patch=1;新增路径不计) */
 export declare function measureWriteScale(args: unknown, getBind: () => unknown): WriteScaleResult;
-/** 中间件工厂参数(getBind/tools/getPlanConfirmation/onEvent;挂起经 ctx.emit approval_request) */
-export interface BulkGuardMiddlewareOptions extends BulkGuardOptions {
-  getBind: () => unknown;
-  tools?: unknown[];
-  getPlanConfirmation?: () => { at: number; summary: string } | undefined;
-  onEvent?: (info: { stage: 'bulk_guard'; decision: 'confirm' | 'observe' | 'exempt-plan' | 'exempt-once' | 'pass' | 'timeout' | 'rejected'; kind: string; count: number }) => void;
-}
-/** 会话级豁免态(每形态确认过一次本会话放行;reset 钩子接 switch/resetSession) */
-export interface BulkGuardState {
-  confirmedKinds: Set<string>;
-  reset(): void;
-}
-export declare function createBulkGuardMiddleware(opts: BulkGuardMiddlewareOptions): any;
 export interface CheckpointMeta {
   id: number;
   label?: string;
@@ -1061,6 +1041,8 @@ export interface StorageConfig {
   maxBytesPerSession?: number;
   evictionWatermark?: number;
   debounceMs?: number;
+  /** flush 单项落盘超时 ms(默认 5000):IDB 事务卡死不拖死 flush 调用方,超时项留待后续 flush/pagehide 重试 */
+  flushTimeoutMs?: number;
 }
 /** Skill 独立持久化存储配置(与 storage 选项分离) */
 export interface SkillStoreConfig {
@@ -1071,29 +1053,6 @@ export interface SkillStoreConfig {
   /** DB 命名空间,默认 'chat-sdk'(与 SessionStore 同库,不同 key 前缀) */
   dbName?: string;
 }
-/** 偏好主题枚举(合并键):同 topic 后说覆盖前说 */
-export type PreferenceTopic = 'color' | 'copy' | 'layout' | 'interaction' | 'tech' | 'other';
-/** 持久化的单条用户偏好(captured/提炼后的一句话中性陈述) */
-export interface PersistedPreference {
-  id: string;
-  content: string;
-  topic: PreferenceTopic;
-  sourceSessionId: string;
-  sourceRound: number;
-  createdAt: number;
-  updatedAt: number;
-}
-/** 用户偏好跨会话记忆的独立持久化存储配置(preference-persistence;需 capabilities.preferences:true) */
-export interface PreferenceStoreConfig {
-  /** 存储 id(命名空间);同 id 跨页面/跨 agent 共享,不传按 agentId 隔离 */
-  id?: string;
-  /** 后端类型,默认 'indexed';'local' / 'session' / 'memory' */
-  backend?: StorageBackendType;
-  /** DB 命名空间,默认 'chat-sdk' */
-  dbName?: string;
-  /** FIFO 条目上限(默认 20;超限按 updatedAt 删最旧) */
-  maxEntries?: number;
-}
 export interface SessionMeta {
   agentId: string;
   sessionId: string;
@@ -1202,8 +1161,6 @@ export interface ChatSdkOptions {
   skills?: SkillSpec[];
   /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
   skillStorage?: SkillStoreConfig | false;
-  /** 用户偏好跨会话记忆的独立持久化存储(需 `capabilities.preferences:true`);默认 indexedDB;maxEntries FIFO 上限(默认 20);false 不持久化(仅页面生命周期内有效) */
-  preferenceStorage?: PreferenceStoreConfig | false;
   /** AGENTS.md 风格持久指令。支持 string 与同步/异步函数(异步函数适合加载 RAG 文档) */
   memory?: string | (() => string | Promise<string>);
   data?: DataConfig;
@@ -1234,6 +1191,10 @@ export interface ChatSdkOptions {
   streamStallMs?: number;
   /** 单次模型调用流总时长上限:防空转帧黑洞(keepalive 空转不断喂饱间隔看门狗,超限 → StreamMaxDurationError,重委派/重发即自愈)。默认 600s;0 = 关闭 */
   streamMaxDurationMs?: number;
+  /**
+   * per-tool 看门狗:单工具执行超此 ms → 放弃等待,recoverable 错误结果回灌自纠(防集成方工具永不 settle 拖死整轮:loading 永转 + stop 无效)。只对集成方注入工具生效(defineTool / actions / skill 工具工厂 / rag retriever);内置/MCP/委派与 conflict ask 挂起是设计内等待,豁免。默认 120s;0 = 关闭
+   */
+  toolTimeoutMs?: number;
   /** token 预算上限(累计 total_tokens 超过 → 停止 agent + emit BUDGET_EXCEEDED;需 capabilities.automation:true) */
   tokenBudget?: number;
   /** 单次 invoke 的 token 预算上限(opt-in,默认关):本次 agent 调用累计 total_tokens 超限 → 中断收口(observable emit + 友好文本,已完成部分保留);与 automation 全局 tokenBudget 正交 */
@@ -1253,16 +1214,14 @@ export interface ChatSdkOptions {
   /** 图片输入配置组(image-input-vision):images.upload 上传换 URL(集成方 OSS)/ images.describe 绑定识图转述(集成方识图子 agent / 自有 vision API,非多模态主模型时转述注入) */
   images?: ImagesConfig;
   /** 子 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; inspectEnv?: boolean; draftWrite?: boolean; tracing?: boolean; automation?: boolean; workingMemory?: boolean; focus?: boolean; skillHostScript?: boolean; contextInspector?: boolean; agentCompression?: boolean; preferences?: boolean; bulkGuard?: boolean };
-  subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number; timeoutMs?: number; thinkingMode?: 'simple' | 'deep' };
+  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; automation?: boolean; workingMemory?: boolean; focus?: boolean; contextInspector?: boolean; agentCompression?: boolean };/** tracing/skillHostScript/preferences/bulkGuard 已于 4.1.0 移除;残键静默忽略 */
+  subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number; /** 单次委派总时长毫秒(默认 600000=10min;超时 abort 子流 + recoverable 回灌;0 = 不限制) */ timeoutMs?: number; thinkingMode?: 'simple' | 'deep' };
   /** 预声明子 agent 列表:每个用同主配置方式声明,自动生成 use_<id> 委派工具(与 spawn_agent 共存) */
   subagents?: SubagentConfig[];
   /** 自检:agent 返回前跑 check,不通过则 feedback 回灌自纠(默认关闭)。传 check/maxAttempts/adversarial 任一即自动开启(无需再配 capabilities.verify:true;显式 false 或 enabled:false 可关)。check 省略时默认 createWriteBackCheck 写后读回验证 */
   verify?: { enabled?: boolean; check?: VerifyCheck; maxAttempts?: number; adversarial?: boolean };
   /** 人工确认:工具调用前弹确认框,用户「允许/拒绝」后才执行(默认关闭,不传 = 不装) */
   approval?: ApprovalOptions;
-  /** 大批量变更门禁(默认关;capabilities.bulkGuard:true 开启,须同时配置 approval 否则 no-op)。量纲 = 现有组件节点数(同组件多 patch 不拦,新增内容不计);超阈挂 approval(自带 timeoutMs 超时自动拒);mode:'observe' 无人值守只留痕 */
-  bulkGuard?: { threshold?: number; timeoutMs?: number; mode?: 'confirm' | 'observe' };
   /** 主动征询(默认开启):装载 request_human_confirmation 工具,LLM 在不确定/多方案/高风险时主动征询;false 关闭(types-alignment 补漏) */
   humanConfirm?: boolean;
   /** 会话级 checkpoint 回滚(回到上次正常时)。默认关闭;传 true 或 { maxCheckpoints?, auto? } 开启 */
@@ -1411,12 +1370,6 @@ export interface ChatSdk {
   getMission(): Mission | undefined;
   /** 显式设置/覆盖 mission(传 {goal} 重设;传 {goal,criteria} 整体替换;传 {} 清空);capabilities 关时 warn 不抛 */
   setMission(mission: Partial<Mission>): void;
-  /** 读取跨会话用户偏好快照(updatedAt 新在前;capabilities.preferences:false → 恒 []) */
-  getPreferences(): PersistedPreference[];
-  /** 删除单条跨会话偏好(by id;学错可删);capabilities 关 → false */
-  removePreference(id: string): Promise<boolean>;
-  /** 清空全部跨会话偏好(存储 + 注入段同清);capabilities 关 → no-op */
-  clearPreferences(): Promise<void>;
   /** 读取当前聚焦焦点(兼容:返回首个;未聚焦 / capabilities.focus:false → undefined) */
   getFocus(): Focus | undefined;
   /** 读取全部聚焦焦点(multi-focus;空数组=未聚焦;capabilities.focus:false → []) */
@@ -1569,7 +1522,7 @@ export declare function defineTool(opts: {
   writeCapable?: boolean | ((args: Record<string, unknown>) => boolean);
 }): any;
 export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
-/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。set_data / write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
+/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。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'; snapshotLabel?: string }): { ok: true; hash: string; data: unknown; notices: string[] } | { ok: false; error: string };
 /** path-scoped-validation:增量 patch 逐目标局部校验(全部 apply 后按最终态;兄弟脏数据不株连)。返回写回计划 */
 export interface LocalWriteBack {
@@ -1590,36 +1543,8 @@ export interface LocalValidationPlan {
 export declare function validateRootValueLocally(args: { schema: any; allowKeys: string[] | null; value: unknown; bindRef: unknown }): { ok: true; assembly: unknown; wholeParsed: Record<string, unknown> | null; notices: string[] } | { ok: false; error: string; notices: string[] };
 /** 增量 patch 逐目标局部校验纯函数(appendCaptures/moveCaptures 由 apply 循环捕获;valueAt 为位移兜底) */
 export declare function validateWriteLocally(args: { schema: any; bindRef: unknown; clone: unknown; patches: { op?: string; jsonPath?: string; value?: unknown }[]; schemaErrorMode?: 'zod' | 'schema_invalid'; appendCaptures: { jp: string; elems: unknown[] }[]; moveCaptures: { jp: string; toPath: string; elem: unknown }[]; valueAt?: (jp: string) => unknown }): LocalValidationPlan;
-/** 增量 patch 写入纯函数(clone + 局部校验 + 快照 + 外科手术式写回);edit_data / write(edit) / eval 共用 */
+/** 增量 patch 写入纯函数(clone + 局部校验 + 快照 + 外科手术式写回);write(edit) / eval 共用 */
 export declare function applyPatchesToBind(args: { bindRef: unknown; patches: { op?: string; jsonPath?: string; value?: unknown }[]; schema: any; allowKeys: string[] | null; snapshots: any[]; maxSnapshots: number; markDataDirty?: () => void; schemaErrorMode?: 'zod' | 'schema_invalid'; snapshotLabel?: string; dryRun?: boolean; internalAfterWrite?: (bind: any, before: any) => void; protectedCtx?: unknown }): { ok: true; applied: { op: string; jp: string; value: unknown }[]; clone: unknown; notices: string[] } | { 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' | 'move';
 export declare const UNSAFE_KEYS: Set<string>;
@@ -1764,7 +1689,6 @@ export type CapabilityFlags = Partial<Record<string, boolean>>;
 export type ResolvedCapabilities = Record<string, boolean>;
 export declare const CAPABILITIES: readonly Capability[];
 /** 已列入移除计划的配置键(config-surface-pruning;维护者确认外部零使用,warn 一版后移除)。键 = capabilities 键名,值 = 迁移指引 */
-export declare const DEPRECATED_CAPABILITIES: Readonly<Record<string, string>>;
 /** 单一解析:集成方原始 caps(Partial)→ 全量 boolean(opt-out 默认开 !==false / opt-in 默认关 ===true;requires 依赖未满足强制关)。参数宽松 Record<string,unknown>(兼容含 subagents 等非 boolean 字段的 caps 对象;只读已知 capability 的 boolean) */
 export declare function resolveCapabilities(caps?: Record<string, unknown>): ResolvedCapabilities;
 export declare function resolveStorage(storage: any): any | null;
@@ -1877,41 +1801,6 @@ export declare function createWebStorageBackend(storage: Storage): StorageBacken
 export declare function isQuotaError(err: unknown): boolean;
 /** 创建 Skill 独立持久化存储(与 storage 选项分离;默认 indexedDB,可手动指定 id 跨页复用) */
 export declare function createSkillStore(config?: SkillStoreConfig): SkillStore;
-// ============ 用户偏好跨会话记忆(preference-persistence;capabilities.preferences opt-in)============
-/** FIFO 条目上限默认值(20) */
-export declare const DEFAULT_MAX_PREFERENCES: number;
-/** 创建偏好独立存储(与 storage/skillStorage 同构;同 topic 后说覆盖,FIFO 超限删最旧) */
-export declare function createPreferenceStore(config?: PreferenceStoreConfig): PreferenceStore;
-export interface PreferenceStore {
-  ready: Promise<boolean>;
-  list(): Promise<PersistedPreference[]>;
-  put(pref: Omit<PersistedPreference, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }): Promise<PersistedPreference>;
-  remove(id: string): Promise<boolean>;
-  clear(): Promise<void>;
-  dispose(): void;
-}
-/** 偏好捕获中间件选项 */
-export interface PreferencesMiddlewareOptions {
-  store: PreferenceStore;
-  /** 小 LLM 通道(如 summaryLlmInvoke);缺省 → 只强信号生效(降级) */
-  llmInvoke?: (prompt: string) => Promise<string>;
-  /** 当前会话 id getter(记入条目溯源) */
-  getSessionId: () => string;
-  /** debug 留痕回调 */
-  onDebug?: (data: Record<string, unknown>) => void;
-}
-/** 偏好捕获中间件(afterAgent 收口捕获 + augmentPrompt pin 段注入) */
-export declare function createPreferencesMiddleware(opts: PreferencesMiddlewareOptions): any;
-/** 强信号提取:显式命令句式(「记住:」等)命中 → {content, topic};未命中 → undefined(零 LLM) */
-export declare function extractExplicitPreference(text: string): { content: string; topic: PreferenceTopic } | undefined;
-/** 中信号初筛:模式词命中(松筛,真伪由 LLM 提炼判定) */
-export declare function looksLikePreferenceSignal(text: string): boolean;
-/** 解析提炼 LLM 输出(容错剥围栏;captured 非 true / 非法 → undefined,宁漏勿误) */
-export declare function parsePreferenceJson(raw: string): { content: string; topic: PreferenceTopic } | undefined;
-/** 提炼 prompt(中信号;输出 JSON) */
-export declare function buildExtractPrompt(text: string): string;
-/** 注入 pin 段(cache 快照 → markdown;空 → undefined) */
-export declare function buildPreferencePrompt(prefs: PersistedPreference[]): string | undefined;
 export interface SkillStore {
   ready: Promise<boolean>;
   list(): Promise<PersistedSkill[]>;
@@ -1927,14 +1816,13 @@ export interface PersistedSkill {
   description: string;
   content: string;
 }
-
 // ============ 大 JSON 查询/搜索/沙箱脚本(dataSlotQuery)============
 export interface JpNode {
   /** 相对属性根的点号路径(数组索引用数字,如 components.0.text) */
   path: string;
   /** 匹配元素值 */
   value: unknown;
-  /** 父为数组时的索引(便于后续 edit_data_slot 的 jsonPath 定位) */
+  /** 父为数组时的索引(便于后续 write patch 的 jsonPath 定位) */
   index?: number;
 }
 export interface SearchHit {
@@ -1973,8 +1861,6 @@ export interface SandboxResult {
  * 无 input 传 undefined(skill exec);有 input 作 data 入参(eval_script)。
  */
 export declare function createSandboxRunner(script: string, timeoutMs?: number): (input?: unknown) => Promise<SandboxResult>;
-/** 宿主脚本执行(skill exec context:'host';AsyncFunction 主线程全权,不经静态扫描,需 capabilities.skillHostScript:true) */
-export declare function runHostScript(code: string, timeoutMs?: number): Promise<SandboxResult>;
 
 // ============ 工具报错(结构化 ERROR:{json},供 LLM 排查)============
 export interface ToolErrorInput {
@@ -2126,6 +2012,76 @@ export interface HtmlFormatCheckOptions {
 }
 /** HTML 格式 verify check(beforeReturn 门禁):扫 state.files 代码文件,不通过回灌 feedback 自纠 */
 export declare function createHtmlFormatCheck(opts?: HtmlFormatCheckOptions): VerifyCheck;
+/** 沙箱采集到的原始渲染信号(console.error / js-error / unhandledrejection / 资源失败 / CSP 违规 / console.warn) */
+export interface RenderSignal {
+    type: 'console-error' | 'console-warn' | 'js-error' | 'unhandledrejection' | 'resource-error' | 'csp-violation';
+    message: string;
+    source?: string;
+    lineno?: number;
+}
+/** 渲染指标(收集窗结束时采集;白屏判定口径 = 内容级:body 子节点数 / scrollHeight / 图片数) */
+export interface RenderMetrics {
+    bodyChildren: number;
+    scrollHeight: number;
+    imgCount: number;
+}
+/** 单组件沙箱渲染的原始结果(未归一;noDom = node/无 DOM 环境标记) */
+export interface RawRenderResult {
+    handshake: boolean;
+    signals: RenderSignal[];
+    metrics?: RenderMetrics;
+    timedOut?: boolean;
+    noDom?: boolean;
+}
+/** 归一后的单组件判定:pass / fail(带 problems)/ unavailable(握手缺失或超时,不算通过防假绿) */
+export interface RenderVerdict {
+    verdict: 'pass' | 'fail' | 'unavailable';
+    problems: string[];
+    warnings: string[];
+    metrics?: RenderMetrics;
+    reason?: 'handshake-missing' | 'timeout';
+}
+/** 渲染自检 VerifyCheck 工厂选项(runner 注入供测试桩用) */
+export interface HtmlRenderCheckOptions {
+    vfsPrefix?: string;
+    codeField?: string;
+    writablePaths?: string[];
+    runner?: (html: string) => Promise<RawRenderResult>;
+    maxTargets?: number;
+}
+/** 渲染自检对象:check 组合进 createHtmlSubagent 的 formatCheck 链;两个注入槽由装配期回填 */
+export interface HtmlRenderCheck {
+    check: VerifyCheck;
+    setGetController: (g: () => {
+        get?: () => { bind?: unknown } | null | undefined;
+    } | null | undefined) => void;
+    setWritablePaths: (paths: string[]) => void;
+}
+/** 沙箱运行参数(活动静默窗/硬上限/指标应答宽限;默认 900ms / 4000ms / 500ms) */
+export interface SandboxRunOptions {
+    silenceMs?: number;
+    hardCapMs?: number;
+    metricsGraceMs?: number;
+}
+/**
+ * 渲染级自检(render-check):本轮触达的 code 资产放沙箱 iframe(srcdoc + sandbox="allow-scripts")独立渲染,
+ * 采集 console.error / window.onerror / unhandledrejection / 资源失败 / 白屏指标 → 归一回灌自纠。
+ * 仅门禁形态(组合进 createHtmlSubagent 的 formatCheck 链);node/无 DOM 自动跳过渲染段保留结构段;
+ * 握手缺失(宿主 CSP 拦沙箱内联脚本)/ 超时 → unavailable 不算通过(零信号 ≠ 通过)。
+ */
+export declare function createHtmlRenderCheck(opts?: HtmlRenderCheckOptions): HtmlRenderCheck;
+/** 组合「结构 → 渲染」为单一 VerifyCheck(结构不过短路渲染;runBeforeReturn 不短路,两段必须单 check 内早返回) */
+export declare function composeStructureThenRender(structure: VerifyCheck, render: VerifyCheck): VerifyCheck;
+/** 信号归一纯函数:storage 类 SecurityError 降 warn(沙箱假阳性);无失败信号但 body 空 + scrollHeight<10 → 疑似白屏 fail */
+export declare function normalizeRenderResult(raw: RawRenderResult): RenderVerdict;
+/** 单组件沙箱渲染(离屏 iframe;用后销毁;node/无 DOM 返回 noDom) */
+export declare function renderInSandbox(html: string, opts?: SandboxRunOptions): Promise<RawRenderResult>;
+/** 沙箱 srcdoc 构造(collector 注入文档最前,不改组件原文) */
+export declare function buildSandboxSrcdoc(html: string, nonce: string): string;
+/** collector 采集脚本源码(nonce 握手 + 信号上报 + 活动信号 + 指标应答) */
+export declare function buildCollectorJs(nonce: string): string;
+/** 累计创建/销毁的沙箱 iframe 数(测试观察「用后销毁」契约) */
+export declare function getSandboxLifecycle(): { created: number; destroyed: number };
 /** 内置完整 HTML 生成规范 skill 构造器(示例路径按 root/codeField 参数化,集成方字段命名各异勿写死;默认快照 root='components'/codeField='code') */
 export declare function buildHtmlFragmentSkill(root?: string, codeField?: string): SkillSpec;
 /** 内置完整 HTML 生成规范 skill(createHtmlSubagent 默认装;传自定义 skills 覆盖默认时,显式并回此 skill 保住生成规范/安全底线;默认快照 root='components'/codeField='code') */