@mearl/client 2.13.0 → 2.15.0

package/dist/generated-browser-action-protocol.js

@@ -64,14 +64,12 @@ export const BROWSER_ACTIONS = {
     get_requests: true,
     get_logs: true,
     get_events: true,
-    get_api_schema: true,
     set_mock: true,
     get_mocks: true,
     set_rule: true,
     get_rules: true,
     send_request: true,
     send_mtop_request: true,
-    tdbank_account: true,
     browser_list: true,
     browser_select_browser: true,
     browser_release: true,
@@ -102,7 +100,6 @@ export const BROWSER_ACTIONS = {
     record_start: true,
     record_stop: true,
     request_domain_permission: true,
-    get_user_info: true,
     run_actions: true,
 };
 export const BROWSER_COMMAND_ACTIONS = {
@@ -111,14 +108,12 @@ export const BROWSER_COMMAND_ACTIONS = {
     get_requests: true,
     get_logs: true,
     get_events: true,
-    get_api_schema: true,
     set_mock: true,
     get_mocks: true,
     set_rule: true,
     get_rules: true,
     send_request: true,
     send_mtop_request: true,
-    tdbank_account: true,
     browser_list: true,
     browser_release: true,
     browser_launch: true,
@@ -148,7 +143,6 @@ export const BROWSER_COMMAND_ACTIONS = {
     record_start: true,
     record_stop: true,
     request_domain_permission: true,
-    get_user_info: true,
     run_actions: true,
 };
 export const EXTENSION_BROWSER_ACTIONS = {
@@ -157,14 +151,12 @@ export const EXTENSION_BROWSER_ACTIONS = {
     get_requests: true,
     get_logs: true,
     get_events: true,
-    get_api_schema: true,
     set_mock: true,
     get_mocks: true,
     set_rule: true,
     get_rules: true,
     send_request: true,
     send_mtop_request: true,
-    tdbank_account: true,
     browser_release: true,
     page_screenshot: true,
     page_selected_element: true,
@@ -191,7 +183,6 @@ export const EXTENSION_BROWSER_ACTIONS = {
     record_start: true,
     record_stop: true,
     request_domain_permission: true,
-    get_user_info: true,
     run_actions: true,
 };
 export function isBrowserAction(value) {

package/dist/index.d.ts

@@ -4,10 +4,11 @@
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
-export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.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 } from './plugin.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_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, BrowserLaunchParams, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } 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, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, 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';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -18,10 +19,8 @@ export declare function getLogs(params?: Protocol.GetLogsParams, options?: Unifi
 export declare function getEvents(params?: Protocol.GetEventsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_events'>>;
 export declare function setMock(params: Protocol.SetMockParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_mock'>>;
 export declare function getMocks(params?: Protocol.GetMocksParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_mocks'>>;
-export declare function getApiSchema(params: Protocol.GetApiSchemaParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_api_schema'>>;
 export declare function sendRequest(params: Protocol.SendRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_request'>>;
 export declare function sendMtopRequest(params: Protocol.SendMtopRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_mtop_request'>>;
-export declare function tdbankAccount(params?: Protocol.TdbankAccountParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tdbank_account'>>;
 export declare function browserList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
 export declare function selectBrowser(params?: Protocol.SelectBrowserParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_select_browser'>>;
 export declare function browserRelease(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
@@ -51,5 +50,4 @@ export declare function setAppProfile(params: Protocol.SetAppProfileParams, opti
 export declare function setTimezone(params: Protocol.SetTimezoneParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_timezone'>>;
 export declare function getCookie(params: Protocol.GetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_cookie'>>;
 export declare function setCookie(params: Protocol.SetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_cookie'>>;
-export declare function getUserInfo(params?: Protocol.GetUserInfoParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_user_info'>>;
 export declare function runActions(params: Protocol.RunActionsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'run_actions'>>;

package/dist/index.js

@@ -4,7 +4,7 @@
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
-export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
+export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_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) {
@@ -29,18 +29,12 @@ export function setMock(params, options) {
 export function getMocks(params = {}, options) {
     return invoke('get_mocks', params, options);
 }
-export function getApiSchema(params, options) {
-    return invoke('get_api_schema', params, options);
-}
 export function sendRequest(params, options) {
     return invoke('send_request', params, options);
 }
 export function sendMtopRequest(params, options) {
     return invoke('send_mtop_request', params, options);
 }
-export function tdbankAccount(params = {}, options) {
-    return invoke('tdbank_account', params, options);
-}
 export function browserList(options) {
     return invoke('browser_list', {}, options);
 }
@@ -128,9 +122,6 @@ export function getCookie(params, options) {
 export function setCookie(params, options) {
     return invoke('set_cookie', params, options);
 }
-export function getUserInfo(params = {}, options) {
-    return invoke('get_user_info', params, options);
-}
 export function runActions(params, options) {
     return invoke('run_actions', params, options);
 }

package/dist/plugin.d.ts

@@ -1,18 +1,42 @@
+import { type BucApi } from './buc.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, } from './pluginRegistry.js';
+export { type BucApi, type BucIdentity, type BucProfile, type BucRequestAuth, type BucRequestFormValue, type BucRequestParams, type BucRequestResult, } from './buc.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
 export type PluginOptions = UnifiedInvokeOptions;
+export interface PluginInvocation {
+    command: string;
+    input: Record<string, any>;
+}
+export interface PluginInvokeOptions extends UnifiedInvokeOptions {
+    onProgress?: (message: string) => void;
+}
+export interface PluginExecutionContext {
+    buc?: BucApi;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+}
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
+    readonly buc: BucApi;
     command(signature: string, handler: PluginHandler, description?: string): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     progress(message: string): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
-export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'> & {
+    buc?: BucApi;
+}, pluginName?: string): Promise<{
+    name: string | undefined;
+    description: string | undefined;
+    version: string | undefined;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown): Promise<unknown>;
+}>;
+export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown): Promise<unknown>;
 }>;
+export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;

package/dist/plugin.js

@@ -2,7 +2,8 @@ import { readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
-import { PluginError } from './pluginRegistry.js';
+import { buc } from './buc.js';
+import { findPluginRegistration, PluginError } from './pluginRegistry.js';
 export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
 function readPluginVersion(entry) {
     try {
@@ -31,9 +32,12 @@ function missingPluginEntryMessage(entry, pluginName) {
 }
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
+    let entryVersion;
     try {
-        if (!statSync(entry).isFile())
+        const stat = statSync(entry);
+        if (!stat.isFile())
             throw new Error('not a file');
+        entryVersion = `${stat.mtimeMs}-${stat.size}`;
     }
     catch {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
@@ -45,6 +49,23 @@ export async function loadPlugin(entry, context, pluginName) {
     let description;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
+        buc: Object.freeze({
+            request(params) {
+                if (!executing)
+                    throw new Error('app.buc.request 只能在命令执行期间调用');
+                return (context.buc ?? buc).request(params);
+            },
+            whoami() {
+                if (!executing)
+                    throw new Error('app.buc.whoami 只能在命令执行期间调用');
+                return (context.buc ?? buc).whoami();
+            },
+            profile() {
+                if (!executing)
+                    throw new Error('app.buc.profile 只能在命令执行期间调用');
+                return (context.buc ?? buc).profile();
+            },
+        }),
         command(signature, handler, description = '') {
             if (!registering)
                 throw new Error('命令只能在入口注册阶段声明');
@@ -78,7 +99,9 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     });
     try {
-        const module = await import(pathToFileURL(entry).href);
+        const moduleUrl = pathToFileURL(entry);
+        moduleUrl.searchParams.set('mearl-version', entryVersion);
+        const module = await import(moduleUrl.href);
         if (module.name !== undefined && typeof module.name !== 'string')
             throw new Error('入口的 name 导出必须为字符串');
         name = module.name;
@@ -171,3 +194,29 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     };
 }
+export async function loadRegisteredPlugin(name, context, options = {}) {
+    const registration = findPluginRegistration(name);
+    if (!registration) {
+        throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${name}`);
+    }
+    const { onProgress, ...invokeOptions } = options;
+    return loadPlugin(registration.entry, {
+        options: invokeOptions,
+        ...(context.buc ? { buc: context.buc } : {}),
+        progress: onProgress ?? (() => undefined),
+        async invoke(action, payload, overrides) {
+            const result = await context.invoke(action, payload, {
+                ...invokeOptions,
+                ...overrides,
+            });
+            if (result?.action?.success === false) {
+                throw new Error(result.action.error || `${action} failed`);
+            }
+            return result;
+        },
+    }, name);
+}
+export async function invokeRegisteredPlugin(name, invocation, context, options = {}) {
+    const plugin = await loadRegisteredPlugin(name, context, options);
+    return plugin.run([], invocation);
+}

package/dist/pluginRegistry.d.ts

@@ -5,11 +5,15 @@ export declare class PluginError extends Error {
 export interface PluginRegistration {
     entry: string;
     description?: string;
+    managedBy?: string;
+}
+export interface PluginRegistrationOptions {
+    managedBy?: string;
 }
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;
 export declare function resolvePluginEntry(target: string): string;
-export declare function registerPlugin(name: string, target: string, description?: string): string;
+export declare function registerPlugin(name: string, target: string, description?: string, options?: PluginRegistrationOptions): string;
 export declare function unregisterPlugin(name: string): boolean;
 export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
 export declare function findPluginEntry(name: string): string | undefined;

package/dist/pluginRegistry.js

@@ -40,7 +40,7 @@ export function resolvePluginEntry(target) {
         throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
     }
 }
-export function registerPlugin(name, target, description) {
+export function registerPlugin(name, target, description, options = {}) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
     const directory = pluginDirectory();
@@ -49,7 +49,12 @@ export function registerPlugin(name, target, description) {
     // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
     const temporary = `${file}.${randomUUID()}.tmp`;
     const summary = description?.trim();
-    const record = { entry, ...(summary ? { description: summary } : {}) };
+    const managedBy = options.managedBy?.trim();
+    const record = {
+        entry,
+        ...(summary ? { description: summary } : {}),
+        ...(managedBy ? { managedBy } : {}),
+    };
     try {
         writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
         renameSync(temporary, file);
@@ -92,7 +97,14 @@ export function findPluginRegistration(name) {
         const description = typeof record.description === 'string' && record.description.trim()
             ? record.description.trim()
             : undefined;
-        return { entry: record.entry, ...(description ? { description } : {}) };
+        const managedBy = typeof record.managedBy === 'string' && record.managedBy.trim()
+            ? record.managedBy.trim()
+            : undefined;
+        return {
+            entry: record.entry,
+            ...(description ? { description } : {}),
+            ...(managedBy ? { managedBy } : {}),
+        };
     }
     catch {
         throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);

package/dist/socket.js

@@ -77,14 +77,16 @@ function browserListFromProviderRecords(browsers) {
         .map(browser => ({
         browserId: browser.browserId,
         name: browser.browserName,
-        type: 'regular',
-        status: browser.status === 'pairing' ? 'pairing' : 'connected',
+        type: 'managed',
+        status: browser.status ?? 'running_disconnected',
         transport: 'provider',
-        providerId: browser.providerId,
-        providerName: browser.providerName,
-        providerVersion: browser.providerVersion,
-        providerProtocolVersion: browser.providerProtocolVersion,
+        provider: browser.provider,
+        ownership: browser.ownership,
+        persistence: browser.persistence,
+        operations: browser.operations,
         pairing: browser.pairing,
+        references: browser.references,
+        details: browser.details,
     }));
     return {
         count: providerBrowsers.length,
@@ -99,11 +101,23 @@ function mergeWarnings(result, warnings) {
     const merged = [...new Set([...resultWarnings, ...warnings])];
     return { ...result, ...(merged.length > 0 ? { warnings: merged } : {}) };
 }
-function supportsAction(browser, action) {
-    if (browser.transport === 'provider' &&
-        (action === 'get_versions' || action === 'browser_close')) {
+function isConnectedBrowser(browser) {
+    return browser.status === undefined || browser.status === 'connected';
+}
+function supportsAction(browser, action, data) {
+    if (action === 'get_versions')
         return true;
+    if (action === 'get_browser_access_url') {
+        return browser.transport !== 'provider' || browser.operations?.includes('access') === true;
+    }
+    if (action === 'browser_close') {
+        if (browser.transport !== 'provider')
+            return true;
+        const required = data.deleteProfile === true ? 'deleteData' : 'close';
+        return browser.operations?.includes(required) === true;
     }
+    if (!isConnectedBrowser(browser))
+        return false;
     return (browser.transport !== 'provider' ||
         browser.capabilities?.actions.some(capability => capability === action) === true);
 }
@@ -117,7 +131,7 @@ function selectBrowserResult(data) {
         };
     }
     const browsers = listLiveBrowsers();
-    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const controllableBrowsers = browsers.filter(isConnectedBrowser);
     const match = findBrowser(controllableBrowsers, selector);
     if (!match)
         throw new Error(formatNoMatchError(selector, browsers));
@@ -218,20 +232,20 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         }
     }
     const browsers = listLiveBrowsers();
-    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const controllableBrowsers = browsers.filter(isConnectedBrowser);
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
         if (!match) {
             throw new Error(formatNoMatchError(selector, browsers));
         }
-        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
-            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
-        }
         if (transport === 'cdp' && match.transport === 'provider') {
             throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
         }
-        if (!supportsAction(match, action)) {
+        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
+        }
+        if (!supportsAction(match, action, data)) {
             throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
         }
         try {
@@ -248,7 +262,8 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     // No explicit target: prefer the most-recently-focused live browser; on a
     // stale socket, fall through to the legacy path + auto-spawn.
-    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') && supportsAction(browser, action));
+    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') &&
+        supportsAction(browser, action, data));
     if (routableBrowsers.length > 0) {
         const target = routableBrowsers[0];
         try {
@@ -288,9 +303,9 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     /* isRetry */ true);
                 }
                 const browsers = listLiveBrowsers();
-                const target = browsers.find(browser => browser.status !== 'pairing' &&
+                const target = browsers.find(browser => isConnectedBrowser(browser) &&
                     !(transport === 'cdp' && browser.transport === 'provider') &&
-                    supportsAction(browser, action));
+                    supportsAction(browser, action, data));
                 if (target) {
                     return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
                 }

package/dist/unified.d.ts

@@ -1,4 +1,5 @@
 import { type CloudConnectorListResult } from '@mearl/cloud-types';
+import type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
 export interface UnifiedInvokeOptions {
     timeoutSec?: number;
     /** Global browser id, source-local browser id, or unique browser name. */
@@ -36,6 +37,7 @@ export declare class UnifiedClient {
     private closing;
     constructor(options?: UnifiedClientOptions);
     disconnect(): void;
+    invokePlugin(name: string, invocation: PluginInvocation, options?: PluginInvokeOptions): Promise<unknown>;
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
     private invokeExplicitLocal;
     private invokeLaunchWithoutControlBrowser;
@@ -61,5 +63,6 @@ export declare class UnifiedClient {
     private rejectAllPending;
 }
 export declare function invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function invokePlugin(name: string, invocation: PluginInvocation, options?: PluginInvokeOptions): Promise<unknown>;
 export declare function listCloudConnectors(): Promise<CloudConnectorListResult>;
 export {};

package/dist/unified.js

@@ -13,8 +13,10 @@ function encodeBrowserTarget(target) {
 }
 function omitTransientBrowserSecrets(browser) {
     const safeBrowser = { ...browser };
-    delete safeBrowser.agentbayAccessUrl;
-    delete safeBrowser.accessUrl;
+    for (const key of Object.keys(safeBrowser)) {
+        if (/accessUrl$/i.test(key))
+            delete safeBrowser[key];
+    }
     return safeBrowser;
 }
 export function decodeBrowserTarget(selector) {
@@ -117,6 +119,12 @@ export class UnifiedClient {
         this.ws?.close();
         this.ws = null;
     }
+    async invokePlugin(name, invocation, options = {}) {
+        const { invokeRegisteredPlugin } = await import('./plugin.js');
+        return invokeRegisteredPlugin(name, invocation, {
+            invoke: (action, payload, invokeOptions) => this.invoke(action, payload, invokeOptions),
+        }, options);
+    }
     async invoke(action, data = {}, options = {}) {
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
         if (action === 'connector_list')
@@ -420,17 +428,7 @@ export class UnifiedClient {
     decorateActionResult(action, result, source) {
         if (action !== 'browser_launch' || typeof result?.browserId !== 'string')
             return result;
-        const safeResult = omitTransientBrowserSecrets(result);
-        const originalBrowserId = result.browserId;
-        return {
-            ...safeResult,
-            browserId: encodeBrowserTarget({
-                browser: originalBrowserId,
-                ...(source.connectorId ? { connector: source.connectorId } : {}),
-            }),
-            originalBrowserId,
-            source,
-        };
+        return decorateBrowser(result, source);
     }
     async ensureConnected() {
         if (this.ws?.readyState === WebSocket.OPEN)
@@ -579,6 +577,20 @@ export async function invoke(action, data = {}, options = {}) {
         client.disconnect();
     }
 }
+export async function invokePlugin(name, invocation, options = {}) {
+    const serverUrl = process.env.MEARL_SERVER_URL ?? loadCloudServerConfig()?.server;
+    const client = new UnifiedClient({
+        ...(serverUrl ? { serverUrl } : {}),
+        defaultBrowser,
+        defaultConnector,
+    });
+    try {
+        return await client.invokePlugin(name, invocation, options);
+    }
+    finally {
+        client.disconnect();
+    }
+}
 export function listCloudConnectors() {
     return invoke('connector_list', {});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.13.0",
-    "@mearl/provider": "2.13.0"
+    "@mearl/cloud-types": "2.15.0",
+    "@mearl/provider": "2.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",