@webskill/sdk 0.15.0 → 0.16.0

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { Ct as SkillsLockfile, Et as TrustedKeyStore, H as FileStat, Mt as WebSkillError, N as ArchiveLimits, S as UiBridge, U as FileSystemProvider, _t as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as VerifyResult, kt as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore } from "./types-C3V6lAeO-BIf7UB2e.js";
-import { Kt as ScriptExecutionContext, M as DocumentSurfaceHost, R as ExternalSkillProvider, S as BridgeResponse, Un as WebSkillApi, Yn as bridgeError, ct as NetworkPolicy, gn as ToolDefinition, m as ApprovalScope, ot as LinkedDocumentReader, qt as ScriptExecutor, x as BridgeRequest, y as BridgeCapabilities, yn as ToolResult, yr as parseBridgeRequest, z as ExternalToolSource } from "./index-Oc3H89TJ.js";
-import { Ct as PerceptionCaptureOptions, Et as PerceptionResult, J as NestedFrameRef, Ot as PerceptionScopeInput, _t as PagePerceptionReader, ct as PageActionRequest, dt as PageActionTarget, ht as PagePerceptionPolicy, it as PageActionOutcome, nt as PageActionExecutor, ut as PageActionScopeInput, xt as PerceivedNode } from "./index-CQYo4tcT.js";
+import { Ct as SkillsLockfile, Et as TrustedKeyStore, H as FileStat, Mt as WebSkillError, N as ArchiveLimits, S as UiBridge, U as FileSystemProvider, _t as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as VerifyResult, kt as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore } from "./types-C3V6lAeO-BUpcRLER.js";
+import { Kt as ScriptExecutionContext, M as DocumentSurfaceHost, R as ExternalSkillProvider, S as BridgeResponse, Un as WebSkillApi, Yn as bridgeError, ct as NetworkPolicy, gn as ToolDefinition, m as ApprovalScope, ot as LinkedDocumentReader, qt as ScriptExecutor, x as BridgeRequest, y as BridgeCapabilities, yn as ToolResult, yr as parseBridgeRequest, z as ExternalToolSource } from "./index-DbVqg2V3.js";
+import { $ as NestedFrameRef, Ct as PagePerceptionPolicy, It as PerceptionScopeInput, Pt as PerceptionResult, Tt as PagePerceptionReader, Xt as SubtreeRejection, ft as PageActionOutcome, gt as PageActionRequest, jt as PerceptionCaptureOptions, kt as PerceivedNode, ut as PageActionExecutor, vt as PageActionScopeInput, yt as PageActionTarget } from "./index-BLfnO7sz.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -418,6 +418,12 @@ interface RoleHint {
 }
 //#endregion
 //#region src/dom/perception.d.ts
+/**
+ * 句柄的用途（分册 14 §6.1）。`anchor` 只能做 `perceive_page` 的子树根，
+ * 拿去 `act_on_page` 一律被拒——否则放宽读的范围会顺带放宽写的范围。
+ * @experimental
+ */
+type HandleKind = 'action' | 'anchor';
 interface DomPerceptionReaderOptions {
   /** 选择器求值的根；缺省 `globalThis.document` */
   document?: Document;
@@ -456,8 +462,12 @@ interface DomPerceptionReaderOptions {
 interface DomPerceptionReader extends PagePerceptionReader {
   read(scope: PerceptionScopeInput): readonly PerceivedNode[];
   read(scope: PerceptionScopeInput, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
+  /** 子树续读（分册 14）：只能缩小范围，拒绝以返回值而非抛错表达 */
+  readSubtree(scope: PerceptionScopeInput, ref: string, capture?: PerceptionCaptureOptions): Promise<PerceptionResult | SubtreeRejection>;
   /** 把句柄换回元素；未知或已过期的句柄返回 undefined。供执行器使用，不自建第二张表 */
   resolve(ref: string): Element | undefined;
+  /** 句柄的用途；`anchor` 只能做子树根，执行器据此拒掉写动作（分册 14 §6.1） */
+  handleKindOf(ref: string): HandleKind | undefined;
   /** 句柄所属的帧；主文档目标返回 undefined（FR-24.6 的确认卡措辞与审计据此区分） */
   frameOf(ref: string): string | undefined;
   /** 操作前的活动模态快照；与操作后做差集即「本次新打开的模态」（FR-25.6） */
@@ -496,6 +506,11 @@ interface DomPageActionOptions {
    * 不注入即 `attach` 一律按「用户取消」处理 —— Agent 永远传不进本地路径。
    */
   pickFiles?: () => Promise<readonly File[] | undefined>;
+  /**
+   * `back` 作用的文档；缺省 `globalThis.document`。
+   * 其余动作不用它——它们的文档从元素自带的 `ownerDocument` 取，跨帧时才不会拿错。
+   */
+  document?: Document;
 }
 /**
  * @experimental
@@ -537,6 +552,11 @@ type PageAgentReply = {
   type: 'perceive-result';
   result: PerceptionResult;
   targets: readonly PageAgentTargetEntry[];
+  /**
+   * 这批句柄属于哪个文档（分册 11 / FR-11.1）。**可选**是有意的：
+   * 0.15.0 的页面侧处理器不会回它，此时 reader 退回单分片，行为逐字不变。
+   */
+  document?: PageDocumentIdentity;
 } | {
   type: 'execute-result';
   outcome: PageActionOutcome;
@@ -545,6 +565,18 @@ type PageAgentReply = {
   code: string;
   message: string;
 };
+/**
+ * 文档标识（分册 11 / FR-11.1）。
+ *
+ * `key` 是**不透明**的：SDK 只拿它做相等比较与分片，不解析、不从中还原地址。
+ * `url` / `title` 只用于确认卡与留痕的可读性，不参与任何判定。
+ * @experimental
+ */
+interface PageDocumentIdentity {
+  key: string;
+  url?: string;
+  title?: string;
+}
 /**
  * 感知期随结果一并回传的句柄描述表（D-13-3）；**不进模型上下文**。
  *
@@ -562,22 +594,117 @@ interface PageAgentTargetEntry {
 }
 //#endregion
 //#region src/remote/registry.d.ts
+/**
+ * 句柄解析结果（0.16.0 分册 11 / FR-11.6）。
+ *
+ * 三种失败必须可区分：「不在当前这一页」「那一页已经变了」「从没见过」——
+ * 它们对模型的下一步要求完全不同，压成一个 `undefined` 就只能让它盲试。
+ * @experimental
+ */
+type TargetResolution = {
+  status: 'ok';
+  target: PageActionTarget;
+} |
+/** 认识，但它属于另一个还活着的页面 */
+{
+  status: 'unfocused';
+} |
+/** 认识过，但它那一页已经变了或被丢弃了 */
+{
+  status: 'expired';
+} |
+/** 从没见过（含上一轮 run 的句柄） */
+{
+  status: 'unknown';
+};
 /**
  * 感知期写入、执行期读取的句柄描述表（分册 13 / FR-13.3）。
  *
  * 由**宿主创建并同时交给 reader 和 executor**——两者共享同一个实例是本册的装配前提。
  * 工厂单独导出就是为了让这件事在宿主代码里显式可见，
  * 而不是藏在某个工厂内部让人以为「自己会连上」。
+ *
+ * 0.16.0 起按**文档**分片（分册 11 / D-11-1(d)）：分片键是一个不透明串，
+ * 「标签页」只是宿主给它的一种解释——本包不认识标签页，也不该认识（AC-G8）。
  * @experimental
  */
 interface RemoteTargetRegistry {
-  /** 用新一批条目**整体替换**旧表 */
-  replace(entries: readonly PageAgentTargetEntry[]): void;
+  /**
+   * 用新一批条目**整体替换**该文档分片的旧表，并把焦点移到它。
+   * `document` 缺省即单分片形态，行为与 0.15.0 逐字一致。
+   */
+  replace(entries: readonly PageAgentTargetEntry[], document?: PageDocumentIdentity): void;
+  /** 只查当前焦点分片。语义与 0.15.0 一致，既有调用点不必改 */
   get(ref: string): PageActionTarget | undefined;
+  /** `get` 的可诊断版本；`get` 保留是因为 `PageActionExecutor.describe` 的同步契约不能动 */
+  resolve(ref: string): TargetResolution;
+  /** 把后续的 `get` / `resolve` 指向该分片；分片不存在时焦点仍然移过去（其 `get` 全落空） */
+  focus(shard: string): void;
+  readonly focused: string | undefined;
+  /** 焦点分片的文档标识；用于留痕与确认卡文案，**不参与**任何判定 */
+  describePage(): PageDocumentIdentity | undefined;
+  /** 该分片失效（文档变了 / 标签页关了）。**不影响其它分片**（FR-11.3 / AC-11.5） */
+  drop(shard: string): void;
+  /** run 结束时清空（FR-11.4）。它只丢句柄，**不关闭任何标签页**——那是用户的浏览器 */
+  clear(): void;
+  /** 当前焦点分片的条目数；单分片下与 0.15.0 同值 */
   readonly size: number;
+  readonly shardCount: number;
+}
+/**
+ * 分片数的防泄漏软上限（分册 11 / DV-2）。
+ *
+ * 它**不是** FR-11.5 那个容量闸门：那一条管的是「同时有几个**标签页**可操作」，
+ * 触顶硬拒绝，落在 `TabWorksetPolicy`。这里管的是同一个标签页里连续跳页攒下的历史分片，
+ * 那些本来就该失效，按最久未使用逐出即可，逐出不构成对模型的拒绝。
+ */
+declare const SHARD_SOFT_LIMIT = 24;
+/**
+ * 把解析结果翻译成给模型看的补充说明（分册 11 / FR-11.6）；
+ * 接到 `PageActionPolicyOptions.diagnose` 上即可：
+ *
+ * ```ts
+ * diagnose: (ref) => explainResolution(targets.resolve(ref))
+ * ```
+ *
+ * `unknown` 返回 `undefined` 而不是自己拼一句：让 policy 落回它的缺省文案，
+ * 于是 AC-11.3 要求的「与 0.15.0 逐字相同」是**构造性**成立的，
+ * 而不是靠两个文件里的字符串抄得一样。
+ * @experimental
+ */
+declare function explainResolution(resolution: TargetResolution): string | undefined;
+/** @experimental */
+interface RemoteTargetRegistryOptions {
+  /** 分片数软上限；缺省 `SHARD_SOFT_LIMIT`。小于 1 的值按 1 处理 */
+  maxShards?: number;
 }
 /** @experimental */
-declare function createRemoteTargetRegistry(): RemoteTargetRegistry;
+declare function createRemoteTargetRegistry(options?: RemoteTargetRegistryOptions): RemoteTargetRegistry;
+//#endregion
+//#region src/remote/documentIdentity.d.ts
+/**
+ * 文档标识（0.16.0 分册 11 · FR-11.1）。
+ *
+ * 它有且只有两个消费者，且**必须是同一个函数**：
+ * ① 感知回复里的 `document.key`，决定这批句柄进哪个分片；
+ * ② `PageActionOutcome.navigated`，执行前后各取一次。
+ * 两处各写一套判定，就会出现「操作说导航了、分片说没换」的不一致（AC-11.4 / AC-13.4 验的就是这个）。
+ */
+/** `Window` 的最小切面；取这个而不是 `Window` 是为了让本模块在无 DOM 的测试里也能跑 */
+interface DocumentLocationView {
+  readonly location: {
+    readonly href: string;
+  };
+}
+/**
+ * `instance` + 当前地址。真导航换 `instance`，帧内路由（SPA）换 `href`，
+ * 两类都被这一个串覆盖——靠 origin 比对识别不出后者。
+ *
+ * `href` 含 hash 是有意的：纯 hash 跳转在很多站点上会换掉整块内容，
+ * 判成换文档是安全侧的选择（代价是多感知一次；漏判没有便宜的补救）。
+ * @experimental
+ */
+declare function documentKey(view: DocumentLocationView | null | undefined): string | undefined;
 //#endregion
 //#region src/remote/reader.d.ts
 /** @experimental */
@@ -587,6 +714,12 @@ interface RemotePerceptionReaderOptions {
   targets: RemoteTargetRegistry;
   /** 单次感知超时毫秒；缺省 10000 */
   timeoutMs?: number;
+  /**
+   * 刚读到的是哪个文档（分册 11）。宿主据此维护「标签页 → 分片」的归属，
+   * 页面自己跳走时才知道该丢哪个分片。**SDK 不替宿主记这层映射**——
+   * 那需要标签页概念，而本包不认识标签页（AC-G8）。
+   */
+  onDocument?: (document: PageDocumentIdentity) => void;
 }
 /**
  * 跨上下文的页面感知（分册 13 / FR-13.2）。
@@ -1381,4 +1514,4 @@ declare function watchBlockedResources(host: ViewerBlockedHost, notice: ViewerBl
 /** 提示文案的单一来源；判据直接引用，不各写一份字面量 */
 declare function blockedMessage(origins: readonly string[]): string;
 //#endregion
-export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, WORKER_BOOTSTRAP_SOURCE, type WindowLike, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };
+export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentLocationView, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HandleKind, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PageDocumentIdentity, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RemoteTargetRegistryOptions, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, type SandboxMode, type SerializedError, type TargetResolution, TsTranspiler, type TypeScriptSupportOptions, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, WORKER_BOOTSTRAP_SOURCE, type WindowLike, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, documentKey, explainResolution, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };