@mearl/provider 2.19.2 → 2.20.0

package/README.md

@@ -6,6 +6,10 @@ Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时
 
 ## 核心模型
 
+控制会话由 Mearl 管理。Provider 继续接收目标实例、页面与普通 action，无需处理控制会话 ID、资源归属或人工交接状态。带 `--session` 的释放只结束 Mearl 任务控制；实例关闭、退出接管与 Cookie 同步仍使用 Provider 的生命周期方法。上传与下载分别按 `capabilities.actions` 中的 `page_upload`、`page_download` 声明使用。
+
+`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 分开表达实例状态与控制方式：
 
 - `status`：实例处于 `connected`、`pairing`、`running_disconnected` 或 `stopped`。

package/dist/control-host.d.ts

@@ -0,0 +1,11 @@
+import { type DaemonRecord } from '@mearl/daemon-core';
+export interface ProviderControlHostRecord extends DaemonRecord {
+    socketPath: string;
+    token: string;
+    ready: boolean;
+}
+export declare function providerControlHostFile(): string;
+export declare function providerControlSocketPath(pid: number): string;
+export declare function readProviderControlHost(): ProviderControlHostRecord | null;
+/** A single host owns Provider sessions across independent CLI and connector processes. */
+export declare function ensureProviderControlHost(timeoutMs?: number): Promise<ProviderControlHostRecord>;

package/dist/control-host.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isAlive, keyedConfigFile, claimRecord, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecordIfPid, } from '@mearl/daemon-core';
+export function providerControlHostFile() {
+    return keyedConfigFile('control', 'providers');
+}
+export function providerControlSocketPath(pid) {
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\mearl-provider-control-${pid}`
+        : join(tmpdir(), `mearl-provider-control-${pid}.sock`);
+}
+export function readProviderControlHost() {
+    const record = readRecord(providerControlHostFile());
+    return record?.ready && typeof record.socketPath === 'string' && isAlive(record.pid)
+        ? record
+        : null;
+}
+let startup;
+/** A single host owns Provider sessions across independent CLI and connector processes. */
+export function ensureProviderControlHost(timeoutMs = 10_000) {
+    if (startup)
+        return startup;
+    const pending = (async () => {
+        const file = providerControlHostFile();
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const ready = readProviderControlHost();
+            if (ready)
+                return ready;
+            const previous = readRecord(file);
+            if (!previous || !isAlive(previous.pid)) {
+                if (previous)
+                    removeRecordIfPid(file, previous.pid);
+                else
+                    removeInvalidRecord(file);
+                const token = randomUUID();
+                if (claimRecord(file, { pid: process.pid, socketPath: '', token, ready: false })) {
+                    try {
+                        const entry = process.env.MEARL_NATIVE_HOST_ENTRY;
+                        const child = spawn(entry ? process.execPath : 'mearl-native-host', [...(entry ? [entry] : []), '--provider-control', token], { detached: true, stdio: 'ignore', windowsHide: true });
+                        await new Promise((resolve, reject) => {
+                            child.once('error', reject);
+                            child.once('spawn', resolve);
+                        });
+                        child.unref();
+                        if (!child.pid)
+                            throw new Error('Provider control host did not report its pid');
+                        writeRecordIfPid(file, process.pid, {
+                            pid: child.pid,
+                            socketPath: providerControlSocketPath(child.pid),
+                            token,
+                            ready: false,
+                        });
+                    }
+                    catch (error) {
+                        removeRecordIfPid(file, process.pid);
+                        throw error;
+                    }
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+        throw new Error('Provider control host startup timed out');
+    })();
+    startup = pending;
+    void pending
+        .finally(() => {
+        if (startup === pending)
+            startup = undefined;
+    })
+        .catch(() => { });
+    return pending;
+}

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"];
+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 type ProviderAction = (typeof PROVIDER_ACTIONS)[number];
 export declare function isProviderAction(value: unknown): value is ProviderAction;

package/dist/generated-provider-actions.js

@@ -38,6 +38,7 @@ export const PROVIDER_ACTIONS = [
     'set_cookie',
     'request_domain_permission',
     'run_actions',
+    'page_download',
 ];
 const providerActionSet = new Set(PROVIDER_ACTIONS);
 export function isProviderAction(value) {

package/dist/host.d.ts

@@ -1,2 +1,4 @@
 export { listInstalledProviders, registerProviderPackage, stopProvider, 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 +1,2 @@
 export { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from './registry.js';
+export { ensureProviderControlHost, readProviderControlHost, providerControlHostFile, providerControlSocketPath, } from './control-host.js';

package/dist/server.js

@@ -81,6 +81,8 @@ export function createProviderServer(options) {
         throw new Error('browserId is required when the provider has multiple browsers');
     }
     async function dispatch(request) {
+        if (request.controlSessionId)
+            throw new Error('CONTROL_SESSION_UNSUPPORTED: this Provider does not implement control sessions');
         const context = providerContext(request);
         if (request.action === 'browser_launch') {
             if (request.browserId)

package/dist/types.d.ts

@@ -11,6 +11,14 @@ export interface ProviderCapabilities {
     actions: ProviderAction[];
     screenshot: ProviderScreenshotKind;
 }
+/** Completed download staged on the local Provider process host for Mearl transfer. */
+export interface ProviderDownloadResult {
+    filename: string;
+    filePath: string;
+    action: JsonValue;
+    /** Allows Mearl to remove the staged file after importing it. */
+    owned?: boolean;
+}
 export interface ProviderPairingInfo {
     kind: 'qr';
     url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/provider",
-  "version": "2.19.2",
+  "version": "2.20.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.19.2"
+    "@mearl/daemon-core": "2.20.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",