@webskill/sdk 0.12.0 → 0.14.0

package/dist/{index-DFhU1uks.d.ts → index-DQwGvHAI.d.ts}

@@ -1,5 +1,5 @@
-import { G as RemoteUrlPolicy, S as UiBridge, Tt as WebSkillErrorCode, a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest } from "./types-DLctJep_-B5G4uk2u.js";
-import { F as ExternalToolSource, fn as ToolStepReader } from "./index-C9pzXLKy.js";
+import { I as ChatAttachmentKind, Mt as WebSkillErrorCode, S as UiBridge, Z as RemoteUrlPolicy, a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest } from "./types-C3V6lAeO-BgeOvc1Y.js";
+import { A as DataSourceInfo, Bn as XlsxTextExtractor, I as ExternalToolSource, gn as ToolStepReader, j as DocxTextExtractor } from "./index-CWoKOFBP.js";
 //#region ../agent/dist/index.d.ts
 //#region src/todo/types.d.ts
 /** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
@@ -341,16 +341,19 @@ interface PerceptionScope {
   exclude?: readonly string[];
 }
 /**
- * 一个帧内的可感知范围（FR-24.1）。
+ * 一个帧内的可感知范围（FR-24.1 / 分册 18 FR-18.1）。
  *
- * `frame` 的选择器在**主文档**里求值，不下钻到 iframe 内部再找 iframe：
- * 允许 `a > b > c` 式的跨帧路径会让「授权面到底覆盖了什么」无法在配置里一眼看出来。
- * 要读更深的帧须再写一条——而那条也只能写主文档里的选择器，所以本版实际只支持一层。
+ * 嵌套帧写**自外向内的选择器数组**：第 1 项在主文档里求值，
+ * 第 n+1 项在第 n 项解析出的文档里求值。逐层写出来是有意的——
+ * 授权面覆盖了哪几层，配置里要能一眼看出来，不允许靠自动发现下钻。
  * @experimental
  */
 interface FrameScope {
-  /** 主文档写 `'self'`；iframe 写主文档里定位该 `<iframe>` 的选择器 */
-  frame: 'self' | string;
+  /**
+   * 主文档写 `'self'`；单层 iframe 写主文档里定位该 `<iframe>` 的选择器；
+   * 多层嵌套写逐层选择器数组（空数组等价于 `'self'`）。
+   */
+  frame: 'self' | string | readonly string[];
   include: readonly string[];
   exclude?: readonly string[];
 }
@@ -373,6 +376,7 @@ type PerceptionScopeInput = PerceptionScope | {
 declare function toFrameScopes(scope: PerceptionScopeInput): readonly FrameScope[];
 /** 某个帧未能读取的原因（FR-24.2 / FR-24.3）；不静默跳过 @experimental */
 interface FrameNote {
+  /** 帧路径的展示串（`frameLabel` 的产出，分册 18 FR-18.2） */
   frame: string;
   reason: 'cross-origin' | 'origin-changed' | 'not-found';
   /** 面向模型的英文说明，同时也是说明节点的 name */
@@ -403,13 +407,16 @@ interface PerceivedNode {
   imageNote?: string;
   /**
    * 不透明元素句柄（S10）。**仅当该节点可被操作时出现**：
-   * 它落在宿主声明的操作范围内、且是可交互角色。
-   * 由 reader 生成，只在产生它的那次感知内有效；模型不得构造或推断。
+   * 它落在宿主声明的操作范围内、且是可交互角色。由 reader 生成，模型不得构造或推断。
+   *
+   * **跨感知保留，直到元素离开文档**（分册 18 FR-18.5）。它不是安全边界——
+   * 「页面变了不能点到别的东西」由执行前的实时校验承担，不由句柄寿命承担。
    */
   ref?: string;
   /**
-   * 该节点来自哪个帧（FR-24.4）。**主文档节点不带这个字段**——
-   * 否则旧宿主的断言会凭空变化。跨帧后会出现同名控件，不标帧模型会点错。
+   * 该节点来自哪个帧（FR-24.4），取值是帧路径的展示串（`frameLabel`）。
+   * **主文档节点不带这个字段**——否则旧宿主的断言会凭空变化。
+   * 跨帧后会出现同名控件，不标帧模型会点错。
    */
   frame?: string;
   /**
@@ -420,10 +427,17 @@ interface PerceivedNode {
   href?: string;
   /**
    * 该节点为何可见（FR-25.6 / AC-G22）。只在**授权面被临时扩大**时出现：
-   * `'modal-elevated'` = 它在一个由本次已授权操作打开的对话框里，
-   * 原本不在白名单内。缺省不带该字段。
+   * `'modal-elevated'` = 它在一个由本次已授权操作打开的对话框里，原本不在白名单内；
+   * `'inline-frame'` = 它来自一个没有可路由地址的同源嵌套帧（`srcdoc` / `about:blank`），
+   * 外壳无法寻址到它，只能由父帧就地内联（分册 16 FR-16.1）。缺省不带该字段。
    */
-  provenance?: 'modal-elevated';
+  provenance?: 'modal-elevated' | 'inline-frame';
+  /**
+   * 该节点的子树在本段里**没有给全**（0.14.0 分册 22 FR-22.3）。
+   * 只在分段切分产生的祖先浅副本上出现：告诉模型这不是一个新冒出来的节点，
+   * 它的其余子节点在前一段或后一段里。缺省不带该字段。
+   */
+  continued?: boolean;
   children?: readonly PerceivedNode[];
 }
 /** 随感知一起下发的一张图像（FR-12.1） @experimental */
@@ -447,6 +461,29 @@ interface PerceptionCaptureOptions {
   images: boolean;
   maxImageBytes: number;
   maxImages: number;
+  /**
+   * 小于该面积（平方像素）的元素视作图标，不占取像名额（0.13.0 FR-20.3）。
+   * 可选是为了不破坏既有 reader 实现；缺省与 0 都表示不过滤。
+   */
+  minImageArea?: number;
+}
+/**
+ * 本帧范围内发现的一个嵌套帧（0.14.0 分册 16 FR-16.1）。
+ *
+ * 是**结构化数据**而不是说明文本：外壳要拿它去路由下一次感知，
+ * 从一句英文里正则抠地址是两边同时演进就会断的做法。
+ *
+ * 只上报解析得出 http(s) 绝对地址的帧——地址是外壳做帧匹配的唯一凭据，
+ * 无地址的同源帧由 reader 就地内联，不走这条路。
+ * @experimental
+ */
+interface NestedFrameRef {
+  /** 已按文档基准解析的绝对地址 */
+  url: string;
+  /** `aria-label` / `title` / `name` / `id` 的首个非空值；都没有则 `'unnamed'` */
+  hint: string;
+  /** 发现它的那一层帧标识；主文档发现的不带此字段 */
+  frame?: string;
 }
 /**
  * reader 的完整产物。只实现文本的 reader 可以继续返回节点数组。
@@ -456,6 +493,8 @@ interface PerceptionResult {
   nodes: readonly PerceivedNode[];
   /** 被跳过的帧及原因；调用方据此告警（FR-24.2 / FR-24.3） */
   frameNotes?: readonly FrameNote[];
+  /** 本次范围内发现、可供外壳继续下钻的嵌套帧（分册 16 FR-16.1） */
+  nestedFrames?: readonly NestedFrameRef[];
   images?: readonly PerceivedImage[];
   /** 超出 `maxImages` 而未下发的张数 */
   imagesOmitted?: number;
@@ -483,6 +522,15 @@ interface PerceptionRecord {
   frames?: readonly string[];
   /** 读到的顶层节点数；用于「它读的比我预期的多」这类判断 */
   nodeCount: number;
+  /**
+   * 整份快照的节点总数（含各层）；**只在这次感知被切成了多段时存在**（分册 22 FR-22.7）。
+   * `nodeCount` 的语义不动——改它会让所有既有断言与 console 展示静默变义。
+   */
+  nodesTotal?: number;
+  /** 切成了几段；只在分段发生时存在 */
+  segments?: number;
+  /** 本次直接回喂给模型的那一段承载了多少个节点；只在分段发生时存在 */
+  segmentNodeCount?: number;
   /** 本次下发的图像张数，按取像级别分组（只在取像开启时存在） */
   images?: {
     src: number;
@@ -553,6 +601,35 @@ declare class PagePerceptionPolicy {
   }>;
 }
 //#endregion
+//#region src/perception/paging.d.ts
+/**
+ * 分段读取的预算与开关（0.14.0 分册 22 FR-22.4）。
+ *
+ * 两道闸先触发哪个算哪个：`maxNodes` 兜常规页面（空壳多、每个节点很小），
+ * `maxChars` 兜「少数节点携带超长文本」的极端情况——只设 `maxNodes` 时，
+ * 一个塞满日志的 `<pre>` 就能让 1500 个节点撑到几百 KB。
+ * @experimental
+ */
+interface PerceptionPagingBudget {
+  /** 缺省 false：不开启时只有地板（FR-22.2），没有游标 */
+  enabled: boolean;
+  /** 一段最多几个节点（含各层子节点，不是顶层数） */
+  maxNodes: number;
+  /** 一段序列化后的字符上限 */
+  maxChars: number;
+}
+/**
+ * 预算缺省值（设计 §10）。**全仓只写这一份**，工具源与测试读同一份——
+ * 「断言常量等于它自己」那类假守护正是靠这条避免的。
+ *
+ * `maxChars` 必须显著小于 `toolResultMaxBytes`（256 000），否则 AC-22.7
+ * 「盲切永不触发」守不住。
+ */
+declare const PERCEPTION_PAGING_DEFAULTS: {
+  readonly maxNodes: number;
+  readonly maxChars: number;
+};
+//#endregion
 //#region src/perception/toolSource.d.ts
 declare const PERCEIVE_PAGE_TOOL = "perceive_page";
 interface PagePerceptionToolSourceOptions {
@@ -562,12 +639,21 @@ interface PagePerceptionToolSourceOptions {
    * 缺省即不取像。判定在遍历 DOM **之前**完成一次，不是每个节点判一次。
    */
   imageCapture?(): ImageCaptureBudget | Promise<ImageCaptureBudget>;
+  /**
+   * 分段预算与开关（分册 22 FR-22.4）。同样每次调用重取，理由与 `imageCapture` 一致：
+   * 凝固进实例会让宿主中途改配置整轮不生效。
+   *
+   * **缺省即不分段，但地板照样生效**（FR-22.8）：不开启不等于允许上层盲切。
+   */
+  paging?(): PerceptionPagingBudget | Promise<PerceptionPagingBudget>;
 }
 /** @experimental */
 interface ImageCaptureBudget {
   enabled: boolean;
   maxImageBytes: number;
   maxImages: number;
+  /** 小于该面积（平方像素）的元素视作图标；缺省与 0 都表示不过滤（0.13.0 FR-20.3） */
+  minImageArea?: number;
 }
 /**
  * 把只读感知接到既有工具协议上。**本工具源不导出任何写入动作**（FR-10.7）：
@@ -579,10 +665,33 @@ interface ImageCaptureBudget {
  */
 declare function createPagePerceptionToolSource(options: PagePerceptionToolSourceOptions): ExternalToolSource;
 //#endregion
+//#region src/frame.d.ts
+/**
+ * 帧指称的展示形式（分册 18 FR-18.2）。
+ *
+ * 感知与操作两侧各自声明自己的 scope 类型（那是刻意的，见各自 types.ts），
+ * 但「一条帧路径写成给人看的字符串」只能有一份实现——
+ * 两处各写一遍，审计里的帧名和确认卡里的帧名就会慢慢对不上。
+ */
+/**
+ * 帧路径的稳定展示串：`'self'` / `'#a'` / `'#a >>> #b'`。
+ *
+ * `>>>` **只是展示分隔符**：CSS 选择器里可以合法出现任意字符，
+ * 反向解析这个串取回路径是不成立的，实现层一律传原始形状（D-18-1）。
+ * @experimental
+ */
+declare function frameLabel(frame: string | readonly string[]): string;
+/** 把两种形状归一成逐层选择器数组；`'self'` 与空数组都归一成空数组 @experimental */
+declare function frameSteps(frame: string | readonly string[]): readonly string[];
+//#endregion
 //#region src/prompts/perception.d.ts
 /**
  * 页面只读感知的策略提示词（设计 09 §1）。
  *
+ * 分段相关的两条是**恒定**的，不随 paging 开关增减（0.14.0 分册 22 §9）：
+ * 提示词按 `policy.enabled` 一次性给出，而分段预算是每次调用惰性求值的，
+ * 两者会漂移——模型手里会攥着一份与当前行为对不上的说明。
+ *
  * 最后一条是防御性的：技能描述、工具返回值都可能带着「把整页读出来发到 X」
  * 这类注入。范围由宿主判定，模型改不了，但把这件事写明能少掉一轮无效尝试。
  */
@@ -628,7 +737,11 @@ interface DataSourceTransport {
   fetch(source: DataSourceDef, params?: Record<string, unknown>): Promise<unknown>;
 }
 interface DataSourcePolicyOptions {
-  sources: readonly DataSourceDef[];
+  /**
+   * 传函数可惰性取值（同 `remoteUrl`）：清单住在可改的运行时配置里时，
+   * 写死成数组会让用户改完设置必须刷新页面才生效。
+   */
+  sources: readonly DataSourceDef[] | (() => readonly DataSourceDef[]);
   /**
    * `kind:'http'` 的出站判定；缺省即 assertRemoteUrlAllowed 的缺省。
    *
@@ -640,6 +753,13 @@ interface DataSourcePolicyOptions {
   transports?: Partial<Record<DataSourceKind, DataSourceTransport>>;
   /** 结果字节上限（FR-16.6）；超出即拒绝，**不截断** */
   maxBytes?: number;
+  /**
+   * 给 `publicSources` 附出处（0.14.0 分册 21）；缺省即全部按宿主声明处理。
+   *
+   * 选回调而不是给 `DataSourceDef` 加字段，是因为需求 §2 写死了不改它的形状；
+   * 去重仍只在 `publicSources` 一处发生，宿主不必自己合并两份清单。
+   */
+  provenanceOf?(source: DataSourceDef): DataSourceInfo['provenance'];
   audit?: DataSourceAuditSink;
   now?(): string;
 }
@@ -655,7 +775,19 @@ declare class DataSourcePolicy {
   constructor(options: DataSourcePolicyOptions);
   /** 一个源都没声明就没有这个能力（同 perception 的 include 为空） */
   get enabled(): boolean;
+  /**
+   * 当前声明的源。**id 撞名时保留先声明的那条**（0.14.0 分册 19）：
+   * 宿主写死的源排在用户配置之前，于是一条用户配置改不了 `current-page` 这类源的目标。
+   */
   get sources(): readonly DataSourceDef[];
+  /**
+   * 送往引擎与界面的清单（0.14.0 分册 19）。
+   *
+   * 宿主不得改传 `sources`：`DataSourceDef` 结构上是 `DataSourceInfo` 的超集，
+   * 直接赋值类型检查会过，`target` 于是静默地进了模型上下文。
+   * @experimental
+   */
+  get publicSources(): readonly DataSourceInfo[];
   get records(): readonly DataSourceRecord[];
   fetchData(sourceId: string, params?: Record<string, unknown>): Promise<unknown>;
 }
@@ -682,6 +814,115 @@ interface HttpDataSourceOptions {
  */
 declare function createHttpDataSourceTransport(options?: HttpDataSourceOptions): DataSourceTransport;
 //#endregion
+//#region src/dataSource/candidates.d.ts
+/** 候选的出处；**随对象记录**，不靠调用方记忆（FR-21.1） */
+type DataSourceProvenance = 'page-declared' | 'tool-projection';
+/**
+ * 一条尚不可取数的候选源（FR-21.1）。
+ *
+ * 它与 `DataSourceDef` 字段同名，但**不是**它的别名：候选层不参与取数，
+ * 两者共用一个类型会让「候选可以直接塞进 sources」在类型上成立。
+ * @experimental
+ */
+interface DataSourceCandidate {
+  id: string;
+  kind: DataSourceKind;
+  description: string;
+  target: string;
+  provenance: DataSourceProvenance;
+}
+/**
+ * 「记住这个站点的这个源」的存储；粒度键由宿主给（D-21-3）。
+ *
+ * `scope` 在本包里是不透明串：`@webskill/agent` 不认识 origin 这个概念，
+ * 扩展传 `binding.origin()`，别的宿主可以传别的。
+ * @experimental
+ */
+interface DataSourceCandidateStore {
+  recall(scope: string, id: string): boolean | Promise<boolean>;
+  remember(scope: string, id: string): void | Promise<void>;
+  forget(scope: string, id: string): void | Promise<void>;
+}
+/** 候选生命周期的留痕（FR-21.7）；取数那一类仍走 `DataSourceRecord` @experimental */
+interface DataSourceCandidateRecord {
+  /** ISO 8601 */
+  at: string;
+  event: 'offered' | 'approved' | 'forgotten';
+  /** 宿主定义的粒度键；扩展侧即 origin */
+  scope: string;
+  id?: string;
+  /** 批准记录必须带（FR-21.7）：只记 id 的话，事后无从知道当时点头的是哪个地址 */
+  target?: string;
+  kind?: DataSourceKind;
+  provenance?: DataSourceProvenance;
+  /** 批准方式：`true` 为「已记住」，`false` 为仅当次 */
+  remembered?: boolean;
+  /** `offered` 专有：本批被接受 / 被丢弃的条数 */
+  accepted?: number;
+  rejected?: number;
+}
+interface DataSourceCandidateAuditSink {
+  record(event: DataSourceCandidateRecord): void | Promise<void>;
+}
+interface DataSourceCandidatePolicyOptions {
+  store?: DataSourceCandidateStore;
+  audit?: DataSourceCandidateAuditSink;
+  /** 一个 scope 最多接受多少条提议；缺省 32 */
+  maxCandidates?: number;
+  now?(): string;
+}
+/**
+ * 候选源策略（分册 21）。
+ *
+ * **本类不持有任何取数通道，也不引用任何出站 API**（AC-21.13）：
+ * 页面提议里携带的 `target` 在用户点头之前不可能被请求，
+ * 这是结构结论，不是一句 `if (!approved) return`。
+ * @experimental
+ */
+declare class DataSourceCandidatePolicy {
+  #private;
+  constructor(options?: DataSourceCandidatePolicyOptions);
+  get records(): readonly DataSourceCandidateRecord[];
+  /**
+   * 页面提议入表。**同步返回，且不做任何网络动作**。
+   *
+   * 不触发确认卡：页面每次刷新都会重发一遍提议，
+   * 接到弹窗上等于把打断用户的权力交给页面（设计 §4.1）。
+   */
+  offer(scope: string, candidates: readonly unknown[], provenance?: DataSourceProvenance): {
+    accepted: number;
+    rejected: number;
+  };
+  /** 尚待确认的：已批准的那些不再重复出现在这里 */
+  pending(scope: string | undefined): readonly DataSourceCandidate[];
+  approve(scope: string, id: string, options?: {
+    remember?: boolean;
+  }): Promise<void>;
+  /** 撤销：立刻回到候选状态，不需要重载页面（FR-21.2） */
+  forget(scope: string, id: string): Promise<void>;
+  /**
+   * 已获批的，投影成既有 `DataSourceDef`（**出处不在其中**：
+   * `DataSourceDef` 的形状不改，出处经 `provenanceOf` 单独取）。
+   *
+   * `undefined` 返回空数组：没绑定 tab 时不是「全部可用」，是「一条都没有」。
+   */
+  approved(scope: string | undefined): readonly DataSourceDef[];
+  /** 供 `DataSourcePolicy.provenanceOf` 直接接线：不是候选出身的返回 undefined */
+  provenanceOf(scope: string | undefined, id: string): DataSourceProvenance | undefined;
+  /**
+   * 切绑定 tab 时调用。清「待批的」与「当次批准的」，
+   * **不动已记住的**——那些通过 `approved(新 scope)` 自然只对新 scope 生效。
+   */
+  clearPending(): void;
+  /**
+   * 从 store 回填已记住的批准。
+   *
+   * `recall` 是异步端口而 `approved()` 是同步 getter（`DataSourcePolicy.sources` 要求同步），
+   * 所以命中与否必须在提议入表时先问一遍，而不是取数时现问。
+   */
+  restore(scope: string): Promise<void>;
+}
+//#endregion
 //#region src/pageAction/types.d.ts
 /**
  * 页面操作的策略层类型（需求 23）。
@@ -704,15 +945,18 @@ interface PageActionScope {
   exclude?: readonly string[];
 }
 /**
- * 一个帧内的可操作范围（FR-24.1）。
+ * 一个帧内的可操作范围（FR-24.1 / 分册 18 FR-18.1）。
  *
  * 与感知侧的 `FrameScope` 同构但**独立声明**，理由同上：合并成一个类型会让
  * 「一份配置同时当感知范围和操作范围用」在类型层面合法。
  * @experimental
  */
 interface ActionFrameScope {
-  /** 主文档写 `'self'`；iframe 写主文档里定位该 `<iframe>` 的选择器 */
-  frame: 'self' | string;
+  /**
+   * 主文档写 `'self'`；单层 iframe 写主文档里定位该 `<iframe>` 的选择器；
+   * 多层嵌套写逐层选择器数组（空数组等价于 `'self'`）。
+   */
+  frame: 'self' | string | readonly string[];
   include: readonly string[];
   exclude?: readonly string[];
 }
@@ -770,6 +1014,15 @@ interface PageActionOutcome {
   noop?: boolean;
   /** 本次操作新打开的模态的可访问名；授权面临时扩大要在留痕里看得见（FR-25.6） */
   elevatedModal?: string;
+  /**
+   * 本次操作后目标所在帧的地址变了（帧内跳转 / SPA 路由，分册 18 FR-18.6）。
+   * 没变时**不带**该字段：带个 `false` 会让旧宿主的断言凭空变化。
+   *
+   * 真正的跨文档导航会销毁执行上下文，那种情况拿不到本字段——固有限制，不假装。
+   */
+  navigated?: boolean;
+  /** 变更后的地址；仅 `navigated` 时带 */
+  documentUrl?: string;
   /** 失败原因（英文） */
   reason?: string;
 }
@@ -806,8 +1059,11 @@ interface PageActionRecord {
   name?: string;
   /** 目标所在的帧；主文档目标不带该字段（FR-24.6） */
   frame?: string;
-  /** 是否经用户确认；宿主预授权的操作记 `'preauthorized'` */
-  approved: boolean | 'preauthorized';
+  /**
+   * 是否经用户确认；宿主预授权的操作记 `'preauthorized'`，
+   * 命中用户此前「不再询问」的记 `'remembered'`（需求 11 / FR-11.5）。
+   */
+  approved: boolean | 'preauthorized' | 'remembered';
   ok: boolean;
   /** 目标位于本次会话中被提升的模态里（授权面临时扩大，FR-25.6 / AC-G22） */
   elevated?: boolean;
@@ -825,6 +1081,24 @@ interface PageActionRecord {
 interface PageActionUi {
   request(input: InteractionRequest): Promise<InteractionResponse>;
 }
+/**
+ * 「不再询问」的记忆端口（需求 11 / FR-11.1）。**存储与粒度归宿主**：
+ * 粒度键通常是 origin，而本包不认识 origin。
+ *
+ * 不注入即完全无记忆：确认卡不出复选框，行为与 0.13.0 逐字一致。
+ * @experimental
+ */
+interface PageActionConsent {
+  /** 该目标 + 动作是否已被记住；`true` 即本次不弹卡 */
+  recall(target: PageActionTarget, action: PageActionKind): boolean | Promise<boolean>;
+  /** 用户勾了「不再询问」并允许后写入 */
+  remember(target: PageActionTarget, action: PageActionKind): void | Promise<void>;
+  /**
+   * 复选框旁的文案。宿主不实现即用通用兜底串——
+   * SDK 无权替宿主宣称记住的是「此站点」，写死会在宿主换粒度时变成谎报授权范围。
+   */
+  describeScope?(target: PageActionTarget, action: PageActionKind): string | undefined;
+}
 interface PageActionPolicyOptions {
   /** 宿主声明的可操作范围；`include` 为空即整个能力不可用 */
   scope: PageActionScopeInput;
@@ -839,6 +1113,11 @@ interface PageActionPolicyOptions {
    * 只有宿主显式配置才生效，SDK 不提供任何缺省放行项。
    */
   preauthorized?: readonly PageActionKind[];
+  /**
+   * 「不再询问」的记忆端口（需求 11）。与 `preauthorized` 并列且互不引用：
+   * 前者是宿主装配时写死的静态配置，后者是用户运行期一次一次攒出来的。
+   */
+  consent?: PageActionConsent;
   now?(): string;
 }
 /**
@@ -896,4 +1175,150 @@ declare function createPageActionToolSource(options: PageActionToolSourceOptions
  */
 declare const PAGE_ACTION_SYSTEM_PROMPT: string;
 //#endregion
-export { PerceptionScope as $, PageActionKind as A, PageActionUi as B, MANAGE_TODO_TOOL as C, createPageActionToolSource as Ct, PERCEIVE_PAGE_TOOL as D, toActionFrameScopes as Dt, PAGE_ACTION_TOOL as E, createTodoToolSource as Et, PageActionRequest as F, PagePerceptionToolSourceOptions as G, PagePerceptionPolicy as H, PageActionScope as I, PerceivedNode as J, ParentBudget as K, PageActionScopeInput as L, PageActionPolicy as M, PageActionPolicyOptions as N, PERCEPTION_SYSTEM_PROMPT as O, toFrameScopes as Ot, PageActionRecord as P, PerceptionResult as Q, PageActionTarget as R, ImageCaptureBudget as S, createHttpDataSourceTransport as St, PAGE_ACTION_SYSTEM_PROMPT as T, createSkillGenerationToolSource as Tt, PagePerceptionPolicyOptions as U, PageAuditSink as V, PagePerceptionReader as W, PerceptionCaptureOptions as X, PerceptionAuditSink as Y, PerceptionRecord as Z, FrameNote as _, TodoListener as _t, DataSourceDef as a, SkillGenerationPolicy as at, GeneratedSkillDraft as b, TodoToolSourceOptions as bt, DataSourcePolicyOptions as c, SkillGeneratorOptions as ct, DelegationBudget as d, SubAgentRunInput as dt, PerceptionScopeInput as et, DelegationOrchestrator as f, SubAgentRunner as ft, DelegationToolSourceOptions as g, TodoList as gt, DelegationResult as h, TodoItem as ht, DataSourceAuditSink as i, SkillGenerationOutcome as it, PageActionOutcome as j, PageActionExecutor as k, withDelegationOrigin as kt, DataSourceRecord as l, SkillTraceEvidence as lt, DelegationRequest as m, TodoEvent as mt, DELEGATE_TASK_TOOL as n, SkillCandidateSink as nt, DataSourceKind as o, SkillGenerationToolSourceOptions as ot, DelegationOrchestratorOptions as p, TODO_SYSTEM_PROMPT as pt, PerceivedImage as q, DELEGATION_SYSTEM_PROMPT as r, SkillGenerationMessages as rt, DataSourcePolicy as s, SkillGenerator as st, ActionFrameScope as t, SKILL_GENERATION_SYSTEM_PROMPT as tt, DataSourceTransport as u, SkillTraceEvidenceStep as ut, FrameScope as v, TodoStatus as vt, PAGE_ACTION_KINDS as w, createPagePerceptionToolSource as wt, HttpDataSourceOptions as x, createDelegationToolSource as xt, GENERATE_SKILL_TOOL as y, TodoStore as yt, PageActionToolSourceOptions as z };
+//#region src/downloads/types.d.ts
+/**
+ * 一条已下载文件的目录项。
+ * @experimental
+ */
+interface DownloadedFileEntry {
+  /**
+   * 不透明标识。**不得是路径，也不得可反推出路径**（FR-20.2）：
+   * 模型手里只该有一个宿主认得、别人认不出的取件号。
+   */
+  id: string;
+  name: string;
+  contentType: string;
+  size: number;
+  /** ISO 8601，下载完成时刻 */
+  at: string;
+}
+/** `list_downloaded_files` 下发给模型的条目：目录项 + 可读性判定 @experimental */
+interface DownloadedFileListing extends DownloadedFileEntry {
+  readable: boolean;
+  /** 不可读的原因（英文）；可读时不存在 */
+  reason?: string;
+}
+/**
+ * 本机下载文件的取件实现（FR-20.1）。**不注入即整条通路不存在**——
+ * 工具不注册，模型看不到它。
+ * @experimental
+ */
+interface DownloadedFileReader {
+  list(): Promise<readonly DownloadedFileEntry[]>;
+  /**
+   * 按不透明标识取字节。**`contentType` 必须由本方法重新给出**，
+   * 不复用 `list()` 那次的值：两次调用之间文件可能被替换，
+   * 信 list 的类型等于让「列出时是 csv、读取时是别的东西」这条路存在。
+   */
+  read(id: string): Promise<{
+    contentType: string;
+    bytes: Uint8Array;
+  }>;
+}
+/** 授权动作。列出与读取各自确认，措辞不同（D-20-3） @experimental */
+type DownloadedFileAction = 'list' | 'read';
+/**
+ * 「不再询问」的记忆端口（D-20-2）。**存储与粒度归宿主**：
+ * SDK 不认识「下载目录」这个概念，`remember` 记的是什么由装配方决定。
+ *
+ * 不注入即完全无记忆：确认卡不出复选框。
+ * @experimental
+ */
+interface DownloadedFileConsent {
+  recall(action: DownloadedFileAction, entry?: DownloadedFileEntry): boolean | Promise<boolean>;
+  remember(action: DownloadedFileAction, entry?: DownloadedFileEntry): void | Promise<void>;
+  /**
+   * 复选框旁的文案。宿主不实现即用通用兜底串——
+   * SDK 无权替宿主宣称记住的是「整个下载目录」，写死会变成谎报授权范围。
+   */
+  describeScope?(action: DownloadedFileAction, entry?: DownloadedFileEntry): string | undefined;
+}
+/** 一次列出或读取的留痕（FR-20.5） @experimental */
+interface DownloadedFileRecord {
+  at: string;
+  action: DownloadedFileAction;
+  /** `list` 时不存在：审计要回答「模型什么时候看过目录」，抄下整份清单是把一次披露变成两次 */
+  name?: string;
+  size?: number;
+  contentType?: string;
+  approved: boolean | 'remembered';
+  ok: boolean;
+  reason?: string;
+}
+/** 读取成功后交给工具层的形态；`kind` 决定它以哪种分片进上下文 @experimental */
+interface DownloadedFileReadResult {
+  entry: DownloadedFileEntry;
+  /** `read()` 重新给出的类型，不是 `entry.contentType` */
+  contentType: string;
+  kind: ChatAttachmentKind;
+  /** `text` / `document-text`：已按上下文形态格式化并截断 */
+  text?: string;
+  /** `file` / `image`：原始字节 */
+  bytes?: Uint8Array;
+}
+//#endregion
+//#region src/downloads/policy.d.ts
+/**
+ * 授权卡的最小出口。与 `PageActionUi` 结构相同，宿主传同一个对象即可——
+ * 不复用那个名字是因为「下载文件策略 import 一个叫 PageAction… 的类型」会被读成有依赖关系。
+ * @experimental
+ */
+interface ConsentUi {
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+}
+interface DownloadedFilePolicyOptions {
+  /** 取件实现。**不注入即整条通路不存在**：`enabled` 为 false，工具不注册（AC-20.1） */
+  reader?: DownloadedFileReader;
+  /**
+   * 授权卡出口。**必填**：引擎的 `#confirm` 在没接 UI 桥时自动放行，
+   * 那条 fail-open 的路对「读用户本机磁盘」不成立。接不上就构造不出策略。
+   */
+  ui: ConsentUi;
+  /** 能力开关（`sandbox.downloadedFiles`）。每次读取，设置改完立刻生效；缺省即**关闭** */
+  capabilityEnabled?(): boolean;
+  consent?: DownloadedFileConsent;
+  audit?: PageAuditSink;
+  /** 审计事件的 target（缺省 `downloads`） */
+  auditTarget?: string;
+  /** 选中模型能否读图（D-20-7）。缺省即**不能**：不知道就不给看 */
+  imageCapable?(): boolean | Promise<boolean>;
+  /** docx → 文本。必须与手动上传用的是**同一个**抽取器（AC-20.6） */
+  docxExtractor?: DocxTextExtractor;
+  /** xlsx → 文本。同上 */
+  xlsxExtractor?: XlsxTextExtractor;
+  now?(): string;
+}
+/**
+ * 读取本机下载文件的策略（0.14.0 分册 20）。
+ *
+ * 三道闸门依次是：宿主有没有接端口并打开开关、用户认不认、文件类型读不读得了。
+ * 模型能表达的只有「列目录」与「读这个取件号」——它没有任何指定路径的入口（AC-20.9）。
+ * @experimental
+ */
+declare class DownloadedFilePolicy {
+  #private;
+  constructor(options: DownloadedFilePolicyOptions);
+  /** 端口未注入或开关关闭即整个能力不存在（AC-20.1 / AC-20.2） */
+  get enabled(): boolean;
+  /** 最近的记录（只读展示用），新的在前 */
+  get records(): readonly DownloadedFileRecord[];
+  list(): Promise<readonly DownloadedFileListing[]>;
+  read(id: string): Promise<DownloadedFileReadResult>;
+}
+//#endregion
+//#region src/downloads/toolSource.d.ts
+declare const LIST_DOWNLOADED_FILES_TOOL = "list_downloaded_files";
+declare const READ_DOWNLOADED_FILE_TOOL = "read_downloaded_file";
+interface DownloadedFileToolSourceOptions {
+  policy: DownloadedFilePolicy;
+}
+/**
+ * 把下载文件读取接到既有工具协议上。
+ *
+ * 端口未注入或能力开关关闭时 `listToolSpecs()` 返回空数组——
+ * 模型连这两个工具的存在都看不到，而不是看得到再被拒（AC-20.1 / AC-20.2）。
+ * @experimental
+ */
+declare function createDownloadedFileToolSource(options: DownloadedFileToolSourceOptions): ExternalToolSource;
+//#endregion
+export { PageActionOutcome as $, frameSteps as $t, DownloadedFilePolicyOptions as A, SkillGenerationToolSourceOptions as At, ImageCaptureBudget as B, TodoList as Bt, DelegationResult as C, PerceptionScopeInput as Ct, DownloadedFileEntry as D, SkillGenerationMessages as Dt, DownloadedFileConsent as E, SkillCandidateSink as Et, FrameNote as F, SubAgentRunInput as Ft, PAGE_ACTION_SYSTEM_PROMPT as G, createDelegationToolSource as Gt, MANAGE_TODO_TOOL as H, TodoStatus as Ht, FrameScope as I, SubAgentRunner as It, PERCEPTION_PAGING_DEFAULTS as J, createPageActionToolSource as Jt, PAGE_ACTION_TOOL as K, createDownloadedFileToolSource as Kt, GENERATE_SKILL_TOOL as L, TODO_SYSTEM_PROMPT as Lt, DownloadedFileReader as M, SkillGeneratorOptions as Mt, DownloadedFileRecord as N, SkillTraceEvidence as Nt, DownloadedFileListing as O, SkillGenerationOutcome as Ot, DownloadedFileToolSourceOptions as P, SkillTraceEvidenceStep as Pt, PageActionKind as Q, frameLabel as Qt, GeneratedSkillDraft as R, TodoEvent as Rt, DelegationRequest as S, PerceptionScope as St, DownloadedFileAction as T, SKILL_GENERATION_SYSTEM_PROMPT as Tt, NestedFrameRef as U, TodoStore as Ut, LIST_DOWNLOADED_FILES_TOOL as V, TodoListener as Vt, PAGE_ACTION_KINDS as W, TodoToolSourceOptions as Wt, PageActionConsent as X, createSkillGenerationToolSource as Xt, PERCEPTION_SYSTEM_PROMPT as Y, createPagePerceptionToolSource as Yt, PageActionExecutor as Z, createTodoToolSource as Zt, DataSourceRecord as _, PerceptionAuditSink as _t, DataSourceAuditSink as a, PageActionScopeInput as at, DelegationOrchestrator as b, PerceptionRecord as bt, DataSourceCandidatePolicy as c, PageActionUi as ct, DataSourceCandidateStore as d, PagePerceptionPolicyOptions as dt, toActionFrameScopes as en, PageActionPolicy as et, DataSourceDef as f, PagePerceptionReader as ft, DataSourceProvenance as g, PerceivedNode as gt, DataSourcePolicyOptions as h, PerceivedImage as ht, DELEGATION_SYSTEM_PROMPT as i, PageActionScope as it, DownloadedFileReadResult as j, SkillGenerator as jt, DownloadedFilePolicy as k, SkillGenerationPolicy as kt, DataSourceCandidatePolicyOptions as l, PageAuditSink as lt, DataSourcePolicy as m, ParentBudget as mt, ConsentUi as n, withDelegationOrigin as nn, PageActionRecord as nt, DataSourceCandidate as o, PageActionTarget as ot, DataSourceKind as p, PagePerceptionToolSourceOptions as pt, PERCEIVE_PAGE_TOOL as q, createHttpDataSourceTransport as qt, DELEGATE_TASK_TOOL as r, PageActionRequest as rt, DataSourceCandidateAuditSink as s, PageActionToolSourceOptions as st, ActionFrameScope as t, toFrameScopes as tn, PageActionPolicyOptions as tt, DataSourceCandidateRecord as u, PagePerceptionPolicy as ut, DataSourceTransport as v, PerceptionCaptureOptions as vt, DelegationToolSourceOptions as w, READ_DOWNLOADED_FILE_TOOL as wt, DelegationOrchestratorOptions as x, PerceptionResult as xt, DelegationBudget as y, PerceptionPagingBudget as yt, HttpDataSourceOptions as z, TodoItem as zt };

package/dist/{index-3fCHc1mQ.d.ts → index-sd-gVKey.d.ts}

@@ -1,5 +1,5 @@
-import { B as JsonSchema, C as UiSpecActionCapability, D as UiSpecSnapshot, S as UiBridge, b as RenderResultRequest, bt as UiSpecNode, c as InteractionResponse, r as ChartSpec, s as InteractionRequest, y as RenderBlock } from "./types-DLctJep_-B5G4uk2u.js";
-import { F as ExternalToolSource } from "./index-C9pzXLKy.js";
+import { C as UiSpecActionCapability, D as UiSpecSnapshot, Dt as UiSpecNode, K as JsonSchema, S as UiBridge, b as RenderResultRequest, c as InteractionResponse, r as ChartSpec, s as InteractionRequest, y as RenderBlock } from "./types-C3V6lAeO-BgeOvc1Y.js";
+import { I as ExternalToolSource } from "./index-CWoKOFBP.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
 //#region ../ui/dist/index.d.ts