@webskill/sdk 0.20.0 → 0.22.0

package/dist/{index-BDyXe-a5.d.ts → index-YPd8ZSEa.d.ts}

@@ -1,4 +1,4 @@
-import { At as ValidationReport, B as DiscoveryResult, K as JsonSchema, Nt as WebSkillErrorCode, O as UiSurfaceActionRequest, Ot as UiSpecNode, S as UiBridge, T as UiSpecEvent, U as FileSystemProvider, X as PageQuery, Y as Page, Z as RemoteUrlPolicy, _ as LlmToolSpec, _t as SkillManifest, b as RenderResultRequest, d as LlmContentPart, dt as SkillDiscovery, f as LlmMessage, ft as SkillDocument, g as LlmToolCall, h as LlmTokenUsage, i as FormField, l as LlmClient, lt as SkillCatalog, m as LlmStreamEvent, n as ArtifactStore, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, r as ChartSpec, s as InteractionRequest, t as Artifact, u as LlmCompleteInput, ut as SkillCatalogEntry, v as MemoryStore, w as UiSpecDrafts, y as RenderBlock } from "./types-Btpdd1y--BcxQ10Fa.js";
+import { Ft as ValidationReport, H as DiscoveryResult, K as FileSystemProvider, Nt as UiSpecNode, O as UiSurfaceActionRequest, Rt as WebSkillErrorCode, S as UiBridge, St as SkillManifest, T as UiSpecEvent, X as JsonSchema, _ as LlmToolSpec, _t as SkillDocument, b as RenderResultRequest, d as LlmContentPart, et as Page, f as LlmMessage, g as LlmToolCall, gt as SkillDiscovery, h as LlmTokenUsage, ht as SkillCatalogEntry, i as FormField, l as LlmClient, m as LlmStreamEvent, mt as SkillCatalog, n as ArtifactStore, nt as RemoteUrlPolicy, o as InteractionPolicy, p as LlmResponse, r as ChartSpec, s as InteractionRequest, t as Artifact, tt as PageQuery, u as LlmCompleteInput, v as MemoryStore, vt as SkillInstallSource, w as UiSpecDrafts, y as RenderBlock } from "./types-CpDRZ0rA-BM5FI9oN.js";
 //#region ../runtime/dist/index.d.ts
 //#region src/llm/parts.d.ts
 /** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
@@ -6,6 +6,97 @@ declare const textParts: (text: string) => LlmContentPart[];
 /** 取出 parts 中的文本（非文本分片在纯文本语境下无法表达，此处按丢弃处理——调用方须先校验） */
 declare const partsToText: (parts: readonly LlmContentPart[] | undefined) => string;
 //#endregion
+//#region src/spreadsheet/types.d.ts
+/**
+ * 表格导出契约（0.21.0 分册 10 FR-10.2）。
+ *
+ * 这份契约是**三处同源**的唯一事实源：`export_spreadsheet` 的参数 schema、
+ * `context.writeSpreadsheet` 的入参、编码器的输入。
+ */
+/** 单元格取值。`null` / `undefined` / `''` 三者同义，均产出空单元格（DV-3） */
+type SpreadsheetCell = string | number | boolean | null | undefined;
+interface SpreadsheetSheet {
+  /** 工作表名。Excel 限制：1–31 字符，且不含 `: \ / ? * [ ]` */
+  name: string;
+  /** 表头文本。给了就作为首行并加粗；不给则首行即数据 */
+  columns?: string[];
+  /** 数据行。每行长度不必与 `columns` 相等，短则补空 */
+  rows: SpreadsheetCell[][];
+  /**
+   * 嵌入本表的图片（0.22.0 分册 20 FR-20.1）。逐表独立。
+   *
+   * **不承载字节**：这份规格是跨沙箱桥的 JSON 契约，字节由 `ref` 解析得到（FR-20.3）。
+   */
+  images?: SpreadsheetImage[];
+}
+/**
+ * 图片锚点。行列按 **Excel 口径从 1 起**，与校验错误信息里的行号同一口径：
+ * 存在 `columns` 时表头占第 1 行，数据第 n 行的锚点行号即 `n + 1`（FR-20.4）。
+ */
+interface SpreadsheetImageAnchor {
+  row: number;
+  column: number;
+}
+interface SpreadsheetImage {
+  /**
+   * 图片引用。前缀族与投放通道的 `data-webskill-image` 同一套（FR-20.2）——
+   * 但**编码器不认识前缀**：它只把 `ref` 交给解析出口，认不认得由解析那一层说了算。
+   */
+  ref: string;
+  anchor: SpreadsheetImageAnchor;
+  /** 显示宽度（px）。锚点所在列的列宽由它推导（FR-20.5） */
+  width: number;
+  /** 显示高度（px）。锚点所在行的行高由它推导 */
+  height: number;
+  /** 无障碍描述，写进 xlsx 的 drawing 描述位 */
+  alt?: string;
+}
+/** 解析出来的图片字节。`contentType` 决定 xlsx 里 media 条目的扩展名 */
+interface SpreadsheetImageBytes {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+}
+/**
+ * 引用 → 字节的解析出口（FR-20.3）。
+ *
+ * 由调用方提供，**不写进编码器内部**：编码器至今不认识产物、run 与工具，
+ * 0.21.0 AC-10.8「双消费面逐字节相同」靠这一点结构性成立。
+ * 解析不到时返回 `undefined`，由编码器归因成带定位的 `VALIDATION_FAILED`（FR-20.9）。
+ */
+type SpreadsheetImageResolver = (ref: string) => Promise<SpreadsheetImageBytes | undefined>;
+interface SpreadsheetSpec {
+  sheets: SpreadsheetSheet[];
+}
+/** 规模上限（FR-10.7）。越界一律 `VALIDATION_FAILED`，不静默截断 */
+declare const SPREADSHEET_LIMITS: {
+  readonly sheets: 16;
+  readonly rowsPerSheet: 10000;
+  readonly columnsPerSheet: 256;
+  /** Excel 对单个单元格文本的硬限制 */
+  readonly charsPerCell: 32767;
+  readonly bytes: number;
+  /**
+   * 单张图片的字节上限（FR-20.6）。在解析后、编码前查，
+   * 好过让调用方等整包编码完才被告知超了 16 MB 的总顶。
+   */
+  readonly imageBytes: number;
+  /** 单表图片张数上限；与行数上限同性质，防止一次编码退化成几千次解析 */
+  readonly imagesPerSheet: 2000;
+};
+declare const SPREADSHEET_MIME_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+declare const SPREADSHEET_EXTENSION = ".xlsx";
+/**
+ * 本版**不支持**的 xlsx 能力（FR-10.8，备案 D75）。
+ *
+ * 导出这张表是为了让上层能如实向用户/模型声明缺什么，而不是笼统写「基础支持」——
+ * 与 `XLSX_UNEXTRACTED` 同一条口径。
+ *
+ * `'images'` 已于 0.22.0 分册 20 移出。`'column-widths'` **仍在**：
+ * 那一册只让图片锚点所在的行列拿到够用的尺寸，没有开放通用的行高列宽 API（FR-20.5）。
+ */
+declare const XLSX_UNSUPPORTED: readonly ["cell-styles", "fonts-and-colors", "borders", "formulas", "merged-cells", "charts", "comments", "date-and-time-cell-types", "column-widths", "frozen-panes", "auto-filter", "incremental-edit-of-existing-file"];
+type XlsxUnsupportedFeature = (typeof XLSX_UNSUPPORTED)[number];
+//#endregion
 //#region src/tools/types.d.ts
 interface ToolDefinition {
   /** LLM 可见名：脚本工具为 `${skillName}__${scriptName}` */
@@ -49,13 +140,23 @@ declare const TEXT_BUDGETED_CONTENT_TYPES: ReadonlySet<string>;
  */
 declare const DEFAULT_MAX_DOCUMENT_BYTES = 25600000;
 /**
- * `document-text` 分片的上限（FR-23.4）。
+ * `document-text` 分片的上限（FR-23.4；值由 0.22.0 分册 15 修订）。
+ *
+ * 它是一道**闸门**，不是配额：抽出来的文本整段进上下文，超了整份拒绝、绝不截断。
+ * 抬高它不会让任何一份文档变大，只在「正文落在新旧值之间」时改变行为。
+ *
+ * 原值 500 KB 的依据是「按英文 4 字节/token 折算 ≈ 128K token，占 200K 窗口的多半」。
+ * 那个依据有两处站不住：中文 UTF-8 约 4.5 字节/token，按英文口径设闸对中文偏紧；
+ * 而窗口是宿主选的模型决定的，SDK 替宿主假定一个 2026 年初的典型值，
+ * 代价由「模型明明装得下却被拒绝」的用户承担——他们从提示里看不出这一点（FR-15.1）。
  *
- * 约束来自**上下文窗口**而不是请求大小：抽出来的文本要整段进上下文。
- * 按英文约 4 字节/token 折算，500 KB ≈ 128K token，占 200K 窗口的多半，
- * 给历史消息与模型的回答留下其余。
+ * 新值之下，超窗口的失败由 provider 报出而不再由 SDK 提前拦截，这是分册 15 有意的取舍：
+ * 误拒浪费的是一次**本可成功**的请求，provider 拒收浪费的是一次**必然失败**的请求。
+ * SDK 不做请求体总量预检——那需要知道每个 provider 的窗口与分词口径，又回到「替宿主假定」。
+ *
+ * 取 1024 的整数倍：设置界面按 KB 展示（5 120 000 = 5000 KB）。
  */
-declare const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 512000;
+declare const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 5120000;
 /**
  * 单次 fetchData 结果的字节上限（分册 16，FR-16.6）：1000 KB。
  * 结构化数据不是文档，量级差一个数量级；超出**只拒不截**——截断的 JSON 解不出来。
@@ -171,6 +272,18 @@ interface ScriptExecutionContext {
     mimeType?: string;
     metadata?: Record<string, unknown>;
   }): Promise<Artifact>;
+  /**
+   * 把表格规格编码为 xlsx 并写成 run 产物（0.21.0 分册 10 FR-10.4）。
+   *
+   * 编码跑在**宿主侧**：沙箱产物里没有编码器，桥上传的是规格而不是几百 KB 的
+   * `number[]`，产物字节因此也不可能由脚本伪造。
+   * `mimeType` 由实现固定，调用方无从覆盖；`options.metadata` 透传给 `writeArtifact`，
+   * 所以 `resultCard: false` 对它同样生效。
+   * 宿主未装配即整个键不存在（同 fetchData / documentSurface）。 @experimental
+   */
+  writeSpreadsheet?(path: string, spec: SpreadsheetSpec, options?: {
+    metadata?: Record<string, unknown>;
+  }): Promise<Artifact>;
   /**
    * 按**宿主声明的 sourceId** 取数（FR-16.1）。脚本给不了 URL——
    * 目标由宿主在 `DataSourceDef.target` 里写死，这就是「唯一授权面」。
@@ -501,6 +614,11 @@ declare function createScriptContext(deps: {
    * 脚本 `typeof context.documentSurface` 即可探测。
    */
   documentSurface?: boolean;
+  /**
+   * 宿主允许技能写表格产物（分册 10 FR-10.4）。传 `false` 与不传同义。
+   * 它不是一个新能力，是 `writeArtifact` 的一个便利入口——授权与开关都走那一位（DV-7）。
+   */
+  writeSpreadsheet?: boolean;
   /**
    * 本次 run 可读的用户上传文件（分册 17）。传进来的 `read` **已经过授权与预算**：
    * 把守在引擎侧只做一遍，四个执行器才不会各自实现一套而出现不一致。
@@ -563,6 +681,16 @@ type ExecuteLifecycleData = {
   kind: 'surface-action-resumed';
   surfaceId: string;
   actionId: string;
+} |
+/**
+ * 视觉委派的逐张进度（分册 26 FR-26.9）。只在委派进行中发，不进 trace：
+ * 它是过程指示，不是结果的一部分。`source` 是触发取图的工具名。
+ */
+{
+  kind: 'vision-progress';
+  source: string;
+  done: number;
+  total: number;
 };
 /** interact 相位：脚本发起的交互请求，或声明式 surface 上的动作等待 */
 type InteractLifecycleData = {
@@ -693,6 +821,11 @@ interface AgentLoopConfig {
   maxDocumentTextBytes?: number;
   /** `read_linked_document` 的出站准入策略；与脚本取数共用同一个判定（AC-G23） */
   remoteUrl?: RemoteUrlPolicy;
+  /**
+   * 视觉委派的并发度（默认 2，上限 3，分册 26 FR-26.5）。
+   * 越界一律夹取而不报错：这是性能旋钮，配错了应该退化成能用，不是让 run 失败。
+   */
+  visionConcurrency?: number;
 }
 /** 技能状态拦截 port（治理装配；无注入默认全放行） */
 interface SkillStateGuard {
@@ -830,6 +963,38 @@ declare function schemaToForm(schema: JsonSchema, providedArgs?: Record<string,
  * 实现在 `browser`，两者的公共下游只有 `core` 与 `runtime`，
  * 而 `runtime/interaction` 已经是 surface 协议的归属地。
  */
+/**
+ * 一张已解析图片的**实测事实**（0.22.0 FR-11.14）。
+ *
+ * 尺寸只能由宿主侧实测得出，不得取自创作模型里的图片块：块的内容来自模型，
+ * 拿它去算预算等于让被限制方自报限额（`{ width: 1 }` 就能把像素维度关掉）。
+ * @experimental
+ */
+interface ViewerImageFact {
+  /** 图片在创作模型里的引用，进拒绝消息与丢图归因 */
+  ref: string;
+  /** 实测像素宽 */
+  width: number;
+  /** 实测像素高 */
+  height: number;
+  /** 这张图在载荷里占的 UTF-16 code unit 数（即填进 `src` 的 data URL 长度） */
+  units: number;
+}
+/**
+ * 一张没能进到文档里的图（0.22.0 FR-11.8 / AC-G3）。
+ *
+ * 三处产生点共用同一个形状：解析、DOCX 编码、PPTX 编码。
+ * `alt` 一并带出来，是因为归因要给人看，而 `ref` 对用户是一串无意义的产物名。
+ * @experimental
+ */
+interface ImageOmission {
+  ref: string;
+  alt: string;
+  /** 丢在哪一环 */
+  stage: 'resolve' | 'encode-docx' | 'encode-pptx';
+  /** 英文、可执行：说清楚是什么原因，用户据此判断该重取图还是换一张 */
+  reason: string;
+}
 /**
  * 宿主侧的文档投放实现；`@webskill/browser` 的 `createDocumentSurfaceHost` 满足它。
  *
@@ -841,10 +1006,20 @@ interface DocumentSurfaceHost {
   open(input: {
     skillName: string;
     dataSource: string;
+    /**
+     * `data` 是单向下发给 viewer 的结构化数据（`startViewerShell` 的第三个回调收它）。
+     * 外壳一直支持，只是端口类型此前没暴露；DWG 投放（0.22.0 分册 19）必须走它——
+     * 几万个实体的几何塞进 `html` 等于先序列化成几十兆字符再解析回来。
+     */
     document: {
       html: string;
       css?: string;
+      data?: unknown;
     };
+    /** 已填进文档的图片事实；缺省表示这份文档没有图 */
+    images?: readonly ViewerImageFact[];
+    /** 解析阶段丢掉的图；缺省表示一张都没丢 */
+    omissions?: readonly ImageOmission[];
   }): Promise<void>;
 }
 /**
@@ -1227,8 +1402,22 @@ declare class FsArtifactStore implements ArtifactStore {
     metadata?: Record<string, unknown>;
   }): Promise<Artifact>;
   listArtifacts(runId: string): Promise<Artifact[]>;
+  readArtifact(runId: string, path: string): Promise<Uint8Array>;
 }
 //#endregion
+//#region src/spreadsheet/encodeSpreadsheet.d.ts
+/**
+ * 把表格规格编码为 xlsx 字节。
+ *
+ * 纯函数——不认识产物、run 与工具，因此工具、脚本能力、测试三个消费面共用同一份
+ * 实现，AC-10.8「双消费面逐字节相同」是结构性成立的。
+ *
+ * `resolveImage` 是图片引用的解析出口（0.22.0 分册 20 FR-20.3）。它同样不破坏纯函数性：
+ * 给定相同的规格与相同的解析结果，输出逐字节相同。规格里有图片却没给它，是
+ * `VALIDATION_FAILED` 而不是静默出一份缺图的文件（FR-20.9）。
+ */
+declare function encodeSpreadsheet(spec: SpreadsheetSpec, resolveImage?: SpreadsheetImageResolver): Promise<Uint8Array>;
+//#endregion
 //#region src/sandbox/bridgeProtocol.d.ts
 /** 能力桥 RPC 消息类型 + 入站校验（Worker 沙箱 ↔ 宿主；browser/node 共用单一来源） */
 type BridgeRequest = {
@@ -1257,6 +1446,18 @@ type BridgeRequest = {
    * 在这里拒绝只能 `return undefined`，而那会丢掉请求 id 使脚本挂到超时。
    */
   metadata?: unknown;
+} |
+/**
+ * 表格导出（0.21.0 分册 10 FR-10.5）。桥上传的是**规格**不是字节：
+ * 编码器留在宿主侧，沙箱产物里没有它，二进制也不必退化成 number[] 传一遍。
+ */
+{
+  kind: 'writeSpreadsheet';
+  id: string;
+  path: string;
+  /** `SpreadsheetSpec` 的 JSON 形态。**不可信载荷**，形状判定在宿主侧的编码器里 */
+  spec: unknown;
+  metadata?: unknown;
 } | {
   kind: 'confirm';
   id: string;
@@ -1458,11 +1659,22 @@ declare const SUPPORTED_DOCUMENT_MIME: {
   readonly pdf: "application/pdf";
   readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
   readonly xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  readonly pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation";
 };
+/**
+ * 读到就**只留字节**的类型（0.22.0 FR-19.9b）：不抽文本，也不作为 `file` 分片外发，
+ * 模型只拿到取件号。DWG 是第一例——17 MB 图纸 base64 进请求体既烧穿预算又毫无意义，
+ * 几何该交给解析器。服务端常把 `.dwg` 发成 `application/octet-stream`，所以按扩展名兜底。
+ */
+declare const BYTES_ONLY_DOCUMENT_MIME: readonly ["image/vnd.dwg", "application/acad", "application/x-acad", "application/dwg", "application/x-dwg", "drawing/dwg"];
+/** 只按字节留存的判定。`url` 只在 MIME 说不清时用到 @experimental */
+declare function isBytesOnlyDocument(mime: string, url: string): boolean;
 /** docx 抽取实现由宿主注入（`DOMParser` 是浏览器 API，Node 没有；备案 D55） */
 type DocxTextExtractor = (bytes: Uint8Array) => Promise<string>;
 /** xlsx 抽取实现由宿主注入（0.13.0 FR-12.5；限制与 docx 相同） */
 type XlsxTextExtractor = (bytes: Uint8Array) => Promise<string>;
+/** pptx 抽取实现由宿主注入（0.22.0 分册 18；限制与 docx 相同） */
+type PptxTextExtractor = (bytes: Uint8Array) => Promise<string>;
 /**
  * PDF → 文本（0.13.0 FR-22.1）。**只用于直传被端点拒后的回退**，
  * 不改变 PDF 默认直传的路径。SDK 不带实现：正确取到文本层要处理
@@ -1482,6 +1694,70 @@ declare const READ_LINKED_DOCUMENT_TOOL: ToolDefinition;
 /** 二进制转 base64；`btoa` 只吃 latin1，必须逐字节喂而不是先 decode 成字符串 */
 declare function toBase64(bytes: Uint8Array): string;
 //#endregion
+//#region src/engine/visionDelegate.d.ts
+/**
+ * 视觉委派注入位（0.21.0 分册 17 · FR-17.11a）。
+ *
+ * 形状与 `PdfTextExtractor` 同类：环境无关、不注入即无此能力、逐层透传。
+ * 引擎只负责「什么时候该委派、预算够不够、失败怎么说」，
+ * **选哪个端点、要不要征得用户同意、怎么留痕**全在宿主实现里——
+ * 那些都要读 `RuntimeConfig` 与界面语言，运行时看不见也不该看见。
+ */
+/** 交给视觉端点的一张图；`data` 是 base64，与 `LlmImagePart` 同口径 */
+interface VisionDelegateImage {
+  readonly mimeType: string;
+  readonly data: string;
+}
+interface VisionDelegateRequest {
+  /** 本轮要认的全部图。**一次调用**认完，不逐张发（FR-17.3a） */
+  readonly images: readonly VisionDelegateImage[];
+  /**
+   * 当轮任务文本：本轮用户输入。**不含完整对话历史**（FR-17.3b）——
+   * 把历史全带上等于把整段对话也交给了第二个厂商。
+   */
+  readonly task: string;
+  /** 触发取图的工具名，用于留痕里的「触发来源」（FR-17.6） */
+  readonly source: string;
+  /**
+   * 这张图所属的整批。逐张调用是并发的需要（FR-26.5），但用户看到的是**一次委派**：
+   * 授权卡上的张数得是整批的张数，整批也只该问一次（FR-26.8）。
+   * 缺席时按「这一次调用就是一整批」处理。
+   */
+  readonly batch?: {
+    readonly id: string;
+    readonly total: number;
+  };
+  /** 本次委派的时间预算，已与父运行剩余时长取小（FR-17.4a） */
+  readonly timeoutMs: number;
+  /** 超时或父 run 被取消时触发；实现必须把它传给底层请求 */
+  readonly signal: AbortSignal;
+}
+/**
+ * 委派结果。用判别联合而不是「文本 + 可选字段」：
+ * 面向模型的措辞归引擎统一拼（AGENTS.md §1），宿主只回报发生了什么。
+ */
+type VisionDelegateResult = {
+  readonly outcome: 'described';
+  readonly endpoint: string;
+  readonly text: string;
+} | {
+  readonly outcome: 'declined';
+} | {
+  readonly outcome: 'failed';
+  readonly reason: string;
+};
+interface VisionDelegate {
+  /**
+   * 当前是否需要把工具产出的图交给第二个端点认。
+   * **每次调用时读配置**：用户中途换成支持图像的模型，下一轮就该回到直传。
+   *
+   * 用户同意与否**不在这里判**：在用户作出选择之前不得发出任何请求（FR-17.7b），
+   * 而「问不问」本身取决于有没有图可认——所以同意在 `describe` 里把关。
+   */
+  applies(): Promise<boolean>;
+  describe(request: VisionDelegateRequest): Promise<VisionDelegateResult>;
+}
+//#endregion
 //#region src/engine/toolStep.d.ts
 /**
  * 一次工具调用的**未截断**参数留存（分册 30 / FR-30.2）。
@@ -1552,6 +1828,27 @@ declare class FsToolStepStore implements ToolStepStore {
  * **不影响可执行性**——要限制访问的宿主应当使用禁用（各来源自己的 enabled 通道）。
  */
 type ToolDisclosure = 'always' | 'on-demand';
+/**
+ * run 内暂存的一份原始字节（0.22.0 FR-19.9b）。
+ *
+ * 存在的理由：有些文件**字节有用、内容不该进上下文**——DWG 图纸是第一例。
+ * 把它当 `file` 分片 base64 发出去既烧穿预算又毫无意义，几何该交给解析器而不是模型。
+ * 于是 `read_linked_document` 把字节留在这里，只回一个取件号。
+ * @experimental
+ */
+interface RunBinaryEntry {
+  readonly name: string;
+  readonly mimeType: string;
+  readonly bytes: Uint8Array;
+}
+/**
+ * 取件号 → 字节。**只读**：写入是引擎的事，工具源拿得到写口就会出现
+ * 「谁都能往 run 里塞字节」的第二个事实源。
+ * @experimental
+ */
+interface RunBinaryStore {
+  get(id: string): RunBinaryEntry | undefined;
+}
 /**
  * 一次工具调用的调用侧上下文（0.14.0 分册 22 FR-22.5）。
  *
@@ -1562,6 +1859,19 @@ type ToolDisclosure = 'always' | 'on-demand';
  */
 interface ToolCallContext {
   readonly runId: string;
+  /**
+   * run 的取消信号（0.21.0 分册 22 · FR-22.15）。`cancel()` 与 `totalTimeoutMs`
+   * 硬期限共用同一个 controller，所以这一个字段两件事都覆盖。
+   *
+   * 加它是因为长跑工具（逐页渲染 PDF 并逐张送多模态识别）在用户点停之后
+   * 没有任何别的办法知道该收手。不读它的工具源行为完全不变。
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * 本 run 暂存的原始字节（0.22.0 FR-19.9b）。随 run 结束一起丢弃——
+   * 它是「这一轮对话里读到的东西」，不是文件系统。
+   */
+  readonly binaries?: RunBinaryStore;
 }
 /**
  * 外部工具来源（runtime 扩展点，mcp 包实现并插入）。
@@ -1747,11 +2057,17 @@ interface AgentLoopDeps {
   /** docx → 文本；`DOMParser` 是浏览器 API，因此由宿主注入（Node 侧无此能力，备案 D55） */
   docxExtractor?: DocxTextExtractor;
   xlsxExtractor?: XlsxTextExtractor;
+  pptxExtractor?: PptxTextExtractor;
   /**
    * PDF → 文本（FR-22.1）。**只在直传被端点拒后用作回退**，不改变 PDF 默认直传。
    * 不注入即没有回退能力，失败照报——与 docx / xlsx「不注入即没这个能力」同款。
    */
   pdfExtractor?: PdfTextExtractor;
+  /**
+   * 视觉委派（0.21.0 分册 17 · FR-17.11a）。选中模型看不了图时，把**工具产出**的图
+   * 交给第二个端点认一遍。不注入即无此能力，工具产出的图照旧直接投给主模型。
+   */
+  visionDelegate?: VisionDelegate;
   /** 文档读取留痕出口（FR-22.6）；不注入即不留痕，装配方要自己承担这个选择 */
   documentAudit?: {
     append(event: {
@@ -1765,6 +2081,12 @@ interface AgentLoopDeps {
    * 投放本身靠用户手势触发，脚本拿到端口也只会得到一个必然被拦的弹窗。
    */
   documentSurface?: true;
+  /**
+   * 宿主开放 `context.writeSpreadsheet`（0.21.0 分册 10 FR-10.4）。
+   * 不传即键不存在，技能能提前分支而不是调完才拿到运行时错误；
+   * 开了也仍然要过 `writeArtifact` 的能力开关与授权卡（DV-7）。
+   */
+  writeSpreadsheet?: true;
   /**
    * 本次 run 触发消息带上来的用户上传文件（0.15.0 分册 17）。
    * 由 `runtime.run(prompt, { uploadFiles })` 逐 run 传入，因此子 run 天然拿不到。
@@ -1959,8 +2281,11 @@ interface WebSkillRuntimeDeps {
   docxExtractor?: DocxTextExtractor;
   /** xlsx → 文本；不注入即 Excel 工作簿明确报「本环境不支持」（FR-12.5） */
   xlsxExtractor?: XlsxTextExtractor;
+  pptxExtractor?: PptxTextExtractor;
   /** PDF → 文本；**只在直传被端点拒后做回退**，不注入即没有回退能力（FR-22.1） */
   pdfExtractor?: PdfTextExtractor;
+  /** 视觉委派（0.21.0 分册 17 FR-17.11a）；不注入即工具产出的图照旧直接投给主模型 */
+  visionDelegate?: VisionDelegate;
   /** 文档读取留痕出口（FR-22.6） */
   documentAudit?: {
     append(event: {
@@ -1971,6 +2296,8 @@ interface WebSkillRuntimeDeps {
   };
   /** 宿主具备文档投放面（0.15.0 分册 13 FR-13.4）；只是能力位，端口本体不进脚本上下文 */
   documentSurface?: true;
+  /** 宿主开放 `context.writeSpreadsheet`（0.21.0 分册 10 FR-10.4）；授权仍走 writeArtifact 那一位 */
+  writeSpreadsheet?: true;
   /** 上传文件读取留痕出口（0.15.0 分册 17 FR-17.7）；批准与拒绝都写 */
   uploadFileAudit?: {
     append(event: {
@@ -2004,10 +2331,25 @@ declare class WebSkillRuntime {
    * 既有 runtime.run(prompt) 保持无状态单次语义不变。
    * 同 handle 并发 run 经 per-handle 队列串行化（防历史 last-writer-wins 丢轮次）；
    * maxHistoryMessages（默认取 `DEFAULT_LOOP_LIMITS`）超出时滚动裁剪中段（保留首尾；边界对齐 tool 契约）。
+   *
+   * 配了 `contextWindow` 时另加一道**主动压缩**（分册 20 FR-20.6）：按上一轮的真实
+   * `prompt_tokens` 与窗口的比值判定，超阈值就在下一轮发起前把最早的一段摘要掉。
+   * 三个输入（窗口、用量、足够长的历史）缺一不压——不估算、不猜。
    */
   createSession(options?: {
     sessionId?: string;
     maxHistoryMessages?: number;
+    /** 该会话所用模型的上下文窗口（token）；缺省即不压缩 */
+    contextWindow?: number;
+    /** 触发比例，默认 `DEFAULT_COMPACTION_THRESHOLD` */
+    compactionThreshold?: number;
+    /** 压缩后至少保留的原文消息数，默认 12，下界 6 */
+    keepRecentMessages?: number;
+    /** 压缩留痕出口（FR-20.8）；只在真的压了之后调 */
+    onCompacted?: (info: {
+      removed: number;
+      kept: number;
+    }) => void;
   }): RuntimeSessionHandle;
   discover(): Promise<DiscoveryResult>;
   run(userPrompt: string | readonly LlmContentPart[], options?: {
@@ -2201,6 +2543,14 @@ interface RunUsageSummary {
   inputTokens?: number;
   /** 各轮 llm.usage 的输出 token 合计；缺省语义同 inputTokens */
   outputTokens?: number;
+  /**
+   * **最后一轮** llm.usage 的输入 token：本 run 结束时的上下文水位线（分册 20 FR-20.5）。
+   *
+   * 与 `inputTokens` 不是一回事——后者是各轮相加，一次 run 调三轮就把同一段历史数了三遍，
+   * 回答的是「这次花了多少」；水位线回答的是「上下文占了多少」。历史在 run 内只增不减，
+   * 所以末轮即水位。缺省语义同上。
+   */
+  lastInputTokens?: number;
 }
 /**
  * 从 run 的 trace 聚合大模型用量（请求次数 + 输入/输出 token）。
@@ -2348,4 +2698,60 @@ interface RedactedArgs {
  */
 declare function redactToolStepArgs(args: Record<string, unknown>, schema: JsonSchema | undefined, trust: ToolStepTrust): RedactedArgs;
 //#endregion
-export { IntegrityVerdict as $, diffUserProfile as $n, SessionMeta as $t, DEFAULT_USER_PROFILE_LIMITS as A, USER_PROFILE_EXPORT_VERSION as An, schemaSourceLabel as Ar, RunToolCall as At, FS_SESSION_PAGE_SIZE as B, UserProfileImportDiff as Bn, toVercelToolSpecs as Br, RuntimeSession as Bt, CapabilityApproval as C, ToolStepTrust as Cn, readProfileEntries as Cr, RouteResult as Ct, DEFAULT_MAX_DOCUMENT_BYTES as D, TraceRecorder as Dn, renderUserProfileContext as Dr, RunSnapshotListEntry as Dt, DEFAULT_MAX_DATA_SOURCE_BYTES as E, TraceEventType as En, refineUserProfile as Er, RunSnapshot as Et, EMPTY_USER_PROFILE as F, UnsupportedRunSnapshot as Fn, summarizeToolCalls as Fr, RunTraceSummary as Ft, FsSessionStore as G, WebSkillRuntimeDeps as Gn, SchemaInferer as Gt, FsMemoryStore as H, VercelToolSpec as Hn, validateUiSpecNode as Hr, SENSITIVE_ANNOTATION as Ht, EventBus as I, UploadFileInfo as In, textParts as Ir, RunUploadFiles as It, GoogleGenAiClient as J, applyUserProfileImport as Jn, SealOptions as Jt, FsToolStepStore as K, XlsxTextExtractor as Kn, ScriptExecutionContext as Kt, ExecuteLifecycleData as L, UserProfile as Ln, toBase64 as Lr, RunUsageSummary as Lt, DocumentSurfaceHost as M, USER_PROFILE_NO_INVENTION_RULE as Mn, scriptToolName as Mr, RunTraceFilter as Mt, DocumentSurfacePort as N, USER_PROFILE_PROMPT_HEADER as Nn, sealToolCallPairs as Nr, RunTraceMetrics as Nt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as O, UNSUPPORTED_DOCUMENT_MESSAGE as On, resolveToolName as Or, RunSnapshotStore as Ot, DocxTextExtractor as P, USER_PROFILE_REFINE_PROMPT as Pn, summarizeRunUsage as Pr, RunTraceStore as Pt, InstalledSkillManifest as Q, createWebSkillApi as Qn, SessionListPage as Qt, ExternalSkillProvider as R, UserProfileEntry as Rn, toLlmToolSpec as Rr, RuntimePhase as Rt, BridgeResponse as S, ToolStepStore as Sn, readBehaviorRecords as Sr, RouteLifecycleData as St, DEFAULT_LOOP_LIMITS as T, TraceEvent as Tn, redactToolStepArgs as Tr, RunResult as Tt, FsRunSnapshotStore as U, WebSkillApi as Un, SESSION_SCHEMA_VERSION as Ut, FsArtifactStore as V, UserProfileLimits as Vn, validateUiSpecEvent as Vr, RuntimeSessionHandle as Vt, FsRunTraceStore as W, WebSkillRuntime as Wn, SUPPORTED_DOCUMENT_MIME as Wt, HookRunner as X, buildRenderResult as Xn, SealResult as Xt, GoogleGenAiClientConfig as Y, bridgeError as Yn, SealRecord as Yt, HookRunnerOptions as Z, createScriptContext as Zn, SerializingMemoryStore as Zt, BehaviorRecordKind as _, ToolDisclosure as _n, normalizeToolContent as _r, READ_SKILL_FILE_TOOL_NAME as _t, ASK_USER_TOOL as a, SkillRouter as an, formatSkillScriptManifest as ar, LifecycleListener as at, BridgeCapability as b, ToolStepReader as bn, parseUserProfileExport as br, RedactedArgs as bt, AgentLoop as c, SkillStateGuard as cn, interruptedToolResult as cr, NetworkPolicy as ct, AnthropicClient as d, TerminalLifecycleData as dn, listSkillScripts as dr, PdfTextExtractor as dt, SessionRecord as en, exportUserProfile as er, InteractLifecycleData as et, AnthropicClientConfig as f, TextualToolContent as fn, mergeCatalogEntries as fr, ProgressiveRouter as ft, BehaviorRecord as g, ToolDefinition as gn, normalizeErrorCode as gr, READ_SKILL_FILE_TOOL as gt, BEHAVIOR_RECORDS_KEY as h, ToolContent as hn, networkUrlHost as hr, READ_SKILL_FILE_INPUT_SCHEMA as ht, ASK_USER_MAX_FIELDS as i, SkillOutcomeReporter as in, findUnpairedToolCalls as ir, LifecycleHookContext as it, DataSourceInfo as j, USER_PROFILE_KEY as jn, schemaToForm as jr, RunTraceFile as jt, DEFAULT_MAX_UPLOAD_FILE_BYTES as k, UPLOAD_FILES_UNAVAILABLE as kn, sampleBehaviorRecords as kr, RunTerminationReason as kt, AgentLoopConfig as l, SkillSuccessReport as ln, isNetworkAllowed as lr, OpenAiCompatibleClient as lt, ApprovalScope as m, ToolCallContext as mn, networkPolicyLibSource as mr, READ_LINKED_DOCUMENT_TOOL_NAME as mt, ASK_USER_FIELD_TYPES as n, SkillFailureReport as nn, extractTodoTraceEvents as nr, LifecycleEventInit as nt, ASK_USER_TOOL_NAME as o, SkillScriptDescriptor as on, fromVercelResult as or, LinkedDocumentReader as ot, ApprovalDecision as p, TodoTraceEvent as pn, mergeProfileEntries as pr, READ_LINKED_DOCUMENT_TOOL as pt, FullDisclosureRouter as q, appendBehaviorRecords as qn, ScriptExecutor as qt, ASK_USER_INPUT_SCHEMA as r, SkillIntegrityGuard as rn, extractUiSpecEvents as rr, LifecycleHook as rt, ActivateLifecycleData as s, SkillScriptSchemaSource as sn, fromVercelStreamPart as sr, MAX_TOOL_STEP_ARG_BYTES as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, SessionStore as tn, extractChartSpec as tr, LifecycleEvent as tt, AgentLoopDeps as u, TEXT_BUDGETED_CONTENT_TYPES as un, isUnsupportedRunSnapshot as ur, OpenAiCompatibleClientConfig as ut, BehaviorScene as v, ToolResolution as vn, normalizeToolError as vr, RUN_SNAPSHOT_SCHEMA_VERSION as vt, CapabilityMode as w, TraceClock as wn, readUserProfile as wr, RunLimitErrorDetails as wt, BridgeRequest as x, ToolStepRecord as xn, partsToText as xr, RefineUserProfileInput as xt, BridgeCapabilities as y, ToolResult as yn, parseBridgeRequest as yr, RUN_TRACE_SCHEMA_VERSION as yt, ExternalToolSource as z, UserProfileExport as zn, toRecordDigests as zr, RuntimeRun as zt };
+//#region src/engine/visionBatch.d.ts
+/**
+ * 视觉委派的分批并发调度（0.21.0 分册 26 · FR-26.5 ~ FR-26.7）。
+ *
+ * 从 `agentLoop` 里拆出来，是因为它有三条彼此独立的分支——并发、慢降级、失败隔离——
+ * 塞进那个已经三千行的文件里就只能靠端到端测，而这三条恰恰是最需要单独逼出来的。
+ * @experimental
+ */
+/** 并发度上限。再高只会让每一张都变慢，同时把端点的速率限制撞穿（FR-26.5） @experimental */
+declare const VISION_MAX_CONCURRENCY = 3;
+/** @experimental */
+declare const VISION_DEFAULT_CONCURRENCY = 2;
+/**
+ * 超过它就退回串行（FR-26.6）。云端视觉端点单张 3–15 秒，本地 Qwen-VL 一类 20–40 秒；
+ * 越过 25 秒说明端点已经在排队，继续并发只会让第一张有用的描述来得更晚。
+ * @experimental
+ */
+declare const VISION_SLOW_THRESHOLD_MS = 25000;
+/** 配错了应该退化成能用，不是让 run 失败（FR-26.5） @experimental */
+declare function clampVisionConcurrency(value: unknown): number;
+/** @experimental */
+interface VisionBatchOptions {
+  images: readonly VisionDelegateImage[];
+  concurrency: number;
+  slowThresholdMs?: number;
+  /** 单张委派。`index` 只用于报错定位，实现方不必回传 */
+  describe(image: VisionDelegateImage, index: number): Promise<VisionDelegateResult>;
+  /** 每结算一张调一次（FR-26.9），`done` 递增、`total` 恒为总张数 */
+  onProgress?(done: number, total: number): void;
+  /** 父运行取消：置位后不再派发新的一张 */
+  signal?: AbortSignal;
+  now?(): number;
+}
+/** @experimental */
+interface VisionBatchOutcome {
+  /** 与输入等长、逐张对位；`undefined` = 那张没成 */
+  described: (string | undefined)[];
+  /** 端点标识（首个成功的那张给出；一张都没成时缺席） */
+  endpoint?: string;
+  failures: {
+    index: number;
+    reason: string;
+  }[];
+  /** 用户拒绝：对整批有效，剩下的图不再派发 */
+  declined: boolean;
+}
+/**
+ * 逐张委派、按并发度并行。
+ *
+ * 第一波结算后测一次墙钟决定要不要降级：测第一波而不是第一张，
+ * 因为并发下第一张返回得早纯属运气，一波的完成时间才反映端点的实际吞吐。
+ * 降级是**单向**的，本次委派内不再回升。
+ * @experimental
+ */
+declare function runVisionBatch(options: VisionBatchOptions): Promise<VisionBatchOutcome>;
+//#endregion
+export { ImageOmission as $, UserProfileEntry as $n, readProfileEntries as $r, SchemaInferer as $t, DEFAULT_MAX_UPLOAD_FILE_BYTES as A, ToolContent as An, extractChartSpec as Ar, RunResult as At, ExternalToolSource as B, TraceEvent as Bn, isUnsupportedRunSnapshot as Br, RunTraceSummary as Bt, BridgeResponse as C, SpreadsheetSheet as Cn, buildRenderResult as Cr, RedactedArgs as Ct, DEFAULT_MAX_DATA_SOURCE_BYTES as D, TextualToolContent as Dn, diffUserProfile as Dr, RunBinaryEntry as Dt, DEFAULT_LOOP_LIMITS as E, TerminalLifecycleData as En, createWebSkillApi as Er, RouteResult as Et, DocxTextExtractor as F, ToolStepReader as Fn, fromVercelResult as Fr, RunToolCall as Ft, FsRunTraceStore as G, USER_PROFILE_EXPORT_VERSION as Gn, networkUrlHost as Gr, RuntimeSession as Gt, FsArtifactStore as H, TraceRecorder as Hn, mergeCatalogEntries as Hr, RunUsageSummary as Ht, EMPTY_USER_PROFILE as I, ToolStepRecord as In, fromVercelStreamPart as Ir, RunTraceFile as It, FullDisclosureRouter as J, USER_PROFILE_PROMPT_HEADER as Jn, normalizeToolError as Jr, SESSION_SCHEMA_VERSION as Jt, FsSessionStore as K, USER_PROFILE_KEY as Kn, normalizeErrorCode as Kr, RuntimeSessionHandle as Kt, EventBus as L, ToolStepStore as Ln, interruptedToolResult as Lr, RunTraceFilter as Lt, DataSourceInfo as M, ToolDisclosure as Mn, extractUiSpecEvents as Mr, RunSnapshotListEntry as Mt, DocumentSurfaceHost as N, ToolResolution as Nn, findUnpairedToolCalls as Nr, RunSnapshotStore as Nt, DEFAULT_MAX_DOCUMENT_BYTES as O, TodoTraceEvent as On, encodeSpreadsheet as Or, RunBinaryStore as Ot, DocumentSurfacePort as P, ToolResult as Pn, formatSkillScriptManifest as Pr, RunTerminationReason as Pt, HookRunnerOptions as Q, UserProfile as Qn, readBehaviorRecords as Qr, SUPPORTED_DOCUMENT_MIME as Qt, ExecuteLifecycleData as R, ToolStepTrust as Rn, isBytesOnlyDocument as Rr, RunTraceMetrics as Rt, BridgeRequest as S, SpreadsheetImageResolver as Sn, bridgeError as Sr, RUN_TRACE_SCHEMA_VERSION as St, CapabilityMode as T, TEXT_BUDGETED_CONTENT_TYPES as Tn, createScriptContext as Tr, RouteLifecycleData as Tt, FsMemoryStore as U, UNSUPPORTED_DOCUMENT_MESSAGE as Un, mergeProfileEntries as Ur, RuntimePhase as Ut, FS_SESSION_PAGE_SIZE as V, TraceEventType as Vn, listSkillScripts as Vr, RunUploadFiles as Vt, FsRunSnapshotStore as W, UPLOAD_FILES_UNAVAILABLE as Wn, networkPolicyLibSource as Wr, RuntimeRun as Wt, GoogleGenAiClientConfig as X, UnsupportedRunSnapshot as Xn, parseUserProfileExport as Xr, SPREADSHEET_LIMITS as Xt, GoogleGenAiClient as Y, USER_PROFILE_REFINE_PROMPT as Yn, parseBridgeRequest as Yr, SPREADSHEET_EXTENSION as Yt, HookRunner as Z, UploadFileInfo as Zn, partsToText as Zr, SPREADSHEET_MIME_TYPE as Zt, BehaviorRecord as _, toVercelToolSpecs as _i, SkillSuccessReport as _n, XLSX_UNSUPPORTED as _r, READ_LINKED_DOCUMENT_TOOL_NAME as _t, ASK_USER_TOOL as a, runVisionBatch as ai, SerializingMemoryStore as an, VISION_SLOW_THRESHOLD_MS as ar, LifecycleHook as at, BridgeCapabilities as b, SpreadsheetImageAnchor as bn, appendBehaviorRecords as br, READ_SKILL_FILE_TOOL_NAME as bt, AgentLoop as c, schemaToForm as ci, SessionRecord as cn, VisionBatchOptions as cr, LinkedDocumentReader as ct, AnthropicClient as d, summarizeRunUsage as di, SkillIntegrityGuard as dn, VisionDelegateImage as dr, OpenAiCompatibleClient as dt, readUserProfile as ei, ScriptExecutionContext as en, UserProfileExport as er, InstalledSkillManifest as et, AnthropicClientConfig as f, summarizeToolCalls as fi, SkillOutcomeReporter as fn, VisionDelegateRequest as fr, OpenAiCompatibleClientConfig as ft, BYTES_ONLY_DOCUMENT_MIME as g, toRecordDigests as gi, SkillStateGuard as gn, WebSkillRuntimeDeps as gr, READ_LINKED_DOCUMENT_TOOL as gt, BEHAVIOR_RECORDS_KEY as h, toLlmToolSpec as hi, SkillScriptSchemaSource as hn, WebSkillRuntime as hr, ProgressiveRouter as ht, ASK_USER_MAX_FIELDS as i, resolveToolName as ii, SealResult as in, VISION_MAX_CONCURRENCY as ir, LifecycleEventInit as it, DEFAULT_USER_PROFILE_LIMITS as j, ToolDefinition as jn, extractTodoTraceEvents as jr, RunSnapshot as jt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as k, ToolCallContext as kn, exportUserProfile as kr, RunLimitErrorDetails as kt, AgentLoopConfig as l, scriptToolName as li, SessionStore as ln, VisionBatchOutcome as lr, MAX_TOOL_STEP_ARG_BYTES as lt, ApprovalScope as m, toBase64 as mi, SkillScriptDescriptor as mn, WebSkillApi as mr, PptxTextExtractor as mt, ASK_USER_FIELD_TYPES as n, refineUserProfile as ni, SealOptions as nn, UserProfileLimits as nr, InteractLifecycleData as nt, ASK_USER_TOOL_NAME as o, sampleBehaviorRecords as oi, SessionListPage as on, VercelToolSpec as or, LifecycleHookContext as ot, ApprovalDecision as p, textParts as pi, SkillRouter as pn, VisionDelegateResult as pr, PdfTextExtractor as pt, FsToolStepStore as q, USER_PROFILE_NO_INVENTION_RULE as qn, normalizeToolContent as qr, SENSITIVE_ANNOTATION as qt, ASK_USER_INPUT_SCHEMA as r, renderUserProfileContext as ri, SealRecord as rn, VISION_DEFAULT_CONCURRENCY as rr, LifecycleEvent as rt, ActivateLifecycleData as s, schemaSourceLabel as si, SessionMeta as sn, ViewerImageFact as sr, LifecycleListener as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, redactToolStepArgs as ti, ScriptExecutor as tn, UserProfileImportDiff as tr, IntegrityVerdict as tt, AgentLoopDeps as u, sealToolCallPairs as ui, SkillFailureReport as un, VisionDelegate as ur, NetworkPolicy as ut, BehaviorRecordKind as v, validateUiSpecEvent as vi, SpreadsheetCell as vn, XlsxTextExtractor as vr, READ_SKILL_FILE_INPUT_SCHEMA as vt, CapabilityApproval as w, SpreadsheetSpec as wn, clampVisionConcurrency as wr, RefineUserProfileInput as wt, BridgeCapability as x, SpreadsheetImageBytes as xn, applyUserProfileImport as xr, RUN_SNAPSHOT_SCHEMA_VERSION as xt, BehaviorScene as y, validateUiSpecNode as yi, SpreadsheetImage as yn, XlsxUnsupportedFeature as yr, READ_SKILL_FILE_TOOL as yt, ExternalSkillProvider as z, TraceClock as zn, isNetworkAllowed as zr, RunTraceStore as zt };