@mearl/client 2.20.6 → 2.22.0

package/dist/generated/plugin-tasks.d.ts

@@ -0,0 +1,74 @@
+import type { PluginExecutionError, PluginExecutionHost, PluginInvocationSource } from './plugin-execution.js';
+import type { PluginTaskCheckpointReference } from './plugin-recovery.js';
+export declare const PLUGIN_TASK_PROTOCOL_VERSION = 5;
+export type PluginTaskState = 'queued' | 'running' | 'cancelling' | 'success' | 'error' | 'cancelled' | 'interrupted';
+export interface PluginTaskResultReference {
+    bytes: number;
+    sha256: string;
+    chunks: number;
+}
+export interface PluginTask {
+    taskId: string;
+    host: PluginExecutionHost;
+    plugin: string;
+    installationId: string;
+    revision: string;
+    command: string;
+    kind?: 'command' | 'model';
+    parentTaskId?: string;
+    resumedFrom?: {
+        taskId: string;
+        revision: string;
+        checkpointSequence: number;
+        checkpointVersion: number;
+    };
+    checkpoint?: PluginTaskCheckpointReference;
+    input: Record<string, unknown>;
+    source: PluginInvocationSource;
+    cwd: string;
+    state: PluginTaskState;
+    sequence: number;
+    createdAt: number;
+    updatedAt: number;
+    progress?: string | {
+        message: string;
+        data?: Record<string, unknown>;
+    };
+    result?: PluginTaskResultReference;
+    error?: PluginExecutionError;
+}
+export interface PluginTaskEvent {
+    sequence: number;
+    time: number;
+    type: 'state' | 'progress' | 'checkpoint' | 'diagnostic';
+    checkpoint?: PluginTaskCheckpointReference;
+    state: PluginTaskState;
+    progress?: PluginTask['progress'];
+}
+export interface PluginTaskEvents {
+    task: PluginTask;
+    events: PluginTaskEvent[];
+    firstAvailableSequence: number;
+    nextCursor: number;
+    gap: boolean;
+}
+export interface PluginTaskStartResult {
+    taskId: string;
+    state: PluginTaskState;
+    host: PluginExecutionHost;
+    reused?: true;
+}
+export interface PluginTaskListResult {
+    tasks: PluginTask[];
+    nextCursor?: string;
+}
+export interface PluginTaskResultChunk {
+    taskId: string;
+    index: number;
+    data: string;
+    bytes: number;
+    sha256: string;
+    chunks: number;
+}
+export declare function isPluginTaskActive(state: PluginTaskState): boolean;
+export declare function isPluginTaskId(value: unknown): value is string;

package/dist/generated/plugin-tasks.js

@@ -0,0 +1,7 @@
+export const PLUGIN_TASK_PROTOCOL_VERSION = 5;
+export function isPluginTaskActive(state) {
+    return state === 'queued' || state === 'running' || state === 'cancelling';
+}
+export function isPluginTaskId(value) {
+    return typeof value === 'string' && /^pt_[0-9a-f-]{36}_[0-9a-f-]{36}$/i.test(value);
+}

package/dist/generated/toolbox-icon.d.ts

@@ -0,0 +1,10 @@
+export type ParsedToolboxIcon = {
+    kind: 'name';
+    name: string;
+} | {
+    kind: 'image';
+    src: string;
+    monochrome?: true;
+};
+/** SVG is an image source so its markup never becomes executable extension DOM. */
+export declare function parseToolboxIcon(value: unknown): ParsedToolboxIcon | undefined;

package/dist/generated/toolbox-icon.js

@@ -0,0 +1,37 @@
+/** SVG is an image source so its markup never becomes executable extension DOM. */
+export function parseToolboxIcon(value) {
+    if (typeof value !== 'string')
+        return;
+    const icon = value.trim();
+    if (!icon || icon.length > 32 * 1024)
+        return;
+    if (/^[a-z][a-z0-9-]{0,39}$/.test(icon))
+        return { kind: 'name', name: icon };
+    if (/^(?:<\?xml\s[^>]*\?>\s*)?<svg\b[^>]*(?:\/>|>[\s\S]*<\/svg\s*>)$/i.test(icon)) {
+        const svg = /<svg\b[^>]*\sxmlns\s*=/i.test(icon)
+            ? icon
+            : icon.replace(/<svg\b/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+        try {
+            return {
+                kind: 'image',
+                src: `data:image/svg+xml,${encodeURIComponent(svg)}`,
+                ...(/\bcurrentColor\b/i.test(svg) ? { monochrome: true } : {}),
+            };
+        }
+        catch {
+            return;
+        }
+    }
+    const dataHeader = /^data:image\/(?:svg\+xml|png|jpeg|gif|webp|avif)(?:;charset=utf-8|;utf8)?(?:;base64)?,/i.exec(icon);
+    if (dataHeader && icon.length > dataHeader[0].length)
+        return { kind: 'image', src: icon };
+    try {
+        const url = new URL(icon);
+        if (['http:', 'https:'].includes(url.protocol) && !url.username && !url.password) {
+            return { kind: 'image', src: url.href };
+        }
+    }
+    catch {
+        /* Non-URL values cannot be image sources. */
+    }
+}

package/dist/index.d.ts

@@ -1,16 +1,21 @@
+export { PluginHostConnection, type PluginHostConnectionOptions, type PluginHostClientOptions, } from './plugins/clients/pluginHostConnection.js';
 /**
  * @mearl/client — unified Mearl browser client
  *
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
+export { PluginTaskClient, type PluginTaskStartOptions, type PluginTaskWaitOptions, type PluginTaskClientOptions, type PluginTask, type PluginTaskEvents, type PluginTaskListResult, type PluginTaskStartResult, } from './plugins/clients/pluginTasks.js';
+export { PluginPageClient } from './plugins/clients/pluginPages.js';
+export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from './plugins/clients/pluginPages.js';
+export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, type PluginCommandContext, type PluginExecutionHost, type PluginInvocationIdentity, type PluginInvocationSource, } from './plugins/sdk/plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
+export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugins/sdk/plugin.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated/browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated/browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
-import type * as Protocol from './generated-browser-action-protocol.js';
+import type * as Protocol from './generated/browser-action-protocol.js';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
 /** Compatibility wrapper for tabCheckpoint. */
 export declare function captureCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -61,3 +66,9 @@ export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
     outputPath: string;
     bytes: number;
 }>;
+export { PluginStateClient } from './plugins/clients/pluginState.js';
+export { PluginModelClient } from './plugins/clients/pluginModels.js';
+export type * from './generated/plugin-state.js';
+export type * from './generated/plugin-models.js';
+export type * from './generated/plugin-recovery.js';
+export type * from './generated/plugin-diagnostics.js';

package/dist/index.js

@@ -1,11 +1,15 @@
+export { PluginHostConnection, } from './plugins/clients/pluginHostConnection.js';
 /**
  * @mearl/client — unified Mearl browser client
  *
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
+export { PluginTaskClient, } from './plugins/clients/pluginTasks.js';
+export { PluginPageClient } from './plugins/clients/pluginPages.js';
+export { executeRegisteredPlugin, } from './plugins/sdk/plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated/browser-action-protocol.js';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params, options) {
     return invoke('tab_checkpoint', params, options);
@@ -140,3 +144,5 @@ export async function saveArtifact(artifact, outputPath, options = {}) {
     const { exportArtifact } = await import('./artifacts.js');
     return exportArtifact({ invoke }, artifact, outputPath, options);
 }
+export { PluginStateClient } from './plugins/clients/pluginState.js';
+export { PluginModelClient } from './plugins/clients/pluginModels.js';

package/dist/pageEvalArguments.d.ts

@@ -1,3 +1,3 @@
-import { type PageEvalParams } from './generated-browser-action-protocol.js';
+import { type PageEvalParams } from './generated/browser-action-protocol.js';
 /** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
 export declare function invokePageEvalWithArgs(invoke: (payload: Record<string, unknown>, transfer?: boolean) => Promise<any>, params: PageEvalParams): Promise<any>;

package/dist/pageEvalArguments.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated-browser-action-protocol.js';
+import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated/browser-action-protocol.js';
 const CHUNK_CHARACTERS = 48 * 1024;
 /** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
 export async function invokePageEvalWithArgs(invoke, params) {

package/dist/plugin-task-host.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin-task-host.js

@@ -0,0 +1,14 @@
+import { startPluginHostServer } from './plugins/runtime/pluginHostServer.js';
+try {
+    const server = await startPluginHostServer();
+    const close = () => {
+        void server.close().then(() => process.exit(0));
+    };
+    process.once('SIGTERM', close);
+    process.once('SIGINT', close);
+}
+catch (error) {
+    if (error.code !== 'PLUGIN_TASK_HOST_OWNED')
+        process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exitCode = error.code === 'PLUGIN_TASK_HOST_OWNED' ? 0 : 1;
+}

package/dist/plugin-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin-worker.js

@@ -0,0 +1,17 @@
+import { supervisePluginExecutor } from './plugins/runtime/pluginExecutorSupervisor.js';
+if (process.argv[2] === '--command') {
+    let command;
+    // Register IPC before loading command code so startup messages retain their order.
+    process.on('message', (message) => {
+        void (command ??= import('./plugins/runtime/pluginCommandWorker.js'))
+            .then(worker => worker.handlePluginWorkerMessage(message))
+            .catch(error => {
+            process.stderr.write(String(error));
+            process.exit(1);
+        });
+    });
+    process.on('disconnect', () => process.exit(1));
+}
+else {
+    supervisePluginExecutor(import.meta.url);
+}

package/dist/plugin.d.ts

@@ -1,65 +1 @@
-import type { AppProfileContribution } from './generated-app-profile-definition.js';
-export type { AppProfileContribution, AppProfileDefinition, } from './generated-app-profile-definition.js';
-export { invokePageEvalWithArgs } from './pageEvalArguments.js';
-import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
-import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
-import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from './pluginRegistry.js';
-export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from './officialPluginCatalog.js';
-export type PluginOptions = UnifiedInvokeOptions;
-export interface StructuredPluginProgress {
-    message: string;
-    data?: Record<string, unknown>;
-}
-export type PluginProgress = string | StructuredPluginProgress;
-export interface PluginInvocation {
-    command: string;
-    input: Record<string, any>;
-}
-export interface PluginInvokeOptions extends UnifiedInvokeOptions {
-    onProgress?: (progress: PluginProgress) => void;
-}
-export interface PluginExecutionContext {
-    ensurePlugin?: OfficialPluginInstaller;
-    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
-}
-export interface PluginApp {
-    readonly options: Readonly<PluginOptions>;
-    /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
-    command(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
-    /** Registers a page-only command, also declared in toolbox.page.commands. */
-    toolboxCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
-    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
-    progress(progress: PluginProgress): void;
-}
-export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
-/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
-export declare function refreshRegisteredPlugin(name: string, includePage?: boolean): Promise<PluginRegistration | undefined>;
-/** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
-export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
-    name: string | undefined;
-    description: string | undefined;
-    toolbox: PluginToolboxContribution | undefined;
-    appProfiles: AppProfileContribution | undefined;
-    profileSources: Record<string, string> | undefined;
-    version: string | undefined;
-    commandHelp(namespace: string): string;
-    help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
-    runToolbox(invocation: PluginInvocation): Promise<unknown>;
-}>;
-export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
-    name: string | undefined;
-    description: string | undefined;
-    toolbox: PluginToolboxContribution | undefined;
-    appProfiles: AppProfileContribution | undefined;
-    profileSources: Record<string, string> | undefined;
-    version: string | undefined;
-    commandHelp(namespace: string): string;
-    help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
-    runToolbox(invocation: PluginInvocation): Promise<unknown>;
-}>;
-export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
-/** Entry point for the native toolbox service; nested plugin calls retain public-command access. */
-export declare function invokeRegisteredToolboxPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
+export * from './plugins/sdk/plugin.js';