@mearl/provider 2.20.5 → 2.21.0

package/README.md

@@ -8,6 +8,8 @@ Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时
 
 控制会话由 Mearl 管理。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
 
+普通 action 响应中的 `session` 由 Mearl 附加，只包含路由与控制状态；`browser_control` 交接时还包含会话页面清单。`page_snapshot` 的文本 ref 可直接用于后续操作，Provider 应在自身运行时保存其定位映射，不在响应中输出内部节点 ID 字典。
+
 `page_upload` 接收执行宿主上的 `filePaths`，Mearl 负责中转调用方文件与浏览器产物。`page_download` 接收 `{ tabId, trigger, url?, timeout? }`；Provider 先监听下载，再执行点击，等待文件完成后返回 `ProviderDownloadResult`：`{ filename, filePath, action, owned? }`。`filePath` 是本地 Provider 进程宿主上的绝对路径，云端文件由 Provider 取回；`action` 是点击结果，`owned:true` 允许 Mearl 在导入后删除该中转文件。Mearl 将结果转为统一的浏览器产物，支持调用方保存、后续上传与会话清理。下载超时或来源不确定时返回错误，不重复点击。
 
 Provider v2 分开表达实例状态与控制方式：
@@ -114,6 +116,7 @@ server.updateBrowsers([
 `status: "stopped"` 和 `control: { kind: "none" }`。运行但尚未接通控制链路时使用
 `status: "running_disconnected"`。
 Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。
+`capabilities.actions` 应明确列出适配器已经实现并验证的动作，避免通过全量动作减排除项生成清单，使 SDK 新增动作被误报为可用。适配器转发请求时，只有能证明请求尚未发送的连接失败才可自动重连重试；已经发送、响应丢失或业务执行失败的动作不应自动重放。
 `start`、`detach`、`getAccess`、`syncCookies` 等可选实现必须与实例声明的 operation 对应；
 这些是 Provider runtime 的内部能力，不会要求 Mearl 公共协议增加一一对应的 action。
 
@@ -173,6 +176,8 @@ Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Local
 或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 `ProviderContext.host` 注入，Provider 合同本身不依赖 Extension、Native Messaging 或
 具体浏览器服务 SDK。
 
+指定 Provider 的启动、配置和动态表单查询只启动该 Provider；完整浏览器发现仍检查所有已安装 Provider。Mearl 的 Provider 控制宿主按调用方绝对期限管理排队及后续动作，旧调用方使用按动作推导的等待时间，持久化关闭和长时间等待不受固定两分钟限制。适配器自己的转发链路也应覆盖对应动作的时间预算，并在等待失败时保留执行结果不确定的语义。
+
 外部 Provider 的安装、发现与启动仍由 `@mearl/setup` 管理：
 
 ```bash

package/dist/generated-provider-actions.d.ts

@@ -1,3 +1,3 @@
-export declare const PROVIDER_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "set_rule", "get_rules", "send_request", "send_mtop_request", "browser_release", "page_screenshot", "tab_open", "tab_close", "tab_list", "tab_group", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "request_domain_permission", "run_actions", "page_download"];
+export declare const PROVIDER_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "set_rule", "get_rules", "send_request", "send_mtop_request", "browser_release", "page_screenshot", "tab_open", "tab_close", "tab_list", "tab_group", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_runtime", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "request_domain_permission", "run_actions", "page_download"];
 export type ProviderAction = (typeof PROVIDER_ACTIONS)[number];
 export declare function isProviderAction(value: unknown): value is ProviderAction;

package/dist/generated-provider-actions.js

@@ -24,6 +24,7 @@ export const PROVIDER_ACTIONS = [
     'page_scroll',
     'page_hover',
     'page_eval',
+    'page_runtime',
     'page_inspect',
     'page_snapshot',
     'page_press',

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-export { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from './registry.js';
+export { listInstalledProviders, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from './registry.js';
 export type { InstalledProviderManifest, ProviderPackageMetadata } from './types.js';
 export { ensureProviderControlHost, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';
 export type { ProviderControlHostRecord } from './control-host.js';

package/dist/host.js

@@ -1,2 +1,2 @@
-export { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from './registry.js';
+export { listInstalledProviders, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from './registry.js';
 export { ensureProviderControlHost, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';

package/dist/launcher.d.ts

@@ -1,3 +1,3 @@
 export declare const PROVIDER_LOGS_SUBDIR = "providers/logs";
 /** Start explicitly installed on-demand providers before browser discovery. */
-export declare function ensureInstalledProvidersRunning(): Promise<string[]>;
+export declare function ensureInstalledProvidersRunning(providerIds?: readonly string[]): Promise<string[]>;

package/dist/launcher.js

@@ -48,9 +48,10 @@ async function spawnProvider(manifest, logFile, startToken) {
     }
 }
 /** Start explicitly installed on-demand providers before browser discovery. */
-export async function ensureInstalledProvidersRunning() {
+export async function ensureInstalledProvidersRunning(providerIds) {
     const warnings = [];
-    const installed = listInstalledProviders();
+    const selected = providerIds ? new Set(providerIds) : undefined;
+    const installed = listInstalledProviders().filter(provider => !selected || selected.has(provider.providerId));
     const live = liveProviderIds();
     const starting = new Map();
     for (const manifest of installed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/provider",
-  "version": "2.20.5",
+  "version": "2.21.0",
   "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@mearl/daemon-core": "2.20.5"
+    "@mearl/daemon-core": "2.21.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",