@webskill/sdk 0.10.0 → 0.12.0

package/dist/{index-DtFdMKBX.d.ts → index-C9pzXLKy.d.ts}

@@ -1,4 +1,4 @@
-import { B as JsonSchema, I as DiscoveryResult, O as UiSurfaceActionRequest, R as FileSystemProvider, S as UiBridge, St as ValidationReport, T as UiSpecEvent, Tt as WebSkillErrorCode, U as Page, W as PageQuery, _ as LlmToolSpec, at as SkillDiscovery, b as RenderResultRequest, bt as UiSpecNode, d as LlmContentPart, dt as SkillManifest, f as LlmMessage, g as LlmToolCall, h as LlmTokenUsage, i as FormField, it as SkillCatalogEntry, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, o as InteractionPolicy, ot as SkillDocument, p as LlmResponse, r as ChartSpec, rt as SkillCatalog, s as InteractionRequest, st as SkillInstallSource, t as Artifact, u as LlmCompleteInput, v as MemoryStore, w as UiSpecDrafts, y as RenderBlock } from "./types-CrRcT-LM-DZAp8sWv.js";
+import { B as JsonSchema, G as RemoteUrlPolicy, I as DiscoveryResult, O as UiSurfaceActionRequest, R as FileSystemProvider, S as UiBridge, St as ValidationReport, T as UiSpecEvent, Tt as WebSkillErrorCode, U as Page, W as PageQuery, _ as LlmToolSpec, at as SkillDiscovery, b as RenderResultRequest, bt as UiSpecNode, d as LlmContentPart, dt as SkillManifest, f as LlmMessage, g as LlmToolCall, h as LlmTokenUsage, i as FormField, it as SkillCatalogEntry, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, o as InteractionPolicy, ot as SkillDocument, p as LlmResponse, r as ChartSpec, rt as SkillCatalog, s as InteractionRequest, st as SkillInstallSource, t as Artifact, u as LlmCompleteInput, v as MemoryStore, w as UiSpecDrafts, y as RenderBlock } from "./types-DLctJep_-B5G4uk2u.js";
 //#region ../runtime/dist/index.d.ts
 //#region src/llm/parts.d.ts
 /** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
@@ -22,6 +22,45 @@ type TextualToolContent = {
   text?: string;
   data?: unknown;
 };
+/**
+ * 参与 `toolResultMaxBytes` 截断的分片类型（FR-23.3）。**判据的单一来源。**
+ *
+ * 白名单而不是黑名单：黑名单式下新加的分片默认「参与截断」，
+ * 漏改一处就会把一份 PDF 截成坏文件、把 docx 文本腰斩，而且没有任何报错。
+ * 白名单式下新分片默认**不参与**，要受文本预算约束必须显式加进来。
+ * @experimental
+ */
+declare const TEXT_BUDGETED_CONTENT_TYPES: ReadonlySet<string>;
+/**
+ * `file` 分片的上限（FR-23.4），量的是**实际上线的 base64 长度**而不是解码后的字节——
+ * provider 的限额算的是请求载荷。
+ *
+ * 2026-08-14 查证的三家上限：
+ * | provider  | 上限                                    | 出处                    |
+ * | --------- | --------------------------------------- | ----------------------- |
+ * | Anthropic | **32 MB**（**整个请求载荷**）、600 页   | PDF support / 请求大小  |
+ * | OpenAI    | 单文件 50 MB，全部文件合计 50 MB        | File inputs / 使用须知  |
+ * | Gemini    | 50 MB 或 1000 页（内联与 Files API 同） | 文档理解 / 技术详情     |
+ *
+ * 取最小值 Anthropic 的 32 MB。它是**整个请求**的额度，不是文档单独的额度，
+ * 所以再留出余量给系统提示词、catalog（约 34 KB）、历史消息与其余分片。
+ * 25 000 KB base64 ≈ 18.75 MB 原始 PDF。取 1024 的整数倍：设置界面按 KB 展示，
+ * 十进制的 24 000 000 会显示成 23437.5 这种读不出来的数。
+ */
+declare const DEFAULT_MAX_DOCUMENT_BYTES = 25600000;
+/**
+ * `document-text` 分片的上限（FR-23.4）。
+ *
+ * 约束来自**上下文窗口**而不是请求大小：抽出来的文本要整段进上下文。
+ * 按英文约 4 字节/token 折算，500 KB ≈ 128K token，占 200K 窗口的多半，
+ * 给历史消息与模型的回答留下其余。
+ */
+declare const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 512000;
+/**
+ * 单次 fetchData 结果的字节上限（分册 16，FR-16.6）：1000 KB。
+ * 结构化数据不是文档，量级差一个数量级；超出**只拒不截**——截断的 JSON 解不出来。
+ */
+declare const DEFAULT_MAX_DATA_SOURCE_BYTES = 1024000;
 /**
  * 工具结果的内容分片（0.6.0 §1.1）。
  * `image` 分片不参与 `toolResultMaxBytes` 截断——那份预算是给文本的，
@@ -35,6 +74,27 @@ type ToolContent = TextualToolContent | {
   data: string;
   id: string;
   text?: undefined;
+} |
+/** 原样直通给模型的文档（PDF 等），受 `maxDocumentBytes` 约束 @experimental */
+{
+  type: 'file';
+  mimeType: string;
+  data: string;
+  name?: string;
+  id: string;
+  text?: undefined;
+} |
+/**
+ * 从文档里抽出来的文本（docx 等），受 `maxDocumentTextBytes` 约束。
+ * 它**就是**文本，但与普通工具文本分开计预算：混算会出现
+ * 「PDF 读全了、Word 只读了一半」这种无法解释的差异。
+ * @experimental
+ */
+{
+  type: 'document-text';
+  text: string;
+  name?: string;
+  id: string;
 };
 interface ToolResult {
   ok: boolean;
@@ -51,9 +111,25 @@ interface ScriptExecutionContext {
   skillName: string;
   runId: string;
   readReference(relativePath: string): Promise<string>;
+  /** 读技能自己的 `assets/`；与 readReference 共用路径断言，不得跨目录 @experimental */
+  readAsset?(relativePath: string): Promise<string>;
+  /** `assets/` 的典型内容是图片/字体/数据包，纯文本出口不够 @experimental */
+  readAssetBinary?(relativePath: string): Promise<Uint8Array>;
+  /**
+   * 写 run 产物。`options.metadata` 由技能自定义并随产物索引落盘；
+   * 约定键 `resultCard: false` 表示该产物不出自动下载卡（分册 18）。
+   * 必须是可 JSON 序列化的 plain object，否则抛 `VALIDATION_FAILED` 且产物不落盘。
+   */
   writeArtifact(path: string, content: string | Uint8Array, options?: {
     mimeType?: string;
+    metadata?: Record<string, unknown>;
   }): Promise<Artifact>;
+  /**
+   * 按**宿主声明的 sourceId** 取数（FR-16.1）。脚本给不了 URL——
+   * 目标由宿主在 `DataSourceDef.target` 里写死，这就是「唯一授权面」。
+   * 宿主未装配即不存在（同 readAsset / confirm）。 @experimental
+   */
+  fetchData?(sourceId: string, params?: Record<string, unknown>): Promise<unknown>;
   /** 脚本主动请求人在环确认；策略见 InteractionPolicy.confirmations */
   confirm?(message: string): Promise<boolean>;
   /** 宿主侧降级 warning 出口（网络阻断等；引擎接线到 run.warning trace） */
@@ -329,14 +405,18 @@ declare const READ_SKILL_FILE_TOOL: ToolDefinition;
 //#endregion
 //#region src/tools/askUserTool.d.ts
 declare const ASK_USER_TOOL_NAME = "ask_user";
+/** 一次 `ask_user` 能收的字段数上限（FR-11.3 裁决值），可由 `AgentLoopConfig` 覆盖 */
+declare const ASK_USER_MAX_FIELDS = 20;
+/** `fields[].type`：`FormField['type']` 的八种。`multi-select` 不在其中——它的值是数组（FR-11.1b） */
+declare const ASK_USER_FIELD_TYPES: readonly ["text", "number", "boolean", "select", "textarea", "file", "password", "date"];
 declare const ASK_USER_INPUT_SCHEMA: JsonSchema;
 /** 内建工具：LLM 信息不足时主动向用户提问；仅当配置了 UiBridge 时注册 */
 declare const ASK_USER_TOOL: ToolDefinition;
 //#endregion
 //#region src/tools/scriptContext.d.ts
 /**
- * 脚本执行上下文：只暴露 readReference / writeArtifact 两个显式能力，
- * 不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
+ * 脚本执行上下文：只暴露 readReference / readAsset / readAssetBinary / writeArtifact
+ * 四个显式能力，不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
  */
 declare function createScriptContext(deps: {
   fs: FileSystemProvider;
@@ -346,6 +426,12 @@ declare function createScriptContext(deps: {
   runId: string;
   /** 提供时暴露 context.confirm（由引擎按交互策略实现） */
   confirm?: (message: string) => Promise<boolean>;
+  /**
+   * 提供时暴露 context.fetchData（引擎按 DataSourcePolicy 实现，FR-16.1）。
+   * 宿主没声明数据源就整个键不存在——脚本 `typeof context.fetchData` 即可探测，
+   * 不给「存在但永远失败」的假出口。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
   /** 宿主侧降级 warning 出口（网络阻断等；引擎接线到 run.warning trace） */
   onWarning?: (message: string) => void;
   /** writeArtifact 创建产物后的回调（引擎记录新产物 ID，执行后单次 listArtifacts 过滤） */
@@ -416,6 +502,11 @@ type InteractLifecycleData = {
 /** complete / fail：终态原因 */
 interface TerminalLifecycleData {
   reason: RunTerminationReason;
+  /**
+   * 失败时的具体说明（`RuntimeRun.error.message`）。`reason` 只有七种取值，
+   * 说不出「哪个上限、哪个模型、本轮带了文档」这类唯一能指导下一步的信息。
+   */
+  detail?: string;
 }
 interface LifecycleEventBase {
   runId: string;
@@ -502,6 +593,23 @@ interface AgentLoopConfig {
    * 不设上限的话，模型会一路猜到 maxTurns 用完，用户等到最后拿到的还是一句失败。
    */
   maxUnknownToolRetries?: number;
+  /**
+   * 一次 `ask_user` 能收的字段数上限（默认 20，FR-11.3）。超出即拒绝整次调用，
+   * **不截断**——截断会让模型以为字段全收到了。
+   */
+  askUserMaxFields?: number;
+  /**
+   * `file` 分片的 base64 长度上限（默认 `DEFAULT_MAX_DOCUMENT_BYTES`，FR-23.4）。
+   * 超出即**拒绝并说明**：截断一份 PDF 等于给模型一份坏文件。
+   */
+  maxDocumentBytes?: number;
+  /**
+   * `document-text` 分片的字节上限（默认 `DEFAULT_MAX_DOCUMENT_TEXT_BYTES`，FR-23.4）。
+   * 同样拒绝而不截断：截半份内容给模型，而它不知道自己少看了什么。
+   */
+  maxDocumentTextBytes?: number;
+  /** `read_linked_document` 的出站准入策略；与脚本取数共用同一个判定（AC-G23） */
+  remoteUrl?: RemoteUrlPolicy;
 }
 /** 技能状态拦截 port（治理装配；无注入默认全放行） */
 interface SkillStateGuard {
@@ -999,16 +1107,39 @@ type BridgeRequest = {
   kind: 'readReference';
   id: string;
   path: string;
+} | {
+  kind: 'readAsset';
+  id: string;
+  path: string;
+} |
+/** 回值走 `number[]`：进程沙箱的桥是 JSON stdio，与 writeArtifact 同口径 */
+{
+  kind: 'readAssetBinary';
+  id: string;
+  path: string;
 } | {
   kind: 'writeArtifact';
   id: string;
   path: string;
   content: string | number[];
   mimeType?: string;
+  /**
+   * 技能声明的产物 metadata（分册 18）。**不可信载荷**，故声明为 `unknown`：
+   * 形状判定在 `createScriptContext.writeArtifact`（唯一汇聚点，DV-10），
+   * 在这里拒绝只能 `return undefined`，而那会丢掉请求 id 使脚本挂到超时。
+   */
+  metadata?: unknown;
 } | {
   kind: 'confirm';
   id: string;
   message: string;
+} |
+/** 取数只传宿主声明的 sourceId；**脚本给不了 URL**（FR-16.2 的唯一授权面） */
+{
+  kind: 'fetchData';
+  id: string;
+  sourceId: string;
+  params?: Record<string, unknown>;
 };
 interface BridgeResponse {
   id: string;
@@ -1026,11 +1157,18 @@ interface BridgeResponse {
 type CapabilityMode = boolean | 'require-approval';
 /** 授权粒度：'once-per-run'（默认，run 内同类能力批准一次）/ 'every-call'（每次调用都问） */
 type ApprovalScope = 'once-per-run' | 'every-call';
-/** 三能力独立开关；缺省全开，显式 false 即关闭（TOOL_UNSUPPORTED） */
+/** 能力独立开关；缺省全开，显式 false 即关闭（TOOL_UNSUPPORTED） */
 interface BridgeCapabilities {
   readReference?: CapabilityMode;
+  /** 同时管 readAsset 与 readAssetBinary；与 readReference 分开是为了审计可区分 */
+  readAsset?: CapabilityMode;
   writeArtifact?: CapabilityMode;
   confirm?: CapabilityMode;
+  /**
+   * 脚本取数（FR-16.1）。**缺省关**——与其余能力相反：
+   * 它会出网，缺省开等于让任何技能默认拥有出站能力。
+   */
+  fetchData?: CapabilityMode;
 }
 /** 入站校验：非法 kind / 缺 id / 缺字段 → undefined（调用方忽略并记 warning） */
 declare function parseBridgeRequest(data: unknown): BridgeRequest | undefined;
@@ -1086,8 +1224,8 @@ declare function normalizeToolError(code: unknown, message: string): {
 };
 //#endregion
 //#region src/sandbox/approval.d.ts
-/** 桥消息对应的三类能力 */
-type BridgeCapability = 'readReference' | 'writeArtifact' | 'confirm';
+/** 桥消息对应的四类能力（readAsset 同时覆盖文本与二进制读取） */
+type BridgeCapability = 'readReference' | 'readAsset' | 'writeArtifact' | 'confirm' | 'fetchData';
 /** allowed 放行；denied 用户拒绝/无法询问；disabled 能力关闭（两者都回 TOOL_UNSUPPORTED，仅消息不同） */
 type ApprovalDecision = 'allowed' | 'denied' | 'disabled';
 /**
@@ -1143,6 +1281,116 @@ interface TodoTraceEvent {
  */
 declare function extractTodoTraceEvents(data: unknown): TodoTraceEvent[];
 //#endregion
+//#region src/tools/linkedDocument.d.ts
+/**
+ * 读取页面上链接指向的文档（分册 22）。
+ *
+ * 与脚本侧的 `fetchData` **分工明确**，两者不得互相蚕食：
+ * - `fetchData`：技能脚本按宿主声明的 sourceId 取**业务数据**，目标宿主写死；
+ * - 本工具：模型读**页面上出现的链接**指向的文档，目标来自感知结果。
+ *
+ * 共同点是准入判定必须共用 `assertRemoteUrlAllowed`（AC-G23），不得各写一套。
+ */
+/** 宿主提供的文档取数实现；不注入即整个工具不注册 @experimental */
+interface LinkedDocumentReader {
+  /**
+   * 宿主页面的 origin，用于同源判定。
+   *
+   * **缺省即一律按跨源处理**（DV-10）：拿不到 origin 时保守到「每次都问」，
+   * 而不是保守到「都不问」。Node 宿主没有页面 origin，因此总是要确认。
+   */
+  readonly origin?: string;
+  read(url: string): Promise<{
+    mimeType: string;
+    bytes: Uint8Array;
+  }>;
+}
+declare const READ_LINKED_DOCUMENT_TOOL_NAME = "read_linked_document";
+/**
+ * 能直接给模型用的 MIME。其余一律拒绝并列出这份清单——
+ * 「尽力而为地猜格式」会让模型收到乱码却以为读成功了。
+ */
+declare const SUPPORTED_DOCUMENT_MIME: {
+  readonly pdf: "application/pdf";
+  readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+};
+/** docx 抽取实现由宿主注入（`DOMParser` 是浏览器 API，Node 没有；备案 D55） */
+type DocxTextExtractor = (bytes: Uint8Array) => Promise<string>;
+/** 引擎侧固定流程（§2.3）用到的错误文案，集中一处便于判据引用 */
+declare const UNSUPPORTED_DOCUMENT_MESSAGE: string;
+/**
+ * 内建工具：读页面链接指向的文档。
+ *
+ * **始终注册**（只要宿主装配了 reader）：docx 与纯文本这条路对所有模型成立。
+ * PDF 目标在模型不支持文档时**取数后拒绝**，而不是入口就拦 ——
+ * 入口拦会误伤 docx，它抽成文本后根本不需要文档能力。
+ */
+declare const READ_LINKED_DOCUMENT_TOOL: ToolDefinition;
+//#endregion
+//#region src/engine/toolStep.d.ts
+/**
+ * 一次工具调用的**未截断**参数留存（分册 30 / FR-30.2）。
+ *
+ * 刻意不并入 `RunTraceFile`：那是 `@stable` 且不留扩展位的契约，
+ * 每个 run 都写、所有宿主都读；为一个默认关闭的能力抬它的 schemaVersion
+ * 不划算（D-30-1 裁为 B）。
+ * @stable
+ */
+interface ToolStepRecord {
+  runId: string;
+  sessionId: string;
+  callId: string;
+  /** LLM 可见的工具名 */
+  tool: string;
+  at: string;
+  /** 脱敏后的参数：被脱敏的键仍在，值不在 */
+  args: Record<string, unknown>;
+  /** 被脱敏掉的字段路径（如 `credentials.token`），供确认卡与审计 */
+  redacted: readonly string[];
+  /** 超出体积上限：`args` 为空对象，生成器据此拒绝该步骤 */
+  truncated?: true;
+  /** 未脱敏字段的依据（AC-30.6d） */
+  trust: ToolStepTrust;
+}
+/**
+ * 参数留存的信任层级。
+ * - `reviewed`：本仓自带工具源，schema 标注已被审查
+ * - `host-trusted`：外部来源，但宿主显式声明信任（`declaredBy` 记声明标识）
+ * - `untrusted`：缺省——未标注字段一律按敏感处理
+ * @stable
+ */
+type ToolStepTrust = {
+  tier: 'reviewed' | 'host-trusted';
+  declaredBy?: string;
+} | {
+  tier: 'untrusted';
+};
+/** 只读侧：生成器只需要「这个会话有哪些步骤」 @stable */
+interface ToolStepReader {
+  listBySession(sessionId: string): Promise<ToolStepRecord[]>;
+}
+/** @stable */
+interface ToolStepStore extends ToolStepReader {
+  append(record: ToolStepRecord): Promise<void>;
+}
+/**
+ * 按会话分文件的 append-only JSONL 留存。
+ *
+ * 分文件维度取会话而非 run：读取侧唯一的查询就是「这个会话的全部步骤」，
+ * 按 run 分会让一次生成要开 N 个文件。
+ */
+declare class FsToolStepStore implements ToolStepStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+    /** 留存失败不阻断对话：默认降级为告警 */
+    onError?: (error: unknown, record: ToolStepRecord) => void;
+  });
+  append(record: ToolStepRecord): Promise<void>;
+  listBySession(sessionId: string): Promise<ToolStepRecord[]>;
+}
+//#endregion
 //#region src/engine/external.d.ts
 /**
  * 外部工具来源（runtime 扩展点，mcp 包实现并插入）。
@@ -1161,6 +1409,28 @@ interface ExternalToolSource {
   systemPrompt?(): Promise<string | undefined>;
   canHandle(llmToolName: string): boolean;
   call(llmToolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+  /**
+   * 参数留存的信任判定（分册 30 / FR-30.3）。**不实现 ⇒ 该源全部工具按 untrusted 处理**（参数全脱敏）。
+   *
+   * 字段级敏感性只写在 `inputSchema` 的 `x-webskill-sensitive` 标注里，本方法不重复表达它，
+   * 否则会有两份事实源。本方法回答的是另一个问题：**这一次调用的参数整体能不能按审查过的处理**。
+   *
+   * 传入 `args` 是为了让「敏感与否取决于运行期目标」的工具能如实回答——
+   * 例如 `act_on_page` 的填写内容是否敏感，取决于目标是不是密码类控件，
+   * 静态 schema 看不出来。这类工具应在敏感目标上返回 `untrusted`（整调用全脱敏），
+   * 而不是把字段永久标成敏感、让所有正常填写也一并丢失。
+   */
+  argCaptureTrust?(llmToolName: string, args: Record<string, unknown>): ToolStepTrust | undefined;
+  /**
+   * 留存前把入参补成自解释的形状（分册 30 / FR-30.2）。**不实现即原样留存。**
+   *
+   * 给的是 `act_on_page` 这类工具一个出口：它的 `ref` 是本次感知产出的不透明句柄，
+   * 换一次运行就失效，只留它等于留了一个指向不存在东西的引用。工具源在这里补上
+   * 目标的角色与可访问名，生成的技能才说得出「填进哪个框」。
+   *
+   * 补出来的字段照样过脱敏：它们不在 `inputSchema` 里，因此在 `untrusted` 层同样被抹掉。
+   */
+  captureArgs?(llmToolName: string, args: Record<string, unknown>): Record<string, unknown> | undefined;
 }
 /** 外部技能提供者（页面动态技能等；技能随来源生灭，不持久化） */
 interface ExternalSkillProvider {
@@ -1278,6 +1548,27 @@ interface AgentLoopDeps {
   schemaInferer?: SchemaInferer;
   /** 缺省 MemoryArtifactStore */
   artifactStore?: ArtifactStore;
+  /**
+   * 宿主声明的数据源取数入口（分册 16）。注入后脚本上下文才有 `fetchData`。
+   * 策略本体（`DataSourcePolicy`）住在 `@webskill/agent`，它依赖 runtime，
+   * 所以这里只收一个函数，不收策略对象——否则依赖方向反了。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * 页面链接文档的读取实现（分册 22）。不注入即 `read_linked_document` 不注册——
+   * 模型连这个工具的存在都看不到，而不是看得到再被拒。
+   */
+  linkedDocuments?: LinkedDocumentReader;
+  /** docx → 文本；`DOMParser` 是浏览器 API，因此由宿主注入（Node 侧无此能力，备案 D55） */
+  docxExtractor?: DocxTextExtractor;
+  /** 文档读取留痕出口（FR-22.6）；不注入即不留痕，装配方要自己承担这个选择 */
+  documentAudit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
   fs: FileSystemProvider;
   /** name → skillRoot（来自发现结果） */
   skillIndex: Map<string, string>;
@@ -1317,6 +1608,11 @@ interface AgentLoopDeps {
   skillOutcomeReporter?: SkillOutcomeReporter;
   /** D3：interrupt 点快照存储（无配置则行为与现状完全一致） */
   snapshotStore?: RunSnapshotStore;
+  /**
+   * 工具调用的完整参数留存（分册 30）。**不注入即不留存**——
+   * AC-30.15 因此是结构性的：不是「有个判断没走进去」，是根本没有写入方。
+   */
+  toolSteps?: ToolStepStore;
 }
 /**
  * 多轮 Agent 循环。
@@ -1357,10 +1653,18 @@ declare class AgentLoop {
  * @stable
  */
 declare const DEFAULT_LOOP_LIMITS: {
-  readonly maxTurns: 10;
+  readonly maxTurns: 1000;
   readonly totalTimeoutMs: 3600000;
   readonly toolTimeoutMs: 600000;
+  readonly maxHistoryMessages: 1000;
 };
+/**
+ * 工具参数留存的单次体积上限（分册 30 / FR-30.2）。**全仓唯一来源**（S8）。
+ *
+ * 超限时不留半截参数，整条标记为 `truncated`。
+ * @stable
+ */
+declare const MAX_TOOL_STEP_ARG_BYTES = 32768;
 /**
  * 触顶类失败（`RUN_TIMEOUT` / `RUN_MAX_TURNS_EXCEEDED`）记进 `run.failed`
  * 轨迹事件 `data` 的结构化细节：程序化消费方据此判断是哪个上限、当时的生效值，
@@ -1417,12 +1721,34 @@ interface WebSkillRuntimeDeps {
   }) => Promise<void>;
   /** D3：interrupt 点快照存储（配置后 interrupted run 可 resumeRun 恢复） */
   snapshotStore?: RunSnapshotStore;
+  /** 工具调用的完整参数留存（分册 30）；**不注入即不留存** */
+  toolSteps?: ToolStepStore;
   /** 技能状态拦截 port（治理 SkillStatePolicy.toSkillStateGuard 装配；无注入默认全放行） */
   skillStateGuard?: SkillStateGuard;
   /** D3 激活期完整性校验 port（治理 SkillStatePolicy.toSkillIntegrityGuard 装配；无注入即关闭） */
   skillIntegrityGuard?: SkillIntegrityGuard;
   /** F1 技能执行失败上报 port（治理 SkillStatePolicy.toSkillOutcomeReporter 装配；无注入即关闭） */
   skillOutcomeReporter?: SkillOutcomeReporter;
+  /**
+   * 宿主声明的数据源取数入口（分册 16）；注入后脚本上下文才有 `fetchData`。
+   * 通常由 `@webskill/agent` 的 `DataSourcePolicy.fetchData` 绑定过来。
+   */
+  fetchData?: (sourceId: string, params?: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * 读页面链接指向的文档（分册 22）；不注入即 `read_linked_document` 不注册。
+   * 实现住在 `@webskill/browser`（docx 抽取要 `DOMParser`），由宿主装配。
+   */
+  linkedDocuments?: LinkedDocumentReader;
+  /** docx → 文本；不注入即 Word 文档明确报「本环境不支持」（FR-23.8） */
+  docxExtractor?: DocxTextExtractor;
+  /** 文档读取留痕出口（FR-22.6） */
+  documentAudit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
 }
 /**
  * runtime 门面：组合 discovery / router / agent loop / lifecycle
@@ -1445,7 +1771,7 @@ declare class WebSkillRuntime {
    * 多会话：session 对象的 run(prompt) 跨 run 延续消息历史（同一 session 对话上下文连续）。
    * 既有 runtime.run(prompt) 保持无状态单次语义不变。
    * 同 handle 并发 run 经 per-handle 队列串行化（防历史 last-writer-wins 丢轮次）；
-   * maxHistoryMessages（默认 100）超出时滚动裁剪中段（保留首尾；边界对齐 tool 契约）。
+   * maxHistoryMessages（默认取 `DEFAULT_LOOP_LIMITS`）超出时滚动裁剪中段（保留首尾；边界对齐 tool 契约）。
    */
   createSession(options?: {
     sessionId?: string;
@@ -1526,6 +1852,10 @@ interface RunTraceSummary {
 interface RunTraceFilter {
   /** 状态精确匹配 */
   status?: string;
+  /**
+   * 会话精确匹配。刻意不走 `search`：子串匹配会让 `sess-1` 命中 `sess-10`。
+   */
+  sessionId?: string;
   /** 大小写不敏感子串：匹配 runId 或任一激活技能名 */
   search?: string;
   limit?: number;
@@ -1754,4 +2084,31 @@ declare class FsSessionStore<TMessage = unknown> implements SessionStore<TMessag
   delete(id: string): Promise<void>;
 }
 //#endregion
-export { READ_SKILL_FILE_INPUT_SCHEMA as $, schemaToForm as $n, TraceEventType as $t, FS_SESSION_PAGE_SIZE as A, fromVercelStreamPart as An, SealResult as At, HookRunnerOptions as B, normalizeToolContent as Bn, SkillScriptDescriptor as Bt, DEFAULT_LOOP_LIMITS as C, exportUserProfile as Cn, RuntimeSessionHandle as Ct, ExecuteLifecycleData as D, findUnpairedToolCalls as Dn, ScriptExecutor as Dt, EventBus as E, extractUiSpecEvents as En, ScriptExecutionContext as Et, FsSessionStore as F, mergeCatalogEntries as Fn, SessionStore as Ft, LifecycleEventInit as G, readBehaviorRecords as Gn, TextualToolContent as Gt, IntegrityVerdict as H, parseBridgeRequest as Hn, SkillStateGuard as Ht, FullDisclosureRouter as I, mergeProfileEntries as In, SkillFailureReport as It, LifecycleListener as J, refineUserProfile as Jn, ToolDefinition as Jt, LifecycleHook as K, readProfileEntries as Kn, TodoTraceEvent as Kt, GoogleGenAiClient as L, networkPolicyLibSource as Ln, SkillIntegrityGuard as Lt, FsMemoryStore as M, isNetworkAllowed as Mn, SessionListPage as Mt, FsRunSnapshotStore as N, isUnsupportedRunSnapshot as Nn, SessionMeta as Nt, ExternalSkillProvider as O, formatSkillScriptManifest as On, SealOptions as Ot, FsRunTraceStore as P, listSkillScripts as Pn, SessionRecord as Pt, ProgressiveRouter as Q, schemaSourceLabel as Qn, TraceEvent as Qt, GoogleGenAiClientConfig as R, networkUrlHost as Rn, SkillOutcomeReporter as Rt, CapabilityMode as S, diffUserProfile as Sn, RuntimeSession as St, EMPTY_USER_PROFILE as T, extractTodoTraceEvents as Tn, SchemaInferer as Tt, InteractLifecycleData as U, parseUserProfileExport as Un, SkillSuccessReport as Ut, InstalledSkillManifest as V, normalizeToolError as Vn, SkillScriptSchemaSource as Vt, LifecycleEvent as W, partsToText as Wn, TerminalLifecycleData as Wt, OpenAiCompatibleClient as X, resolveToolName as Xn, ToolResult as Xt, NetworkPolicy as Y, renderUserProfileContext as Yn, ToolResolution as Yt, OpenAiCompatibleClientConfig as Z, sampleBehaviorRecords as Zn, TraceClock as Zt, BridgeCapabilities as _, applyUserProfileImport as _n, RunTraceStore as _t, ActivateLifecycleData as a, USER_PROFILE_REFINE_PROMPT as an, toLlmToolSpec as ar, RouteLifecycleData as at, BridgeResponse as b, createScriptContext as bn, RuntimePhase as bt, AgentLoopDeps as c, UserProfileEntry as cn, validateUiSpecEvent as cr, RunResult as ct, ApprovalDecision as d, UserProfileLimits as dn, RunSnapshotStore as dt, TraceRecorder as en, scriptToolName as er, READ_SKILL_FILE_TOOL as et, ApprovalScope as f, VercelToolSpec as fn, RunTerminationReason as ft, BehaviorScene as g, appendBehaviorRecords as gn, RunTraceMetrics as gt, BehaviorRecordKind as h, WebSkillRuntimeDeps as hn, RunTraceFilter as ht, ASK_USER_TOOL_NAME as i, USER_PROFILE_PROMPT_HEADER as in, textParts as ir, RefineUserProfileInput as it, FsArtifactStore as j, interruptedToolResult as jn, SerializingMemoryStore as jt, ExternalToolSource as k, fromVercelResult as kn, SealRecord as kt, AnthropicClient as l, UserProfileExport as ln, validateUiSpecNode as lr, RunSnapshot as lt, BehaviorRecord as m, WebSkillRuntime as mn, RunTraceFile as mt, ASK_USER_INPUT_SCHEMA as n, USER_PROFILE_KEY as nn, summarizeRunUsage as nr, RUN_SNAPSHOT_SCHEMA_VERSION as nt, AgentLoop as o, UnsupportedRunSnapshot as on, toRecordDigests as or, RouteResult as ot, BEHAVIOR_RECORDS_KEY as p, WebSkillApi as pn, RunToolCall as pt, LifecycleHookContext as q, readUserProfile as qn, ToolContent as qt, ASK_USER_TOOL as r, USER_PROFILE_NO_INVENTION_RULE as rn, summarizeToolCalls as rr, RUN_TRACE_SCHEMA_VERSION as rt, AgentLoopConfig as s, UserProfile as sn, toVercelToolSpecs as sr, RunLimitErrorDetails as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, USER_PROFILE_EXPORT_VERSION as tn, sealToolCallPairs as tr, READ_SKILL_FILE_TOOL_NAME as tt, AnthropicClientConfig as u, UserProfileImportDiff as un, RunSnapshotListEntry as ut, BridgeCapability as v, bridgeError as vn, RunTraceSummary as vt, DEFAULT_USER_PROFILE_LIMITS as w, extractChartSpec as wn, SESSION_SCHEMA_VERSION as wt, CapabilityApproval as x, createWebSkillApi as xn, RuntimeRun as xt, BridgeRequest as y, buildRenderResult as yn, RunUsageSummary as yt, HookRunner as z, normalizeErrorCode as zn, SkillRouter as zt };
+//#region src/engine/toolStepRedaction.d.ts
+/**
+ * 参数敏感标注关键字（分册 30 / FR-30.3）。
+ *
+ * 不用 `format: 'password'`：`format` 是 JSON Schema 的规范关键字，provider 侧
+ * 可能据其做转换或校验，而且它只对 `type: 'string'` 有意义，对象型凭据标不了。
+ * `x-` 前缀走 `JsonSchema` 的索引签名，不与任何规范语义抢占。
+ */
+declare const SENSITIVE_ANNOTATION = "x-webskill-sensitive";
+interface RedactedArgs {
+  /** 脱敏后的参数：被脱敏的键仍在，值为 `null` */
+  args: Record<string, unknown>;
+  /** 被脱敏掉的字段路径，点号分隔；数组元素用 `field[0]` */
+  redacted: string[];
+  truncated?: true;
+}
+/**
+ * 分层脱敏（FR-30.3）——**全仓唯一实现**。
+ *
+ * 1. `untrusted` → 所有字段脱敏；
+ * 2. `reviewed` / `host-trusted` → 逐字段走 schema，标注为敏感的脱敏。
+ *
+ * 标注为敏感的字段在**任何**层级都脱敏：信任声明说的是「未标注的可以留」，
+ * 不是「标注了也能留」。
+ */
+declare function redactToolStepArgs(args: Record<string, unknown>, schema: JsonSchema | undefined, trust: ToolStepTrust): RedactedArgs;
+//#endregion
+export { LifecycleHook as $, isUnsupportedRunSnapshot as $n, SkillRouter as $t, DocxTextExtractor as A, UserProfileImportDiff as An, validateUiSpecNode as Ar, RunTraceSummary as At, FsRunTraceStore as B, createScriptContext as Bn, ScriptExecutionContext as Bt, CapabilityApproval as C, USER_PROFILE_NO_INVENTION_RULE as Cn, summarizeRunUsage as Cr, RunSnapshotStore as Ct, DEFAULT_MAX_DOCUMENT_BYTES as D, UserProfile as Dn, toRecordDigests as Dr, RunTraceFilter as Dt, DEFAULT_MAX_DATA_SOURCE_BYTES as E, UnsupportedRunSnapshot as En, toLlmToolSpec as Er, RunTraceFile as Et, ExternalToolSource as F, WebSkillRuntimeDeps as Fn, RuntimeSessionHandle as Ft, GoogleGenAiClientConfig as G, extractTodoTraceEvents as Gn, SerializingMemoryStore as Gt, FsToolStepStore as H, diffUserProfile as Hn, SealOptions as Ht, FS_SESSION_PAGE_SIZE as I, appendBehaviorRecords as In, SENSITIVE_ANNOTATION as It, InstalledSkillManifest as J, formatSkillScriptManifest as Jn, SessionRecord as Jt, HookRunner as K, extractUiSpecEvents as Kn, SessionListPage as Kt, FsArtifactStore as L, applyUserProfileImport as Ln, SESSION_SCHEMA_VERSION as Lt, EventBus as M, VercelToolSpec as Mn, RuntimePhase as Mt, ExecuteLifecycleData as N, WebSkillApi as Nn, RuntimeRun as Nt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as O, UserProfileEntry as On, toVercelToolSpecs as Or, RunTraceMetrics as Ot, ExternalSkillProvider as P, WebSkillRuntime as Pn, RuntimeSession as Pt, LifecycleEventInit as Q, isNetworkAllowed as Qn, SkillOutcomeReporter as Qt, FsMemoryStore as R, bridgeError as Rn, SUPPORTED_DOCUMENT_MIME as Rt, BridgeResponse as S, USER_PROFILE_KEY as Sn, sealToolCallPairs as Sr, RunSnapshotListEntry as St, DEFAULT_LOOP_LIMITS as T, USER_PROFILE_REFINE_PROMPT as Tn, textParts as Tr, RunToolCall as Tt, FullDisclosureRouter as U, exportUserProfile as Un, SealRecord as Ut, FsSessionStore as V, createWebSkillApi as Vn, ScriptExecutor as Vt, GoogleGenAiClient as W, extractChartSpec as Wn, SealResult as Wt, InteractLifecycleData as X, fromVercelStreamPart as Xn, SkillFailureReport as Xt, IntegrityVerdict as Y, fromVercelResult as Yn, SessionStore as Yt, LifecycleEvent as Z, interruptedToolResult as Zn, SkillIntegrityGuard as Zt, BehaviorRecordKind as _, TraceEvent as _n, resolveToolName as _r, RouteLifecycleData as _t, ASK_USER_TOOL as a, TerminalLifecycleData as an, normalizeErrorCode as ar, OpenAiCompatibleClient as at, BridgeCapability as b, UNSUPPORTED_DOCUMENT_MESSAGE as bn, schemaToForm as br, RunResult as bt, AgentLoop as c, ToolContent as cn, parseBridgeRequest as cr, READ_LINKED_DOCUMENT_TOOL as ct, AnthropicClient as d, ToolResult as dn, readBehaviorRecords as dr, READ_SKILL_FILE_TOOL as dt, SkillScriptDescriptor as en, listSkillScripts as er, LifecycleHookContext as et, AnthropicClientConfig as f, ToolStepReader as fn, readProfileEntries as fr, READ_SKILL_FILE_TOOL_NAME as ft, BehaviorRecord as g, TraceClock as gn, renderUserProfileContext as gr, RefineUserProfileInput as gt, BEHAVIOR_RECORDS_KEY as h, ToolStepTrust as hn, refineUserProfile as hr, RedactedArgs as ht, ASK_USER_MAX_FIELDS as i, TEXT_BUDGETED_CONTENT_TYPES as in, networkUrlHost as ir, NetworkPolicy as it, EMPTY_USER_PROFILE as j, UserProfileLimits as jn, RunUsageSummary as jt, DEFAULT_USER_PROFILE_LIMITS as k, UserProfileExport as kn, validateUiSpecEvent as kr, RunTraceStore as kt, AgentLoopConfig as l, ToolDefinition as ln, parseUserProfileExport as lr, READ_LINKED_DOCUMENT_TOOL_NAME as lt, ApprovalScope as m, ToolStepStore as mn, redactToolStepArgs as mr, RUN_TRACE_SCHEMA_VERSION as mt, ASK_USER_FIELD_TYPES as n, SkillStateGuard as nn, mergeProfileEntries as nr, LinkedDocumentReader as nt, ASK_USER_TOOL_NAME as o, TextualToolContent as on, normalizeToolContent as or, OpenAiCompatibleClientConfig as ot, ApprovalDecision as p, ToolStepRecord as pn, readUserProfile as pr, RUN_SNAPSHOT_SCHEMA_VERSION as pt, HookRunnerOptions as q, findUnpairedToolCalls as qn, SessionMeta as qt, ASK_USER_INPUT_SCHEMA as r, SkillSuccessReport as rn, networkPolicyLibSource as rr, MAX_TOOL_STEP_ARG_BYTES as rt, ActivateLifecycleData as s, TodoTraceEvent as sn, normalizeToolError as sr, ProgressiveRouter as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, SkillScriptSchemaSource as tn, mergeCatalogEntries as tr, LifecycleListener as tt, AgentLoopDeps as u, ToolResolution as un, partsToText as ur, READ_SKILL_FILE_INPUT_SCHEMA as ut, BehaviorScene as v, TraceEventType as vn, sampleBehaviorRecords as vr, RouteResult as vt, CapabilityMode as w, USER_PROFILE_PROMPT_HEADER as wn, summarizeToolCalls as wr, RunTerminationReason as wt, BridgeRequest as x, USER_PROFILE_EXPORT_VERSION as xn, scriptToolName as xr, RunSnapshot as xt, BridgeCapabilities as y, TraceRecorder as yn, schemaSourceLabel as yr, RunLimitErrorDetails as yt, FsRunSnapshotStore as z, buildRenderResult as zn, SchemaInferer as zt };