@mearl/provider 2.20.0 → 2.20.1

package/README.md

@@ -136,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/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

@@ -84,6 +84,14 @@ export function createProviderServer(options) {
         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

@@ -62,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';
@@ -97,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';
@@ -210,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 {
@@ -223,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.20.0",
+  "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.20.0"
+    "@mearl/daemon-core": "2.20.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",