@mearl/provider 2.19.3 → 2.20.1

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`。
@@ -132,6 +136,31 @@ Provider 可用 `component: "switch"` 渲染紧凑布尔开关；`formHidden`
 `browserType.documentationUrl` 声明 HTTP(S) 文档地址；`configuration.inputSchema` 声明配置参数，
 配置只传给所选 Provider 的 `configure`，不存入页面本地存储。
 
+Provider 需要查询设备池、已有会话或动态候选项时，声明 `browserType.dynamicLaunchForm: true`
+并实现只读的 `getLaunchForm({ variant?, values }, context)`。
+`browserType.launchForm` 可提供无网络依赖的初始表单，弹窗立即渲染其字段和模式；
+各 `variants[]` 可用 `inputSchema/values/refreshOn/dynamicFields` 覆盖该模式的初值。
+`dynamicFields` 指定异步查询期间需要禁用的字段，其余字段与模式选择保持可操作；加载状态在表单状态行显示。
+初次查询携带静态表单默认值；查询只传入可解析的字段，最终启动仍严格校验全部输入。
+用户在等待期间输入的内容会保留，切换模式或环境会使旧请求失效。
+管理器通过内部
+`browser_provider_launch_form` 请求获取 `ProviderLaunchForm`，不识别 Provider ID 或业务字段：
+
+- `inputSchema` 描述当前模式的用户输入，`required` 决定必填标识与提交校验。
+- `variants` 的 `id/title/description` 描述连接方式，`variant` 指定当前方式。
+- `values` 是 Provider 给出的固定启动参数，提交时与用户输入合并；只包含非敏感参数。
+- 字符串字段的 `options` 使用 `{ value, label, description?, disabled? }` 描述候选项。
+  禁用项只供展示；运行时的最终资源状态由 Provider 的 `launch` 再次核验。
+- `refreshOn` 指定需要重新查询表单的字段；字段变化会清空其他选项字段的选择。
+  刷新时保留已有输入，选项字段仅保留仍有效的选择；切换模式重新使用该模式默认值。
+- `message` 展示查询结果，`blocked` 阻止无资源、无有效会话等情况下的提交。
+
+查询过程不得创建或租用资源，也不得返回凭据。Runtime 会校验返回的 schema、候选项、
+模式与固定参数。最终 `launch` 仍使用 `browserType.inputSchema` 校验，动态表单不改变 CLI/API
+参数契约。未声明动态表单的 Provider 继续使用静态 schema。
+开发联调时，Provider 应链接包含该公开契约的本地 `@mearl/provider` 构建；分发时需配套发布
+包含动态表单能力的 SDK、Mearl 宿主与 Provider。
+
 `details` 中的通用键具有固定类型：`headless` 为布尔值，`createdAt` 为可解析时间字符串，
 `cdpPort` 为有效端口，`account` 包含 `nickname` 和可选的字符串 `accountId/loginId`，
 `copiedCookies` 包含字符串数组 `domains` 和非负整数 `count`。其余键允许非敏感 JSON，界面同样展示。

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/index.d.ts

@@ -1,5 +1,5 @@
 export * from './types.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
 export { providerDataDir } from './registry.js';
-export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, validateProviderLaunchForm, } from './provider-runtime.js';
 export { createProviderServer } from './server.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export * from './types.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
 export { providerDataDir } from './registry.js';
-export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, validateProviderLaunchForm, } from './provider-runtime.js';
 export { createProviderServer } from './server.js';

package/dist/provider-runtime.d.ts

@@ -1,5 +1,6 @@
-import type { BrowserProviderDefinition, JsonObject, ProviderBrowser, ProviderInputSchema, ProviderObjectSchema, ProviderRuntime } from './types.js';
+import type { BrowserProviderDefinition, JsonObject, ProviderBrowser, ProviderInputSchema, ProviderObjectSchema, ProviderRuntime, ProviderLaunchForm } from './types.js';
 export declare function isProviderInputSchema(value: unknown, depth?: number): value is ProviderInputSchema;
 export declare function validateProviderInput(schema: ProviderObjectSchema, value: JsonObject): void;
 export declare function validateProviderBrowser(browser: ProviderBrowser): void;
+export declare function validateProviderLaunchForm(form: ProviderLaunchForm): void;
 export declare function createProviderRuntime(definition: BrowserProviderDefinition): ProviderRuntime;

package/dist/provider-runtime.js

@@ -71,7 +71,18 @@ export function isProviderInputSchema(value, depth = 0) {
                 Number(schema.minLength) <= Number(schema.maxLength)) &&
             isOptionalString(schema.pattern) &&
             validPattern &&
-            isOptionalString(schema.placeholder);
+            isOptionalString(schema.placeholder) &&
+            (schema.options === undefined ||
+                (Array.isArray(schema.options) &&
+                    schema.options.every(option => option &&
+                        typeof option === 'object' &&
+                        !Array.isArray(option) &&
+                        typeof option.value === 'string' &&
+                        typeof option.label === 'string' &&
+                        isOptionalString(option.description) &&
+                        (option.disabled === undefined || typeof option.disabled === 'boolean') &&
+                        (schema.enum === undefined || schema.enum.includes(option.value))) &&
+                    new Set(schema.options.map(option => option.value)).size === schema.options.length));
         if (!valid)
             return false;
     }
@@ -387,6 +398,13 @@ function validateDefinition(definition) {
         (typeof definition.browserType.documentationUrl !== 'string' ||
             !/^https?:\/\//.test(definition.browserType.documentationUrl)))
         throw new Error('Provider documentation URL must use HTTP(S)');
+    if (definition.browserType.dynamicLaunchForm !== undefined &&
+        typeof definition.browserType.dynamicLaunchForm !== 'boolean')
+        throw new Error('Provider dynamic launch form declaration is invalid');
+    if (definition.browserType.dynamicLaunchForm && !definition.getLaunchForm)
+        throw new Error('Provider does not implement getLaunchForm');
+    if (definition.browserType.launchForm !== undefined)
+        validateProviderLaunchForm(definition.browserType.launchForm);
     const configuration = definition.browserType.configuration;
     if (configuration &&
         (!isProviderInputSchema(configuration.inputSchema) ||
@@ -394,6 +412,45 @@ function validateDefinition(definition) {
         throw new Error('Provider configuration schema is invalid');
     }
 }
+export function validateProviderLaunchForm(form) {
+    if (!form ||
+        !isProviderInputSchema(form.inputSchema) ||
+        form.inputSchema.type !== 'object' ||
+        !isOptionalString(form.variant) ||
+        !isOptionalString(form.message) ||
+        (form.blocked !== undefined && typeof form.blocked !== 'boolean') ||
+        (form.values !== undefined &&
+            (!form.values ||
+                typeof form.values !== 'object' ||
+                Array.isArray(form.values) ||
+                !isJsonValue(form.values))) ||
+        (form.dynamicFields !== undefined &&
+            (!Array.isArray(form.dynamicFields) ||
+                form.dynamicFields.some(field => typeof field !== 'string' || !(field in form.inputSchema.properties)))) ||
+        (form.refreshOn !== undefined &&
+            (!Array.isArray(form.refreshOn) ||
+                form.refreshOn.some(field => typeof field !== 'string' || !(field in form.inputSchema.properties)))) ||
+        (form.variants !== undefined &&
+            (!Array.isArray(form.variants) ||
+                !form.variants.length ||
+                form.variants.some(variant => !variant ||
+                    typeof variant.id !== 'string' ||
+                    !variant.id ||
+                    typeof variant.title !== 'string' ||
+                    !isOptionalString(variant.description)) ||
+                new Set(form.variants.map(variant => variant.id)).size !== form.variants.length ||
+                !form.variants.some(variant => variant.id === form.variant)))) {
+        throw new Error('Provider returned an invalid launch form');
+    }
+    for (const variant of form.variants ?? []) {
+        validateProviderLaunchForm({
+            inputSchema: variant.inputSchema === undefined ? form.inputSchema : variant.inputSchema,
+            values: variant.values === undefined ? form.values : variant.values,
+            refreshOn: variant.refreshOn === undefined ? form.refreshOn : variant.refreshOn,
+            dynamicFields: variant.dynamicFields === undefined ? form.dynamicFields : variant.dynamicFields,
+        });
+    }
+}
 export function createProviderRuntime(definition) {
     validateDefinition(definition);
     let publishedBrowsers = [];
@@ -445,6 +502,26 @@ export function createProviderRuntime(definition) {
             }
             publishedBrowsers = [...browsers];
         },
+        async getLaunchForm(request, context = {}) {
+            if (!definition.browserType.dynamicLaunchForm || !definition.getLaunchForm)
+                throw new Error('Provider does not support dynamic launch forms');
+            if (!request ||
+                !isOptionalString(request.variant) ||
+                !request.values ||
+                typeof request.values !== 'object' ||
+                Array.isArray(request.values) ||
+                !isJsonValue(request.values))
+                throw new Error('Invalid launch form request');
+            const form = await definition.getLaunchForm(request, context);
+            validateProviderLaunchForm(form);
+            for (const [key, value] of Object.entries(form.values ?? {})) {
+                const schema = definition.browserType.inputSchema.properties[key];
+                if (!schema)
+                    throw new Error(`Launch form returned an unknown parameter: ${key}`);
+                validateSchemaValue(schema, value, key);
+            }
+            return form;
+        },
         async launch(options, context = {}) {
             validateProviderInput(definition.browserType.inputSchema, options);
             const browser = await definition.launch(options, context);

package/dist/registry.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { claimRecord, ensureDir, hashKey, isAlive, keyedConfigFile, keyedDir, listRecordFiles, readLiveRecords, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecord, writeRecordIfPid, } from '@mearl/daemon-core';
 import { MEARL_PROVIDER_PROTOCOL_VERSION, } from './types.js';
-import { isProviderInputSchema } from './provider-runtime.js';
+import { validateProviderLaunchForm, isProviderInputSchema } from './provider-runtime.js';
 export const INSTALLED_PROVIDERS_SUBDIR = 'providers/installed';
 export const LIVE_PROVIDERS_SUBDIR = 'providers/live';
 export const STARTING_PROVIDERS_SUBDIR = 'providers/starting';
@@ -155,6 +155,17 @@ function isProviderBrowserType(value) {
         return false;
     if (!isProviderObjectSchema(browserType.inputSchema))
         return false;
+    if (browserType.dynamicLaunchForm !== undefined &&
+        typeof browserType.dynamicLaunchForm !== 'boolean')
+        return false;
+    if (browserType.launchForm !== undefined) {
+        try {
+            validateProviderLaunchForm(browserType.launchForm);
+        }
+        catch {
+            return false;
+        }
+    }
     return (browserType.configuration === undefined ||
         (Boolean(browserType.configuration) &&
             typeof browserType.configuration === 'object' &&

package/dist/server.js

@@ -81,7 +81,17 @@ 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_provider_launch_form') {
+            if (request.browserId)
+                throw new Error('Provider launch form does not accept browserId');
+            return runtime.getLaunchForm({
+                variant: request.data?.variant,
+                values: request.data?.values,
+            }, context);
+        }
         if (request.action === 'browser_launch') {
             if (request.browserId)
                 throw new Error('browser_launch does not accept 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;
@@ -54,6 +62,37 @@ export interface ProviderStringSchema extends ProviderSchemaBase {
     maxLength?: number;
     pattern?: string;
     placeholder?: string;
+    options?: readonly ProviderInputOption[];
+}
+export interface ProviderInputOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+export interface ProviderLaunchFormRequest {
+    variant?: string;
+    values: JsonObject;
+}
+export interface ProviderLaunchFormVariant {
+    id: string;
+    title: string;
+    description?: string;
+    inputSchema?: ProviderObjectSchema;
+    values?: JsonObject;
+    refreshOn?: readonly string[];
+    dynamicFields?: readonly string[];
+}
+/** Read-only presentation data; values are fixed launch parameters, never credentials. */
+export interface ProviderLaunchForm {
+    inputSchema: ProviderObjectSchema;
+    variants?: readonly ProviderLaunchFormVariant[];
+    variant?: string;
+    values?: JsonObject;
+    refreshOn?: readonly string[];
+    dynamicFields?: readonly string[];
+    message?: string;
+    blocked?: boolean;
 }
 export interface ProviderNumberSchema extends ProviderSchemaBase {
     type: 'number';
@@ -89,6 +128,8 @@ export interface ProviderBrowserType {
     help?: readonly string[];
     inputSchema: ProviderObjectSchema;
     configuration?: ProviderConfigurationDefinition;
+    dynamicLaunchForm?: boolean;
+    launchForm?: ProviderLaunchForm;
 }
 export type ProviderBrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
 export type ProviderOwnership = 'owned' | 'attached';
@@ -202,6 +243,7 @@ export interface BrowserProviderDefinition {
     syncCookies?: (request: ProviderSyncCookiesRequest, context: ProviderContext) => Promise<unknown>;
     getAccess?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderAccess>;
     configure?: (options: JsonObject, context: ProviderContext) => Promise<unknown>;
+    getLaunchForm?: (request: ProviderLaunchFormRequest, context: ProviderContext) => Promise<ProviderLaunchForm>;
     handleAction?: (context: ProviderActionContext) => Promise<unknown>;
 }
 export interface ProviderRuntime {
@@ -215,6 +257,7 @@ export interface ProviderRuntime {
     syncCookies(request: ProviderSyncCookiesRequest, context?: ProviderContext): Promise<unknown>;
     getAccess(request: ProviderInstanceRequest, context?: ProviderContext): Promise<ProviderAccess>;
     configure(options: JsonObject, context?: ProviderContext): Promise<unknown>;
+    getLaunchForm(request: ProviderLaunchFormRequest, context?: ProviderContext): Promise<ProviderLaunchForm>;
     invokeAction(context: ProviderActionContext): Promise<unknown>;
 }
 export interface ProviderServerOptions {

package/package.json

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