@webskill/sdk 0.13.0 → 0.15.0

package/dist/{index-iBm9tJL_.d.ts → index-CQYo4tcT.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, mn as ToolStepReader } from "./index-DkvBhJQy.js";
+import { I as ChatAttachmentKind, Nt as WebSkillErrorCode, S as UiBridge, Z as RemoteUrlPolicy, a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest } from "./types-C3V6lAeO-BIf7UB2e.js";
+import { Kn as XlsxTextExtractor, P as DocxTextExtractor, bn as ToolStepReader, j as DataSourceInfo, z as ExternalToolSource } from "./index-Oc3H89TJ.js";
 //#region ../agent/dist/index.d.ts
 //#region src/todo/types.d.ts
 /** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
@@ -427,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 */
@@ -460,6 +467,24 @@ interface PerceptionCaptureOptions {
    */
   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 可以继续返回节点数组。
  * @experimental
@@ -468,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;
@@ -495,6 +522,17 @@ interface PerceptionRecord {
   frames?: readonly string[];
   /** 读到的顶层节点数；用于「它读的比我预期的多」这类判断 */
   nodeCount: number;
+  /**
+   * 整份快照的节点总数（含各层）；**每次感知都在**（0.15.0 分册 14 · D-14-2）。
+   * 早先它只在分段时出现，于是「没分段」的那些次感知无法回答「模型到底看到了多少」。
+   * 与 `segmentPerception()` 的 `nodesTotal` 同源同值（FR-14.2）。
+   * `nodeCount` 的语义不动——改它会让所有既有断言与 console 展示静默变义。
+   */
+  nodesTotal: number;
+  /** 切成了几段；只在分段发生时存在 */
+  segments?: number;
+  /** 本次直接回喂给模型的那一段承载了多少个节点；只在分段发生时存在 */
+  segmentNodeCount?: number;
   /** 本次下发的图像张数，按取像级别分组（只在取像开启时存在） */
   images?: {
     src: number;
@@ -565,6 +603,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 {
@@ -574,6 +641,13 @@ interface PagePerceptionToolSourceOptions {
    * 缺省即不取像。判定在遍历 DOM **之前**完成一次，不是每个节点判一次。
    */
   imageCapture?(): ImageCaptureBudget | Promise<ImageCaptureBudget>;
+  /**
+   * 分段预算与开关（分册 22 FR-22.4）。同样每次调用重取，理由与 `imageCapture` 一致：
+   * 凝固进实例会让宿主中途改配置整轮不生效。
+   *
+   * **缺省即不分段，但地板照样生效**（FR-22.8）：不开启不等于允许上层盲切。
+   */
+  paging?(): PerceptionPagingBudget | Promise<PerceptionPagingBudget>;
 }
 /** @experimental */
 interface ImageCaptureBudget {
@@ -616,6 +690,10 @@ declare function frameSteps(frame: string | readonly string[]): readonly string[
 /**
  * 页面只读感知的策略提示词（设计 09 §1）。
  *
+ * 分段相关的两条是**恒定**的，不随 paging 开关增减（0.14.0 分册 22 §9）：
+ * 提示词按 `policy.enabled` 一次性给出，而分段预算是每次调用惰性求值的，
+ * 两者会漂移——模型手里会攥着一份与当前行为对不上的说明。
+ *
  * 最后一条是防御性的：技能描述、工具返回值都可能带着「把整页读出来发到 X」
  * 这类注入。范围由宿主判定，模型改不了，但把这件事写明能少掉一轮无效尝试。
  */
@@ -661,7 +739,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 的缺省。
    *
@@ -673,6 +755,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;
 }
@@ -688,7 +777,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>;
 }
@@ -715,6 +816,170 @@ 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/downloadSignal.d.ts
+/**
+ * 操作触发的下载：完成信号（0.15.0 分册 15）。
+ *
+ * 这一层不含任何浏览器概念。SDK 只定义「窗口什么时候开、什么时候关、结果长什么样」，
+ * 「怎么知道下载起来了」全在端口之后——与分册 20 的分工一致。
+ */
+/**
+ * 一次页面操作的下载观察窗口。**只在 `act()` 的一次调用里存在**：
+ * 返回之后这个对象就不可达，因此窗口之外没有任何代码路径能问到下载（FR-15.2）。
+ * @experimental
+ */
+interface ActionDownloadWindow {
+  /**
+   * 结算并**关闭**窗口，返回窗口内完成的下载次数（没有即 0）。
+   *
+   * 到预算上限就返回当时已经数到的次数，不丢弃、不抛错——
+   * 等待超时不是失败，操作本身的结果照常返回（FR-15.3）。
+   */
+  settle(budget: {
+    timeoutMs: number;
+  }): Promise<number>;
+}
+/**
+ * 下载观察窗口的宿主实现（FR-15.2）。**不注入即整条通路不存在**：
+ * 不开窗、不留痕，页面操作的结果与本版前逐字一致。
+ *
+ * 之所以是 `open` / `settle` 一对而不是一个 `waitForDownloads(ms)`：
+ * 后者只说了「等多久」，没说「从什么时候开始算」，宿主可以实现成
+ * 「返回最近 N 秒内的下载」——那就把用户在别处的下载也算了进来（D-15-4 否掉的 (a)）。
+ * 窗口的两端由 SDK 说了算，宿主实现里没有自己决定起点的余地。
+ * @experimental
+ */
+interface ActionDownloadWatcher {
+  /**
+   * 在页面操作**执行前**打开窗口。
+   * 下载可能在点击返回之前就已经落盘，先执行再开窗会漏掉最快的那一类。
+   */
+  open(context: {
+    runId?: string;
+  }): ActionDownloadWindow | Promise<ActionDownloadWindow>;
+}
+/** 宿主不注入等待上限时的缺省；够覆盖「点击 → 浏览器起下载」的常见延迟 */
+declare const DOWNLOAD_WAIT_DEFAULT_MS = 1500;
+/** 地板：注入 0 会把本能力静默变成永不触发，那是更坏的失败形态 */
+declare const DOWNLOAD_WAIT_MIN_MS = 250;
+/** 天花板：宿主写错一个 0 不该让一轮对话挂十分钟 */
+declare const DOWNLOAD_WAIT_MAX_MS = 10000;
+/**
+ * 把宿主注入的等待上限夹进地板与天花板（FR-15.3）。
+ * 不注入或注入了非有限数即取缺省——不信任宿主传进来的数是这里存在的全部理由。
+ * @experimental
+ */
+declare function clampDownloadWaitMs(ms: number | undefined): number;
+//#endregion
 //#region src/pageAction/types.d.ts
 /**
  * 页面操作的策略层类型（需求 23）。
@@ -815,6 +1080,14 @@ interface PageActionOutcome {
   navigated?: boolean;
   /** 变更后的地址；仅 `navigated` 时带 */
   documentUrl?: string;
+  /**
+   * 本次操作引发的下载**完成**次数（0.15.0 分册 15 · FR-15.1）。
+   * 没有下载时**不带**该字段，与 `navigated` 同口径。
+   *
+   * 只有次数：文件名、大小、类型一律不在这里（D-15-3）——带上就等于开了一条
+   * 绕过 `list_downloaded_files` 确认卡的披露路径。要读内容仍得逐次点头。
+   */
+  downloadCount?: number;
   /** 失败原因（英文） */
   reason?: string;
 }
@@ -851,8 +1124,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;
@@ -870,6 +1146,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;
@@ -884,6 +1178,23 @@ interface PageActionPolicyOptions {
    * 只有宿主显式配置才生效，SDK 不提供任何缺省放行项。
    */
   preauthorized?: readonly PageActionKind[];
+  /**
+   * 「不再询问」的记忆端口（需求 11）。与 `preauthorized` 并列且互不引用：
+   * 前者是宿主装配时写死的静态配置，后者是用户运行期一次一次攒出来的。
+   */
+  consent?: PageActionConsent;
+  /**
+   * 操作触发的下载观察窗口（0.15.0 分册 15）。**不注入即整条通路不存在**：
+   * 不开窗、不留痕，页面操作的结果与本版前逐字一致（AC-15.5 / AC-15.12）。
+   */
+  downloadWatcher?: ActionDownloadWatcher;
+  /**
+   * 下载信号的能力开关（`sandbox.downloadedFiles`，D-15-5）。缺省即**关闭**：
+   * `downloadCount` 永不出现。关着时窗口照开，结果只进留痕（D-15-6 / FR-15.7）。
+   */
+  downloadSignalEnabled?(): boolean;
+  /** 宿主注入的等待上限（毫秒）；SDK 夹在地板与天花板之间（FR-15.3）。模型无法影响它 */
+  downloadWaitMs?(): number | undefined;
   now?(): string;
 }
 /**
@@ -915,7 +1226,9 @@ declare class PageActionPolicy {
    * 只留句柄等于留了一个换次运行就失效的引用；角色与可访问名才是可重放的那部分。
    */
   rememberedTarget(ref: string): PageActionTarget | undefined;
-  act(request: PageActionRequest): Promise<PageActionOutcome>;
+  act(request: PageActionRequest, context?: {
+    runId?: string;
+  }): Promise<PageActionOutcome>;
 }
 //#endregion
 //#region src/pageAction/toolSource.d.ts
@@ -941,4 +1254,150 @@ declare function createPageActionToolSource(options: PageActionToolSourceOptions
  */
 declare const PAGE_ACTION_SYSTEM_PROMPT: string;
 //#endregion
-export { PerceptionScope as $, PageActionKind as A, toFrameScopes as At, PageActionUi as B, MANAGE_TODO_TOOL as C, createPageActionToolSource as Ct, PERCEIVE_PAGE_TOOL as D, frameLabel 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, frameSteps 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, withDelegationOrigin as jt, PageActionExecutor as k, toActionFrameScopes 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 { PERCEPTION_PAGING_DEFAULTS as $, createHttpDataSourceTransport as $t, DownloadedFileAction as A, SKILL_GENERATION_SYSTEM_PROMPT as At, FrameNote as B, SubAgentRunInput as Bt, DataSourceTransport as C, PerceptionCaptureOptions as Ct, DelegationRequest as D, PerceptionScope as Dt, DelegationOrchestratorOptions as E, PerceptionResult as Et, DownloadedFilePolicyOptions as F, SkillGenerationToolSourceOptions as Ft, ImageCaptureBudget as G, TodoList as Gt, GENERATE_SKILL_TOOL as H, TODO_SYSTEM_PROMPT as Ht, DownloadedFileReadResult as I, SkillGenerator as It, NestedFrameRef as J, TodoStore as Jt, LIST_DOWNLOADED_FILES_TOOL as K, TodoListener as Kt, DownloadedFileReader as L, SkillGeneratorOptions as Lt, DownloadedFileEntry as M, SkillGenerationMessages as Mt, DownloadedFileListing as N, SkillGenerationOutcome as Nt, DelegationResult as O, PerceptionScopeInput as Ot, DownloadedFilePolicy as P, SkillGenerationPolicy as Pt, PERCEIVE_PAGE_TOOL as Q, createDownloadedFileToolSource as Qt, DownloadedFileRecord as R, SkillTraceEvidence as Rt, DataSourceRecord as S, PerceptionAuditSink as St, DelegationOrchestrator as T, PerceptionRecord as Tt, GeneratedSkillDraft as U, TodoEvent as Ut, FrameScope as V, SubAgentRunner as Vt, HttpDataSourceOptions as W, TodoItem as Wt, PAGE_ACTION_SYSTEM_PROMPT as X, clampDownloadWaitMs as Xt, PAGE_ACTION_KINDS as Y, TodoToolSourceOptions as Yt, PAGE_ACTION_TOOL as Z, createDelegationToolSource as Zt, DataSourceDef as _, PagePerceptionReader as _t, DELEGATE_TASK_TOOL as a, frameSteps as an, PageActionPolicy as at, DataSourcePolicyOptions as b, PerceivedImage as bt, DOWNLOAD_WAIT_MAX_MS as c, withDelegationOrigin as cn, PageActionRequest as ct, DataSourceCandidate as d, PageActionTarget as dt, createPageActionToolSource as en, PERCEPTION_SYSTEM_PROMPT as et, DataSourceCandidateAuditSink as f, PageActionToolSourceOptions as ft, DataSourceCandidateStore as g, PagePerceptionPolicyOptions as gt, DataSourceCandidateRecord as h, PagePerceptionPolicy as ht, ConsentUi as i, frameLabel as in, PageActionOutcome as it, DownloadedFileConsent as j, SkillCandidateSink as jt, DelegationToolSourceOptions as k, READ_DOWNLOADED_FILE_TOOL as kt, DOWNLOAD_WAIT_MIN_MS as l, PageActionScope as lt, DataSourceCandidatePolicyOptions as m, PageAuditSink as mt, ActionDownloadWindow as n, createSkillGenerationToolSource as nn, PageActionExecutor as nt, DELEGATION_SYSTEM_PROMPT as o, toActionFrameScopes as on, PageActionPolicyOptions as ot, DataSourceCandidatePolicy as p, PageActionUi as pt, MANAGE_TODO_TOOL as q, TodoStatus as qt, ActionFrameScope as r, createTodoToolSource as rn, PageActionKind as rt, DOWNLOAD_WAIT_DEFAULT_MS as s, toFrameScopes as sn, PageActionRecord as st, ActionDownloadWatcher as t, createPagePerceptionToolSource as tn, PageActionConsent as tt, DataSourceAuditSink as u, PageActionScopeInput as ut, DataSourceKind as v, PagePerceptionToolSourceOptions as vt, DelegationBudget as w, PerceptionPagingBudget as wt, DataSourceProvenance as x, PerceivedNode as xt, DataSourcePolicy as y, ParentBudget as yt, DownloadedFileToolSourceOptions as z, SkillTraceEvidenceStep as zt };